RAGMap

Subregistro e servidor MCP focado em RAG para descobrir e rotear para servidores MCP com capacidade de recuperação, utilizando busca semântica, filtros e ranqueamento explicável.

GitHub
6
Experimente este MCPPatrocinado

Documentação

RAGMap (Registro de Localizador de MCPs RAG)

Release Deploy monitor-freshness Glama

Experimente: https://ragmap-api.web.app/browse/ Comece aqui: https://github.com/khalidsaidi/ragmap/discussions/17

RAGMap é um subregistro leve compatível com o Registro MCP, além de um servidor MCP focado em servidores MCP relacionados a RAG.

Ele:

  • Consome o Registro MCP oficial, enriquece registros para casos de uso de RAG e serve uma API de subregistro.
  • Expõe um servidor MCP (HTTP remoto via Streamable + stdio local) para que agentes possam buscar/filtrar servidores MCP de RAG.

MapRag (RAGMap)

MapRag é uma camada de descoberta + roteamento para recuperação. Ele ajuda agentes e humanos a responder: qual servidor MCP de recuperação devo usar para esta tarefa, dadas as minhas restrições?

O RAGMap não faz recuperação em si. Ele indexa e enriquece servidores com capacidade de recuperação e, em seguida, roteia você para a ferramenta/servidor correto.

O que você obtém após a instalação (em linguagem simples)

  • Você obtém ferramentas de descoberta/roteamento (rag_find_servers, rag_get_server, rag_list_categories, rag_explain_score).
  • O RAGMap ajuda você a encontrar o melhor servidor de recuperação para sua tarefa e restrições.
  • Seu agente então se conecta ao servidor escolhido para fazer a recuperação de fato.

O RAGMap não:

  • Ingere seus documentos privados automaticamente.
  • Hospeda seu banco de dados vetorial pessoal.
  • Substitui seu pipeline RAG de ponta a ponta.

Se você precisar de recuperação sobre seus próprios dados, use um servidor de recuperação dos resultados do RAGMap (ou seu próprio servidor) que suporte seu fluxo de ingestão/indexação.

Atualização e ingestão

  • O RAGMap hospedado atualiza seu índice em um cronograma. Servidores recém-publicados/alterados podem aparecer com algum atraso.
  • A maioria dos usuários não executa a ingestão por conta própria ao usar o serviço hospedado.
  • Se você precisar de controle mais rígido de atualização ou comportamento de indexação privada, faça self-host e execute seu próprio cronograma de ingestão (docs/DEPLOYMENT.md).

Recursos: API compatível com Registro; busca semântica + por palavras-chave (quando OPENAI_API_KEY estiver definido, por exemplo, via env ou gerenciador de segredos da sua implantação); categorias e ragScore; filtrar por hasRemote, reachable (verificado por probe para streamable-http/SSE), citations, localOnly, transport, minScore, categories. Interface de navegação humana em ragmap-api.web.app/browse — busque, filtre, copie configuração do Cursor/Claude. Ferramentas MCP: rag_find_servers, rag_get_server, rag_list_categories, rag_explain_score.

Início rápido

Requisitos: curl e jq

1) Recuperadores mais acessíveis (verificados nas últimas 24h)

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

2) Busca com filtro de confiança (acessíveis recentemente)

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

3) Obter configuração de instalação para um servidor

Dica: codifique na URL nomes que contenham /.

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

4) Inspecionar atualização e cobertura

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

5) Resumo de telemetria de uso

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

Visão geral completa: docs/OVERVIEW.md
Histórico de versões: CHANGELOG.md

Arquitetura

RAGMap architecture diagram

Fonte 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

Estrutura do monorepo

  • apps/api: API REST + endpoints compatíveis com Registro MCP + worker de ingestão
  • apps/mcp-remote: Servidor MCP remoto (Streamable HTTP)
  • packages/mcp-local: Servidor MCP local (stdio)
  • packages/shared: Esquemas Zod + tipos compartilhados
  • docs: documentação + ativos estáticos do Firebase Hosting

Desenvolvimento local

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

Opcional: defina OPENAI_API_KEY em .env (veja .env.example) para habilitar busca semântica localmente; GET /health mostrará "embeddings": true.

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

Ingestão

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

Uso do MCP

Remoto (Streamable HTTP):

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 principais

  • GET /embed — widget incorporável “Buscar servidores MCP de RAG” (iframe; parâmetros de consulta: q, limit)
  • GET /health (inclui embeddings: true|false quando a busca semântica está ativada/desativada)
  • GET /readyz
  • GET /v0.1/servers
  • GET /v0.1/servers/:serverName/versions
  • GET /v0.1/servers/:serverName/versions/:version (suporta latest)
  • GET /rag/search
  • GET /rag/top (recomendações padrão ordenadas; limit máximo 50)
  • GET /rag/install
  • GET /rag/stats
  • GET /rag/categories
  • GET /api/stats (agregados públicos de uso; sem PII)
  • GET /api/usage-graph (gráfico HTML de uso)
  • POST /internal/ingest/run (protegido)

Para ragmap-api.web.app hospedado, as rotas /internal/* não são expostas publicamente.

Parâmetros de consulta GET /rag/search:

  • q (string)
  • categories (separados por vírgula)
  • minScore (0-100)
  • transport (stdio ou streamable-http)
  • registryType (string)
  • hasRemote (true ou false — apenas servidores com endpoint remoto)
  • reachable (true — apenas servidores verificados recentemente por probe como acessíveis via streamable-http/SSE)
  • reachableMaxAgeHours (opcional, apenas com reachable=true — manter apenas resultados verificados nas últimas N horas)
  • citations (true — apenas servidores que mencionam citações/fundamentação nos metadados)
  • localOnly (true — apenas stdio, sem remoto)

Testes de fumaça

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

Documentação

  • docs/DISCOVERY-LINK-CONVENTION.md — discoveryService opcional em server.json para que clientes possam mostrar “Descobrir mais”
  • docs/AGENT-USAGE.md — para agentes: descoberta, API REST, instalação MCP (sem intervenção 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 flags públicas de pontuação Glama (inspecionável/versão/uso)