neutrinos-mcp

Ein Retrieval-MCP-Server über den Neutrinos-Dokumentationskorpus (53 Publikationen, 3.117 Themen, 7.810 indizierte Chunks). Hybride BM25- und dichte Suche, RRF-Fusion, Cross-Encoder-Reranking, kollabierte beinahe Duplikate über Versionen hinweg und bedingte Link-Graph-Erweiterung – entwickelt, um die Frage zu beantworten: „Stimmt das für die Version, die der Benutzer tatsächlich verwendet?“, was ein naives semantisches Such-Setup über Dokumente bei diesem Korpus in mehr als der Hälfte der Fälle falsch beantwortet. Siehe implementation_plan.md für die vollständige Design-Begründung (Architekturentscheidungen, Datenmodell, Evaluierungsmethodik).

Schnellstart

neutrinos-mcp ist ein öffentliches Repository, daher ist keine Authentifizierung erforderlich, um es zu klonen, ein Release abzurufen oder einen der beiden Einzeiler unten auszuführen – nur git und (optional) gh, um die vorgefertigte Datenbank schneller zu ziehen (siehe Distribution unten; ohne gh lädt der Server sie stattdessen automatisch bei der ersten Verwendung, nur nicht während der Installation).

macOS/Linux – eine Zeile:

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

Windows (PowerShell) – eine Zeile:

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

Jeder lädt das Installationsskript selbst (nicht das gesamte Repository) und führt es direkt aus – frühere Versionen dieser README ließen den Einzeiler zuerst ein eigenes git clone ausführen und dann das Skript von innen aufrufen, was den eigenen Klon-Schritt des Skripts duplizierte und auf einem Rechner mit einem veralteten ~/.neutrinos-mcp, das von einem unterbrochenen vorherigen Lauf übrig geblieben war, bei diesem äußeren Klon fehlschlug, bevor das Skript überhaupt die Chance hatte, das Durcheinander zu erkennen und zu bereinigen (git clone weigert sich, gegen ein nicht leeres Ziel zu laufen). Nur das Skript zu holen und ihm die Verwaltung des Zielverzeichnisses selbst zu überlassen, vermeidet diese Klasse von Fehlern vollständig.

Jedes Skript: prüft, ob dort bereits eine Installation existiert und wirklich vollständig ist (ein .install_complete-Marker, der nur am Ende eines früheren erfolgreichen Laufs geschrieben wird) – wenn ja, aktualisiert es an Ort und Stelle (git pull); wenn ein Verzeichnis existiert, aber nicht als vollständig markiert ist (Überreste eines unterbrochenen Laufs, genau das, was den obigen Fehler verursacht hat), wird es entfernt, bevor frisch geklont wird. Anschließend erstellt es eine venv, installiert das Paket (python -m pip install -e . – niemals ein nacktes pip/pip.exe, da diese ausführbare Datei auf einigen restriktiven Unternehmensrechnern von der Ausführungsrichtlinie blockiert wird, während python.exe selbst weiterhin erlaubt ist), lädt die neueste vorgefertigte data/neutrinos.db aus dem neuesten GitHub-Release über gh release download herunter, falls gh installiert ist (andernfalls lädt der laufende Server sie stattdessen bei der ersten Verwendung – siehe Distribution unten), registriert neutrinos-docs bei Claude Code im Benutzerbereich (für jedes Projekt, nicht nur dieses) und fügt einen Eintrag in claude_desktop_config.json von Claude Desktop ein (macOS/Linux/Windows-Pfade werden behandelt; mit einem kleinen Python-Skript zusammengeführt, nicht überschrieben, da diese Datei üblicherweise bereits andere MCP-Server enthält). Dies deckt auch Cowork ab – der Agentic-Work-Tab in der Claude-Desktop-App ist keine separate App und hat keine eigene Konfiguration; die eigene SDK-Schicht von Desktop überbrückt Server, die in seiner Konfiguration registriert sind, automatisch in die Sandbox-VM von Cowork. Ein Server, der direkt in einer Cowork-Sitzung hinzugefügt wird, kann dagegen überhaupt keine Verbindung herstellen (die VM ist vom Host isoliert), weshalb das Registrierungsziel speziell die Konfigurationsdatei von Desktop ist. Wenn irgendetwas bis zur Paketinstallation fehlschlägt, wird alles, was der Lauf erstellt hat, vor dem Beenden entfernt – ein fehlgeschlagener Versuch hinterlässt nie Überreste, die den nächsten Lauf brechen; ein Fehler beim Abrufen der Datenbank oder bei einem der beiden Registrierungsschritte tut das nicht, da eine funktionierende lokale Installation, die nur ihre Datenbank noch nicht abgerufen hat oder noch manuelle Registrierung benötigt, nicht „fehlgeschlagen“ ist. Starten Sie Claude Code / Claude Desktop danach neu – ein Server, der registriert wird, während eine Sitzung bereits läuft, wird erst übernommen, wenn der Client sich wieder verbindet.

Um aus dem Quellcode zu bauen, anstatt die vorgefertigte Release-Datenbank zu verwenden:

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

Auf einem restriktiven Windows-Rechner können zwei getrennte Dinge ein einfaches pip install -e .-Setup blockieren, und sie benötigen unterschiedliche Workarounds:

• pip.exe selbst weigerte sich zu laufen (Access is denied) – verwenden Sie python.exe -m pip install -e . anstelle eines nackten pip install. Die Blockade betrifft diese spezifische Wrapper-ausführbare Datei; der Interpreter ist nicht betroffen.

• Selbst nach einer erfolgreichen Installation können die von pip generierten .exe-Launcher für neutrinos-mcp, neutrinos-cli und neutrinos-build (in .venv\Scripts\) beim tatsächlichen Ausführen auf den *identischen* Access is denied stoßen – bestätigt auf dem eigenen Entwicklungsrechner dieses Projekts. Welche Richtlinie auch immer pip.exe blockiert, blockiert offenbar allgemein frisch generierte Konsolen-Skript-Launcher, nicht speziell pip.exe mit Namen. Die Lösung ist in beiden Fällen dieselbe: Rufen Sie niemals die .exe auf, gehen Sie immer über den Interpreter – python.exe -m neutrinos_mcp.cli ... anstelle von neutrinos-cli ..., und für den Server:

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

  Dies funktioniert unabhängig davon, ob pip install -e . erfolgreich war – config.py löst jeden Pfad gegen den Quellcode-Checkout auf, nicht gegen site-packages. Wenn der Installationsschritt also vollständig fehlgeschlagen ist, fügen Sie -e PYTHONPATH="<repo>\src" zum obigen Befehl hinzu, und er verhält sich identisch. install.ps1 macht dies bereits (siehe unten), das ist also nur relevant, wenn Sie von Hand registrieren.

Related MCP server: knowledge-server

Distribution und automatische Aktualisierung

.github/workflows/build-db.yml führt die vier Ingest-Stufen täglich gegen die Live-Site aus und veröffentlicht data/neutrinos.db als GitHub-Release-Asset (raw/ wird zwischen den Läufen zwischengespeichert, sodass dies tatsächlich inkrementell ist und nicht jeden Tag ein vollständiger Neudurchlauf – siehe die Kommentare im Workflow). install.sh klont das Repository und zieht die neueste Release-Datenbank über gh release download; wenn gh nicht verfügbar ist, lädt neutrinos_mcp.server._check_for_db_updates_once sie stattdessen beim ersten Start des Servers. Diese Prüfung läuft einmal pro Prozess in einem Hintergrundthread und niemals auf dem Anforderungspfad – siehe Docstring, warum diese Unterscheidung wichtig ist (eine synchrone Version davon hat einmal eine Live-MCP-Verbindung in einem langsamen Unternehmensnetzwerk abgerissen).

Layout

.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

Testen

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

Konfiguration

Alles Einstellbare befindet sich in config/settings.toml, nicht im Code – Retrieval-Kandidatenzahlen, die RRF-Konstante, MMR-Lambda, Reranker-Trunkierung/Threading, Veraltungsfenster, Token-Budgets. Modellgewichte sind namentlich festgelegt und werden beim Serverstart gegen das Build-Manifest verifiziert (AD-12): Das Ausliefern eines Index, der mit einem anderen Embedding-Modell erstellt wurde, schlägt laut fehl, anstatt stillschweigend verschlechterte Ergebnisse zu liefern.

Was dies nicht ist

Keine allgemeine Websuche oder Code-Ausführungsoberfläche, kein LLM-extrahierter Entitätsgraph, kein Autor – der Server liefert Belege mit stabilen Zitaten (ref-Tokens); das Verfassen der Antwort ist Aufgabe des aufrufenden Agenten. Siehe Plan §1.4.