拉格-MCP服务器

Name: 拉格-MCP服务器
Author: tungetti

作者：tungetti2 星标更新：2025-06-23

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

项目介绍

技术文档摘要

RAG MCP 服务器

这是一个用于检索增强生成（RAG）操作的模型上下文协议（MCP）服务器。该服务器提供了构建和查询基于向量的知识库的工具，支持语义搜索和文档检索功能。

特性
架构
安装
设置
使用示例
- 样本LLM查询
- 命令行示例
MCP工具
技术细节
配置示例
故障排除
贡献
许可证

特性

文档处理：支持多种文件格式（.txt, .pdf），并自动提取文本
智能分块：可配置的文本分块，带有重叠以保留上下文
向量嵌入：使用SentenceTransformers进行高质量的文本嵌入
语义搜索：使用FAISS进行相似度搜索，实现快速准确的检索
增量更新：智能文档跟踪，仅处理新文件或更改过的文件
持久存储：使用SQLite数据库存储元数据和变更跟踪
灵活配置：可自定义嵌入模型、分块大小和搜索参数

架构

rag-mcp-server/
├── src/rag_mcp_server/
│   ├── server.py              # 主MCP服务器实现
│   └── core/
│       ├── document_processor.py  # 文档加载和分块
│       ├── embedding_service.py   # 文本嵌入生成
│       ├── faiss_index.py        # 向量相似度搜索
│       └── document_store.py     # 文档元数据存储

安装

使用uvx（推荐）

# 使用uvx安装（uv自带）
uvx rag-mcp-server

使用pip

pip install rag-mcp-server

从源代码安装

git clone <repository-url>
cd rag-mcp-server
pip install -e .

设置

运行MCP服务器最简单的方法是使用uvx，但也可以手动设置。

查找客户端的MCP设置文件

Claude Desktop

根据需要安装Claude Desktop
打开配置文件：打开Claude Desktop应用，进入其设置，打开“开发者”标签页，点击“编辑配置”按钮
按照下面的“设置MCP服务器”步骤操作

Claude Code

根据需要安装Claude Code

运行以下命令添加RAG服务器：

claude mcp add rag

或者手动添加自定义配置：

claude mcp add-json rag '{"command":"uvx","args":["rag-mcp-server","--knowledge-base","/path/to/your/docs","--embedding-model","all-MiniLM-L6-v2","--chunk-size","1000","--chunk-overlap","200"]}'

Cursor

根据需要安装Cursor
打开配置文件：打开Cursor，进入“Cursor设置”（不是正常的VSCode IDE设置），打开“MCP”标签页，点击“添加新的全局MCP服务器”按钮
按照下面的“设置MCP服务器”步骤操作

Cline

根据需要在IDE中安装Cline
打开配置文件：打开IDE，打开Cline侧边栏，点击顶部左侧第二个图标“MCP服务器”，打开“已安装”标签页，点击“配置MCP服务器”按钮
按照下面的“设置MCP服务器”步骤操作

Windsurf

根据需要安装Windsurf
打开配置文件：打开Windsurf，进入“Windsurf设置”（不是正常的VSCode IDE设置），打开“级联”标签页，在“模型上下文协议（MCP）服务器”部分点击“查看原始配置”按钮
按照下面的“设置MCP服务器”步骤操作

其他任何客户端

查找MCP设置文件，通常是类似[client]_mcp_config.json的文件
按照下面的“设置MCP服务器”步骤操作

设置MCP服务器

根据需要安装uv（uvx自带uv）

在您的MCP设置中添加以下内容：

基本配置：

{
  "mcpServers": {
    "rag": {
      "command": "uvx",
      "args": ["rag-mcp-server"]
    }
  }
}

包含所有参数的完整配置：

{
  "mcpServers": {
    "rag": {
      "command": "uvx",
      "args": [
        "rag-mcp-server",
        "--knowledge-base", "/path/to/your/documents",
        "--embedding-model", "ibm-granite/granite-embedding-278m-multilingual",
        "--chunk-size", "500",
        "--chunk-overlap", "200",
        "--top-k", "7",
        "--verbose"
      ]
    }
  }
}

变体：使用uvx的手动设置

如果您希望手动运行服务器或需要特定的Python版本：

# 使用默认设置运行
uvx rag-mcp-server

# 使用所有参数指定运行
uvx rag-mcp-server \
  --knowledge-base /path/to/documents \
  --embedding-model "ibm-granite/granite-embedding-278m-multilingual" \
  --chunk-size 500 \
  --chunk-overlap 200 \
  --top-k 7 \
  --verbose

# 从源目录运行
uvx --from . rag-mcp-server \
  --knowledge-base /home/user/documents \
  --embedding-model "all-MiniLM-L6-v2" \
  --chunk-size 800 \
  --chunk-overlap 100 \
  --top-k 5

使用示例

样本LLM查询

这里有一些示例查询，您可以使用这些查询与RAG服务器交互：

初始化具有自定义参数的知识库：

初始化知识库时使用：
- 知识库路径："/home/user/research_papers"
- 嵌入模型："ibm-granite/granite-embedding-278m-multilingual"
- 分块大小：300
- 分块重叠：50

使用特定参数搜索：

在知识库"/home/user/research_papers"中搜索"机器学习优化技术"，返回前10个结果及其相似度分数。

使用高质量嵌入初始化：

在"/data/technical_docs"处设置一个知识库，使用"all-mpnet-base-v2"模型，分块大小为1000，分块重叠为400，以更好地保留上下文。

刷新并获取统计信息：

刷新知识库"/home/user/documents"以包括任何新文件，然后显示包括总文档数、分块数和当前配置在内的统计信息。

列出和搜索文档：

列出知识库中的所有文档，然后搜索关于"API认证"的信息，并显示前5个最相关的分块。

复杂工作流程示例：

1. 在"/home/user/project_docs"处初始化一个知识库，使用嵌入模型"all-MiniLM-L6-v2"，分块大小800，分块重叠150
2. 显示统计信息
3. 搜索"数据库优化策略"
4. 列出所有已处理的文档

多语言搜索示例：

在"/docs/international"处初始化知识库，使用多语言模型"ibm-granite/granite-embedding-278m-multilingual"，然后搜索"机器学习"，并在多种语言中显示前7个结果。

命令行示例

研究用的高质量配置：

uvx rag-mcp-server \
  --knowledge-base /home/tommasomariaungetti/RAG \
  --embedding-model "all-mpnet-base-v2" \
  --chunk-size 1000 \
  --chunk-overlap 400 \
  --top-k 10 \
  --verbose

大型文档集的快速处理：

uvx rag-mcp-server \
  --knowledge-base /data/large_corpus \
  --embedding-model "all-MiniLM-L6-v2" \
  --chunk-size 2000 \
  --chunk-overlap 100 \
  --top-k 5

多语言文档处理：

uvx rag-mcp-server \
  --knowledge-base /docs/multilingual \
  --embedding-model "ibm-granite/granite-embedding-278m-multilingual" \
  --chunk-size 500 \
  --chunk-overlap 200 \
  --top-k 7

使用自定义设置从源运行：

uvx --from . rag-mcp-server \
  --embedding-model "all-MiniLM-L6-v2" \
  --chunk-size 800 \
  --chunk-overlap 100 \
  --top-k 5 \
  --knowledge-base /home/tommasomariaungetti/RAG

MCP工具

以下工具可用：

1. 初始化知识库

从文档目录初始化知识库。

参数：

knowledge_base_path（可选）：文档目录路径，默认为服务器配置
embedding_model（可选）：嵌入模型名称，默认为"ibm-granite/granite-embedding-278m-multilingual"
chunk_size（可选）：最大分块大小（字符数），默认为500
chunk_overlap（可选）：分块重叠大小（字符数），默认为200

示例工具调用：

{
  "tool": "initialize_knowledge_base",
  "arguments": {
    "knowledge_base_path": "/path/to/docs",
    "embedding_model": "all-mpnet-base-v2",
    "chunk_size": 1000,
    "chunk_overlap": 200
  }
}

示例LLM查询：

"从/home/user/documents初始化知识库，使用all-mpnet-base-v2嵌入模型，分块大小为1000字符，重叠为200字符"

2. 语义搜索

在知识库上执行语义搜索。

参数：

query：搜索查询文本
knowledge_base_path（可选）：知识库路径，默认为当前KB
top_k（可选）：要返回的结果数量，默认为7
include_scores（可选）：是否包含相似度分数，默认为false

示例工具调用：

{
  "tool": "semantic_search",
  "arguments": {
    "query": "如何实现RAG系统？",
    "knowledge_base_path": "/path/to/docs",
    "top_k": 5,
    "include_scores": true
  }
}

示例LLM查询：

"搜索'machine learning optimization techniques'，并显示前5个结果及其相似度分数"

3. 更新知识库

更新知识库以包含新文件或更改过的文件。

参数：

knowledge_base_path（可选）：知识库路径，默认为当前KB

示例工具调用：

{
  "tool": "refresh_knowledge_base",
  "arguments": {
    "knowledge_base_path": "/path/to/docs"
  }
}

示例LLM查询：

"刷新知识库以包含任何新文件或修改过的文件"

4. 获取知识库统计信息

获取有关知识库的详细统计信息。

参数：

knowledge_base_path（可选）：知识库路径，默认为当前KB

示例工具调用：

{
  "tool": "get_knowledge_base_stats",
  "arguments": {
    "knowledge_base_path": "/path/to/docs"
  }
}

示例LLM查询：

"显示知识库的统计信息，包括文档数量、分块信息和当前配置"

5. 列出文档

列出知识库中的所有文档及其元数据。

参数：

knowledge_base_path（可选）：知识库路径，默认为当前KB

示例工具调用：

{
  "tool": "list_documents",
  "arguments": {
    "knowledge_base_path": "/path/to/docs"
  }
}

示例LLM查询：

"列出知识库中的所有文档及其分块数量和元数据"

技术细节

文档处理

系统使用复杂的文档处理流水线：

文件检测：扫描目录以查找支持的文件类型
内容提取：
- 纯文本文件：直接读取UTF-8/Latin-1
- PDF文件：基于PyMuPDF的文本提取
文本分块：
- 将文档分割成可管理的块
- 保留词边界
- 通过可配置的重叠来维持上下文

嵌入生成

默认模型：ibm-granite/granite-embedding-278m-multilingual
批量处理：对大量文档集进行高效的批量编码
备用支持：如果主要模型失败，则自动回退到all-MiniLM-L6-v2
进度跟踪：大型操作的可视化进度条

向量搜索

索引类型：FAISS IndexFlatIP（内积）
相似度度量：余弦相似度（通过L2归一化）
性能：扩展到数百万文档
准确性：精确的最近邻搜索

文档存储

存储：SQLite数据库
跟踪：文件哈希值、修改时间、分块数量
增量更新：仅处理更改过的文件
位置：存储在知识库文档旁边

配置示例

MCP客户端配置

基本配置（Claude Desktop/Cursor/Cline）：

{
  "mcpServers": {
    "rag": {
      "command": "uvx",
      "args": ["rag-mcp-server"]
    }
  }
}

包含所有参数的完整配置：

{
  "mcpServers": {
    "rag": {
      "command": "uvx",
      "args": [
        "rag-mcp-server",
        "--knowledge-base", "/path/to/documents",
        "--embedding-model", "ibm-granite/granite-embedding-278m-multilingual",
        "--chunk-size", "500",
        "--chunk-overlap", "200",
        "--top-k", "7",
        "--verbose"
      ]
    }
  }
}

多个知识库配置：

{
  "mcpServers": {
    "rag-technical": {
      "command": "uvx",
      "args": [
        "rag-mcp-server",
        "--knowledge-base", "/docs/technical",
        "--embedding-model", "all-mpnet-base-v2",
        "--chunk-size", "1000",
        "--chunk-overlap", "400"
      ]
    },
    "rag-research": {
      "command": "uvx",
      "args": [
        "rag-mcp-server",
        "--knowledge-base", "/docs/research",
        "--embedding-model", "all-MiniLM-L6-v2",
        "--chunk-size", "500",
        "--chunk-overlap", "100",
        "--port", "8001"
      ]
    }
  }
}

命令行示例

研究用的高质量配置：

uvx rag-mcp-server \
  --knowledge-base /path/to/research/docs \
  --embedding-model "all-mpnet-base-v2" \
  --chunk-size 1000 \
  --chunk-overlap 400 \
  --top-k 10

快速处理配置：

uvx rag-mcp-server \
  --knowledge-base /path/to/large/corpus \
  --embedding-model "all-MiniLM-L6-v2" \
  --chunk-size 2000 \
  --chunk-overlap 100 \
  --top-k 5

多语言配置：

uvx rag-mcp-server