Ragmap

RAGMap（RAG MCP 注册表查找器）

试用： https://ragmap-api.web.app/browse/ 从这里开始： https://github.com/khalidsaidi/ragmap/discussions/17

RAGMap 是一个轻量级、兼容 MCP Registry 的子注册表和 MCP 服务，专注于与 RAG 相关的 MCP 服务。

它可以：

• 接入官方 MCP Registry，为 RAG 用例丰富记录，并提供子注册表 API。
• 提供 MCP 服务（远程 Streamable HTTP + 本地 stdio），让 Agent 能够搜索和筛选 RAG MCP 服务。

MapRag（RAGMap）

MapRag 是用于检索的发现和路由层。 它帮助 Agent 和用户回答：在当前约束条件下，这项任务应该使用哪个检索 MCP 服务？

RAGMap 不会自行执行检索。它会为支持检索的服务建立索引并丰富其信息，然后将你路由到合适的工具/服务。

安装后你会获得什么（通俗版）

• 你会获得发现/路由工具（rag_find_servers、rag_get_server、rag_list_categories、rag_explain_score）。
• RAGMap 可帮助你根据任务和约束条件找到最合适的检索服务。
• 随后，你的 Agent 会连接到所选服务来执行实际检索。

RAGMap 不会：

• 自动接入你的私有文档。
• 托管你的个人向量数据库。
• 替代你的端到端 RAG 流水线。

如果你需要检索自己的数据，请使用 RAGMap 搜索结果中的检索服务（或你自己的服务），并确保它支持你的接入/索引流程。

数据新鲜度与接入

• 托管版 RAGMap 会按计划更新索引。新发布或有更改的服务可能会延迟一段时间才显示。
• 使用托管服务时，大多数用户无需自行运行数据接入。
• 如果你需要更严格地控制数据新鲜度或采用私有索引方式，请自行托管并运行自己的数据接入计划（docs/DEPLOYMENT.md）。

功能：兼容 Registry 的 API；语义搜索 + 关键词搜索（设置 OPENAI_API_KEY 后可用，例如通过环境变量或部署所用的密钥管理器设置）；分类和 ragScore；可按 hasRemote、reachable（通过探测检查 streamable-http/SSE）、citations、localOnly、transport、minScore、categories 筛选。提供面向用户的浏览界面，支持搜索、筛选，以及复制 Cursor/Claude 配置。MCP 工具：rag_find_servers、rag_get_server、rag_list_categories、rag_explain_score。

快速开始

要求：curl 和 jq

1) 可访问的顶级检索服务（24 小时内检查过）

curl -s "https://ragmap-api.web.app/rag/top?hasRemote=true&reachable=true&reachableMaxAgeHours=24&serverKind=retriever&limit=25" | jq .

2) 使用可信度筛选器搜索（近期可访问）

curl -s "https://ragmap-api.web.app/rag/search?q=rag&hasRemote=true&reachable=true&reachableMaxAgeHours=24&limit=10" | jq .

3) 获取服务的安装配置

提示：名称包含 / 时，请对其进行 URL 编码。

curl -s "https://ragmap-api.web.app/rag/install?name=ai.filegraph%2Fdocument-processing" | jq .

4) 检查数据新鲜度和覆盖范围

curl -s "https://ragmap-api.web.app/rag/stats" | jq .

5) 使用情况遥测摘要

curl -s "https://ragmap-api.web.app/api/stats" | jq .

完整概览：docs/OVERVIEW.md
发布历史：CHANGELOG.md

架构

%%{init: {"theme":"base","themeVariables":{"primaryColor":"#ffffff","primaryTextColor":"#000000","primaryBorderColor":"#000000","lineColor":"#000000","secondaryColor":"#ffffff","tertiaryColor":"#ffffff","clusterBkg":"#ffffff","clusterBorder":"#000000","edgeLabelBackground":"#ffffff"},"flowchart":{"curve":"linear","nodeSpacing":75,"rankSpacing":70}}}%%
flowchart TB
  %% Concept-only diagram (product value; no deployment/framework/datastore details)

  classDef mono fill:#ffffff,stroke:#000000,color:#000000,stroke-width:1px;

  subgraph Inputs[" "]
    direction LR

    subgraph Query["Agent-native interface"]
      direction TB
      Users["Agents + humans"]:::mono
      subgraph Tooling["Tool call"]
        direction LR
        Criteria["Routing constraints<br/>domain, privacy, citations,<br/>freshness, auth, limits"]:::mono
        Tools["MCP tools<br/>rag_find_servers<br/>rag_get_server<br/>rag_list_categories<br/>rag_explain_score"]:::mono
      end
      Users --> Criteria --> Tools
    end

    subgraph Subregistry["Subregistry (read-only)"]
      direction TB
      subgraph Ingest["Ingest"]
        direction LR
        Sources["Upstream MCP registries<br/>(official + optional)"]:::mono
        Sync["Sync + normalize<br/>(stable schema)"]:::mono
        Catalog["Enriched catalog<br/>(servers + versions)"]:::mono
        Sources --> Sync --> Catalog
      end

      subgraph Enrich["Enrich (adds value)"]
        direction LR
        Cap["Structured metadata<br/>domain: docs|code|web|mixed<br/>retrieval: dense|sparse|hybrid (+rerank)<br/>freshness: static|continuous (max lag)<br/>grounding: citations|provenance<br/>privacy/auth: local|remote + req|optional<br/>limits: top_k|rate|max ctx"]:::mono
        Trust["Trust signals (lightweight)<br/>status, reachability,<br/>schema stability, reports"]:::mono
      end

      Catalog --> Cap
      Catalog --> Trust
    end
  end

  subgraph Selection["Selection (the added value)"]
    direction LR
    Router["Router<br/>match + rank + explain"]:::mono
    Ranked["Ranked candidates<br/>+ reasons + connect info"]:::mono
    Retrieval["Chosen retrieval MCP server(s)<br/>(do retrieval)"]:::mono
    Router --> Ranked --> Retrieval
  end

  Tools --> Router
  Catalog --> Router

  %% Keep the layout without adding a third visible "box" around Inputs.
  style Inputs fill:#ffffff,stroke:#ffffff,stroke-width:0px

Monorepo 目录结构

• apps/api：REST API + 兼容 MCP registry 的端点 + 数据接入工作进程
• apps/mcp-remote：远程 MCP 服务（Streamable HTTP）
• packages/mcp-local：本地 MCP 服务（stdio）
• packages/shared：Zod 模式 + 共享类型
• docs：文档 + Firebase Hosting 静态资源

本地开发

cp .env.example .env
corepack enable
pnpm -r install
pnpm -r dev

可选：在 .env 中设置 OPENAI_API_KEY（参见 .env.example），以便在本地启用语义搜索；GET /health 将显示 "embeddings": true。

API：http://localhost:3000 MCP 远程服务：http://localhost:4000/mcp

导入

curl -X POST http://localhost:3000/internal/ingest/run \
  -H "Content-Type: application/json" \
  -H "X-Ingest-Token: $INGEST_TOKEN" \
  -d '{"mode":"full"}'

MCP 用法

远程（Streamable HTTP）：

claude mcp add --transport http ragmap https://<your-mcp-domain>/mcp

本地（stdio，npm）：

npx -y @khalidsaidi/ragmap-mcp@latest

本地（stdio）：

pnpm -C packages/mcp-local dev

主要端点

• GET /embed — 可嵌入的“搜索 RAG MCP 服务”小组件（iframe；查询参数：q、limit）
• GET /health（启用或关闭语义搜索时，分别包含 embeddings: true|false）
• GET /readyz
• GET /v0.1/servers
• GET /v0.1/servers/:serverName/versions
• GET /v0.1/servers/:serverName/versions/:version（支持 latest）
• GET /rag/search
• GET /rag/top（默认排序的推荐；limit 最大为 50）
• GET /rag/install
• GET /rag/stats
• GET /rag/categories
• GET /api/stats（公开使用情况汇总；不含个人身份信息）
• GET /api/usage-graph（使用情况的 HTML 图表）
• POST /internal/ingest/run（受保护）

对于托管服务 ragmap-api.web.app，/internal/* 路由不会公开。

GET /rag/search 查询参数：

• q（字符串）
• categories（逗号分隔）
• minScore（0-100）
• transport（stdio 或 streamable-http）
• registryType（字符串）
• hasRemote（true 或 false — 仅包含具有远程端点的服务）
• reachable（true — 仅包含近期通过 streamable-http/SSE 探测确认可访问的服务）
• reachableMaxAgeHours（可选，仅在 reachable=true 时使用 — 仅保留 N 小时内检查过的结果）
• citations（true — 仅包含在元数据中提及引用/依据的服务）
• localOnly（true — 仅包含 stdio，不含远程服务）

冒烟测试

API_BASE_URL=https://ragmap-api.web.app ./scripts/smoke-public.sh
MCP_URL=https://ragmap-api.web.app/mcp ./scripts/smoke-mcp.sh

文档

• docs/DISCOVERY-LINK-CONVENTION.md — 在 server.json 中可选添加 discoveryService，以便客户端显示“发现更多”
• docs/AGENT-USAGE.md — **面向 Agent：**发现、REST API、MCP 安装（无需人工干预）
• docs/DEPLOYMENT.md
• docs/OVERVIEW.md
• docs/DATA_MODEL.md
• docs/PRIVACY.md
• docs/PUBLISHING.md
• docs/GLAMA-CHECKLIST.md
• docs/GLAMA-DOCKERFILE.md
• scripts/glama-score-status.sh — 打印公开的 Glama 评分标记（可检查/发布/使用情况）