使用说明

RAG MCP服务器

RAG MCP Server

用于检索增强生成（RAG）操作的模型上下文协议（MCP）服务器。该服务器提供用于从文档集合中构建和查询基于向量的知识库的工具，从而实现语义搜索和文档检索功能。

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

特性

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

建筑

rag-mcp-server/
├── src/rag_mcp_server/
│   ├── server.py              # Main MCP server implementation
│   └── core/
│       ├── document_processor.py  # Document loading and chunking
│       ├── embedding_service.py   # Text embedding generation
│       ├── faiss_index.py        # Vector similarity search
│       └── document_store.py     # Document metadata storage

安装

使用uvx（推荐）

# Install with uvx (comes with 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应用程序，进入其设置，打开“开发人员”选项卡，然后单击“编辑配置”按钮，打开配置文件
按照以下“设置MCP服务器”步骤进行操作

克劳德代码

安装克劳德代码根据需要

运行以下命令以添加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 Settings”（不是正常的VSCode IDE设置），打开“MCP”选项卡，然后单击“Add new global MCP server”按钮，打开配置文件
按照以下“设置MCP服务器”步骤进行操作

克莱恩

安装Cline 根据需要在IDE中
打开IDE，打开Cline侧栏，单击顶部左起第二个“MCP服务器”图标按钮，打开“已安装”选项卡，然后单击“配置MCP服务器”按钮，打开配置文件
按照以下“设置MCP服务器”步骤进行操作

帆板运动

安装挡风玻璃根据需要
打开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版本：

# Run with default settings
uvx rag-mcp-server

# Run with all parameters specified
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

# Run from source directory
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查询示例

以下是您可以使用LLM与RAG服务器交互的示例查询：

使用自定义参数初始化知识库：

Initialize the knowledge base with:
- knowledge_base_path: "/home/user/research_papers"
- embedding_model: "ibm-granite/granite-embedding-278m-multilingual"
- chunk_size: 300
- chunk_overlap: 50

使用特定参数搜索：

Search for "machine learning optimization techniques" in the knowledge base at "/home/user/research_papers" and return the top 10 results with similarity scores.

使用高质量的嵌入进行初始化：

Set up a knowledge base at "/data/technical_docs" using the "all-mpnet-base-v2" model with chunk_size of 1000 and chunk_overlap of 400 for better context preservation.

刷新并获取统计数据：

Refresh the knowledge base at "/home/user/documents" to include any new files, then show me the statistics including total documents, chunks, and current configuration.

列出和搜索文档：

List all documents in the knowledge base, then search for information about "API authentication" and show me the top 5 most relevant chunks.

复杂工作流示例：

1. Initialize a knowledge base at "/home/user/project_docs" with embedding_model "all-MiniLM-L6-v2", chunk_size 800, and chunk_overlap 150
2. Show me the statistics
3. Search for "database optimization strategies"
4. List all documents that were processed

多语言搜索示例：

Initialize the knowledge base at "/docs/international" using the multilingual model "ibm-granite/granite-embedding-278m-multilingual", then search for "machine learning" in multiple languages and show the top 7 results.

命令行示例

高质量的研究配置：

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-multilanguage”
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查询示例：

“使用具有1000个字符块和200个字符重叠的全mpnet-base-v2嵌入模型从/home/user/documents初始化知识库”

2.语义研究

对知识库进行语义搜索。

参数：

query：搜索查询文本
knowledge_base_path （可选）：知识库路径-默认为当前KB
top_k （可选）：要返回的结果数-默认为7
include_scores （可选）：包括相似性得分-默认为false

工具调用示例：

{
  "tool": "semantic_search",
  "arguments": {
    "query": "How to implement RAG systems?",
    "knowledge_base_path": "/path/to/docs",
    "top_k": 5,
    "include_scores": true
  }
}

LLM查询示例：

“搜索‘机器学习优化技术’，并向我展示具有相似性得分的前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指数FlatIP（内部产品）
相似性度量：余弦相似度（通过L2归一化）
演出：可扩展到数百万份文档
准确度：精确最近邻搜索

文档存储

存储：SQLite数据库
追踪：文件哈希、修改时间、块计数
增量更新：仅处理更改的文件
位置：与知识库文档一起存储

配置示例

MCP客户端配置

基本配置（克劳德桌面/光标/鼠标）：

{
  "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 \
  --knowledge-base /path/to/multilingual/docs \
  --embedding-model "ibm-granite/granite-embedding-278m-multilingual" \
  --chunk-size 500 \
  --chunk-overlap 200 \
  --top-k 7

详细日志记录的开发配置：

uvx --from . rag-mcp-server \
  --knowledge-base ./test_documents \
  --embedding-model "all-MiniLM-L6-v2" \
  --chunk-size 300 \
  --chunk-overlap 50 \
  --top-k 3 \
  --verbose

错误处理

服务器实现了全面的错误处理：

文件访问错误：妥善处理许可问题
编码错误：自动编码检测和回退
模型加载错误：回退到默认模型
数据库错误：事务回滚和恢复
搜索错误：信息性错误消息

性能注意事项

内存使用

嵌入内容存储在内存中，以便快速搜索
大致内存： num_chunks × embedding_dimension × 4 bytes
示例：10000个块×384个维度≈15 MB

处理速度

文档处理：约100-500个文档/分钟（取决于大小）
嵌入生成：~50-200块/秒（取决于模型）
搜索延迟：对于10万个文档，搜索延迟<10ms

优化提示

使用较小的嵌入模型以加快处理速度
增加块大小以减少块数量（可能会降低准确性）
减少重叠以加快处理速度（可能会丢失上下文）
将SSD存储用于文档存储数据库

发展

运行测试

pytest tests/

代码格式化

black src/
isort src/

类型检查

mypy src/

故障排除

常见问题

“未提供知识库路径”
- 解决方案：在工具调用中提供路径或使用 --knowledge-base 旗帜
“检测到型号不匹配”
- 解决方案：这是一个警告；系统将使用最接近的可用模型
“初始化嵌入模型失败”
- 解决方案：检查互联网连接或使用本地缓存模型
“在知识库中找不到文档”
- 解决方案：确保目录包含.txt或.pdf文件

调试模式

启用详细日志记录以进行故障排除：

uvx rag-mcp-server --verbose

帮助和资源

贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支
添加新功能的测试
确保所有测试通过
提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

致谢

建立在 MCP（模型上下文协议）
由...驱动句子转换
矢量搜索费斯
PDF处理方式 PyMuPDF

使用说明

RAG MCP服务器

RAG MCP Server

特性

建筑

安装

使用uvx（推荐）

使用pip

来源

设置

查找客户端的MCP设置文件

克劳德桌面

克劳德代码

光标

克莱恩

帆板运动

任何其他客户

设置MCP服务器

变体：使用uvx手动设置

使用示例

LLM查询示例

命令行示例

MCP工具

1.初始化知识库

2.语义研究

3.刷新知识库

4.获取知识库状态

5.列表_文件

技术细节

文档处理

嵌入生成

矢量搜索

文档存储

配置示例

MCP客户端配置

命令行示例

错误处理

性能注意事项

内存使用

处理速度

优化提示

发展

运行测试

代码格式化

类型检查

故障排除

常见问题

调试模式

帮助和资源

贡献

许可证

致谢

相关 MCP

PowerPoint操作服务器

AI持久记忆服务器

Markdown转换服务器

Zotero文献库搜索与阅读MCP服务

Qdrant向量搜索MCP服务器

本地LLM模型控制协议