企业官网建设流程全解析

R2R 检索系统的 MCP 服务器接入指南：让 Claude Desktop 直连向量检索、知识图谱与 RAG

【免费下载链接】R2RSoTA production-ready AI retrieval system. Agentic Retrieval-Augmented Generation (RAG) with a RESTful API.项目地址: https://gitcode.com/GitHub_Trending/r2/R2R

R2R（Retrieval-Augmented Generation）项目将自身定位为基于 Model Context Protocol（MCP）的检索服务器，为 Claude 等 AI 客户端提供知识库检索能力。本文以 docs/cookbooks/mcp.md 为主线，结合 py/r2r/mcp.py 源码与 Python SDK 实现，完整讲解 MCP 服务器的安装、Claude Desktop 配置、search / rag 两个核心工具的用法、返回结果格式以及底层调用链，帮助你在一小时内把本地或云端 R2R 服务接入 Claude，用自然语言完成向量搜索、图谱搜索、Web 搜索与文档搜索。

MCP 是什么，R2R 如何扮演 MCP 服务器

Model Context Protocol（MCP）是 AI 客户端（如 Claude Desktop）与外部工具/数据源之间的标准化通信协议。一个 MCP 服务器对外暴露一组可被大模型调用的"工具"（tool），客户端负责把这些工具的能力交给模型决策。

R2R 的 MCP 服务器封装在 py/r2r/mcp.py 中。该文件基于官方mcpPython 包提供的FastMCP构建，启动后即注册一个名为R2R Retrieval System的 MCP 服务器：

# 来自 py/r2r/mcp.py try: from mcp.server.fastmcp import FastMCP mcp = FastMCP("R2R Retrieval System") except Exception as e: raise ImportError( "MCP is not installed. Please run `pip install mcp`" ) from e # Pass lifespan to server mcp = FastMCP("R2R Retrieval System")

从源码结构可以看到，服务器注册了search与rag两个异步工具，它们内部通过 R2R 官方 Python SDK 的R2RClient调用 REST API。因此，MCP 服务器本身不持有数据，它是"Claude ↔ R2R API"之间的适配层：Claude 说"帮我检索"，MCP 工具负责把检索请求转发给 R2R 服务并格式化返回。

核心能力一览

MCP 服务器为 Claude 提供以下五类检索能力（对应 docs/cookbooks/mcp.md 的 Features 章节）：

• Vector Search（向量搜索）：基于语义相似度查找最相关的文本分块（chunk）。
• Graph Search（图谱搜索）：在知识图谱中探索实体、关系与社区之间的关联。
• Web Search（Web 搜索）：从在线来源检索信息。
• Document Search（文档搜索）：访问并查询本地上下文的文档。
• RAG（检索增强生成）：基于检索到的上下文生成答案。

这些能力并非 MCP 层凭空实现，而是对应 R2R v3 API 中AggregateSearchResult的多个检索通道。在 py/shared/abstractions/search.py 中可以看到聚合结果的数据结构，它同时承载五类结果：

class AggregateSearchResult(R2RSerializable): chunk_search_results: Optional[list[ChunkSearchResult]] = None graph_search_results: Optional[list[GraphSearchResult]] = None web_page_search_results: Optional[list[WebPageSearchResult]] = None web_search_results: Optional[list[WebSearchResult]] = None document_search_results: Optional[list[DocumentResponse]] = None

环境准备（Prerequisites）

接入前需要准备以下环境：

安装方式：本地安装与云端安装

本地安装

在本地机器上执行两条命令：先安装mcp包，再通过mcp install命令把 R2R 的 MCP 服务器注册到客户端：

pip install mcp mcp install r2r/mcp.py -v R2R_API_URL=http://localhost:7272

• -v用于向服务器进程注入环境变量（-v KEY=VALUE格式）。
• R2R_API_URL指定 R2R API 的地址。默认端口7272与 SDK 的默认值一致（见下文"底层调用链"）。
• 执行前请确认本地 R2R API 服务已在指定 URL 上启动，否则后续检索会失败。

命令中的r2r/mcp.py对应仓库 py/r2r/mcp.py，请替换为克隆到本机后的实际绝对路径（如/my/path/to/R2R/py/r2r/mcp.py）。

云端安装

使用云端部署的 R2R 服务时，把 URL 换成 API Key 即可：

pip install mcp mcp install r2r/mcp.py -v R2R_API_KEY=your_api_key_here

API Key 的传递方式与 SDK 完全一致：在 py/sdk/base/base_client.py 中，R2RClient会读取环境变量R2R_API_KEY作为请求凭据，并通过x-api-key请求头发送给服务端（见 py/sdk/base/base_client.py）。因此 MCP 服务器进程只要继承了该环境变量，SDK 就能自动带上鉴权头。

手动添加到 Claude Desktop（备用方案）

文档明确说明：只有当pip install方式失败时才需要手动配置，大多数情况下上面的安装命令已足够让 R2R 服务器被 Claude 识别。如果确实需要手动配置：

1. 打开 Claude Desktop，进入 Settings：
   • macOS：点击 Claude 菜单 → "Settings..."
   • Windows：点击 Claude 菜单 → "Settings..."
2. 在 Settings 左侧栏点击 "Developer"，然后点击 "Edit Config"。
3. 在配置文件中加入 R2R 服务器条目：

{ "mcpServers": { "r2r": { "command": "mcp", "args": ["run", "/my/path/to/R2R/py/r2r/mcp.py"] } } }

4. 保存配置文件并重启 Claude Desktop。
5. 重启后，输入框右下角会出现锤子（hammer）图标，表示 MCP 工具已就绪。

手动配置的本质与mcp install相同：通过mcp run启动 py/r2r/mcp.py 脚本。若采用此方式，R2R 服务地址/API Key 需要额外通过环境变量注入到该进程（与-v参数等价）。py/r2r/mcp.py 的入口逻辑也支持直接执行：python r2r/mcp.py会调用mcp.run()启动服务器，便于先本地验证再接入客户端。

两个核心工具：search 与 rag

MCP 服务器对外提供两个主要工具（见 py/r2r/mcp.py）。

search：执行多源检索并返回格式化结果

@mcp.tool() async def search(query: str) -> str: """Performs a ...""" client = R2RClient() search_response = client.retrieval.search(query=query) return format_search_results_for_llm(search_response.results)

• 作用：跨向量、图谱、Web、文档四类来源执行检索，返回带Source ID的结构化文本。
• 入参：仅一个query字符串。
• 返回值：search_response.results是AggregateSearchResult，经format_search_results_for_llm格式化为适合大模型阅读的纯文本。

rag：检索增强生成

@mcp.tool() async def rag(query: str) -> str: """Perform a Retrieval-Augmented Generation query""" client = R2RClient() rag_response = client.retrieval.rag(query=query) return rag_response.results.generated_answer

• 作用：先检索相关上下文，再基于上下文生成连贯答案。
• 返回值：直接返回RAGResponse.generated_answer（即最终生成的回答文本，见 py/shared/api/models/retrieval/responses.py 中的generated_answer字段定义）。

在 Claude 中使用

配置完成后，Claude 会在适当时机自动调用这两个工具，你也可以用自然语言显式触发：

• 搜索：让 Claude 用特定查询检索知识库。例如："Search for information about vector databases in our documentation"。
• RAG：请求 Claude 基于检索上下文生成答案。例如："Use RAG to answer: What are the best practices for knowledge graph integration?"。

结果格式化：返回给大模型的结构化文本

format_search_results_for_llm（py/r2r/mcp.py）是 MCP 服务器中最重要的展示层逻辑。它把AggregateSearchResult按四类来源逐段输出，并且使用id_to_shorthand把完整 UUID 压缩为前 7 位短 ID：

def id_to_shorthand(id: str) -> str: return str(id)[:7]

各来源的格式化规则如下：

1. 向量搜索结果：输出Vector Search Results:标题，每个 chunk 输出Source ID [前7位ID]与text正文。
2. 图谱搜索结果：输出Graph Search Results:，并根据content的类型分支处理：
   • 社区（community）：输出Community Name、ID、Summary；
   • 实体（entity）：输出Entity Name、Description；
   • 关系（relationship）：输出Relationship: subject-predicate-object。
3. Web 搜索结果：输出Web Search Results:，逐条输出Title、Link、Snippet。
4. 本地上下文文档：输出Local Context Documents:，包含Full Document ID、Shortened Document ID、Document Title、Summary，若文档含分块，还会继续输出每个Chunk ID及其text。

示例输出

调用 search 工具后，Claude 收到的典型结果如下（来自 docs/cookbooks/mcp.md 的 Example Outputs 章节）：

Vector Search Results: Source ID [abc1234]: Text content from the vector search... Graph Search Results: Source ID [def5678]: Entity Name: Sample Entity Description: This is a description of the entity... Web Search Results: Source ID [ghi9012]: Title: Sample Web Page Link: https://example.com Snippet: A snippet from the web page... Local Context Documents: Full Document ID: jkl3456... Shortened Document ID: jkl3456 Document Title: Sample Document Summary: A summary of the document... Chunk ID abc1234: Text content from the document chunk...

短 ID 的设计非常实用：它既保留了可追溯性（abc1234可还原为完整 UUID），又大幅压缩了送入大模型上下文的 token 量，避免长 UUID 挤占上下文窗口。

底层调用链：MCP 工具如何驱动 R2R API

理解调用链有助于排查问题，也能帮你用同样的模式扩展新工具。整个链路如下：

Claude Desktop └─ mcp run py/r2r/mcp.py（FastMCP 服务器，注册 search / rag 工具） └─ R2RClient（py/sdk/sync_client.py） └─ RetrievalSDK.search() / .rag()（py/sdk/sync_methods/retrieval.py） └─ POST {base_url}/v3/retrieval/search 或 /v3/retrieval/rag └─ R2R API 服务（默认 http://localhost:7272）

关键实现细节：

• SDK 客户端：py/sdk/sync_client.py 中的R2RClient聚合了RetrievalSDK等子客户端，MCP 工具直接用client.retrieval.search()与client.retrieval.rag()。
• 端点：RetrievalSDK.search向v3/retrieval/search发送 POST，rag向v3/retrieval/rag发送 POST（见 py/sdk/sync_methods/retrieval.py 与 py/sdk/sync_methods/retrieval.py）。
• 服务地址与鉴权：R2RClient的默认地址来自环境变量R2R_API_BASE，缺省为http://localhost:7272（py/sdk/base/base_client.py）；R2R_API_KEY环境变量提供x-api-key鉴权。这就是mcp install ... -v注入变量的底层依据——文档中的R2R_API_URL与 SDK 的R2R_API_BASE本质都指向同一个 R2R API 地址，配置时请确保两者与实际服务端口一致。
• RAG 响应的取数：rag工具直接读取rag_response.results.generated_answer，而RAGResponse中还包含search_results（AggregateSearchResult）与citations结构化引用信息（py/shared/api/models/retrieval/responses.py）。当前 MCP 工具只返回最终答案，如需把引用来源一并暴露给 Claude，可以在此基础上扩展。

排查指南（Troubleshooting）

根据 docs/cookbooks/mcp.md 的 Troubleshooting 章节，常见问题与对策如下：

• 服务器没有出现在 Claude 中：检查 Claude Desktop 配置文件（claude_desktop_config.json）的 JSON 格式是否正确，mcpServers条目是否完整。
• 本地安装检索失败：确认 R2R API 服务确实在指定的 URL 上运行。默认地址是http://localhost:7272，可用curl http://localhost:7272/v3/system/health类请求自测（具体健康检查端点以 py/core/main/api/v3/system_router.py 为准）。
• 云端安装鉴权失败：验证 API Key 是否有效，并确认-v R2R_API_KEY=...已正确注入到 MCP 服务器进程的环境变量。
• 仍有异常：查看 Claude Desktop 的日志输出，定位是 MCP 连接问题还是 R2R API 返回的 4xx/5xx 错误。

进一步扩展

• 探索更多 MCP 服务器：将 R2R 与其它 MCP 服务器组合，让 Claude 获得更丰富的工具集。
• 自定义工具：py/r2r/mcp.py 中每个工具只是@mcp.tool()装饰的一个异步函数。你可以照此模式新增工具，例如暴露client.retrieval.agent()（对话式 Agent）、client.documents的文档管理能力，或让rag工具额外返回citations结构化引用——所有能力都已在 py/sdk/sync_methods 中封装好，无需直接拼接 HTTP 请求。
• 参与社区共建：分享你的接入经验与使用案例。

需要特别说明的是，R2R 的 MCP 服务器是一个"薄适配层"，它把 R2R 完整的检索体系（向量、图谱、Web、文档、RAG）以标准化的工具形式交付给 Claude。要真正发挥它的价值，还需先通过 R2R 的 ingestion 流程把文档灌入知识库、配置好 embedding 与 LLM（参考 py/core/configs/full.toml），并保证 R2R API 服务可用——MCP 接入本身只是打通"最后一公里"。

【免费下载链接】R2RSoTA production-ready AI retrieval system. Agentic Retrieval-Augmented Generation (RAG) with a RESTful API.项目地址: https://gitcode.com/GitHub_Trending/r2/R2R