Mermaid source

\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
domain, privacy, citations,
freshness, auth, limits\"]:::mono\n Tools[\"MCP tools
rag_find_servers
rag_get_server
rag_list_categories
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
(official + optional)\"]:::mono\n Sync[\"Sync + normalize
(stable schema)\"]:::mono\n Catalog[\"Enriched catalog
(servers + versions)\"]:::mono\n Sources --> Sync --> Catalog\n end\n\n subgraph Enrich[\"Enrich (adds value)\"]\n direction LR\n 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\n Trust[\"Trust signals (lightweight)
status, reachability,
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
match + rank + explain\"]:::mono\n Ranked[\"Ranked candidates
+ reasons + connect info\"]:::mono\n Retrieval[\"Chosen retrieval MCP server(s)
(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

\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:///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","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"categoryDisplayName","Developer Tools","upstream",{"_95":96,"_97":98,"_99":100,"_101":102,"_103":104},"requiredSecrets",[],"tags",[],"assets",[],"stats",{"_93":80,"_94":80},"ratingAvg","reviewCount","topics",[105,106,107,108,109,110,111,112,113,114,115,116,117,118],"license","MIT","language","TypeScript","registryName","io.github.khalidsaidi/ragmap","homepage","https://ragmap-api.web.app","agent-tools","ai-agents","claude","cursor","discovery","mcp","mcp-server","model-context-protocol","rag","registry","retrieval","retrieval-augmented-generation","semantic-search","subregistry","ENV",{"_121":122,"_123":124,"_125":126},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]

RAGMap MCP