Embedding MCP Server

嵌入向量 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 服务提供了访问知识库的标准化接口：

• 语义搜索功能
• 知识图谱查询和可视化
• 文本处理管道（摘要、提取等）
• 完全符合模型上下文协议

安装

推荐：使用 Python 3.10+ 和 uv

为获得最佳体验，我们建议将 uv 与 Python 3.10 或更高版本搭配使用。这样可以更好地管理依赖项，并确保行为一致。

# Install uv if you don't have it already
pip install -U uv

# Create a virtual environment with Python 3.10 or newer
uv venv --python=3.10  # or 3.11, 3.12, etc.

# Activate the virtual environment (bash/zsh)
source .venv/bin/activate
# For fish shell
# source .venv/bin/activate.fish

# Install from PyPI
uv pip install kb-mcp-server

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

使用 conda

# Create a new conda environment (optional)
conda create -n embedding-mcp python=3.10
conda activate embedding-mcp

# Install from PyPI
pip install kb-mcp-server

从源代码安装

# Create a new conda environment
conda create -n embedding-mcp python=3.10
conda activate embedding-mcp

# Clone the repository
git clone https://github.com/Geeksfino/kb-mcp-server.git.git
cd kb-mcp-server

# Install dependencies
pip install -e .

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

# Install uv if not already installed
pip install uv

# Create a new virtual environment
uv venv
source .venv/bin/activate

# Option 1: Install from PyPI
uv pip install kb-mcp-server

# Option 2: Install from source (for development)
uv pip install -e .

使用 uvx（无需安装）

uvx 可以直接从 PyPI 运行软件包，无需安装：

# Run the MCP server
uvx --from [email protected] kb-mcp-server --embeddings /path/to/knowledge_base

# Build a knowledge base
uvx --from [email protected] kb-build --input /path/to/documents --config config.yml

# Search a knowledge base
uvx --from [email protected] kb-search /path/to/knowledge_base "Your search query"

命令行用法

构建知识库

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

使用从 PyPI 安装的命令

# Build a knowledge base from documents
kb-build --input /path/to/documents --config config.yml

# Update an existing knowledge base with new documents
kb-build --input /path/to/new_documents --update

# Export a knowledge base for portability
kb-build --input /path/to/documents --export my_knowledge_base.tar.gz

# Search a knowledge base
kb-search /path/to/knowledge_base "What is machine learning?"

# Search with graph enhancement
kb-search /path/to/knowledge_base "What is machine learning?" --graph --limit 10

使用 uvx（无需安装）

# Build a knowledge base from documents
uvx --from [email protected] kb-build --input /path/to/documents --config config.yml

# Update an existing knowledge base with new documents
uvx --from [email protected] kb-build --input /path/to/new_documents --update

# Export a knowledge base for portability
uvx --from [email protected] kb-build --input /path/to/documents --export my_knowledge_base.tar.gz

# Search a knowledge base
uvx --from [email protected] kb-search /path/to/knowledge_base "What is machine learning?"

# Search with graph enhancement
uvx --from [email protected] kb-search /path/to/knowledge_base "What is machine learning?" --graph --limit 10

使用 Python 模块

# Build a knowledge base from documents
python -m kb_builder build --input /path/to/documents --config config.yml

# Update an existing knowledge base with new documents
python -m kb_builder build --input /path/to/new_documents --update

# Export a knowledge base for portability
python -m kb_builder build --input /path/to/documents --export my_knowledge_base.tar.gz

使用便捷脚本

仓库包含便捷的包装脚本，可更轻松地构建和搜索知识库：

# Build a knowledge base using a template configuration
./scripts/kb_build.sh /path/to/documents technical_docs

# Build using a custom configuration file
./scripts/kb_build.sh /path/to/documents /path/to/my_config.yml

# Update an existing knowledge base
./scripts/kb_build.sh /path/to/documents technical_docs --update

# Search a knowledge base
./scripts/kb_search.sh /path/to/knowledge_base "What is machine learning?"

# Search with graph enhancement
./scripts/kb_search.sh /path/to/knowledge_base "What is machine learning?" --graph

运行 ./scripts/kb_build.sh --help 或 ./scripts/kb_search.sh --help，了解更多选项。

启动 MCP 服务

使用通过 PyPI 安装的命令

# Start with a specific knowledge base folder
kb-mcp-server --embeddings /path/to/knowledge_base_folder

# Start with a given knowledge base archive
kb-mcp-server --embeddings /path/to/knowledge_base.tar.gz

使用 uvx（无需安装）

# Start with a specific knowledge base folder
uvx [email protected] --embeddings /path/to/knowledge_base_folder

# Start with a given knowledge base archive
uvx [email protected] --embeddings /path/to/knowledge_base.tar.gz

使用 Python 模块

# Start with a specific knowledge base folder
python -m txtai_mcp_server --embeddings /path/to/knowledge_base_folder

# Start with a given knowledge base archive
python -m txtai_mcp_server --embeddings /path/to/knowledge_base.tar.gz

MCP 服务配置

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

以下是配置 MCP 服务的方法：

# Start the server with command-line arguments
kb-mcp-server --embeddings /path/to/knowledge_base --host 0.0.0.0 --port 8000

# Or using uvx (no installation required)
uvx [email protected] --embeddings /path/to/knowledge_base --host 0.0.0.0 --port 8000

# Or using the Python module
python -m txtai_mcp_server --embeddings /path/to/knowledge_base --host 0.0.0.0 --port 8000

# Or use environment variables
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 并使其可全局访问：

# Create a symlink to /usr/local/bin (which is typically in the system PATH)
sudo ln -s /Users/cliang/.local/bin/uvx /usr/local/bin/uvx

这会在你的用户专属安装位置与系统范围的位置之间创建一个符号链接。对于 Claude Desktop 等 macOS 应用，你可以创建或编辑 launchd 配置文件来修改系统范围的 PATH：

# Create a plist file to set environment variables for all GUI applications
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": [
        "[email protected]",
        "--embeddings", "/path/to/knowledge_base",
        "--host", "localhost",
        "--port", "8000"
      ],
      "cwd": "/path/to/working/directory"
    }
  }
}

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

高级知识库配置

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

你可能需要调整分段/分块策略、嵌入模型和评分方法，同时配置图构建、因果增强、混合搜索权重等。

幸运的是，txtai 提供了功能强大的 YAML 配置系统，无需编写代码。以下是用于构建知识库的完整配置示例：

# Path to save/load embeddings index
path: ~/.txtai/embeddings
writable: true

# Content storage in SQLite
content:
  path: sqlite:///~/.txtai/content.db

# Embeddings configuration
embeddings:
  # Model settings
  path: sentence-transformers/nli-mpnet-base-v2
  backend: faiss
  gpu: true
  batch: 32
  normalize: true
  
  # Scoring settings
  scoring: hybrid
  hybridalpha: 0.75

# Pipeline configuration
pipeline:
  workers: 2
  queue: 100
  timeout: 300

# Question-answering pipeline
extractor:
  path: distilbert-base-cased-distilled-squad
  maxlength: 512
  minscore: 0.3

# Graph configuration
graph:
  backend: sqlite
  path: ~/.txtai/graph.db
  similarity: 0.75  # Threshold for creating graph connections
  limit: 10  # Maximum connections per node

配置示例

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

# Or use a storage-specific configuration
python -m kb_builder build --input /path/to/documents --config src/kb_builder/configs/postgres-pgvector.yml

高级功能

知识图谱功能

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

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

因果增强机制

MCP 服务包含一种先进的因果增强机制，通过识别并优先处理因果关系来提升搜索相关性：

• 模式识别：检测查询和文档中的因果语言模式
• 多语言支持：根据检测到的查询语言自动应用相应模式
• 可配置的增强倍数：不同类型的因果匹配可设置自定义增强因子
• 提升相关性：在搜索结果中优先展示能够解释因果关系的内容

该机制通过呈现解释概念间关系的内容，显著改善对“为什么”和“如何”这类问题的回答。因果增强配置可通过 YAML 文件高度自定义，从而适配不同领域和语言。

许可证

MIT 许可证——详情请参阅 LICENSE 文件