RAGMap (RAG MCP Registry Finder)

Try it: https://ragmap-api.web.app/browse/

Start here: https://github.com/khalidsaidi/ragmap/discussions/17

RAGMap is a lightweight MCP Registry-compatible subregistry + MCP server focused on RAG-related MCP servers.

It:

• Ingests the official MCP Registry, enriches records for RAG use-cases, and serves a subregistry API.
• Exposes an MCP server (remote Streamable HTTP + local stdio) so agents can search/filter RAG MCP servers.

MapRag (RAGMap)

MapRag is a discovery + routing layer for retrieval.

It helps agents and humans answer: *which retrieval MCP server should I use for this task, given my constraints?*

RAGMap does not do retrieval itself. It indexes and enriches retrieval-capable servers, then routes you to the right tool/server.

What you get after install (plain English)

• You get discovery/routing tools (`rag_find_servers`, `rag_get_server`, `rag_list_categories`, `rag_explain_score`).
• RAGMap helps you find the best retrieval server for your task and constraints.
• Your agent then connects to that chosen server to do the actual retrieval.

RAGMap does not:

• Ingest your private documents automatically.
• Host your personal vector database.
• Replace your end-to-end RAG pipeline.

If you need retrieval over your own data, use a retrieval server from RAGMap results (or your own server) that supports your ingest/index flow.

Freshness and ingest

• Hosted RAGMap updates its index on a schedule. Newly published/changed servers may appear with some delay.
• Most users do not run ingest themselves when using the hosted service.
• If you need tighter freshness control or private indexing behavior, self-host and run your own ingest schedule (`docs/DEPLOYMENT.md`).

Features: Registry-compatible API; semantic + keyword search (when `OPENAI_API_KEY` is set, e.g. from env or your deployment’s secret manager); categories and `ragScore`; filter by `hasRemote`, `reachable` (probe-checked for streamable-http/SSE), `citations`, `localOnly`, `transport`, `minScore`, `categories`. Human browse UI at ragmap-api.web.app/browse — search, filter, copy Cursor/Claude config. MCP tools: `rag_find_servers`, `rag_get_server`, `rag_list_categories`, `rag_explain_score`.

Quickstart

> Requirements: `curl` and `jq`

1) Top reachable retrievers (checked within 24h)

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

2) Search with trust filter (reachable recently)

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

3) Get install config for a server

Tip: URL-encode names that contain `/`.

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

4) Inspect freshness and coverage

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

5) Usage telemetry summary

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

Full overview: `docs/OVERVIEW.md`

Release history: `CHANGELOG.md`

Architecture

Mermaid source

%%{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 constraintsdomain, privacy, citations,freshness, auth, limits"]:::mono
        Tools["MCP toolsrag_find_serversrag_get_serverrag_list_categoriesrag_explain_score"]:::mono
      end
      Users --> Criteria --> Tools
    end

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

      subgraph Enrich["Enrich (adds value)"]
        direction LR
        Cap["Structured metadatadomain: docs|code|web|mixedretrieval: dense|sparse|hybrid (+rerank)freshness: static|continuous (max lag)grounding: citations|provenanceprivacy/auth: local|remote + req|optionallimits: top_k|rate|max ctx"]:::mono
        Trust["Trust signals (lightweight)status, reachability,schema stability, reports"]:::mono
      end

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

  subgraph Selection["Selection (the added value)"]
    direction LR
    Router["Routermatch + rank + explain"]:::mono
    Ranked["Ranked candidates+ reasons + connect info"]:::mono
    Retrieval["Chosen retrieval MCP server(s)(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 layout

• `apps/api`: REST API + MCP registry-compatible endpoints + ingestion worker
• `apps/mcp-remote`: Remote MCP server (Streamable HTTP)
• `packages/mcp-local`: Local MCP server (stdio)
• `packages/shared`: Zod schemas + shared types
• `docs`: docs + Firebase Hosting static assets

Local dev

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

Optional: set `OPENAI_API_KEY` in `.env` (see `.env.example`) to enable semantic search locally; `GET /health` will show `"embeddings": true`.

API: `http://localhost:3000`

MCP remote: `http://localhost:4000/mcp`

Ingest

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

MCP usage

Remote (Streamable HTTP):

claude mcp add --transport http ragmap https:///mcp

Local (stdio, npm):

npx -y @khalidsaidi/ragmap-mcp@latest

Local (stdio):

pnpm -C packages/mcp-local dev

Key endpoints

• `GET /embed` — embeddable “Search RAG MCP servers” widget (iframe; query params: `q`, `limit`)
• `GET /health` (includes `embeddings: true|false` when semantic search is on/off)
• `GET /readyz`
• `GET /v0.1/servers`
• `GET /v0.1/servers/:serverName/versions`
• `GET /v0.1/servers/:serverName/versions/:version` (supports `latest`)
• `GET /rag/search`
• `GET /rag/top` (default sorted recommendations; `limit` max `50`)
• `GET /rag/install`
• `GET /rag/stats`
• `GET /rag/categories`
• `GET /api/stats` (public usage aggregates; no PII)
• `GET /api/usage-graph` (HTML chart of usage)
• `POST /internal/ingest/run` (protected)

For hosted `ragmap-api.web.app`, `/internal/*` routes are not exposed publicly.

`GET /rag/search` query params:

• `q` (string)
• `categories` (comma-separated)
• `minScore` (0-100)
• `transport` (`stdio` or `streamable-http`)
• `registryType` (string)
• `hasRemote` (`true` or `false` — only servers with a remote endpoint)
• `reachable` (`true` — only servers that were recently probe-checked as reachable via streamable-http/SSE)
• `reachableMaxAgeHours` (optional, only with `reachable=true` — keep only results checked within N hours)
• `citations` (`true` — only servers that mention citations/grounding in metadata)
• `localOnly` (`true` — only stdio, no remote)

Smoke tests

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

• `docs/DISCOVERY-LINK-CONVENTION.md` — optional `discoveryService` in server.json so clients can show “Discover more”
• `docs/AGENT-USAGE.md` — for agents: discovery, REST API, MCP install (no human intervention)
• `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` — print public Glama score flags (inspectable/release/usage)