RAGMap MCP

RAGMap MCP（本地）

只需几秒，即可查找并筛选支持 RAG 的 MCP 服务。此软件包是连接到托管版 RAGMap 子注册表 API 的本地 stdio MCP 桥接程序。

团队选择它的原因

• 无需编写胶水代码：通过 npx 运行，使用 MCP，即可完成。
• 以 Agent 为先：工具契约简洁稳定，输出可预测。
• 开箱即用，适用于生产环境：默认连接托管 API。
• 只读：无需密钥。

你将获得

• 主要用途：为 Claude Desktop、Cursor 和任何 MCP 主机提供 MCP stdio 传输。
• 工具：rag_find_servers、rag_get_server、rag_list_categories、rag_explain_score。

**面向 Agent（零配置）：**使用 GET https://ragmap-api.web.app/.well-known/agent.json 进行发现；使用 apiEndpoints 调用 REST API，或使用 mcpInstall 运行此软件包。请参阅仓库中的 AGENT-USAGE.md。

---

MapRag（RAGMap）

MapRag 是用于检索的发现与路由层。 它会索引支持 RAG 的 MCP 服务，为其补充结构化元数据，并帮助**Agent（以及人类）**在引用、新鲜度、隐私、领域和延迟等约束条件下，快速找到适合任务的检索服务。

MapRag 本身不执行 RAG。 它帮助你选择最适合执行检索的 RAG 工具/服务。

状态（v1.0）

• 以只读方式导入官方 MCP Registry，并为检索用例补充服务记录信息。
• API 启用嵌入功能（OpenAI 密钥）时，支持语义搜索和关键词搜索；否则仅支持关键词搜索。
• 补充信息：categories、ragScore、reasons、hasRemote，以及远程传输的可达性元数据。
• 筛选条件：query、categories、minScore、transport、registryType、hasRemote、reachable 和 reachableMaxAgeHours。
• 提供两种可编程接口：兼容注册表的 REST API（子注册表）+ MCP 服务（远程 HTTP + 本地 stdio）。

路线图

• 更丰富的能力模型（领域、依据/引用、新鲜度、隐私/数据驻留、身份验证、限制）。
• 信任信号（可达性、架构稳定性、延迟/正常运行时间）。
• 用于浏览/筛选/比较服务的人类用户界面。

完整概览：https://github.com/khalidsaidi/ragmap/blob/main/docs/OVERVIEW.md

架构（概览）

---

快速开始（60 秒）

MCP_AGENT_NAME=local-test \
npx -y @khalidsaidi/ragmap-mcp@latest

默认情况下，它使用托管 API 基址 https://ragmap-api.web.app。

用于本地开发：

RAGMAP_API_BASE_URL=http://localhost:3000 \
npx -y @khalidsaidi/ragmap-mcp@latest

安装（可选）

如果你更喜欢全局安装：

npm i -g @khalidsaidi/ragmap-mcp
ragmap-mcp

冒烟测试（一条命令）

printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"0.1","capabilities":{},"clientInfo":{"name":"quick","version":"0.0.1"}}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
'{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"rag_find_servers","arguments":{"query":"rag","limit":3}}}' \
| npx -y @khalidsaidi/ragmap-mcp@latest

---

Claude Desktop 配置

{
  "mcpServers": {
    "ragmap": {
      "command": "npx",
      "args": ["-y", "@khalidsaidi/ragmap-mcp@latest"],
      "env": {
        "MCP_AGENT_NAME": "claude-desktop",
        "RAGMAP_API_BASE_URL": "https://ragmap-api.web.app"
      }
    }
  }
}

---

远程 MCP（无需安装）

如果你更喜欢通过可流式传输的 HTTP 使用 MCP（无需本地安装），请使用托管端点：

claude mcp add --transport http ragmap https://ragmap-api.web.app/mcp

---

工具

• rag_find_servers - 搜索/筛选支持 RAG 的 MCP 服务
• rag_get_server - 按名称获取服务记录（最新版本）
• rag_list_categories - 列出已知的 RAG 类别
• rag_explain_score - 说明某项服务的 RAG 评分

说明：

• 工具响应以 JSON 文本形式返回（因此任何 MCP 主机都可以原样显示）。
• 筛选由 RAGMap API 在服务端执行。

工具调用示例

• 查找看起来适合 RAG 的远程（streamable-http）服务：rag_find_servers({ query: "rag", minScore: 30, transport: "streamable-http", hasRemote: "true", limit: 10 })
• 查找通过特定注册表类型发布的服务：rag_find_servers({ query: "qdrant", registryType: "pypi" })
• 列出类别：rag_list_categories({})
• 获取 RAGMap 自身的记录或说明其评分（使用已发布的注册表名称）：rag_get_server({ name: "io.github.khalidsaidi/ragmap" })、rag_explain_score({ name: "io.github.khalidsaidi/ragmap" })

示例：“注重隐私、带引用的文档 RAG”

这是 MapRag 专为此类查询设计的用例。目前，你可以通过类别和传输筛选条件近似实现：

{
  "tool": "rag_find_servers",
  "input": {
    "query": "docs rag citations",
    "categories": ["documents"],
    "minScore": 30,
    "transport": "stdio",
    "hasRemote": "true",
    "limit": 5
  }
}

---

环境变量

变量	必填	说明
RAGMAP_API_BASE_URL	否	REST API 基础 URL（默认值：https://ragmap-api.web.app）
API_BASE_URL	否	RAGMAP_API_BASE_URL 的别名
MCP_AGENT_NAME	否	客户端标识符（作为 X-Agent-Name 添加到 API 调用中）
SERVICE_VERSION	否	向 MCP 主机报告的版本字符串

---

故障排查（快速指南）

• 没有结果
  • 尝试更宽泛的查询，例如 rag、retrieval、vector、qdrant。
  • 调低 minScore，或省略该参数。
• 连接错误
  • 确认你的环境可以访问 RAGMAP_API_BASE_URL。
  • 对于托管 API，尝试在浏览器中打开 https://ragmap-api.web.app/health。

---

链接

• 文档/OpenAPI：https://ragmap-api.web.app/docs
• Agent 卡片：https://ragmap-api.web.app/.well-known/agent.json
• MCP 远程服务（HTTP）：https://ragmap-api.web.app/mcp
• 代码库：https://github.com/khalidsaidi/ragmap