{
  "markdown": "# RAGMap (RAG MCP Registry Finder)\n\n[![Release](https://img.shields.io/github/v/release/khalidsaidi/ragmap?display_name=tag&sort=semver)](https://github.com/khalidsaidi/ragmap/releases/latest)\n[![Deploy](https://github.com/khalidsaidi/ragmap/actions/workflows/deploy.yml/badge.svg)](https://github.com/khalidsaidi/ragmap/actions/workflows/deploy.yml)\n[![monitor-freshness](https://github.com/khalidsaidi/ragmap/actions/workflows/monitor-freshness.yml/badge.svg)](https://github.com/khalidsaidi/ragmap/actions/workflows/monitor-freshness.yml)\n[![Glama](https://glama.ai/mcp/servers/@khalidsaidi/ragmap/badge)](https://glama.ai/mcp/servers/@khalidsaidi/ragmap)\n\n**Try it:** https://ragmap-api.web.app/browse/\n**Start here:** https://github.com/khalidsaidi/ragmap/discussions/17\n\nRAGMap is a lightweight MCP Registry-compatible subregistry + MCP server focused on **RAG-related MCP servers**.\n\nIt:\n- Ingests the official MCP Registry, enriches records for RAG use-cases, and serves a subregistry API.\n- Exposes an MCP server (remote Streamable HTTP + local stdio) so agents can search/filter RAG MCP servers.\n\n## MapRag (RAGMap)\n\n**MapRag is a discovery + routing layer for retrieval.**\nIt helps agents and humans answer: *which retrieval MCP server should I use for this task, given my constraints?*\n\nRAGMap does **not** do retrieval itself. It indexes and enriches retrieval-capable servers, then routes you to the right tool/server.\n\n## What you get after install (plain English)\n\n- You get **discovery/routing tools** (`rag_find_servers`, `rag_get_server`, `rag_list_categories`, `rag_explain_score`).\n- RAGMap helps you find the best retrieval server for your task and constraints.\n- Your agent then connects to that chosen server to do the actual retrieval.\n\nRAGMap does **not**:\n\n- Ingest your private documents automatically.\n- Host your personal vector database.\n- Replace your end-to-end RAG pipeline.\n\nIf you need retrieval over your own data, use a retrieval server from RAGMap results (or your own server) that supports your ingest/index flow.\n\n## Freshness and ingest\n\n- Hosted RAGMap updates its index on a schedule. Newly published/changed servers may appear with some delay.\n- Most users do **not** run ingest themselves when using the hosted service.\n- If you need tighter freshness control or private indexing behavior, self-host and run your own ingest schedule (`docs/DEPLOYMENT.md`).\n\n**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`.\n\n## Quickstart\n\n> Requirements: `curl` and `jq`\n\n### 1) Top reachable retrievers (checked within 24h)\n\n```bash\ncurl -s \"https://ragmap-api.web.app/rag/top?hasRemote=true&reachable=true&reachableMaxAgeHours=24&serverKind=retriever&limit=25\" | jq .\n```\n\n### 2) Search with trust filter (reachable recently)\n\n```bash\ncurl -s \"https://ragmap-api.web.app/rag/search?q=rag&hasRemote=true&reachable=true&reachableMaxAgeHours=24&limit=10\" | jq .\n```\n\n### 3) Get install config for a server\n\nTip: URL-encode names that contain `/`.\n\n```bash\ncurl -s \"https://ragmap-api.web.app/rag/install?name=ai.filegraph%2Fdocument-processing\" | jq .\n```\n\n### 4) Inspect freshness and coverage\n\n```bash\ncurl -s \"https://ragmap-api.web.app/rag/stats\" | jq .\n```\n\n### 5) Usage telemetry summary\n\n```bash\ncurl -s \"https://ragmap-api.web.app/api/stats\" | jq .\n```\n\nFull overview: `docs/OVERVIEW.md`  \nRelease history: `CHANGELOG.md`\n\n## Architecture\n\n![RAGMap architecture diagram](docs/diagrams/ragmap-architecture.png)\n\n<details>\n<summary>Mermaid source</summary>\n\n```mermaid\n%%{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}}}%%\nflowchart TB\n  %% Concept-only diagram (product value; no deployment/framework/datastore details)\n\n  classDef mono fill:#ffffff,stroke:#000000,color:#000000,stroke-width:1px;\n\n  subgraph Inputs[\" \"]\n    direction LR\n\n    subgraph Query[\"Agent-native interface\"]\n      direction TB\n      Users[\"Agents + humans\"]:::mono\n      subgraph Tooling[\"Tool call\"]\n        direction LR\n        Criteria[\"Routing constraints<br/>domain, privacy, citations,<br/>freshness, auth, limits\"]:::mono\n        Tools[\"MCP tools<br/>rag_find_servers<br/>rag_get_server<br/>rag_list_categories<br/>rag_explain_score\"]:::mono\n      end\n      Users --> Criteria --> Tools\n    end\n\n    subgraph Subregistry[\"Subregistry (read-only)\"]\n      direction TB\n      subgraph Ingest[\"Ingest\"]\n        direction LR\n        Sources[\"Upstream MCP registries<br/>(official + optional)\"]:::mono\n        Sync[\"Sync + normalize<br/>(stable schema)\"]:::mono\n        Catalog[\"Enriched catalog<br/>(servers + versions)\"]:::mono\n        Sources --> Sync --> Catalog\n      end\n\n      subgraph Enrich[\"Enrich (adds value)\"]\n        direction LR\n        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\n        Trust[\"Trust signals (lightweight)<br/>status, reachability,<br/>schema stability, reports\"]:::mono\n      end\n\n      Catalog --> Cap\n      Catalog --> Trust\n    end\n  end\n\n  subgraph Selection[\"Selection (the added value)\"]\n    direction LR\n    Router[\"Router<br/>match + rank + explain\"]:::mono\n    Ranked[\"Ranked candidates<br/>+ reasons + connect info\"]:::mono\n    Retrieval[\"Chosen retrieval MCP server(s)<br/>(do retrieval)\"]:::mono\n    Router --> Ranked --> Retrieval\n  end\n\n  Tools --> Router\n  Catalog --> Router\n\n  %% Keep the layout without adding a third visible \"box\" around Inputs.\n  style Inputs fill:#ffffff,stroke:#ffffff,stroke-width:0px\n```\n\n</details>\n\n## Monorepo layout\n\n- `apps/api`: REST API + MCP registry-compatible endpoints + ingestion worker\n- `apps/mcp-remote`: Remote MCP server (Streamable HTTP)\n- `packages/mcp-local`: Local MCP server (stdio)\n- `packages/shared`: Zod schemas + shared types\n- `docs`: docs + Firebase Hosting static assets\n\n## Local dev\n\n```bash\ncp .env.example .env\ncorepack enable\npnpm -r install\npnpm -r dev\n```\n\nOptional: set `OPENAI_API_KEY` in `.env` (see `.env.example`) to enable **semantic search** locally; `GET /health` will show `\"embeddings\": true`.\n\nAPI: `http://localhost:3000`\nMCP remote: `http://localhost:4000/mcp`\n\n## Ingest\n\n```bash\ncurl -X POST http://localhost:3000/internal/ingest/run \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-Ingest-Token: $INGEST_TOKEN\" \\\n  -d '{\"mode\":\"full\"}'\n```\n\n## MCP usage\n\nRemote (Streamable HTTP):\n\n```bash\nclaude mcp add --transport http ragmap https://<your-mcp-domain>/mcp\n```\n\nLocal (stdio, npm):\n\n```bash\nnpx -y @khalidsaidi/ragmap-mcp@latest\n```\n\nLocal (stdio):\n\n```bash\npnpm -C packages/mcp-local dev\n```\n\n## Key endpoints\n\n- `GET /embed` — embeddable “Search RAG MCP servers” widget (iframe; query params: `q`, `limit`)\n- `GET /health` (includes `embeddings: true|false` when semantic search is on/off)\n- `GET /readyz`\n- `GET /v0.1/servers`\n- `GET /v0.1/servers/:serverName/versions`\n- `GET /v0.1/servers/:serverName/versions/:version` (supports `latest`)\n- `GET /rag/search`\n- `GET /rag/top` (default sorted recommendations; `limit` max `50`)\n- `GET /rag/install`\n- `GET /rag/stats`\n- `GET /rag/categories`\n- `GET /api/stats` (public usage aggregates; no PII)\n- `GET /api/usage-graph` (HTML chart of usage)\n- `POST /internal/ingest/run` (protected)\n\nFor hosted `ragmap-api.web.app`, `/internal/*` routes are not exposed publicly.\n\n`GET /rag/search` query params:\n- `q` (string)\n- `categories` (comma-separated)\n- `minScore` (0-100)\n- `transport` (`stdio` or `streamable-http`)\n- `registryType` (string)\n- `hasRemote` (`true` or `false` — only servers with a remote endpoint)\n- `reachable` (`true` — only servers that were recently probe-checked as reachable via streamable-http/SSE)\n- `reachableMaxAgeHours` (optional, only with `reachable=true` — keep only results checked within N hours)\n- `citations` (`true` — only servers that mention citations/grounding in metadata)\n- `localOnly` (`true` — only stdio, no remote)\n\n## Smoke tests\n\n```bash\nAPI_BASE_URL=https://ragmap-api.web.app ./scripts/smoke-public.sh\nMCP_URL=https://ragmap-api.web.app/mcp ./scripts/smoke-mcp.sh\n```\n\n## Docs\n\n- `docs/DISCOVERY-LINK-CONVENTION.md` — optional `discoveryService` in server.json so clients can show “Discover more”\n- `docs/AGENT-USAGE.md` — **for agents:** discovery, REST API, MCP install (no human intervention)\n- `docs/DEPLOYMENT.md`\n- `docs/OVERVIEW.md`\n- `docs/DATA_MODEL.md`\n- `docs/PRIVACY.md`\n- `docs/PUBLISHING.md`\n- `docs/GLAMA-CHECKLIST.md`\n- `docs/GLAMA-DOCKERFILE.md`\n- `scripts/glama-score-status.sh` — print public Glama score flags (inspectable/release/usage)\n",
  "bytes": 9435,
  "sha": "4981f47d395eb8942c73fe05b46ac667b51876c1a80ae32260972b86905d50e1",
  "repo_slug": "khalidsaidi/ragmap",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_khalidsaidi_ragmap_35b02ea0/readme"
}