{"id":44234122,"url":"https://github.com/khalidsaidi/ragmap","last_synced_at":"2026-03-01T09:03:27.412Z","repository":{"id":337553307,"uuid":"1153981814","full_name":"khalidsaidi/ragmap","owner":"khalidsaidi","description":"RAG MCP Registry Finder (RAGMap): subregistry API + MCP server + Firestore ingestion","archived":false,"fork":false,"pushed_at":"2026-02-18T02:35:31.000Z","size":814,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-18T07:14:07.529Z","etag":null,"topics":["agent-tools","claude","cursor","mcp","model-context-protocol","rag","registry","retrieval","subregistry"],"latest_commit_sha":null,"homepage":"https://ragmap-api.web.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/khalidsaidi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-09T22:14:59.000Z","updated_at":"2026-02-18T02:35:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/khalidsaidi/ragmap","commit_stats":null,"previous_names":["khalidsaidi/ragmap"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/khalidsaidi/ragmap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khalidsaidi%2Fragmap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khalidsaidi%2Fragmap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khalidsaidi%2Fragmap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khalidsaidi%2Fragmap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/khalidsaidi","download_url":"https://codeload.github.com/khalidsaidi/ragmap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khalidsaidi%2Fragmap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29641937,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-20T03:21:14.183Z","status":"ssl_error","status_checked_at":"2026-02-20T03:18:24.455Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-tools","claude","cursor","mcp","model-context-protocol","rag","registry","retrieval","subregistry"],"created_at":"2026-02-10T08:04:55.901Z","updated_at":"2026-03-01T09:03:27.396Z","avatar_url":"https://github.com/khalidsaidi.png","language":"TypeScript","funding_links":[],"categories":["Language-Specific SDKs","📦 Other"],"sub_categories":["Utilities"],"readme":"# RAGMap (RAG MCP Registry Finder)\n\n[![Release](https://img.shields.io/github/v/release/khalidsaidi/ragmap?display_name=tag\u0026sort=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\u003e 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\u0026reachable=true\u0026reachableMaxAgeHours=24\u0026serverKind=retriever\u0026limit=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\u0026hasRemote=true\u0026reachable=true\u0026reachableMaxAgeHours=24\u0026limit=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\u003cdetails\u003e\n\u003csummary\u003eMermaid source\u003c/summary\u003e\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\u003cbr/\u003edomain, privacy, citations,\u003cbr/\u003efreshness, auth, limits\"]:::mono\n        Tools[\"MCP tools\u003cbr/\u003erag_find_servers\u003cbr/\u003erag_get_server\u003cbr/\u003erag_list_categories\u003cbr/\u003erag_explain_score\"]:::mono\n      end\n      Users --\u003e Criteria --\u003e 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\u003cbr/\u003e(official + optional)\"]:::mono\n        Sync[\"Sync + normalize\u003cbr/\u003e(stable schema)\"]:::mono\n        Catalog[\"Enriched catalog\u003cbr/\u003e(servers + versions)\"]:::mono\n        Sources --\u003e Sync --\u003e Catalog\n      end\n\n      subgraph Enrich[\"Enrich (adds value)\"]\n        direction LR\n        Cap[\"Structured metadata\u003cbr/\u003edomain: docs|code|web|mixed\u003cbr/\u003eretrieval: dense|sparse|hybrid (+rerank)\u003cbr/\u003efreshness: static|continuous (max lag)\u003cbr/\u003egrounding: citations|provenance\u003cbr/\u003eprivacy/auth: local|remote + req|optional\u003cbr/\u003elimits: top_k|rate|max ctx\"]:::mono\n        Trust[\"Trust signals (lightweight)\u003cbr/\u003estatus, reachability,\u003cbr/\u003eschema stability, reports\"]:::mono\n      end\n\n      Catalog --\u003e Cap\n      Catalog --\u003e Trust\n    end\n  end\n\n  subgraph Selection[\"Selection (the added value)\"]\n    direction LR\n    Router[\"Router\u003cbr/\u003ematch + rank + explain\"]:::mono\n    Ranked[\"Ranked candidates\u003cbr/\u003e+ reasons + connect info\"]:::mono\n    Retrieval[\"Chosen retrieval MCP server(s)\u003cbr/\u003e(do retrieval)\"]:::mono\n    Router --\u003e Ranked --\u003e Retrieval\n  end\n\n  Tools --\u003e Router\n  Catalog --\u003e 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\u003c/details\u003e\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://\u003cyour-mcp-domain\u003e/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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhalidsaidi%2Fragmap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkhalidsaidi%2Fragmap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhalidsaidi%2Fragmap/lists"}