neutrinos-mcp

Un servidor MCP de recuperación sobre el corpus de documentación de Neutrinos (53 publicaciones, 3,117 temas, 7,810 fragmentos indexados). Recuperación híbrida BM25 + densa, fusión RRF, reordenamiento con cross-encoder, colapso de casi-duplicados entre versiones y expansión condicional del grafo de enlaces — diseñado para responder "¿es esto cierto para la versión que el usuario realmente está usando?", algo que una configuración ingenua de búsqueda semántica sobre documentos falla en este corpus más de la mitad de las veces. Consulte implementation_plan.md para la justificación completa del diseño (decisiones de arquitectura, modelo de datos, metodología de evaluación).

Inicio rápido

neutrinos-mcp es un repositorio público, por lo que no se necesita autenticación para clonarlo, descargar una versión, o ejecutar cualquiera de los comandos de una línea a continuación — solo git y (opcionalmente) gh para descargar la base de datos precompilada más rápido (consulte Distribución a continuación; sin gh, el servidor la descarga automáticamente en el primer uso en su lugar, solo que no durante la instalación).

macOS/Linux — una línea:

curl -fsSL https://raw.githubusercontent.com/jitin-neutrinos/neutrinos-mcp/master/install.sh | bash

Windows (PowerShell) — una línea:

iex (irm https://raw.githubusercontent.com/jitin-neutrinos/neutrinos-mcp/master/install.ps1)

Cada uno descarga el script del instalador en sí (no todo el repositorio) y lo ejecuta directamente — versiones anteriores de este README hacían que el comando de una línea hiciera su propio git clone primero y luego invocara el script desde dentro, lo que duplicaba el paso de clonación del propio script y, en una máquina con un ~/.neutrinos-mcp obsoleto dejado por una ejecución anterior interrumpida, fallaba en esa clonación externa antes de que el script tuviera la oportunidad de detectar y limpiar el desastre (git clone se niega a ejecutarse por completo contra un destino no vacío). Descargar solo el script y dejar que gestione el directorio de destino por sí mismo evita esa clase de error por completo.

Cada script: comprueba si ya existe una instalación allí y si está genuinamente completa (un marcador .install_complete escrito solo al final de una ejecución anterior exitosa) — si es así, actualiza en su lugar (git pull); si existe un directorio pero no está marcado como completo (restos de una ejecución interrumpida, exactamente lo que causó el error anterior), se elimina antes de clonar de nuevo. Luego crea un venv, instala el paquete (python -m pip install -e . — nunca un pip/pip.exe desnudo, ya que ese ejecutable específico es bloqueado por la política de ejecución en algunas máquinas corporativas restringidas mientras que python.exe en sí sigue permitido), descarga la última base de datos precompilada data/neutrinos.db de la versión más reciente de GitHub mediante gh release download si gh está instalado (de lo contrario, el servidor en ejecución la descarga en el primer uso en su lugar — consulte Distribución a continuación), registra neutrinos-docs con Claude Code a nivel de usuario (todos los proyectos, no solo este), y fusiona una entrada en claude_desktop_config.json de Claude Desktop (rutas de macOS/Linux/Windows manejadas; fusionado con un pequeño script de Python, no sobrescrito, ya que ese archivo comúnmente ya tiene otros servidores MCP). Esto también cubre Cowork — la pestaña de trabajo agéntico en la aplicación de Claude Desktop no es una aplicación separada y no tiene configuración propia; la capa SDK de Desktop en sí puentea los servidores registrados en su configuración hacia la VM sandbox de Cowork automáticamente. Un servidor agregado directamente dentro de una sesión de Cowork, por el contrario, no puede conectarse en absoluto (la VM está aislada del host), por lo que el objetivo de registro es específicamente el archivo de configuración de Desktop. Si algo hasta la instalación del paquete falla, todo lo que la ejecución creó se elimina antes de salir — un intento fallido nunca deja restos que rompan el siguiente; un fallo en la descarga de la base de datos o en cualquiera de los pasos de registro no lo hace, ya que una instalación local funcional que aún no ha descargado su base de datos, o que aún necesita registro manual, no está "fallida". Reinicie Claude Code / Claude Desktop después — un servidor registrado mientras una sesión ya está en ejecución no se recoge hasta que el cliente se reconecta.

Para compilar desde el código fuente en lugar de usar la base de datos de la versión precompilada:

pip install -e ".[dev]"

# Build the index (four stages, run in order; full run crawls
# documentation.neutrinos.com and takes ~25 min)
python -m neutrinos_mcp.ingest.crawl      # stage 1 -> raw/*.html (delta by default; --full to re-fetch everything)
python -m neutrinos_mcp.ingest.extract    # stage 2 -> data/topics.jsonl
python -m neutrinos_mcp.ingest.chunk      # stage 3 -> data/chunks.jsonl
python -m neutrinos_mcp.ingest.index      # stage 4 -> data/neutrinos.db

# Query it
neutrinos-cli search "how do I bind a widget to a data model"
neutrinos-cli search "accessing data models" --product Studio --version 9
neutrinos-cli fetch studio-guide-9/data-binding --json
neutrinos-cli products

# Run the MCP server
neutrinos-mcp

En una máquina Windows restringida, dos cosas separadas pueden bloquear una configuración simple de pip install -e ., y necesitan soluciones diferentes:

• pip.exe en sí se niega a ejecutarse (Access is denied) — use python.exe -m pip install -e . en lugar de un pip install desnudo. El bloqueo está en ese ejecutable contenedor específico; el intérprete no se ve afectado.

• Incluso después de una instalación exitosa, los lanzadores .exe que pip genera para neutrinos-mcp, neutrinos-cli y neutrinos-build (en .venv\Scripts\) pueden encontrar el *idéntico* Access is denied al ejecutarse — confirmado en la propia máquina de desarrollo de este proyecto. Cualquier política que bloquee pip.exe evidentemente bloquea los lanzadores de scripts de consola recién generados en general, no solo a pip.exe por nombre específicamente. La solución es la misma en ambos casos: nunca invoque el .exe, siempre pase por el intérprete — python.exe -m neutrinos_mcp.cli ... en lugar de neutrinos-cli ..., y para el servidor:

  claude mcp add neutrinos-docs --scope user `
    -- "<repo>\.venv\Scripts\python.exe" -m neutrinos_mcp.server

  Esto funciona tanto si pip install -e . tuvo éxito como si no — config.py resuelve cada ruta contra el checkout del código fuente, no contra site-packages, por lo que si el paso de instalación falló por completo, agregue -e PYTHONPATH="<repo>\src" al comando anterior y se comporta de manera idéntica. install.ps1 ya hace esto (consulte a continuación), por lo que esto solo importa si está registrando manualmente.

Related MCP server: knowledge-server

Distribución y actualización automática

.github/workflows/build-db.yml ejecuta las cuatro etapas de ingesta diariamente contra el sitio en vivo y publica data/neutrinos.db como un activo de versión de GitHub (raw/ se almacena en caché entre ejecuciones, por lo que esto es realmente incremental, no un rastreo completo cada día — consulte los comentarios del flujo de trabajo). install.sh clona el repositorio y descarga la última base de datos de versión mediante gh release download; si gh no está disponible, neutrinos_mcp.server._check_for_db_updates_once la descarga la primera vez que el servidor se inicia en su lugar. Esa verificación se ejecuta una vez por proceso, en un hilo en segundo plano, y nunca en la ruta de solicitud — consulte su docstring para saber por qué esa distinción importa (una versión síncrona una vez derribó una conexión MCP en vivo en una red corporativa lenta).

Diseño

.github/workflows/build-db.yml   daily ingest + GitHub release publish (see Distribution above)
install.sh       macOS/Linux installer: clone, venv, pip install -e ., fetch release DB, register
config/          settings.toml (runtime config), publications.yaml (product/version registry)
src/neutrinos_mcp/
  ingest/        crawl -> extract -> chunk -> embed -> build (data/neutrinos.db)
  retrieval/     the ranking pipeline: scope -> BM25/dense -> RRF -> rerank -> collapse -> MMR -> expand
  tools/         MCP tool JSON schemas + handlers (the contract; see plan §8.5)
  kb.py          the query API — server.py and cli.py both call this and nothing else touches SQL
  server.py      FastMCP entry point
  cli.py         terminal adapter over the same contract
eval/            golden-set generation, harness, ablation ladder, two-run regression report
tests/           schema contract tests, corpus-integrity tests (skip without a built index), unit tests
data/            neutrinos.db (built artifact), chroma_db (optional mirror), census.json

Pruebas

pytest                                    # unit + schema tests; integrity tests skip without an index
python -m eval.harness --tag baseline     # full-stack retrieval quality on the golden set
python -m eval.ablate                     # §10.4 rung-by-rung ablation
python -m eval.report before.json after.json --gate   # regression gate, exits 1 on a real regression

Configuración

Todo lo ajustable vive en config/settings.toml, no en código — recuentos de candidatos de recuperación, la constante RRF, lambda MMR, truncamiento/threading del reordenador, ventanas de obsolescencia, presupuestos de tokens. Los pesos del modelo están fijados por nombre y verificados contra el manifiesto de compilación al inicio del servidor (AD-12): servir un índice construido con un modelo de incrustación diferente falla de manera ruidosa en lugar de devolver resultados silenciosamente degradados.

Qué no es esto

No es una superficie general de búsqueda web o ejecución de código, no es un grafo de entidades extraído por LLM, no es un escritor — el servidor devuelve evidencia con citas estables (tokens ref); componer la respuesta es tarea del agente que llama. Consulte el plan §1.4.