RAGMap

Subregistro y servidor MCP centrado en RAG para descubrir y enrutar hacia servidores MCP con capacidad de recuperación, mediante búsqueda semántica, filtros y clasificación explicable.

GitHub
6
Prueba este MCPPatrocinado

Documentación

RAGMap (Registro de Descubrimiento de MCP para RAG)

Release Deploy monitor-freshness Glama

Pruébalo: https://ragmap-api.web.app/browse/ Empieza aquí: https://github.com/khalidsaidi/ragmap/discussions/17

RAGMap es un subregistro ligero compatible con el Registro MCP y un servidor MCP enfocado en servidores MCP relacionados con RAG.

Permite:

  • Consumir el Registro MCP oficial, enriquecer los registros para casos de uso de RAG y ofrecer una API de subregistro.
  • Exponer un servidor MCP (HTTP Streamable remoto + stdio local) para que los agentes puedan buscar/filtrar servidores MCP de RAG.

MapRag (RAGMap)

MapRag es una capa de descubrimiento y enrutamiento para recuperación. Ayuda a agentes y humanos a responder: ¿qué servidor MCP de recuperación debería usar para esta tarea, dadas mis restricciones?

RAGMap no realiza la recuperación en sí. Indexa y enriquece servidores con capacidad de recuperación, y luego te enruta a la herramienta/servidor adecuado.

Qué obtienes tras la instalación (en lenguaje sencillo)

  • Obtienes herramientas de descubrimiento/enrutamiento (rag_find_servers, rag_get_server, rag_list_categories, rag_explain_score).
  • RAGMap te ayuda a encontrar el mejor servidor de recuperación para tu tarea y restricciones.
  • Tu agente se conecta luego a ese servidor elegido para realizar la recuperación real.

RAGMap no:

  • Ingiere tus documentos privados automáticamente.
  • Aloja tu base de datos vectorial personal.
  • Reemplaza tu pipeline RAG de extremo a extremo.

Si necesitas recuperación sobre tus propios datos, usa un servidor de recuperación de los resultados de RAGMap (o tu propio servidor) que admita tu flujo de ingesta/índice.

Frescura e ingesta

  • El RAGMap alojado actualiza su índice según un cronograma. Los servidores recién publicados/cambiados pueden aparecer con cierto retraso.
  • La mayoría de los usuarios no ejecutan la ingesta ellos mismos al usar el servicio alojado.
  • Si necesitas un control más estricto de frescura o un comportamiento de indexación privado, auto-aloja y ejecuta tu propio cronograma de ingesta (docs/DEPLOYMENT.md).

Características: API compatible con el Registro; búsqueda semántica + por palabras clave (cuando OPENAI_API_KEY está configurado, p. ej., desde variables de entorno o el administrador de secretos de tu despliegue); categorías y ragScore; filtrar por hasRemote, reachable (verificado por sondeo para streamable-http/SSE), citations, localOnly, transport, minScore, categories. Interfaz de navegación humana en ragmap-api.web.app/browse — buscar, filtrar, copiar configuración de Cursor/Claude. Herramientas MCP: rag_find_servers, rag_get_server, rag_list_categories, rag_explain_score.

Inicio rápido

Requisitos: curl y jq

1) Recuperadores principales alcanzables (verificados en 24 h)

curl -s "https://ragmap-api.web.app/rag/top?hasRemote=true&reachable=true&reachableMaxAgeHours=24&serverKind=retriever&limit=25" | jq .

2) Búsqueda con filtro de confianza (alcanzables recientemente)

curl -s "https://ragmap-api.web.app/rag/search?q=rag&hasRemote=true&reachable=true&reachableMaxAgeHours=24&limit=10" | jq .

3) Obtener configuración de instalación para un servidor

Consejo: codifica en URL los nombres que contengan /.

curl -s "https://ragmap-api.web.app/rag/install?name=ai.filegraph%2Fdocument-processing" | jq .

4) Inspeccionar frescura y cobertura

curl -s "https://ragmap-api.web.app/rag/stats" | jq .

5) Resumen de telemetría de uso

curl -s "https://ragmap-api.web.app/api/stats" | jq .

Descripción general completa: docs/OVERVIEW.md
Historial de versiones: CHANGELOG.md

Arquitectura

RAGMap architecture diagram

Fuente 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<br/>domain, privacy, citations,<br/>freshness, auth, limits"]:::mono
        Tools["MCP tools<br/>rag_find_servers<br/>rag_get_server<br/>rag_list_categories<br/>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<br/>(official + optional)"]:::mono
        Sync["Sync + normalize<br/>(stable schema)"]:::mono
        Catalog["Enriched catalog<br/>(servers + versions)"]:::mono
        Sources --> Sync --> Catalog
      end

      subgraph Enrich["Enrich (adds value)"]
        direction LR
        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
        Trust["Trust signals (lightweight)<br/>status, reachability,<br/>schema stability, reports"]:::mono
      end

      Catalog --> Cap
      Catalog --> Trust
    end
  end

  subgraph Selection["Selection (the added value)"]
    direction LR
    Router["Router<br/>match + rank + explain"]:::mono
    Ranked["Ranked candidates<br/>+ reasons + connect info"]:::mono
    Retrieval["Chosen retrieval MCP server(s)<br/>(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

Estructura del monorepo

  • apps/api: API REST + endpoints compatibles con el Registro MCP + trabajador de ingesta
  • apps/mcp-remote: Servidor MCP remoto (HTTP Streamable)
  • packages/mcp-local: Servidor MCP local (stdio)
  • packages/shared: Esquemas Zod + tipos compartidos
  • docs: Documentación + activos estáticos de Firebase Hosting

Desarrollo local

cp .env.example .env
corepack enable
pnpm -r install
pnpm -r dev

Opcional: configura OPENAI_API_KEY en .env (ver .env.example) para habilitar búsqueda semántica localmente; GET /health mostrará "embeddings": true.

API: http://localhost:3000 MCP remoto: http://localhost:4000/mcp

Ingesta

curl -X POST http://localhost:3000/internal/ingest/run \
  -H "Content-Type: application/json" \
  -H "X-Ingest-Token: $INGEST_TOKEN" \
  -d '{"mode":"full"}'

Uso de MCP

Remoto (HTTP Streamable):

claude mcp add --transport http ragmap https://<your-mcp-domain>/mcp

Local (stdio, npm):

npx -y @khalidsaidi/ragmap-mcp@latest

Local (stdio):

pnpm -C packages/mcp-local dev

Endpoints clave

  • GET /embed — widget incrustable de “Buscar servidores MCP de RAG” (iframe; parámetros de consulta: q, limit)
  • GET /health (incluye embeddings: true|false cuando la búsqueda semántica está activada/desactivada)
  • GET /readyz
  • GET /v0.1/servers
  • GET /v0.1/servers/:serverName/versions
  • GET /v0.1/servers/:serverName/versions/:version (admite latest)
  • GET /rag/search
  • GET /rag/top (recomendaciones ordenadas por defecto; limit máximo 50)
  • GET /rag/install
  • GET /rag/stats
  • GET /rag/categories
  • GET /api/stats (agregados de uso públicos; sin PII)
  • GET /api/usage-graph (gráfico HTML de uso)
  • POST /internal/ingest/run (protegido)

Para ragmap-api.web.app alojado, las rutas /internal/* no se exponen públicamente.

Parámetros de consulta GET /rag/search:

  • q (cadena)
  • categories (separados por comas)
  • minScore (0-100)
  • transport (stdio o streamable-http)
  • registryType (cadena)
  • hasRemote (true o false — solo servidores con endpoint remoto)
  • reachable (true — solo servidores verificados recientemente por sondeo como alcanzables vía streamable-http/SSE)
  • reachableMaxAgeHours (opcional, solo con reachable=true — conservar solo resultados verificados dentro de N horas)
  • citations (true — solo servidores que mencionan citas/fundamentación en metadatos)
  • localOnly (true — solo stdio, sin remoto)

Pruebas de humo

API_BASE_URL=https://ragmap-api.web.app ./scripts/smoke-public.sh
MCP_URL=https://ragmap-api.web.app/mcp ./scripts/smoke-mcp.sh

Documentación

  • docs/DISCOVERY-LINK-CONVENTION.md — discoveryService opcional en server.json para que los clientes puedan mostrar “Descubrir más”
  • docs/AGENT-USAGE.md — para agentes: descubrimiento, API REST, instalación de MCP (sin intervención humana)
  • 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 — imprime las banderas públicas de puntuación de Glama (inspeccionable/versión/uso)