Codebase RAG MCP

Ein lokaler, API-Key-freier MCP-Server für Codebasis-Retrieval. Er scannt angegebene Repositories, chunked nach Code-Fenstern und führt ein hybrides Ranking mittels BM25, Symbolnamen, Dateipfaden und exakter Übereinstimmung durch. Er kann direkt an Codex angebunden werden und bietet auch standardmäßige search/fetch-Tools für ChatGPT-Wissensabruf-Szenarien.

Funktionen

• Bevorzugt git ls-files, beachtet verschachtelte .gitignore-Dateien des Repositories; für Nicht-Git-Verzeichnisse wird das Dateisystem gescannt.

• Unterstützt gängige Text-Code-Formate wie TypeScript, JavaScript, Python, Go, Rust, Java, C/C++, C#, Ruby, Shell, SQL, Markdown, Vue, Svelte.

• Automatische Aufteilung von camelCase, snake_case und Pfadbestandteilen; unterstützt gängige chinesische Code-Abfrageerweiterungen, z. B. „用户登录认证“.

• Gibt exakte Dateipfade, Zeilennummern, Code-Ausschnitte mit Zeilennummern, Übereinstimmungsgrund und stabile IDs für fortgesetztes Lesen zurück.

• Pfad-Lesen ist auf das konfigurierte Repository-Stammverzeichnis beschränkt; standardmäßig werden symbolische Links, Binärdateien, Schlüssel, Umgebungsvariablendateien, komprimierter Code und große Dateien übersprungen.

• Unterstützt gleichzeitig lokales stdio und zustandsloses Streamable HTTP /mcp.

Schnellstart

Erfordert Node.js 20 oder höher.

Projekt von GitHub holen:

git clone https://github.com/sudoriaa/codebase-rag-mcp.git
cd codebase-rag-mcp

Abhängigkeiten installieren und bauen:

npm install
npm run build
node dist/cli.js --root C:/path/to/your-repository

Der letzte Befehl startet den stdio MCP-Server, der auf eine Verbindung eines MCP-Clients wartet. Es ist daher normal, dass das Terminal weiterläuft.

Anbindung an Codex

Folgendes in die benutzerspezifische %USERPROFILE%/.codex/config.toml oder in die .codex/config.toml eines vertrauenswürdigen Repositories einfügen:

[mcp_servers.codebase-rag]
command = "C:/Program Files/nodejs/node.exe"
args = [
  "C:/absolute/path/codebase-rag-mcp/dist/cli.js",
  "--root",
  "C:/absolute/path/your-repository"
]
cwd = "C:/absolute/path/codebase-rag-mcp"
startup_timeout_sec = 60
tool_timeout_sec = 120

Für Windows TOML-Pfade wird / empfohlen. command enthält nur die ausführbare Datei, andere Parameter werden in args eingetragen. Die von Desktop-Anwendungen geerbte PATH-Variable kann sich von der in PowerShell unterscheiden; daher empfiehlt sich bei längerer Nutzung die Angabe des absoluten Pfads zu node.exe.

Alternativ kann die Registrierung auch über die CLI erfolgen:

codex mcp add codebase-rag -- "C:\Program Files\nodejs\node.exe" "C:\absolute\path\codebase-rag-mcp\dist\cli.js" --root "C:\absolute\path\your-repository"
codex mcp get codebase-rag --json

Nach der Konfiguration die Codex-Desktop-Anwendung oder IDE-Erweiterung neu starten. Eine Beispielkonfiguration findet sich in examples/codex-config.toml.

HTTP MCP starten

node dist/cli.js --root C:/path/to/your-repository --transport http --host 127.0.0.1 --port 3000

Endpunkte:

• MCP: http://127.0.0.1:3000/mcp

• Health-Check: http://127.0.0.1:3000/health

• Quelldateien referenzieren: http://127.0.0.1:3000/source/:documentId

Standardmäßig wird nur auf dem lokalen Rechner gelauscht. Bei Bereitstellung auf anderen Rechnern sollten auf der Reverse-Proxy-Ebene TLS, Authentifizierung und Zugriffskontrolle hinzugefügt werden. Mit --public-base-url wird die für das Modell erreichbare kanonische Adresse gesetzt.

Wenn direkt auf 0.0.0.0 oder einer anderen nicht-lokalen Adresse gelauscht wird, erfordert der Dienst ein Bearer Token:

$env:CODEBASE_MCP_TOKEN = "replace-with-a-long-random-token"
node dist/cli.js --root C:/path/to/your-repository --transport http --host 0.0.0.0 --port 3000

Der Client muss dann für /mcp und /health den Header Authorization: Bearer <token> senden. Die vom Dienst zurückgegebenen Referenzadressen werden automatisch mit einer HMAC-Signatur versehen, sodass Benutzer die entsprechenden /source-Links direkt öffnen können; der manuelle Zugriff auf unsignierte /source-Adressen erfordert weiterhin das Bearer Token. Bei Veröffentlichung über einen lokalen Reverse-Proxy kann der Dienst weiterhin auf 127.0.0.1 lauschen, während der Proxy die externe Authentifizierung übernimmt.

MCP-Tools

Empfohlene Aufrufreihenfolge:

1. Mit search_code nach Implementierungen und zugehörigen Ausschnitten suchen.

2. Mit get_code_context die hochbewerteten Ausschnitte erweitern.

3. Bei präziser Positionsbestimmung find_symbol verwenden.

4. fetch nur dann einsetzen, wenn die vollständige Datei tatsächlich benötigt wird.

Suchmethode

Der Index läuft vollständig im Arbeitsspeicher des lokalen Rechners:

1. Codedateien werden in maximal 120 Zeilen lange Abschnitte mit 20 Zeilen Überlappung aufgeteilt.

2. Aus gängigen Sprachdeklarationen werden Symbole wie class, interface, type, enum, function, method extrahiert.

3. Der Textkörper wird mittels BM25 abgerufen, Symbole und Pfade werden separat sortiert.

4. Mittels reciprocal-rank fusion werden die Bewertungen von Textkörper, Symbolen, Pfaden und exakten Übereinstimmungen zusammengeführt.

5. Standardmäßig werden pro Datei maximal zwei Ausschnitte zurückgegeben, um zu vermeiden, dass wiederholter Vorlagencode die Ergebnisse dominiert.

Diese Version verwendet keine externe Vektordatenbank und lädt auch keinen Quellcode hoch. Für eine groß angelegte, sprachübergreifende semantische Suche über mehrere Repositories hinweg kann vor oder nach dem vorhandenen CodebaseIndex.search ein Embedding-Retrieval oder ein Reranker hinzugefügt werden; der MCP-Tool-Vertrag muss dabei nicht geändert werden.

Konfiguration

--root PATH
--transport stdio|http
--host HOST
--port PORT
--public-base-url URL
--max-file-bytes N
--max-files N

Die entsprechenden Umgebungsvariablen lauten:

CODEBASE_ROOT
CODEBASE_TRANSPORT
CODEBASE_HOST
CODEBASE_PORT
CODEBASE_PUBLIC_BASE_URL
CODEBASE_MCP_TOKEN
CODEBASE_MAX_FILE_BYTES
CODEBASE_MAX_FILES

Das Standardlimit für eine einzelne Datei beträgt 1 MiB, die maximale Anzahl an Dateien liegt bei 20.000.

Entwicklung und Validierung

npm run build
npm test

Die Tests decken den Indexaufbau, .gitignore, chinesische Abfrageerweiterung, Symbol- und Pfadfilter, Pfadüberschreitungen, standardmäßige search/fetch, In-Memory-MCP, echte stdio-Subprozesse und Streamable HTTP ab.

Der MCP Inspector kann auch direkt den HTTP-Dienst überprüfen:

npx @modelcontextprotocol/inspector

Anschließend Streamable HTTP auswählen und http://127.0.0.1:3000/mcp eintragen.

Die Implementierung folgt dem OpenAI Official MCP Server Guide sowie den standardmäßigen search/fetch-Datenformen.

Aktuelle Grenzen

• Der Index wird nach einem Prozessneustart neu aufgebaut; es gibt keinen persistenten Cache.

• Git-Repositories beachten die Git-Ignore-Regeln vollständig; Nicht-Git-Verzeichnisse lesen derzeit die .gitignore des Stammverzeichnisses.

• Die Symbolextraktion verwendet eine einfache Deklarationsanalyse, die nicht mit einem vollständigen Compiler-AST gleichzusetzen ist.

• Nach Dateiänderungen muss refresh_index aufgerufen werden; die aktuelle Version verfügt über keine Dateiüberwachung.

Lizenz

MIT