嵌入 MCP 服务器

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

txtai 的强大之处：一体化嵌入数据库

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

• 统一向量数据库：在单个平台中结合了向量索引、图网络和关系数据库
• 语义搜索：根据含义而非仅仅是关键词查找信息
• 知识图谱集成：自动从您的数据构建和查询知识图谱
• 可移植的知识库：将整个知识库保存为压缩存档 (.tar.gz)，可以轻松共享和加载
• 可扩展的管道系统：通过统一的 API 处理文本、文档、音频、图像和视频
• 本地优先架构：在本地运行所有内容，而无需将数据发送到外部服务

工作原理

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

不需要使用知识库构建工具来构建知识库。您始终可以通过编写 Python 脚本甚至使用 jupyter notebook，使用 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 主机将无法连接到服务器，您需要使用虚拟环境的 Python 可执行文件的绝对路径，您在其中执行了 "pip install" 或 "uv pip install"，例如

{
  "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

这会创建一个从您的用户特定安装到系统范围位置的符号链接。对于像 Claude Desktop 这样的 macOS 应用程序，您可以通过创建或编辑启动配置来修改系统范围的 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 文件