gnosis-mcp

Sin un servidor de documentación

• Los LLM alucinan firmas de API que no existen
• Archivos completos volcados en el contexto — 3.000–15.000 tokens por documento
• Decisiones de arquitectura enterradas en decenas de archivos
• Cada búsqueda repetida paga el costo completo del contexto

Con Gnosis MCP

• search_docs devuelve extractos clasificados y resaltados — normalmente 300–800 tokens
• Respuestas reales basadas en tus documentos reales, no suposiciones de los datos de entrenamiento
• Un índice local para cientos de archivos — búsqueda instantánea en múltiples documentos
• Ahorro de 5–10× en tokens por búsqueda cuando tu corpus cubre la pregunta

Qué hace diferente a gnosis-mcp

• Tus datos permanecen en tu máquina. SQLite por defecto, PostgreSQL a escala — nada sale del host.
• Indexa cualquier cosa con forma de documentación. Markdown, historial de commits de git, sitios web rastreados — un índice, una API de búsqueda.
• Medido, no comercializado. Incluye cifras BEIR SciFact (0,671 nDCG@10 — dentro del 1 % del baseline Lucene BM25), un harness de evaluación reproducible (gnosis-mcp eval) y un barrido de tamaños de fragmento que muestra dónde se encuentra realmente la meseta de calidad.

Comparativa completa lado a lado vs Context7 / docs-mcp-server / mcp-local-rag: gnosismcp.com#compare.

Características

• Cero configuración — SQLite por defecto, pip install y listo
• Búsqueda híbrida — por palabras clave (BM25) + semántica (embeddings ONNX locales, sin clave API). Ajusta la fusión RRF con GNOSIS_MCP_RRF_K.
• Reordenamiento con cross-encoder — [reranking] extra opcional con un modelo ONNX de 22M de parámetros. Desactivado por defecto. Pruébalo en tu propio corpus antes de activarlo — el reranker MS-MARCO incluido perjudica la recuperación de documentación de desarrollo en nuestras mediciones.
• Historial de Git — ingiere mensajes de commit como contexto buscable (ingest-git)
• Rastreo web — ingiere documentación de cualquier sitio web mediante sitemap o rastreo de enlaces
• Multi-formato — .md .txt .ipynb .toml .csv .json + .rst .pdf opcional
• Auto-enlazado — relates_to frontmatter crea un grafo de documentos navegable
• Modo vigilancia — re-ingestión automática al cambiar archivos
• Poda de documentos obsoletos — gnosis-mcp ingest --prune elimina fragmentos cuyo archivo fuente fue borrado. --wipe para un reinicio completo antes de re-ingestar.
• Harness de evaluación integrado — gnosis-mcp eval imprime Hit@K / MRR / Precision@K en un solo comando
• Listo para PostgreSQL — pgvector + tsvector cuando necesitas escala

Rendimiento

Rápido. 8,7 ms de tiempo medio de ida y vuelta MCP. Búsqueda híbrida p50 < 30 ms en un corpus de 700 documentos. El QPS de palabras clave escala de 9.463 @ 100 documentos a 471 @ 10.000 documentos (cifras completas).

Encuentra la respuesta correcta. En 558 documentos reales de desarrollo con 25 consultas doradas escritas a mano: Hit@5 = 0,92, nDCG@10 = 0,87, MRR = 0,79. En BEIR SciFact (5.183 documentos, benchmark público de recuperación): nDCG@10 = 0,671 — dentro del 1 % del baseline Lucene BM25.

Tokens ahorrados. Cada llamada a search_docs devuelve 200–500 tokens de fragmentos precisos en lugar de los 3.000–15.000 tokens que habría costado una lectura de archivo completo. Haz un seguimiento de los tuyos con gnosis-mcp savings (v0.12.0+) — el registro escribe en search_access_log en cada llamada y agrega por herramienta y por --days N:

$ gnosis-mcp savings --days 7
  Tool calls:               142
  Tokens returned:        7,104
  Tokens baseline:      231,580
  Tokens saved:         224,476
  Ratio:                   32.6×

La compresión típica oscila entre 10–60× dependiendo de la cobertura del corpus y la especificidad de la consulta — verifícalo en el tuyo. access_log está activado por defecto; GNOSIS_MCP_ACCESS_LOG=false lo desactiva.

Reproducible. gnosis-mcp eval ejecuta un harness de evaluación RAG localmente en un segundo. tests/bench/*.py reproduce cada cifra. Metodología: docs/benchmarks.md.

Los rerankers permanecen desactivados por defecto. El cross-encoder MS-MARCO incluido reduce el nDCG@10 en 27 puntos en documentación de desarrollo y añade 400× de latencia; BGE-reranker-v2-m3 lo reduce 31 puntos a 2400×. Pruébalo en tu corpus antes de activarlo — análisis completo: bench-experiments-2026-04-18.

Inicio rápido

pip install gnosis-mcp           # or: uv tool install gnosis-mcp
gnosis-mcp ingest ./docs/        # loads docs into SQLite (auto-created)
gnosis-mcp serve                 # starts MCP server

Eso es todo. Tu agente de IA ya puede buscar en tus documentos.

Conecta tu editor — consulta llms-install.md para ver fragmentos JSON listos para copiar y pegar para Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, JetBrains y Cline.

¿Reorganizaste tus documentos? gnosis-mcp ingest ./docs --prune re-ingiere y elimina cualquier fragmento de la base de datos cuyo archivo fuente ya no exista. --wipe reinicia todo el índice primero. O ejecuta gnosis-mcp prune ./docs --dry-run para previsualizar lo que se eliminaría.

¿Quieres búsqueda semántica? Añade embeddings locales — sin necesidad de clave API:

pip install gnosis-mcp[embeddings]
gnosis-mcp ingest ./docs/ --embed   # ingest + embed in one step
gnosis-mcp serve                    # hybrid search auto-activated

Pruébalo antes de conectarlo a un editor:

gnosis-mcp search "getting started"           # keyword search
gnosis-mcp search "how does auth work" --embed # hybrid semantic+keyword
gnosis-mcp stats                               # see what was indexed

# Serve your ./docs on http://localhost:8000 — MCP at /mcp, REST at /api/*
docker run -p 8000:8000 \
  -v "$PWD/docs:/docs:ro" -v gnosis-data:/data \
  ghcr.io/nicholasglazer/gnosis-mcp:latest

# First-run: ingest into the persistent volume
docker run --rm \
  -v "$PWD/docs:/docs:ro" -v gnosis-data:/data \
  ghcr.io/nicholasglazer/gnosis-mcp:latest \
  ingest /docs --embed

docker compose up -d
docker compose exec gnosis gnosis-mcp ingest /docs --embed

uvx gnosis-mcp ingest ./docs/
uvx gnosis-mcp serve

Rastreo web

_{Descubrimiento en seco → Rastreo e ingesta → Búsqueda en documentos rastreados → Protección SSRF}

Ingiere documentación de cualquier sitio web — sin necesidad de archivos locales:

pip install gnosis-mcp[web]

# Crawl via sitemap (best for large doc sites)
gnosis-mcp crawl https://docs.stripe.com/ --sitemap

# Depth-limited link crawl with URL filter
gnosis-mcp crawl https://fastapi.tiangolo.com/ --depth 2 --include "/tutorial/*"

# Preview what would be crawled
gnosis-mcp crawl https://docs.python.org/ --dry-run

# Force re-crawl + embed for semantic search
gnosis-mcp crawl https://docs.sveltekit.dev/ --sitemap --force --embed

Respeta robots.txt, almacena en caché con ETag/Last-Modified para re-rastreo incremental y limita la velocidad de las solicitudes (5 concurrentes, 0,2 s de retraso). Las páginas rastreadas usan la URL como ruta del documento y el nombre de host como categoría — buscables como cualquier otro documento.

Historial de Git

Convierte mensajes de commit en contexto buscable — tu agente aprende por qué se construyeron las cosas, no solo qué existe:

gnosis-mcp ingest-git .                                  # current repo, all files
gnosis-mcp ingest-git /path/to/repo --since 6m           # last 6 months only
gnosis-mcp ingest-git . --include "src/*" --max-commits 5 # filtered + limited
gnosis-mcp ingest-git . --dry-run                         # preview without ingesting
gnosis-mcp ingest-git . --embed                           # embed for semantic search

El historial de commits de cada archivo se convierte en un documento Markdown buscable almacenado como git-history/<file-path>. El agente lo encuentra mediante search_docs como cualquier otro documento — sin necesidad de nuevas herramientas. La re-ingestión incremental omite archivos cuyo historial no ha cambiado.

Integraciones con editores

Añade la configuración del servidor a tu editor — tu agente de IA obtiene las herramientas search_docs, get_doc y get_related automáticamente:

{
  "mcpServers": {
    "docs": {
      "command": "gnosis-mcp",
      "args": ["serve"]
    }
  }
}

{
  "servers": {
    "docs": {
      "command": "gnosis-mcp",
      "args": ["serve"]
    }
  }
}

Transporte

Stdio (por defecto) inicia un servidor por sesión de editor — lo más simple. HTTP comparte un solo proceso entre todos los clientes para que la base de datos, la caché de embeddings y el vigilador de archivos permanezcan sincronizados entre sesiones:

gnosis-mcp serve --transport streamable-http --host 0.0.0.0 --port 8000

{ "mcpServers": { "docs": { "type": "url", "url": "http://127.0.0.1:8000/mcp" } } }

Elige HTTP para configuraciones de agentes multi-sesión (Claude Code con equipos de agentes, terminales paralelas, CI). Análisis completo: gnosismcp.com/doc/docs/deployment.

API REST

v0.10.0+ — endpoints HTTP junto a MCP en el mismo puerto.

gnosis-mcp serve --transport streamable-http --rest

CORS, autenticación Bearer, lista blanca personalizada de rutas públicas — referencia completa: docs/rest-api.md · gnosismcp.com/doc/docs/rest-api.

Servicio de embeddings auto-alojado (v0.14.0+)

POST /v1/embed convierte a gnosis-mcp en un backend de embeddings con forma de OpenAI listo para usar. Apunta cualquier cliente que ya hable el formato /v1/embeddings a tu instancia de gnosis-mcp — tu hardware, tu elección de modelo, sin facturas por token:

curl -X POST http://localhost:8000/v1/embed \
  -H "Authorization: Bearer $GNOSIS_MCP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"texts": ["hello", "hola"], "model": "intfloat/multilingual-e5-large"}'

Elige tu modelo con GNOSIS_MCP_EMBED_MODEL (por defecto MongoDB/mdbr-leaf-ir):

• MongoDB/mdbr-leaf-ir — 23M de parámetros, #1 MTEB ≤100M, especializado en inglés
• intfloat/multilingual-e5-large — 560M, más de 100 idiomas
• BAAI/bge-m3 — 568M, multilingüe, híbrido denso + disperso

Límites: 256 textos × 50 KB por solicitud. Misma autenticación Bearer que el resto de la API REST.

Backends

Detección automática: Establece GNOSIS_MCP_DATABASE_URL a postgresql://... y usa PostgreSQL. Si no lo estableces, usa SQLite. Anula con GNOSIS_MCP_BACKEND=sqlite|postgres.

pip install gnosis-mcp[postgres]
export GNOSIS_MCP_DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"
gnosis-mcp init-db              # create tables + indexes
gnosis-mcp ingest ./docs/       # load your markdown
gnosis-mcp serve

CREATE EXTENSION IF NOT EXISTS vector;

gnosis-mcp embed                        # via OpenAI (default)
gnosis-mcp embed --provider ollama      # or use local Ollama

Plugin para Claude Code

Para usuarios de Claude Code, instálalo como plugin para obtener el servidor MCP además de comandos de barra:

claude plugin marketplace add nicholasglazer/gnosis-mcp
claude plugin install gnosis

Esto te proporciona:

{
  "mcpServers": {
    "gnosis": {
      "command": "gnosis-mcp",
      "args": ["serve"]
    }
  }
}

Herramientas y Recursos

Gnosis MCP expone 9 herramientas y 3 recursos a través de MCP. Tu agente de IA llama a estos automáticamente cuando necesita información de tus documentos.

Las herramientas de lectura están siempre disponibles. Las herramientas de escritura requieren GNOSIS_MCP_WRITABLE=true.

Cómo funciona la búsqueda

# Keyword search — works on both SQLite and PostgreSQL
gnosis-mcp search "stripe webhook"

# Hybrid search — keyword + semantic (requires [embeddings] or pgvector)
gnosis-mcp search "how does billing work" --embed

# Filtered — narrow results to a specific category
gnosis-mcp search "auth" -c guides

Cuando se llama a través de MCP, el agente pasa una cadena query para la búsqueda por palabras clave. Con los embeddings configurados, la búsqueda combina automáticamente resultados de palabras clave y semánticos mediante Reciprocal Rank Fusion. Los resultados incluyen un campo highlight con términos coincidentes en etiquetas <mark>.

Carga de Contexto

La herramienta get_context proporciona resúmenes de documentos ponderados por uso — ideal para el inicio de sesión o consultas de "¿qué es lo más importante?".

# Most-accessed docs (no topic)
get_context(limit=10)

# Topic-focused with access enrichment
get_context(topic="deployment", category="guides")

En segundo plano, Gnosis rastrea qué documentos se acceden a través de search_docs y get_doc, y luego usa la frecuencia de acceso para clasificar la importancia. Desactiva el seguimiento con GNOSIS_MCP_ACCESS_LOG=false.

Grafo y Enlaces

Gnosis extrae automáticamente enlaces de tu documentación — tanto declaraciones de frontmatter relates_to como enlaces markdown en el contenido. Usa las herramientas de grafo para explorar conexiones:

# Direct neighbors
get_related("guides/auth.md")

# Multi-hop traversal (2 levels deep, with titles)
get_related("guides/auth.md", depth=2, include_titles=True)

# Filter out noisy git history links
get_related("guides/auth.md", relation_type="relates_to")

# Graph topology: find orphans and hubs
get_graph_stats()

Tipos de relación: related (frontmatter predeterminado), content_link (enlaces markdown del cuerpo + [[wikilinks]]), git_co_change (co-ocurrencia de commits), git_ref (historial de git → archivo fuente). Además, 16 aristas tipadas mediante el bloque frontmatter relations:: prerequisite, depends_on, summarizes / summarized_by, extends / extended_by, replaces / replaced_by, audited_by / audits, implements / implemented_by, tests / tested_by, example_of, references.

Embeddings

Los embeddings permiten la búsqueda semántica — encontrar documentos por significado, no solo por palabras clave.

ONNX local (recomendado) — sin configuración, sin clave API:

pip install gnosis-mcp[embeddings]
gnosis-mcp ingest ./docs/ --embed       # ingest + embed in one step
gnosis-mcp embed                        # or embed existing chunks separately

Usa MongoDB/mdbr-leaf-ir (~23MB cuantizado, Apache 2.0). Se descarga automáticamente en la primera ejecución.

Proveedores remotos — OpenAI, Ollama, o cualquier endpoint compatible con OpenAI:

gnosis-mcp embed --provider openai      # requires GNOSIS_MCP_EMBED_API_KEY
gnosis-mcp embed --provider ollama      # uses local Ollama server

Vectores precomputados — pasa embeddings a upsert_doc o query_embedding a search_docs desde tu propio pipeline.

Configuración

Nada requerido para SQLite — la configuración cero funciona. Sobrescribe mediante variables de entorno GNOSIS_MCP_*. Los más usados:

Lista completa (~40 variables que cubren embeddings, rastreo, REST, anulaciones de columnas, webhooks, registro): docs/config.md · navegable en gnosismcp.com/doc/docs/config.

CREATE FUNCTION my_schema.my_search(
    p_query_text text,
    p_categories text[],
    p_limit integer
) RETURNS TABLE (
    file_path text, title text, content text,
    category text, combined_score double precision
) ...

GNOSIS_MCP_SEARCH_FUNCTION=my_schema.my_search

GNOSIS_MCP_CHUNKS_TABLE=documentation_chunks,api_docs,tutorial_chunks

gnosis-mcp ingest <path> [--dry-run] [--force] [--embed] [--prune] [--wipe] [--include-crawled]
gnosis-mcp ingest-git <repo> [--since] [--until] [--author] [--max-commits-per-file]
                             [--include] [--exclude] [--include-merges]
                             [--dry-run] [--force] [--embed]
gnosis-mcp crawl <url> [--sitemap] [--max-depth N] [--include] [--exclude] [--max-pages N]
                       [--dry-run] [--force] [--embed]
gnosis-mcp serve [--transport stdio|sse|streamable-http] [--host HOST] [--port PORT]
                 [--ingest PATH] [--watch PATH] [--rest]
gnosis-mcp search <query> [-n LIMIT] [-c CAT] [--embed]    Search docs
gnosis-mcp stats                                           Document, chunk, and embedding counts
gnosis-mcp check                                           Verify DB connection + extensions
gnosis-mcp embed [--provider P] [--model M] [--batch-size N] [--dry-run]
gnosis-mcp init-db [--dry-run]                             Create tables + indexes
gnosis-mcp export [-f json|markdown] [-c CAT]              Export documents
gnosis-mcp diff <path>                                     Preview changes on re-ingest
gnosis-mcp prune <path> [--dry-run] [--include-crawled]    Delete chunks for missing files
gnosis-mcp cleanup [--days N]                              Purge old access log entries
gnosis-mcp eval [--json]                                   Retrieval quality harness (Hit@5, MRR, P@5)
gnosis-mcp fix-link-types                                  Migrate pre-0.10 git-history links

src/gnosis_mcp/
├── backend.py         DocBackend protocol + create_backend() factory
├── pg_backend.py      PostgreSQL — asyncpg, tsvector, pgvector
├── sqlite_backend.py  SQLite — aiosqlite, FTS5, sqlite-vec hybrid search (RRF)
├── sqlite_schema.py   SQLite DDL — tables, FTS5, triggers, vec0 virtual table
├── config.py          Config from env vars, backend auto-detection
├── db.py              Backend lifecycle + FastMCP lifespan
├── server.py          FastMCP server — 9 tools, 3 resources, auto-embed queries
├── ingest.py          File scanner + converters — multi-format, smart chunking
├── crawl.py           Web crawler — sitemap/BFS, robots.txt, ETag caching
├── parsers/           Non-file ingest sources (git history, future: schemas)
│   └── git_history.py Git log → markdown documents per file
├── watch.py           File watcher — mtime polling, auto-re-ingest
├── schema.py          PostgreSQL DDL — tables, indexes, search functions
├── embed.py           Embedding providers — OpenAI, Ollama, custom, local ONNX
├── local_embed.py     Local ONNX embedding engine — HuggingFace model download
└── cli.py             CLI — serve, ingest, crawl, search, embed, stats, check, cleanup

Disponible En

Registro MCP (alimenta la galería MCP de VS Code y GitHub Copilot) · PyPI · mcp.so · Glama · cursor.directory

Documentos Amigables con IA

Desarrollo

git clone https://github.com/nicholasglazer/gnosis-mcp.git
cd gnosis-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest                    # 632 tests, no database needed
ruff check src/ tests/

Todas las pruebas se ejecutan sin base de datos. Mantén eso así.

Buenas primeras contribuciones: nuevos proveedores de embeddings, formatos de exportación, ingesta para nuevos tipos de archivo (mediante extras opcionales). Abre un issue primero para cambios más grandes.

Patrocinadores

Si Gnosis MCP te ahorra tiempo, considera patrocinar el proyecto.

Licencia

MIT