docs-rag-mcp

Es ist keine bessere Suchmaschine für deine Dokumente. Es ist ein Filter dafür, was der Agent glauben darf: überholte Entscheidungen verschwinden, die Schwelle sagt „Ich weiß es nicht“, statt zu erfinden, und du siehst immer, warum ein Ergebnis aufgenommen wurde.

Ein MCP-Server, der einen Ordner mit Markdown-Dokumenten jedem MCP-Client (Claude Code, Claude Desktop, Codex, Cursor, Zed…) als ein Suchtool zugänglich macht, search_notes. Alles läuft auf deinem Rechner: Die Embeddings laufen über Ollama, und nichts verlässt deinen Computer – weder beim Indizieren noch bei der Abfrage.

npx -y docs-rag-mcp init      # guided questions -> config.json
npx -y docs-rag-mcp index     # builds the index

Schreibst du die Dokumente, nach denen du suchen wirst? Wie du eine Markdown-Datei strukturierst, entscheidet darüber, wie gut sie gefunden werden kann. Siehe AUTHORING.md – ein kurzer Leitfaden zum Schreiben von Dokumenten, die sich gut abrufen lassen. Fünf Minuten dort verbessern jede Suche.

Was das wirklich anders macht

Das meiste, was dieses Tool tut, tun auch andere lokale RAG-Server. Der Teil, der wirklich selten ist, ist der Dokumentlebenszyklus: Der Index weiß, dass ein Dokoment überholt wurde, und handelt entsprechend.

• Ein Dokument, das in seinem Frontmatter als status: superseded markiert ist, wird standardmäßig nicht mehr zurückgegeben. Wenn es doch zurückkommt – weil du explizit nach der Historie gefragt hast –, kommt es mit der Kennzeichnung [superseded → reference/auth.md; 2026-03-01], sodass der Nachfolger mitgeliefert wird.

• Unterhalb von minScore sagt das Tool „Keine relevanten Ergebnisse (bester Score 0.41, Schwelle 0.55)“, anstatt das nächstbeste Rauschen zu übergeben, das es gefunden hat. Ein Agent, dem ein schlechter Treffer vorgelegt wird, behandelt ihn als Grundwahrheit; ein Mensch hätte gezögert. Die Schwelle ist der Ort, an dem dieses Zögern lebt.

• Jeder Treffer zeigt, warum er da ist: [semantic 0.712], [both 0.712], [exact match]. Keine Blackbox, der du vertrauen musst.

Alle anderen machen Dateifrische – neu synchronisieren, neu indizieren, auf Änderungen achten. Niemand macht Wahrheitsfrische. Darin liegt der ganze Sinn dieses Tools.

Der Rest – nur lokal, Chunking nach Überschriften, SQLite-Speicherung, inkrementelles Indizieren – ist in diesem Bereich Grundvoraussetzung, kein Differenzierungsmerkmal. Er steht in der Feature-Tabelle unten, nicht im Pitch.

Related MCP server: recall-mcp

Wann du das nicht brauchst

Ehrliche Antwort, denn das Feld hat sich weiterentwickelt:

• Für exakte Treffer bei Symbolen hat dein Agent bereits grep, und grep ist schneller und braucht keinen Index. Funktionsnamen, Fehlercodes, Konfigurationsschlüssel: Bau dafür keinen Vektorindex.

• Unterhalb von ein paar Dutzend Dokumenten reicht agentische Suche. Der Agent liest den Dateibaum, führt grep aus, öffnet, was relevant aussieht. Das funktioniert.

• Anthropic hat RAG mit einer Vektordatenbank in Claude Code ausgeliefert und es später entfernt (Mai 2025), weil die agentische Suche besser abschnitt. Cursor, Windsurf, Cline und andere sind denselben Weg gegangen. Das Gegenteil zu behaupten wäre unehrlich.

Was das übersteht und der Grund dafür ist, dass es das gibt: grep findet, was du benennst. Wenn das Dokument es „token refresh window“ nennt und du es „session expiry“ nennst, liefert grep nichts und die semantische Suche liefert das Dokument. Und bei einem langen, mehrschichtigen Korpus kostet semantisches Retrieval weniger Round-Trips und weniger Tokens, als wenn der Agent den Baum abläuft – nicht „bessere Ergebnisse“, günstigere Ergebnisse.

Der Anwendungsbereich ist also eng und spezifisch: ein langer, mehrschichtiger Korpus aus Entscheidungen, Spezifikationen und ADRs in Markdown, mit überholtem Material darin, bei dem der Agent eine tote Entscheidung nicht wiederbeleben soll.

Voraussetzungen

• Node.js ≥ 22.5 – der Index verwendet das eingebaute Modul node:sqlite, es müssen also keine nativen Abhängigkeiten gebaut werden. Je nach Node-Version erscheint auf stderr eine einzeilige Warnung (ExperimentalWarning: SQLite is an experimental feature); sie ist harmlos.

• Ollama mit einem Embedding-Modell. Das Modell wird sowohl zum Erstellen des Index als auch bei jeder Suche benötigt – die Abfrage wird bei jeder Suche neu eingebettet, also muss Ollama immer laufen, wenn der MCP-Server verwendet wird, nicht nur beim Indizieren.

# install Ollama from https://ollama.com, then:
ollama pull bge-m3

Installation

Das veröffentlichte Paket benötigt weder Clone noch Build:

npx -y docs-rag-mcp init      # guided questions -> writes config.json
npx -y docs-rag-mcp index     # builds the index

Wenn du den automatischen Re-Index-Hook verwenden willst, installiere ihn stattdessen global:

npm i -g docs-rag-mcp

npx löst das Paket bei jedem Aufruf neu auf und lädt es bei der ersten Verwendung herunter. Für den MCP-Server ist das irrelevant, der startet einmal pro Sitzung, aber der Hook ist darauf ausgelegt, in null Sekunden zu enden und nach jeder Dateiänderung zu laufen – eine globale Installation beseitigt diesen Overhead vollständig. docs-rag scaffold erkennt eine globale Installation und schreibt die kürzere Befehlsform von selbst.

Du bearbeitest lieber eine Konfiguration von Hand? Kopiere config.example.json nach config.json und setze vaultPath. Alles andere hat sinnvolle Standardwerte.

git clone https://github.com/andreaselmi/docs-rag-mcp
cd docs-rag-mcp
yarn install
yarn setup          # -> config.json
yarn index
yarn build          # compiles to dist/

Die yarn-Skripte bilden eins zu eins auf die Unterbefehle ab (setup→init, serve, index, search, scaffold). Wenn du ein Projekt aus einem Quellcode-Checkout einrichtest, übergib --local: Es schreibt node /abs/path/dist/server.js in die generierten Dateien, statt eines npx-Befehls, der das veröffentlichte Paket auflösen würde, statt deines Arbeitsbaums.

Die Befehle

docs-rag init                 interactive wizard, writes config.json
docs-rag scaffold <dir>       give a project its own scoped instance
docs-rag index                build or update the index
docs-rag search "question"    query the index from the terminal
docs-rag serve                run the MCP server on stdio
docs-rag hook                 Claude Code hook entry point (auto re-index)

Jeder Befehl akzeptiert --config <path>.

Retrieval im Terminal testen

docs-rag search "how do we handle authentication"

Du siehst die passenden Abschnitte, jeweils mit dem Grund, warum sie zurückgegeben wurden:

[semantic 0.712]  reference/auth.md › Auth > How the client refreshes the token
[both 0.688]      decisions/2026-01-session-length.md › Session length  [2026-01-14]
[exact match]     reference/errors.md › Error codes > ERR_TOKEN_EXPIRED

Genau dieses Retrieval wird der MCP-Client verwenden – überprüfe es zuerst hier.

Um für eine einzelne Abfrage Ordner zu überspringen, übergib --exclude (kommagetrennte Pfadfragmente, Groß-/Kleinschreibung wird ignoriert):

docs-rag search "how do we handle auth" --exclude archive,drafts

Das MCP-Tool stellt dasselbe als optionales exclude-Array bei search_notes bereit, sodass du in einem Gespräch sagen kannst: „suche, aber ignoriere den Archiv-Ordner“.

Einige Ordner (archive, plans standardmäßig – siehe defaultExclude) werden bei jeder Abfrage übersprungen, nicht nur, wenn du --exclude übergibst. Um sie für eine Abfrage trotzdem zu durchsuchen, übergib --all (CLI) oder searchAll: true (den Tool-Parameter). Dasselbe Flag bindet auch Dokumente wieder ein, die im Frontmatter als superseded/archived markiert sind und in der Standardsuche ebenfalls ausgeblendet werden.

Zwei Retrieval-Stränge und die Labels

Dense Embeddings sind genau bei den Dingen schwach, von denen eine Spezifikation voll ist: Akronyme, Fehlercodes, Funktionsnamen, Versionsnummern. Deshalb führt jede Abfrage zwei Stränge aus und führt sie zusammen.

• Der semantische Strang ordnet jeden Chunk nach Kosinus-Ähnlichkeit und wendet die Schwellenwerte an.

• Der lexikalische Strang ist eine Volltextsuche (FTS5), die auf die seltenen Begriffe deiner Abfrage beschränkt ist. „Selten“ wird anhand deines eigenen Index gemessen: Ein Begriff qualifiziert sich, wenn er in höchstens max(5, lexicalMaxDocFreq × total chunks) Chunks vorkommt und in nicht mehr als der Hälfte davon. Würde man FTS auf jedes Wort anwenden, würden die Ergebnisse mit Treffern zu häufigen Begriffen überflutet; das Seltenheits-Gate sorgt für die Präzision.

Das Label auf jedem Treffer verrät dir, welcher Strang ihn eingebracht hat:

Nur-lexikalische Treffer sind begrenzt (2 Plätze) und kommen immer nach den semantischen, sodass ein Treffer auf einen seltenen Begrff die Antwrt ergänzen, aber nie übernehmen kann.

Embedding-Modelle

Jedes auf Ollama verfügbare Embedding-Modell funktioniert – setze embedModel in der Konfiguration. bge-m3 ist die Standardeinstellung, und die Schwellenwerte sind standardmäßig darauf abgestimmt.

Ein Wechsel von embedModel erzwingt jetzt einen vollständigen Neuaufbau. Der Index zeichnet auf, welches Modell ihn erstellt hat; das Öffnen mit einem anderen Modell wird verweigert, anstatt stillschweigend gegen inkompatible Vektoren bewertet zu werden. Frühere Versionen hätten sie stillschweigend gemischt und falsche Ergebnisse zurückgegeben, ganz ohne Fehlermeldung.

Manche Modelle benötigen ein Task-Präfix für die Eingabe (nomic-embed-text erwartet search_query: / search_document:). Diese befinden sich in einer kleinen Registry und werden automatisch für dich angewendet. Wenn du ein Modell wählst, das die Registry nicht kennt, meldet docs-rag index das – die Suche funktioniert trotzdem, aber niemand hat die Präfix-Konvention oder die Schwellenwerte dafür verifiziert.

Der Kalibrierungsbericht

Am Ende jedes Index-Laufs erhältst du eine Zeile wie:

Calibration: background noise p99 = 0.421 over 500 random pairs -> suggested minScore 0.45 (in use: 0.55, from the model registry).

Er zieht Stichproben von zufälligen Chunk-Paaren aus deinem eigenen Korpus, die per Definition in keinem Zusammenhang stehen, und berichtet den Ähnlichkeitswert, den sie trotzdem erreichen. Das ist das Grundrauschen des Modells: Alles, was darunter liegt, ist nicht von zwei Dokumenten zu unterscheiden, die nichts miteinander zu tun haben.

Nutze es als Untergrenze, nicht als Einstellung zum Kopieren. Wenn der vorgeschlagene Wert weit über deinem konfigurierten minScore liegt, lässt deine Schwelle Rauschen durch. Liegt er weit darunter, kannst du strenger sein. Ein konfigurierter Wert gewinnt immer – der Bericht überschreibt deine Wahl nie, er sagt dir nur, was er gemessen hat.

Eine Instanz pro Projekt (empfolen)

In der Regel möchtest du eine separate Wissensbasis pro Projekt. Du brauchst keine Kopie dieses Tools pro Projekt – installiere es einmal und gib dann jedem Projekt eine eigene Konfiguration, registriert auf Projektebene:

docs-rag scaffold /path/to/some-project     # asks a few questions (or pass flags)

Für dieses Projekt schreibt es:

• some-project/.rag/config.json – seine Konfiguration (vaultPath ist das Projektverzeichnis; der Index landet daneben in .rag/index.db). Ein erneutes Ausführen von scaffold in einem bereits eingerichteten Projekt erhält diese Datei: abgestimmte pathBoosts und Schwellenwerte bleiben erhalten, und nur Schlüssel, die du bei diesem Lauf explizit als Flags übergeben hast, werden überschrieben.

• some-project/.mcp.json – eine MCP-Registrierung auf Projektebene. Vorhandene Server darin bleiben erhalten. Da der Befehl keinen maschinenspezifischen Pfad enthält, ist diese Datei committbar: Jeder, der das Repo klont, erhält die Suche über dessen Dokumente, ohne manuell etwas installieren zu müssen.

• hängt .rag/index.db* und das bisherige .rag/index.json* an die .gitignore des Projekts an.

• mit --hook: some-project/.claude/settings.local.json, ein Claude-Code-Hook, der nach jeder Markdown-Bearbeitung im Hintergrund neu indiziert (siehe unten).

Dann:

docs-rag index --config /path/to/some-project/.rag/config.json

Nicht-interaktiv, über viele Repos hinweg skriptbar:

docs-rag scaffold /path/to/proj --name proj-docs --include "**/docs/**/*.md" \
  --desc "What's in this project's docs" --hook --yes

Wie --config aufgelöst wird

Jeder Befehl akzeptiert --config. Eine Konfigurationsdatei „trägt“ ihren eigen en Index (ein relativer indexPath wird neben der Konfigurationsdatei aufgelöst), sodass sich Instanzen nie gegenseitig beeinflussen. Auflösungsreihenfolge:

1. Ein absoluter Pfad gewinnt immer.

2. Die Umgebungsvariable CLAUDE_PROJECT_DIR, die Claude Code in der Umgebung der von ihm gestarteten Server und Hooks auf den Projektstamm setzt.

3. Hinaufwandern vom Arbeitsverzeichnis bis zum ersten Vorfahren, in dem der Pfad existiert. Dadurch funktioniert --config .rag/config.json auch auf Clients, die keine eigene Umgebungsvariable setzen.

4. Andernfalls das Arbeitsverzeichnis.

Ganz ohne --config sucht derselbe Aufstieg nach .rag/config.json; daher funktioniert docs-rag search "…" überall in einem mit docs-rag scaffold erzeugten Projekt einfach.

Tragen Sie ${CLAUDE_PROJECT_DIR} nicht selbst in die Args von .mcp.json ein: Claude Code expandiert dort keine Variablen, der Wert würde also wörtlich durchgereicht.

Einbinden in einen MCP-Client

Claude Code

Der Projekt-Scope ist das, was docs-rag scaffold einrichtet. Wenn Sie eine Wissensbasis stattdessen in jeder Sitzung haben möchten, registrieren Sie sie im Benutzer-Scope:

claude mcp add work-docs -s user -- npx -y docs-rag-mcp serve --config ~/vaults/work.json

Prüfen Sie mit claude mcp list, ob der Server verbunden ist, und fragen Sie dann etwas wie "search_notes: Warum haben wir uns für X entschieden?".

Codex CLI, Cursor, Zed und andere MCP-Clients

Der Server ist ein einfacher stdio-MCP-Server, sodass jeder Client, der das Protokoll spricht, ihn ausführen kann. In der ~/.codex/config.toml der Codex CLI:

[mcp_servers.docs-search]
command = "npx"
args = ["-y", "docs-rag-mcp", "serve", "--config", "/absolute/path/to/.rag/config.json"]

Cursor und Zed übernehmen denselben Befehl und dieselben Args in ihren eigenen MCP-Einstellungen.

Ein absoluter --config-Pfad ist hier die richtige Form, weil er von nichts abhängt. Ein relativer Pfad funktioniert ebenfalls über den oben beschriebenen Verzeichnis-Aufstieg – aber dieser Pfad ist durch Konstruktion und Unit-Tests verifiziert, nicht gegen diese Clients getestet. Wenn Sie ihn auf einem von ihnen ausführen, ist ein Bericht willkommen.

Geben Sie jeder Instanz einen eigenen serverName und eine eigene toolDescription: Die Beschreibung ist das, was das Modell liest, um zu entscheiden, ob es das Tool überhaupt aufruft. Beschreiben Sie also, was in dieser Wissensbasis steht, nicht, was das Tool tut.

Den Index aktuell halten

Der Index ist ein Build-Artefakt: index.db, eine SQLite-Datenbank im WAL-Modus, mit ihren -wal- und -shm-Sidecar-Dateien. Führen Sie nach dem Bearbeiten von Dokumenten erneut docs-rag index aus – es ist inkrementell und bettet nur Dateien neu ein, deren mtime sich geändert hat. Ein laufender MCP-Server übernimmt jeden Re-Index automatisch, ohne Neustart. Ein veralteter Index antwortet mit veraltetem Inhalt – schlimmer als ein Fehlschlag.

Automatische Neu-Indexierung (nur Claude Code, optional)

Erstellen Sie das Projekt mit --hook, und ein PostToolUse hook von Claude Code führt den inkrementellen Indexer im Hintergrund erneut aus, sobald Claude eine Markdown-Datei in diesem Projekt schreibt oder bearbeitet – gebündelt auf höchstens einen Lauf alle 30 Sekunden, ohne dass eine Änderung verloren geht. Bearbeitungen außerhalb von Claude Code erfordern weiterhin einen manuellen Lauf.

Der Hook liegt in der .claude/settings.local.json des Projekts (persönlich, nicht committet); löschen Sie den PostToolUse-Eintrag, um ihn zu deaktivieren. Wenn ein Hintergrundlauf nicht funktioniert – meist weil Ollama nicht läuft – erhalten Sie eine Warnung pro Episode in der Sitzung, nicht pro Speicherung, und die Details landen in .rag/hook.log. Andere MCP-Clients führen keine Claude-Code-Hooks aus: Dort müssen Sie von Hand neu indexieren.

Aktualisieren eines vorhandenen Index

Der erste docs-rag index nach einem Upgrade ist eine einmalige vollständige Neueinbettung, nicht der übliche No-op unter einer Sekunde: Das Schema hat die Modell-Identitätstabelle und die FTS5-Tabelle bekommen, und alte Vektoren können nicht übernommen werden. Bei aktiviertem Hook startet er im Hintergrund bei Ihrer ersten Bearbeitung; rechnen Sie also damit, dass dieser erste Lauf Minuten statt einer Sekunde dauert.

Beim Upgrade vom ursprünglichen index.json: Es wird in index.json.bak umbenannt und von Grund auf neu aufgebaut. Löschen Sie die .bak, sobald Sie mit dem Ergebnis zufrieden sind.

Konfigurationsreferenz

Feinabstimmung des Retrievals

Fünf optionale Felder steuern, was zurückkommt (Standardwerte in Klammern):

• defaultExclude (["archive", "plans"]) – Pfad-Teilstrings, die bei jeder Abfrage übersprungen werden. Aufrufer können sie pro Abfrage mit searchAll: true wieder einschließen (CLI: --all); dasselbe Flag schließt auch Dokumente wieder ein, die im Frontmatter als superseded/archived markiert sind.

• minScore (0.55) – absolute Kosinus-Untergrenze. Darunter werden Ergebnisse verworfen und das Tool antwortet mit „No relevant results“ und dem besten abgelehnten Score, statt Rauschen zurückzugeben. Wie Sie den Wert wählen, sehen Sie im Kalibrierungsbericht oben.

• relativeCutoff (0.88) – verwirft Ergebnisse, die unter diesem Anteil des besten verbliebenen Scores liegen.

• lexicalMaxDocFreq (0.01) – wie selten ein Abfragebegriff sein muss, um den lexikalischen Track auszulösen: Er qualifiziert sich, wenn er in höchstens max(5, ratio × total chunks) Chunks vorkommt, und nie, wenn er in mehr als der Hälfte des Korpus vorkommt. Erhöhen Sie den Wert, um mehr Begriffe durchzulassen (mehr exakte Treffer, mehr Rauschen); senken Sie ihn, um den Track wirklich ungewöhnlichen Bezeichnern vorzubehalten.

• pathBoosts ({}) – nur für die Sortierung verwendete Multiplikatoren nach Pfad-Teilstring, z. B. {"reference/": 1.15, "decisions/": 1.1}, um kuratierte Dokumente gegenüber Notizen zu bevorzugen. Boosts setzen die Schwellenwerte nie außer Kraft und ändern den gemeldeten Score nie.

minScore und relativeCutoff sind für bge-m3 abgestimmt. Bei einem anderen Modell führen Sie docs-rag index aus und lesen die Kalibrierungszeile, bevor Sie den Standardwerten vertrauen.

So funktioniert es

Etwa 2.000 Zeilen TypeScript, keine Build-Magie, kein Framework. Der eigentliche Retrieval-Pfad – Chunking, Embedding, Ranking – umfasst etwa 500 davon, und Sie können ihn vollständig lesen.

• src/chunk.ts – zerlegt Markdown anhand von Überschriften, behält die Überschriften-Breadcrumb, entfernt Codeblöcke aus dem eingebetteten Text und zerlegt übermäßig große Abschnitte.

• src/frontmatter.ts – parst status / date / superseded_by und entfernt sie aus dem indexierten Text.

• src/embed.ts + src/models.ts – Ollamas /api/embed, plus das Präfix-Register pro Modell.

• src/store.ts – SQLite-Schema, Versionierung, Modell-Identität, FTS5-Spiegel.

• src/index-docs.ts – durchläuft das Vault, erstellt Chunks, bettet ein, schreibt inkrementell.

• src/calibrate.ts – die Messung der Rauschuntergrenze hinter dem vorgeschlagenen minScore.

• src/lexical.ts – das Seltenheits-Gate: welche Abfragebegriffe eine exakte Suche verdienen.

• src/search.ts – bettet die Abfrage ein, rankt nach Kosinus, wendet Schwellenwerte an, wendet Ausschlüsse und Boosts an und führt den lexikalischen Track zusammen.

• src/server.ts – der MCP-Server, der search_notes über stdio bereitstellt.

• src/scaffold.ts – Generator für Instanzen pro Projekt.

• src/hook.ts – der automatische Re-Index-Hook (Debounce, Sperren, Fehlerhinweise).

• src/cli.ts – die ausführbare Datei docs-rag; eine Unterbefehls-Tabelle und sonst nichts.

Bewusst nicht im Lieferumfang

• Reciprocal-Rank-Fusion für die beiden Tracks. RRF verwirft den absoluten Score, und der absolute Score ist das, worauf minScore – die „Ich weiß nicht“-Schwelle – aufbaut. Die Tracks getrennt zu halten, erhält dieses Versprechen.

• Mehrere Vaults in einer einzigen Instanz (verwenden Sie stattdessen mehrere Konfigurationen).

• Einbindbare Einbettungsanbieter – nur Ollama, um das Nur-lokal-Versprechen zu halten.

• Eine Benutzeroberfläche für Menschen, Zusammenarbeit, Multi-Dokument-Synthese. Das Projekt existiert, damit der Agent, der an Ihrem Code arbeitet, Ihre Entscheidungen kennt – nicht als Ort, an dem Ihr Team Dokumentation liest.

Lizenz

MIT – siehe LICENSE.