知识库MCP服务器

Name: 知识库MCP服务器
Author: Geeksfino

作者：Geeksfino58 星标更新：2025-08-07

安装使用来源：spider==github.com

项目介绍

嵌入式MCP服务器

由txtai驱动的模型上下文协议（MCP）服务器实现，提供语义搜索、知识图谱功能以及通过标准化接口进行AI驱动的文本处理。

txtai的强大之处：一站式嵌入数据库

该项目利用了txtai，这是一个用于RAG的一站式嵌入数据库，结合了语义搜索、知识图谱构建和语言模型工作流。txtai提供了几个关键优势：

统一向量数据库：在一个平台上结合向量索引、图网络和关系数据库
语义搜索：基于意义而不是关键词查找信息
知识图谱集成：自动构建和查询数据的知识图谱
便携式知识库：将整个知识库保存为压缩存档（.tar.gz），可以轻松共享和加载
可扩展流水线系统：通过统一API处理文本、文档、音频、图像和视频
本地优先架构：无需将数据发送到外部服务即可在本地运行所有内容

工作原理

项目包含一个知识库构建工具和一个MCP服务器。知识库构建工具是一个命令行界面，用于创建和管理知识库。MCP服务器提供了一个标准化接口来访问知识库。

使用知识库构建工具构建知识库不是必须的。你可以始终通过编写Python脚本或使用Jupyter笔记本，使用txtai的编程接口来构建知识库。只要使用txtai构建了知识库，就可以被MCP服务器加载。更好的是，知识库可以是文件系统中的一个文件夹或导出的.tar.gz文件。只需将其交给MCP服务器，它就会加载。

1. 使用kb_builder构建知识库

kb_builder模块提供了一个命令行界面，用于创建和管理知识库：

处理来自各种来源的文档（文件、目录、JSON）
提取文本并创建嵌入
自动构建知识图谱
导出便携式知识库

请注意，其功能可能有限，并且目前仅出于方便而提供。

2. 启动MCP服务器

MCP服务器提供了一个标准化接口来访问知识库：

语义搜索能力
知识图谱查询和可视化
文本处理流水线（总结、提取等）
完全符合模型上下文协议

安装

推荐：使用uv与Python 3.10+

我们推荐使用uv与Python 3.10或更高版本以获得最佳体验。这提供了更好的依赖管理并确保了一致的行为。

# 如果还没有安装uv，请先安装
pip install -U uv

# 创建一个Python 3.10或更高版本的虚拟环境
uv venv --python=3.10  # 或者3.11、3.12等

# 激活虚拟环境（bash/zsh）
source .venv/bin/activate
# 对于fish shell
# source .venv/bin/activate.fish

# 从PyPI安装
uv pip install kb-mcp-server

注意：我们将transformers固定在4.49.0版本，以避免在4.50.0及更高版本中出现关于transformers.agents.tools的弃用警告。如果你使用的是transformers的新版本，可能会看到这些警告，但它们不会影响功能。

使用conda

# 创建一个新的conda环境（可选）
conda create -n embedding-mcp python=3.10
conda activate embedding-mcp

# 从PyPI安装
pip install kb-mcp-server

从源代码安装

# 创建一个新的conda环境
conda create -n embedding-mcp python=3.10
conda activate embedding-mcp

# 克隆仓库
git clone https://github.com/Geeksfino/kb-mcp-server.git.git
cd kb-mcp-server

# 安装依赖
pip install -e .

使用uv（更快的替代方案）

# 如果尚未安装，请安装uv
pip install uv

# 创建一个新的虚拟环境
uv venv
source .venv/bin/activate

# 方案1：从PyPI安装
uv pip install kb-mcp-server

# 方案2：从源代码安装（用于开发）
uv pip install -e .

使用uvx（无需安装）

uvx允许你直接从PyPI运行包，而无需安装它们：

# 运行MCP服务器
uvx --from kb-mcp-server@0.3.0 kb-mcp-server --embeddings /path/to/knowledge_base

# 构建知识库
uvx --from kb-mcp-server@0.3.0 kb-build --input /path/to/documents --config config.yml

# 搜索知识库
uvx --from kb-mcp-server@0.3.0 kb-search /path/to/knowledge_base "您的搜索查询"

命令行使用

构建知识库

你可以使用从PyPI安装的命令行工具、直接使用Python模块或方便的shell脚本：

使用从PyPI安装的命令

# 从文档构建知识库
kb-build --input /path/to/documents --config config.yml

# 更新现有知识库的新文档
kb-build --input /path/to/new_documents --update

# 导出知识库以便于携带
kb-build --input /path/to/documents --export my_knowledge_base.tar.gz

# 搜索知识库
kb-search /path/to/knowledge_base "什么是机器学习？"

# 带有图增强的搜索
kb-search /path/to/knowledge_base "什么是机器学习？" --graph --limit 10

使用uvx（无需安装）

# 从文档构建知识库
uvx --from kb-mcp-server@0.3.0 kb-build --input /path/to/documents --config config.yml

# 更新现有知识库的新文档
uvx --from kb-mcp-server@0.3.0 kb-build --input /path/to/new_documents --update

# 导出知识库以便于携带
uvx --from kb-mcp-server@0.3.0 kb-build --input /path/to/documents --export my_knowledge_base.tar.gz

# 搜索知识库
uvx --from kb-mcp-server@0.3.0 kb-search /path/to/knowledge_base "什么是机器学习？"

# 带有图增强的搜索
uvx --from kb-mcp-server@0.3.0 kb-search /path/to/knowledge_base "什么是机器学习？" --graph --limit 10

使用Python模块

# 从文档构建知识库
python -m kb_builder build --input /path/to/documents --config config.yml

# 更新现有知识库的新文档
python -m kb_builder build --input /path/to/new_documents --update

# 导出知识库以便于携带
python -m kb_builder build --input /path/to/documents --export my_knowledge_base.tar.gz

使用方便的脚本

仓库包括方便的包装脚本，使构建和搜索知识库更容易：

# 使用模板配置构建知识库
./scripts/kb_build.sh /path/to/documents technical_docs

# 使用自定义配置文件构建
./scripts/kb_build.sh /path/to/documents /path/to/my_config.yml

# 更新现有知识库
./scripts/kb_build.sh /path/to/documents technical_docs --update

# 搜索知识库
./scripts/kb_search.sh /path/to/knowledge_base "什么是机器学习？"

# 带有图增强的搜索
./scripts/kb_search.sh /path/to/knowledge_base "什么是机器学习？" --graph

运行./scripts/kb_build.sh --help或./scripts/kb_search.sh --help以获取更多选项。

启动MCP服务器

使用从PyPI安装的命令

# 使用特定的知识库文件夹启动
kb-mcp-server --embeddings /path/to/knowledge_base_folder

# 使用给定的知识库存档启动
kb-mcp-server --embeddings /path/to/knowledge_base.tar.gz

使用uvx（无需安装）

# 使用特定的知识库文件夹启动
uvx kb-mcp-server@0.2.6 --embeddings /path/to/knowledge_base_folder

# 使用给定的知识库存档启动
uvx kb-mcp-server@0.2.6 --embeddings /path/to/knowledge_base.tar.gz

使用Python模块

# 使用特定的知识库文件夹启动
python -m txtai_mcp_server --embeddings /path/to/knowledge_base_folder

# 使用给定的知识库存档启动
python -m txtai_mcp_server --embeddings /path/to/knowledge_base.tar.gz

MCP服务器配置

MCP服务器通过环境变量或命令行参数进行配置，而不是YAML文件。YAML文件仅用于在构建知识库时配置txtai组件。

这是如何配置MCP服务器的：

# 使用命令行参数启动服务器
kb-mcp-server --embeddings /path/to/knowledge_base --host 0.0.0.0 --port 8000

# 或使用uvx（无需安装）
uvx kb-mcp-server@0.2.6 --embeddings /path/to/knowledge_base --host 0.0.0.0 --port 8000

# 或使用Python模块
python -m txtai_mcp_server --embeddings /path/to/knowledge_base --host 0.0.0.0 --port 8000

# 或使用环境变量
export TXTAI_EMBEDDINGS=/path/to/knowledge_base
export MCP_SSE_HOST=0.0.0.0
export MCP_SSE_PORT=8000
python -m txtai_mcp_server

常见的配置选项：

--embeddings：知识库路径（必需）
--host：绑定的主机地址（默认：localhost）
--port：监听端口（默认：8000）
--transport：使用的传输方式，要么是'sse'要么是'stdio'（默认：stdio）
--enable-causal-boost：启用因果提升功能以增强相关性评分
--causal-config：自定义因果提升配置YAML文件的路径

配置LLM客户端以使用MCP服务器

要配置LLM客户端以使用MCP服务器，你需要创建一个MCP配置文件。这里是一个示例mcp_config.json：

直接使用服务器

如果你使用虚拟Python环境安装服务器，可以使用以下配置——请注意，像Claude这样的MCP主机如果使用虚拟环境将无法连接到服务器，你需要使用执行“pip install”或“uv pip install”的虚拟环境Python可执行文件的绝对路径，例如

{
  "mcpServers": {
    "kb-server": {
      "command": "/your/home/project/.venv/bin/kb-mcp-server",
      "args": [
        "--embeddings", 
        "/path/to/knowledge_base.tar.gz"
      ],
      "cwd": "/path/to/working/directory"
    }
  }
}

使用系统默认Python

如果你使用系统默认Python，可以使用以下配置：

{
    "rag-server": {
      "command": "python3",
      "args": [
        "-m",
        "txtai_mcp_server",
        "--embeddings",
        "/path/to/knowledge_base.tar.gz",
        "--enable-causal-boost"
      ],
      "cwd": "/path/to/working/directory"
    }
}

或者，如果你使用uvx，假设你已经通过“brew install uvx”等方式在系统中安装了uvx，或者你已安装uvx并使其全局可用：

# 创建一个符号链接到/usr/local/bin（通常在系统PATH中）
sudo ln -s /Users/cliang/.local/bin/uvx /usr/local/bin/uvx

这会从你的用户特定安装创建到系统范围位置的符号链接。对于macOS应用程序如Claude Desktop，你可以通过创建或编辑launchd配置文件来修改系统范围的PATH：

# 创建一个plist文件以设置所有GUI应用程序的环境变量
sudo nano /Library/LaunchAgents/environment.plist

添加以下内容：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>my.startup</string>
  <key>ProgramArguments</key>
  <array>
    <string>sh</string>
    <string>-c</string>
    <string>launchctl setenv PATH $PATH:/Users/cliang/.local/bin</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
</dict>
</plist>

然后加载它：

sudo launchctl load -w /Library/LaunchAgents/environment.plist

你需要重新启动计算机才能生效。

{
  "mcpServers": {
    "kb-server": {
      "command": "uvx",
      "args": [
        "kb-mcp-server@0.2.6",
        "--embeddings", "/path/to/knowledge_base",
        "--host", "localhost",
        "--port", "8000"
      ],
      "cwd": "/path/to/working/directory"
    }
  }
}

将此配置文件放置在LLM客户端可访问的位置，并配置客户端使用它。具体的配置步骤取决于你的具体LLM客户端。

高级知识库配置

使用txtai构建知识库需要一个YAML配置文件，该文件控制嵌入过程的各种方面。此配置由kb_builder工具使用，而不是MCP服务器本身。

你可能需要调整分段/切片策略、嵌入模型和评分方法，以及配置图构建、因果提升、混合搜索权重等。

幸运的是，txtai提供了一个强大的YAML配置系统，不需要编码。这里是一个全面的知识库构建配置示例：

# 保存/加载嵌入索引的路径
path: ~/.txtai/embeddings
writable: true

# 内容存储在SQLite中
content:
  path: sqlite:///~/.txtai/content.db

# 嵌入配置
embeddings:
  # 模型设置
  path: sentence-transformers/nli-mpnet-base-v2
  backend: faiss
  gpu: true
  batch: 32
  normalize: true
  
  # 评分设置
  scoring: hybrid
  hybridalpha: 0.75

# 流水线配置
pipeline:
  workers: 2
  queue: 100
  timeout: 300

# 问答流水线
extractor:
  path: distilbert-base-cased-distilled-squad
  maxlength: 512
  minscore: 0.3

# 图配置
graph:
  backend: sqlite
  path: ~/.txtai/graph.db
  similarity: 0.75  # 创建图连接的阈值
  limit: 10  # 每个节点的最大连接数

配置示例

src/kb_builder/configs目录包含不同用例和存储后端的配置模板：

存储和后端配置

memory.yml：内存向量（开发最快，无持久性）
sqlite-faiss.yml：SQLite用于内容+FAISS用于向量（本地基于文件的持久性）
postgres-pgvector.yml：PostgreSQL+pgvector（具有完全持久性的生产就绪）

领域特定配置

base.yml：基础配置模板
code_repositories.yml：针对代码仓库优化
data_science.yml：针对数据科学文档配置
general_knowledge.yml：通用知识库
research_papers.yml：针对学术论文优化
technical_docs.yml：针对技术文档配置

你可以使用这些作为自己配置的起点：

python -m kb_builder build --input /path/to/documents --config src/kb_builder/configs/technical_docs.yml

# 或使用特定存储配置
python -m kb_builder build --input /path/to/documents --config src/kb_builder/configs/postgres-pgvector.yml

高级功能

知识图谱能力

MCP服务器利用txtai内置的图功能提供强大的知识图谱能力：

自动图构建：从文档自动构建知识图谱
图遍历：导航相关概念和文档
路径查找：发现不同信息之间的联系
社区检测：识别相关信息集群

因果提升机制

MCP服务器包含一个复杂的因果提升机制，通过识别和优先考虑因果关系来增强搜索相关性：

模式识别：在查询和文档中检测因果语言模式
多语言支持：根据检测到的查询语言自动应用适当的模式
可配置的提升乘数：不同类型的原因匹配接收可定制的提升因子
增强的相关性：解释因果关系的结果在搜索结果中优先显示

这种机制显著提高了对“为什么”和“如何”问题的回答，通过展示解释概念之间关系的内容。因果提升配置高度可定制，通过YAML文件允许适应不同的领域和语言。

许可证

MIT许可证 - 详情见LICENSE文件