codegraph-mcp

Lokaler MCP-Server, der Claude Code (CLI und die VS-Code-Erweiterung) ein abfragbares Modell Ihrer Codebasis bietet – wo Dinge definiert sind, wer was aufruft, was von was abhängt und was in früheren Sitzungen entschieden wurde. Ohne ihn entdeckt der Agent Ihre Architektur in jeder Sitzung neu durch grep und dateiweises Lesen; mit ihm erhalten strukturelle Fragen strukturelle Antworten:

• Sicherere Änderungen – bevor der Agent eine Funktion anfasst, sieht er ihren Einflussbereich (analyze_impact), jede Aufrufstelle (find_callers), jede Erwähnung (find_references) und jedes abhängige Modul (who_imports), anstatt zu bearbeiten, was grep zufällig hervorgebracht hat.

• Schnellere Orientierung – ein einziger repo_map-Aufruf kartiert das Projekt nach Import-Zentralität; find_symbol und semantic_search („wo wird das Auth-Token validiert“) landen direkt im richtigen Code.

• Kontinuität – save_note / recall_notes tragen Entscheidungen und Stolperfallen über Sitzungen hinweg, pro Repository.

• Günstigere Erkundung – als Folge davon liest der Agent Signaturen statt ganzer Dateien (file_skeleton, read_symbol), und ein transparenter Proxy komprimiert den Gesprächsverlauf auf Drahtebene. usage_stats berichtet die gemessenen Einsparungen.

100 % portabel: reines JavaScript + WASM-Grammatiken. Kein node-gyp, keine native Kompilierung. npm install funktioniert identisch unter Windows, macOS und Linux.

Dem Agenten zur Verfügung gestellte Tools

Verständnis & Navigation

Änderungssicherheit

Fokussiertes Lesen

Speicher & Betrieb

Unterstützte Sprachen: JavaScript, TypeScript, TSX, Python, Go, Rust, Java, Ruby, C, C++, C#, PHP, GDScript. Dateien, die der Indexer nicht extrahieren kann, werden gezählt und von repo_map gemeldet, sodass eine partielle Abdeckung immer sichtbar ist.

Related MCP server: MCP Context Manager

Installation

Erfordert Node.js ≥ 20 und Claude Code. Identisch unter Windows / macOS / Linux:

git clone https://github.com/denzharkov/codegraph-mcp
cd codegraph-mcp && npm install
node bin/codegraph-mcp.js install     # registers in Claude Code (user scope)

Das war's – der install-Befehl führt claude mcp add für Sie aus, und der Server funktioniert in der CLI und der VS-Code-Erweiterung (sie teilen sich die MCP-Konfiguration). Überprüfen Sie mit claude mcp list oder /mcp in Claude Code.

Der Server indexiert das Verzeichnis, in dem er gestartet wird (Claude Code startet MCP-Server im Projektverzeichnis) oder den Pfad, der über --root / CODEGRAPH_ROOT angegeben wird. Um ihn auf ein einzelnes Projekt statt auf den Benutzerbereich zu beschränken, fügen Sie diesem Projekt .mcp.json hinzu:

{
  "mcpServers": {
    "codegraph": {
      "command": "node",
      "args": ["/absolute/path/to/codegraph-mcp/bin/codegraph-mcp.js"]
    }
  }
}

Zum Entfernen: node bin/codegraph-mcp.js uninstall.

Null Konfiguration

Keine CLAUDE.md-Bearbeitungen oder Prompt-Anpassungen sind nötig: Der Server liefert seine Nutzungsanleitung („führe analyze_impact aus, bevor du eine Funktion änderst, find_symbol statt grep, file_skeleton bevor du eine Datei liest, …“) über das MCP-instructions-Feld, das Claude Code automatisch in den Kontext des Agenten injiziert, sobald die Verbindung hergestellt ist. Installieren, registrieren, fertig.

Transparenter Proxy (garantierte Einsparungen)

Die oben genannten MCP-Tools sparen nur dann Tokens, wenn der Agent sich entscheidet, sie zu verwenden. Die Proxy-Ebene funktioniert andersherum – wie ContextForge sitzt sie zwischen Claude Code und der Anthropic-API und komprimiert den Datenverkehr unabhängig vom Verhalten des Agenten:

• Verlaufs-Deduplizierung: Wenn das Gespräch identische Tool-Ergebnisse enthält (dieselbe Datei zweimal gelesen, wiederholte Befehlsausgabe), wird jedes Vorkommen nach dem ersten durch einen kurzen Stub ersetzt, bevor die Anfrage Ihren Rechner verlässt. Das erste Vorkommen bleibt wörtlich erhalten, sodass das Modell nichts verliert, was es tatsächlich nutzen könnte – und das Prompt-Cache-Präfix bleibt erhalten (nur der neue Schwanz wird jemals umgeschrieben, sodass Deduplizierung niemals Cache-Fehler bei alten Turns verursacht).

• Skeletonisierung veralteter Lesevorgänge: Wenn eine Datei gelesen, bearbeitet und erneut gelesen wurde, wird die ältere vollständige Kopie im Verlauf durch ihr tree-sitter-Signatur-Skelett ersetzt (Importe + Deklarationen mit Zeilenbereichen); der neueste Lesevorgang bleibt immer wörtlich erhalten. Nicht-Code-Dateien fallen auf Kopf+Schwanz-Kürzung zurück. Transformationen sind reine Funktionen des Inhalts, sodass wiederholte Anfragen identische Bytes erzeugen und der Prompt-Cache nach einer einzigen Umschreibung wieder stabil wird.

• Prompt-Verankerung: Ihre Nachricht wird bevor sie das Modell erreicht transformiert – der sichere Weg. Die Wörter werden nie umgeschrieben; stattdessen fügt der Proxy einen klar beschrifteten Block überprüfbarer Fakten über die Bezeichner hinzu, die die Nachricht erwähnt (Art, file:lines, einzeilige Doku aus dem Symbolgraph). Das Modell startet orientiert, anstatt Tool-Roundtrips zu verbringen, um dieselben Fakten zu entdecken. Nur exakte Groß-/Kleinschreibungs-Treffer werden verankert, nur die neueste Nachricht erhält einen frischen Block, und Blöcke werden memoisiert, sodass der Verlauf für den Prompt-Cache byte-stabil bleibt.

• Auth-Header werden unverändert durchgereicht (API-Schlüssel oder OAuth). Alles, was der Proxy nicht parsen kann, wird wörtlich weitergeleitet. Streaming (SSE) wird durchgereicht.

codegraph-mcp wrap                 # like 'cf wrap claude': proxy + claude in one command
codegraph-mcp proxy --port 3210    # or run the proxy standalone

Für die VS-Code-Erweiterung führen Sie den Proxy aus und richten die Erweiterung über Projekt- oder globale Einstellungen darauf aus:

{ "env": { "ANTHROPIC_BASE_URL": "http://127.0.0.1:3210" } }

Kumulative Einsparungen werden in ~/.codegraph/proxy-stats.json verfolgt und beim Proxy-Start ausgegeben.

CLI-Nutzung

node bin/codegraph-mcp.js index                # index cwd, print stats
node bin/codegraph-mcp.js index --root ~/proj  # index another directory
node bin/codegraph-mcp.js dashboard            # HTML report, opens in browser
node bin/codegraph-mcp.js map                  # interactive architecture map
node bin/codegraph-mcp.js                      # start stdio MCP server (cwd)

Die Architekturkarte (.codegraph/map.html) ist eine geschichtete, C4-artige Ansicht des Repos, vollständig aus dem Index abgeleitet:

• Übersicht – Subsystem-Karten (Top-Level-Verzeichnisse) mit gewichteten Importkanten zwischen ihnen, plus automatisch abgeleitete Startpunkte (Hub, Einstiegspunkt, größtes Modul);

• Subsystem – die Dateien eines Verzeichnisses mit ihren Importkanten und eingeklappten Nachbar-Subsystemen; klicken Sie auf eine Datei, um Abhängige und Abhängigkeiten zu verfolgen, klicken Sie erneut, um hineinzuzoomen;

• Datei – ihre Symbole mit Intra-Datei-Aufrufpfeilen, Importeure und Importe als navigierbare Spalten.

Jede Ebene erzählt Zweck, nicht nur Struktur: Beschreibungen werden aus der eigenen Dokumentation des Codes gezogen – Modul-Docstrings und Header-Kommentare für Dateien und Symbole, READMEs / __init__.py / index.* für Ordner und das Repo selbst – und auf Ordnerkarten, in Tooltips und im Seitenpanel angezeigt.

Ebenen sind tief verlinkbar (#d=src, #f=src/proxy.js), Suche mit /, Esc geht eine Ebene höher, Ziehen verschiebt, Rad zoomt. Eigenständiges HTML, offline.

Das Dashboard (--no-open, um nur die Datei zu schreiben) landet in .codegraph/dashboard.html: Token-Einsparungen, Nutzung pro Tool, indexierte Sprachen und die am meisten importierten Dateien. Statisches HTML, kein Server, hell/dunkel-bewusst. Der Agent kann es auch auf Anfrage über usage_stats mit dashboard=true generieren.

So funktioniert es

• Dateien werden mit tree-sitter-WASM-Grammatiken (tree-sitter-wasms-Paket) über web-tree-sitter geparst – keine plattformspezifischen Binärdateien.

• Der Extraktor durchläuft jeden AST einmal und sammelt Definitionen, Aufrufkanten und Importe gemäß Sprachspezifikation (src/languages.js).

• Der Graph wird in .codegraph/index.json im Ziel-Repo gespeichert; Aktualisierungen sind inkrementell (mtime+Größe) und gedrosselt, sodass Abfragen schnell bleiben.

• node_modules, Build-Ausgaben, vendored und minifizierte Dateien werden übersprungen; einfache .gitignore-Muster im Root werden berücksichtigt.

• semantic_search verwendet ein lokales Einbettungsmodell (all-MiniLM-L6-v2 über transformers.js, eine optionale Abhängigkeit). Bei der ersten Verwendung lädt es ~25 MB in ~/.codegraph/models herunter und cached Symbolvektoren pro Repo in .codegraph/vectors.bin. Offline oder ohne die Abhängigkeit fällt es still auf Schlüsselwortsuche zurück – alles andere funktioniert unabhängig davon.

Fügen Sie .codegraph/ zu Ihrem Projekt-.gitignore hinzu (es ist ein Cache plus Ihre privaten Notizen).

Lizenz

MIT