RAGMap (RAG MCP Registry Finder)

1# RAGMap (RAG MCP Registry Finder)
2 
3[![Glama](https://glama.ai/mcp/servers/@khalidsaidi/ragmap/badge)](https://glama.ai/mcp/servers/@khalidsaidi/ragmap)
4 
5RAGMap is a lightweight MCP Registry-compatible subregistry + MCP server focused on **RAG-related MCP servers**.
6 
7It:
8- Ingests the official MCP Registry, enriches records for RAG use-cases, and serves a subregistry API.
9- Exposes an MCP server (remote Streamable HTTP + local stdio) so agents can search/filter RAG MCP servers.
10 
11## MapRag (RAGMap)
12 
13**MapRag is a discovery + routing layer for retrieval.**
14It helps agents and humans answer: *which retrieval MCP server should I use for this task, given my constraints?*
15 
16RAGMap does **not** do retrieval itself. It indexes and enriches retrieval-capable servers, then routes you to the right tool/server.
17 
18## What you get after install (plain English)
19 
20- You get **discovery/routing tools** (`rag_find_servers`, `rag_get_server`, `rag_list_categories`, `rag_explain_score`).
21- RAGMap helps you find the best retrieval server for your task and constraints.
22- Your agent then connects to that chosen server to do the actual retrieval.
23 
24RAGMap does **not**:
25 
26- Ingest your private documents automatically.
27- Host your personal vector database.
28- Replace your end-to-end RAG pipeline.
29 
30If you need retrieval over your own data, use a retrieval server from RAGMap results (or your own server) that supports your ingest/index flow.
31 
32## Freshness and ingest
33 
34- Hosted RAGMap updates its index on a schedule. Newly published/changed servers may appear with some delay.
35- Most users do **not** run ingest themselves when using the hosted service.
36- If you need tighter freshness control or private indexing behavior, self-host and run your own ingest schedule (`docs/DEPLOYMENT.md`).
37 
38**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`** (HEAD-checked), **`citations`**, **`localOnly`**, `transport`, `minScore`, `categories`. **Human browse UI** at [ragmap-api.web.app/browse](https://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`.
39 
40Full overview: `docs/OVERVIEW.md`
41 
42## Architecture
43 
44![RAGMap architecture diagram](docs/diagrams/ragmap-architecture.png)
45 
46<details>
47<summary>Mermaid source</summary>
48 
49```mermaid
50%%{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}}}%%
51flowchart TB
52  %% Concept-only diagram (product value; no deployment/framework/datastore details)
53 
54  classDef mono fill:#ffffff,stroke:#000000,color:#000000,stroke-width:1px;
55 
56  subgraph Inputs[" "]
57    direction LR
58 
59    subgraph Query["Agent-native interface"]
60      direction TB
61      Users["Agents + humans"]:::mono
62      subgraph Tooling["Tool call"]
63        direction LR
64        Criteria["Routing constraints<br/>domain, privacy, citations,<br/>freshness, auth, limits"]:::mono
65        Tools["MCP tools<br/>rag_find_servers<br/>rag_get_server<br/>rag_list_categories<br/>rag_explain_score"]:::mono
66      end
67      Users --> Criteria --> Tools
68    end
69 
70    subgraph Subregistry["Subregistry (read-only)"]
71      direction TB
72      subgraph Ingest["Ingest"]
73        direction LR
74        Sources["Upstream MCP registries<br/>(official + optional)"]:::mono
75        Sync["Sync + normalize<br/>(stable schema)"]:::mono
76        Catalog["Enriched catalog<br/>(servers + versions)"]:::mono
77        Sources --> Sync --> Catalog
78      end
79 
80      subgraph Enrich["Enrich (adds value)"]
81        direction LR
82        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
83        Trust["Trust signals (lightweight)<br/>status, reachability,<br/>schema stability, reports"]:::mono
84      end
85 
86      Catalog --> Cap
87      Catalog --> Trust
88    end
89  end
90 
91  subgraph Selection["Selection (the added value)"]
92    direction LR
93    Router["Router<br/>match + rank + explain"]:::mono
94    Ranked["Ranked candidates<br/>+ reasons + connect info"]:::mono
95    Retrieval["Chosen retrieval MCP server(s)<br/>(do retrieval)"]:::mono
96    Router --> Ranked --> Retrieval
97  end
98 
99  Tools --> Router
100  Catalog --> Router
101 
102  %% Keep the layout without adding a third visible "box" around Inputs.
103  style Inputs fill:#ffffff,stroke:#ffffff,stroke-width:0px
104```
105 
106</details>
107 
108## Monorepo layout
109 
110- `apps/api`: REST API + MCP registry-compatible endpoints + ingestion worker
111- `apps/mcp-remote`: Remote MCP server (Streamable HTTP)
112- `packages/mcp-local`: Local MCP server (stdio)
113- `packages/shared`: Zod schemas + shared types
114- `docs`: docs + Firebase Hosting static assets
115 
116## Local dev
117 
118```bash
119cp .env.example .env
120corepack enable
121pnpm -r install
122pnpm -r dev
123```
124 
125Optional: set `OPENAI_API_KEY` in `.env` (see `.env.example`) to enable **semantic search** locally; `GET /health` will show `"embeddings": true`.
126 
127API: `http://localhost:3000`
128MCP remote: `http://localhost:4000/mcp`
129 
130## Ingest
131 
132```bash
133curl -X POST http://localhost:3000/internal/ingest/run \
134  -H "Content-Type: application/json" \
135  -H "X-Ingest-Token: $INGEST_TOKEN" \
136  -d '{"mode":"full"}'
137```
138 
139## MCP usage
140 
141Remote (Streamable HTTP):
142 
143```bash
144claude mcp add --transport http ragmap https://<your-mcp-domain>/mcp
145```
146 
147Local (stdio, npm):
148 
149```bash
150npx -y @khalidsaidi/ragmap-mcp@latest
151```
152 
153Local (stdio):
154 
155```bash
156pnpm -C packages/mcp-local dev
157```
158 
159## Key endpoints
160 
161- `GET /embed` — embeddable “Search RAG MCP servers” widget (iframe; query params: `q`, `limit`)
162- `GET /health` (includes `embeddings: true|false` when semantic search is on/off)
163- `GET /readyz`
164- `GET /v0.1/servers`
165- `GET /v0.1/servers/:serverName/versions`
166- `GET /v0.1/servers/:serverName/versions/:version` (supports `latest`)
167- `GET /rag/search`
168- `GET /rag/categories`
169- `GET /api/stats` (public usage aggregates; no PII)
170- `GET /api/usage-graph` (HTML chart of usage)
171- `POST /internal/ingest/run` (protected)
172 
173For hosted `ragmap-api.web.app`, `/internal/*` routes are not exposed publicly.
174 
175`GET /rag/search` query params:
176- `q` (string)
177- `categories` (comma-separated)
178- `minScore` (0-100)
179- `transport` (`stdio` or `streamable-http`)
180- `registryType` (string)
181- `hasRemote` (`true` or `false` — only servers with a remote endpoint)
182- `reachable` (`true` — only servers whose streamable-http URL passed a HEAD check)
183- `citations` (`true` — only servers that mention citations/grounding in metadata)
184- `localOnly` (`true` — only stdio, no remote)
185 
186## Smoke tests
187 
188```bash
189API_BASE_URL=https://ragmap-api.web.app ./scripts/smoke-public.sh
190MCP_URL=https://ragmap-api.web.app/mcp ./scripts/smoke-mcp.sh
191```
192 
193## Docs
194 
195- `docs/DISCOVERY-LINK-CONVENTION.md` — optional `discoveryService` in server.json so clients can show “Discover more”
196- `docs/AGENT-USAGE.md` — **for agents:** discovery, REST API, MCP install (no human intervention)
197- `docs/DEPLOYMENT.md`
198- `docs/OVERVIEW.md`
199- `docs/DATA_MODEL.md`
200- `docs/PRIVACY.md`
201- `docs/PUBLISHING.md`
202- `docs/GLAMA-CHECKLIST.md`
203- `docs/GLAMA-DOCKERFILE.md`
204- `scripts/glama-score-status.sh` — print public Glama score flags (inspectable/release/usage)
205