https://github.com/khalidsaidi/ragmap
RAG MCP Registry Finder (RAGMap): subregistry API + MCP server + Firestore ingestion
https://github.com/khalidsaidi/ragmap
agent-tools claude cursor mcp model-context-protocol rag registry retrieval subregistry
Last synced: 4 months ago
JSON representation
RAG MCP Registry Finder (RAGMap): subregistry API + MCP server + Firestore ingestion
- Host: GitHub
- URL: https://github.com/khalidsaidi/ragmap
- Owner: khalidsaidi
- License: mit
- Created: 2026-02-09T22:14:59.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-02-18T02:35:31.000Z (5 months ago)
- Last Synced: 2026-02-18T07:14:07.529Z (5 months ago)
- Topics: agent-tools, claude, cursor, mcp, model-context-protocol, rag, registry, retrieval, subregistry
- Language: TypeScript
- Homepage: https://ragmap-api.web.app
- Size: 795 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-mcp-lists - GitHub - api.web.app) | (Language-Specific SDKs / Utilities)
- awesome-mcp-servers - **khalidsaidi/ragmap 🍎 🪟 🐧** - MapRag: RAG-focused subregistry + MCP server to discover and route to retrieval-capable MCP servers using structured constraints and explainable ranking. `http` `ai` `git` `github` (📦 Other)
README
# RAGMap (RAG MCP Registry Finder)
[](https://github.com/khalidsaidi/ragmap/releases/latest)
[](https://github.com/khalidsaidi/ragmap/actions/workflows/deploy.yml)
[](https://github.com/khalidsaidi/ragmap/actions/workflows/monitor-freshness.yml)
[](https://glama.ai/mcp/servers/@khalidsaidi/ragmap)
**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](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`.
## Quickstart
> Requirements: `curl` and `jq`
### 1) Top reachable retrievers (checked within 24h)
```bash
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)
```bash
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 `/`.
```bash
curl -s "https://ragmap-api.web.app/rag/install?name=ai.filegraph%2Fdocument-processing" | jq .
```
### 4) Inspect freshness and coverage
```bash
curl -s "https://ragmap-api.web.app/rag/stats" | jq .
```
### 5) Usage telemetry summary
```bash
curl -s "https://ragmap-api.web.app/api/stats" | jq .
```
Full overview: `docs/OVERVIEW.md`
Release history: `CHANGELOG.md`
## Architecture
Mermaid source
```mermaid
%%{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
domain, privacy, citations,
freshness, auth, limits"]:::mono
Tools["MCP tools
rag_find_servers
rag_get_server
rag_list_categories
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
(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 metadata
domain: docs|code|web|mixed
retrieval: dense|sparse|hybrid (+rerank)
freshness: static|continuous (max lag)
grounding: citations|provenance
privacy/auth: local|remote + req|optional
limits: 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["Router
match + 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
```bash
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
```bash
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):
```bash
claude mcp add --transport http ragmap https:///mcp
```
Local (stdio, npm):
```bash
npx -y @khalidsaidi/ragmap-mcp@latest
```
Local (stdio):
```bash
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
```bash
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)