技术文档摘要

MCP RAG 服务器

MCP RAG 服务器是一个符合 Model Context Protocol (MCP) 的 Python 服务器，具有 RAG（检索增强生成）功能。它可以将多种格式的文档（如 Markdown、文本、PowerPoint、PDF 等）作为数据源，并使用 multilingual-e5-large 模型进行索引化，通过向量搜索获取相关信息。

概要

此项目除了实现 MCP 服务器的基本功能外，还提供了 RAG 功能。可以对多种格式的文档进行索引化，并基于自然语言查询来搜索相关信息。

功能

• MCP 服务器的基本实现

  • 基于 JSON-RPC over stdio 运行
  • 提供工具注册和执行机制
  • 错误处理和日志记录

• RAG 功能

  • 读取并解析多种格式的文档（Markdown、文本、PowerPoint、PDF）
  • 支持具有层次结构的源目录
  • 使用 markitdown 库将 PowerPoint 和 PDF 转换为 Markdown
  • 使用可选嵌入模型（multilingual-e5-large、ruri 等）生成嵌入
  • 使用 PostgreSQL 的 pgvector 作为向量数据库
  • 通过向量搜索获取相关信息
  • 获取前后片段的功能（确保上下文连续性）
  • 获取全文档的功能（提供完整的上下文）
  • 差异索引化功能（仅处理新文件或更改过的文件）

• 工具

  • 向量搜索工具（MCP）
  • 文档数量获取工具（MCP）
  • 索引管理工具（CLI）

前提条件

• Python 3.10 及以上版本
• PostgreSQL 14 及以上版本（带有 pgvector 扩展）

安装

安装依赖项

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

# 安装依赖项
uv sync

PostgreSQL 和 pgvector 的设置

使用 Docker

# 启动包含 pgvector 的 PostgreSQL 容器
docker run --name postgres-pgvector -e POSTGRES_PASSWORD=password -p 5432:5432 -d pgvector/pgvector:pg17

创建数据库

启动 PostgreSQL 容器后，使用以下命令创建数据库：

# 创建 ragdb 数据库
docker exec -it postgres-pgvector psql -U postgres -c "CREATE DATABASE ragdb;"

在现有 PostgreSQL 中安装 pgvector

-- 安装 pgvector 扩展
CREATE EXTENSION vector;

设置环境变量

创建 .env 文件，并设置以下环境变量：

# PostgreSQL 连接信息
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=password
POSTGRES_DB=ragdb

# 文档目录
SOURCE_DIR=./data/source
PROCESSED_DIR=./data/processed

# 嵌入模型设置
EMBEDDING_MODEL=intfloat/multilingual-e5-large
EMBEDDING_DIM=1024
EMBEDDING_PREFIX_QUERY="query: "
EMBEDDING_PREFIX_EMBEDDING="passage: "

嵌入模型的设置

此服务器允许在环境变量中选择嵌入模型。

支持的模型

multilingual-e5-large（默认）

EMBEDDING_MODEL=intfloat/multilingual-e5-large
EMBEDDING_DIM=1024
EMBEDDING_PREFIX_QUERY="query: "
EMBEDDING_PREFIX_EMBEDDING="passage: "

cl-nagoya/ruri-v3-30m

EMBEDDING_MODEL=cl-nagoya/ruri-v3-30m
EMBEDDING_DIM=256
EMBEDDING_PREFIX_QUERY="查询: "
EMBEDDING_PREFIX_EMBEDDING="文档: "

关于前缀

许多嵌入模型（尤其是 E5 系列）通过根据文本类型添加前缀来提高性能：

• 查询用: EMBEDDING_PREFIX_QUERY - 自动添加到用户的查询中
• 文档用: EMBEDDING_PREFIX_EMBEDDING - 自动添加到被索引化的文档中

前缀会自动处理，因此 MCP 客户端无需特别关注。

更改模型时的注意事项

更改嵌入模型时，由于向量维度可能会改变，需要清除现有的索引并重新创建：

python -m src.cli clear
python -m src.cli index

使用方法

启动 MCP 服务器

使用 uv（推荐）

uv run python -m src.main

如果需要指定选项：

uv run python -m src.main --name "my-rag-server" --version "1.0.0" --description "My RAG Server"

使用普通 Python

python -m src.main

命令行工具（CLI）的使用方法

提供了用于清除和索引化索引的命令行工具。

显示帮助

python -m src.cli --help

清除索引

python -m src.cli clear

索引化文档

# 默认设置下索引化（./data/source 目录）
python -m src.cli index

# 对特定目录进行索引化
python -m src.cli index --directory ./path/to/documents

# 指定片段大小和重叠进行索引化
python -m src.cli index --directory ./data/source --chunk-size 300 --chunk-overlap 50
# 或者使用简短形式
python -m src.cli index -d ./data/source -s 300 -o 50

# 差异索引化（仅处理新文件或更改过的文件）
python -m src.cli index --incremental
# 或者使用简短形式
python -m src.cli index -i

获取索引中的文档数量

python -m src.cli count

在 MCP 主机上的设置

要在 MCP 主机（如 Claude Desktop、Cline、Cursor 等）上使用此服务器，需要进行如下设置。关于设置 json 文件的具体内容，请参阅各 MCP 主机的文档。

设置示例

{
  "mcpServers": {
    "mcp-rag-server": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/mcp-rag-server",
        "python",
        "-m",
        "src.main"
      ]
    }
  }
}

设置要点

• command: uv（推荐）或 python
• args: 实际运行参数的数组
• /path/to/mcp-rag-server: 请替换为此仓库的实际路径

不使用 uv

在未安装 uv 的环境中，可以使用普通 Python：

{
  "command": "python",
  "args": [
    "-m",
    "src.main"
  ],
  "cwd": "/path/to/mcp-rag-server"
}

RAG 工具的使用方法

search

执行向量搜索。

{
  "jsonrpc": "2.0",
  "method": "search",
  "params": {
    "query": "Python 的生成器是什么？",
    "limit": 5,
    "with_context": true,
    "context_size": 1,
    "full_document": false
  },
  "id": 1
}

参数说明

• query: 查询语句（必需）
• limit: 返回的结果数量（默认值: 5）
• with_context: 是否获取前后片段（默认值: true）
• context_size: 获取前后片段的数量（默认值: 1）
• full_document: 是否获取全文档（默认值: false）

搜索结果的改进

此工具通过以下功能提供更好的搜索结果：

1. 前后片段获取功能：

   • 获取与查询匹配的片段的前后片段，并将其包含在结果中
   • 可以通过 with_context 参数启用或禁用
   • 可以通过 context_size 参数调整前后片段的数量

2. 全文档获取功能：

   • 获取与查询匹配的文档的全文，并将其包含在结果中
   • 可以通过 full_document 参数启用或禁用
   • 对于较短的文档或需要整体上下文的文档尤其有用

3. 结果格式的改进：

   • 将搜索结果按文件分组
   • 视觉上区分“搜索命中”、“前后上下文”和“全文档”
   • 按片段索引排序以保持文档流程

get_document_count

获取索引中的文档数量。

{
  "jsonrpc": "2.0",
  "method": "get_document_count",
  "params": {},
  "id": 2
}

使用示例

1. 将文档文件放置在 data/source 目录中。支持的文件格式包括：

   • Markdown（.md, .markdown）
   • 文本（.txt）
   • PowerPoint（.ppt, .pptx）
   • Word（.doc, .docx）
   • PDF（.pdf）

2. 使用 CLI 命令索引化文档：

   # 首次索引化所有文档
   python -m src.cli index
   
   # 之后使用差异索引化高效更新
   python -m src.cli index -i
   

3. 启动 MCP 服务器：

   uv run python -m src.main
   

4. 使用 search 工具进行搜索。

备份与恢复

若要在另一台 PC 上使用已索引化的数据库，需按照以下步骤进行备份与恢复。

最小备份（仅 PostgreSQL 数据库）

如果您只想在另一台 PC 上使用 RAG 搜索功能，则只需备份 PostgreSQL 数据库即可。因为所有向量化数据都存储在数据库中。

PostgreSQL 数据库的备份

使用 Docker 容器内的 pg_dump 命令备份 PostgreSQL 数据库：

# 在 Docker 容器内备份数据库
docker exec -it postgres-pgvector pg_dump -U postgres -d ragdb -F c -f /tmp/ragdb_backup.dump

# 将备份文件从容器复制到主机
docker cp postgres-pgvector:/tmp/ragdb_backup.dump ./ragdb_backup.dump

这将创建一个 PostgreSQL 数据库的备份文件（例如 239MB），位于当前目录中。

最小恢复步骤

1. 在新的 PC 上设置 PostgreSQL 和 pgvector：

# 使用 Docker
docker run --name postgres-pgvector -e POSTGRES_PASSWORD=password -p 5432:5432 -d pgvector/pgvector:pg17

# 创建数据库
docker exec -it postgres-pgvector psql -U postgres -c "CREATE DATABASE ragdb;"

2. 从备份文件恢复数据库：

# 将备份文件复制到容器
docker cp ./ragdb_backup.dump postgres-pgvector:/tmp/ragdb_backup.dump

# 在容器内恢复数据库
docker exec -it postgres-pgvector pg_restore -U postgres -d ragdb -c /tmp/ragdb_backup.dump

3. 确认环境设置：

在新的 PC 上，请确认 .env 文件中的 PostgreSQL 连接信息正确无误。

4. 进行测试：

python -m src.cli count

这将显示索引中的文档数量。如果与原 PC 上的数量相同，则表明已成功恢复。

完整备份（可选）

如果您计划将来添加新的文档，或者希望使用差异索引化功能，则建议进行以下附加备份：

处理过的文档的备份

备份处理过的文档目录：

# 将处理过的文档目录备份为 ZIP 文件
zip -r processed_data_backup.zip data/processed/

环境设置文件的备份

备份 .env 文件：

# 复制 .env 文件
cp .env env_backup.txt

完整恢复步骤

1. 前提条件

新的 PC 上应安装以下软件：

• Python 3.10 及以上版本
• PostgreSQL 14 及以上版本（带有 pgvector 扩展）
• mcp-rag-server 的代码库

2. 按照上述“最小恢复步骤”恢复 PostgreSQL 数据库。

3. 恢复处理过的文档：

# 解压 ZIP 文件
unzip processed_data_backup.zip -d /path/to/mcp-rag-server/

4. 恢复环境设置文件：

# 恢复 .env 文件
cp env_backup.txt /path/to/mcp-rag-server/.env

根据新的 PC 环境需要，可能需要编辑 .env 文件中的设置（特别是 PostgreSQL 连接信息）。

5. 进行测试：

python -m src.cli count

注意事项

• 新旧 PC 上的 PostgreSQL 版本和 pgvector 版本需要兼容。
• 若数据量较大，备份和恢复过程可能耗时较长。
• 新的 PC 上需要安装必要的 Python 包（如 sentence-transformers、psycopg2-binary 等）。

目录结构

mcp-rag-server/
├── data/
│   ├── source/        # 原稿文件（支持层次结构）
│   │   ├── markdown/  # Markdown 文件
│   │   ├── docs/      # 文档文件
│   │   └── slides/    # 幻灯片文件
│   └── processed/     # 处理过的文件（已提取文本）
│       └── file_registry.json  # 处理过的文件信息（用于差异索引化）
├── docs/
│   └── design.md      # 设计文档
├── logs/              # 日志文件
├── src/
│   ├── __init__.py
│   ├── document_processor.py  # 文档处理模块
│   ├── embedding_generator.py # 嵌入生成模块
│   ├── example_tool.py        # 示例工具模块
│   ├── main.py                # 主入口点
│   ├── mcp_server.py          # MCP 服务器模块
│   ├── rag_service.py         # RAG 服务模块
│   ├── rag_tools.py           # RAG 工具模块
│   └── vector_database.py     # 向量数据库模块
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_document_processor.py
│   ├── test_embedding_generator.py
│   ├── test_example_tool.py
│   ├── test_mcp_server.py
│   ├── test_rag_service.py
│   ├── test_rag_tools.py
│   └── test_vector_database.py
├── .env           # 环境变量设置文件
├── .gitignore
├── LICENSE
├── pyproject.toml
└── README.md

许可证

此项目在 MIT 许可证下发布。详情请参见 LICENSE 文件。