project-graph-mcp: Graph für KI-Navigation

project-graph-mcp: Abhängigkeitsgraph für die Navigation von KI-Agenten im Code

Multi-Agent-Entwicklungssysteme erfordern präzise Navigation durch Codebasen. Der project-graph-mcp-Server bietet eine MCP-Schnittstelle, um einen Abhängigkeitsgraphen zu erstellen, der in einem komprimierten JSON-Format vorliegt. Dadurch können Agenten die Projektarchitektur verstehen, ohne Tokens für das Parsen von Quelldateien zu verbrauchen.

Der Server analysiert Dateien, extrahiert Klassen, Methoden, Importe und liefert eine Struktur mit einer Kompression von 10 bis 50-fach. Unterstützung für JavaScript, TypeScript, Python und Go ermöglicht nahtlose Arbeit in polyglotten Projekten.

Projektgerüst im komprimierten Format

Die zentrale Funktion ist die Erzeugung eines "Gerüsts" des Projekts. Der Parser scannt Quelldateien und produziert eine JSON-Ausgabe mit Legenden, Statistiken und einem Knotengraphen.

Beispiel-Ausgabe:

{
  "L": { "SN": "SymNode", "SNG": "SymNodeGraph" },
  "s": { "files": 23, "classes": 10, "functions": 65 },
  "n": { "SN": { "m": 11, "$": 7 }, "SNG": { "m": 16, "$": 5 } },
  "e": 35, "o": 7, "d": 5, "F": 63
}

• L — Legende abgekürzter Namen
• s — Statistiken (Dateien, Klassen, Funktionen)
• n — Knoten mit Methoden (m) und Eigenschaften ($)
• e, o, d, F — Kanten, Objekte, Verzeichnisse, Dateien

Für tiefere Exploration nutzen Sie die Methoden expand und deps, um den Graphen dynamisch zu erweitern.

Mehrsprachiges Parsing ohne AST

Ursprünglich mit Acorn für JavaScript entwickelt. In Version 1.1 wurden Parser für TypeScript, Python und Go mit regulären Ausdrücken hinzugefügt. Dieser Ansatz eliminiert externe Abhängigkeiten und berücksichtigt gleichzeitig sprachspezifische Nuancen.

Eine gemeinsame Hilfsfunktion stripStringsAndComments entfernt Zeichenketten und Kommentare aus dem Code:

// Python
stripStringsAndComments(code, { tripleQuote: true, hashComment: true })

// Go
stripStringsAndComments(code, { backtick: true, templateInterpolation: false })

// TypeScript (Standard)
stripStringsAndComments(code)

Alle Parser vereinigen sich unter ParseResult: Klassen, Funktionen, Importe, Aufrufe. Regex-Muster passen sich an den Projektstil an.

Codeanalyse und Gesundheitswert

Der Server enthält Qualitätsmetriken:

• get_dead_code — erkennt ungenutzten Code
• get_complexity — misst cyclomatische Komplexität
• get_large_files — identifiziert Dateien, die refaktorisiert werden müssen
• get_call_chain — verfolgt Aufrufketten (authMiddleware → validateToken → renderDashboard)

Befehle:

# Legacy- und Abhängigkeitsprüfungen
npx project-graph-mcp outdated .

# Komplexitätsanalyse
npx project-graph-mcp complexity src/

Ergebnisse aggregieren sich zu einem Gesundheitswert (0–100). Antwort-Hinweise schlagen nächste Schritte vor, wie etwa die Überprüfung komplexer Funktionen.

Testchecklisten über JSDoc

Unterstützung für @test- und @expect-Anmerkungen zur Dokumentation von Tests:

/**
 * Benutzer über API erstellen
 * 
 * @test request: POST /api/users mit gültigen Daten
 * @expect status: 201 Created
 */
async createUser(data) { ... }

• get_pending_tests — listet unvollständige Tests auf
• mark_test_passed — markiert Testabschluss

Unterstützt API-, CLI-, Integration- und Browser-Tests.

Anpassung für Frameworks

Integrierte Regelsets für React 18/19, Vue 3, Express 5, TypeScript 5, Symbiote.js (11 Sets, insgesamt 86 Regeln). Automatische Projekt-Erkennung über get_framework_reference.

Für eigene Konventionen:

• Fügen Sie Regeln in das Verzeichnis rules/ hinzu
• Nutzen Sie set_custom_rule vom Agenten aus

Integration mit Agenten-Pools

Bei fraktaler Orchestrierung fordert der IDE-Agent das Gerüst an und delegiert Aufgaben an Worker (Gemini usw.). Jeder Worker führt eine lokale MCP-Instanz zur Navigation mit expand/deps aus.

Nur 132 KB groß, keine externen Abhängigkeiten. Konfiguration für VS Code, Cursor, Zed:

{
  "mcpServers": {
    "project-graph": {
      "command": "npx",
      "args": ["-y", "project-graph-mcp"]
    }
  }
}

Sicherheit und Schutz vor Pfad-Traversierung

Pfad-Validierung nutzt resolve + startsWith, um den Zugriff auf das Arbeitsverzeichnis einzuschränken. Methoden wie expand, deps und get_skeleton erben diesen Schutz – ein Anfrage wie ../../etc/passwd gibt einen Fehler zurück.

Wichtige Vorteile:

• Komprimierte Abhängigkeitsgraphen beschleunigen die Navigation von KI-Agenten
• Regex-basierte Parser für JS/TS/Python/Go ohne externe Bibliotheken
• Gesundheitswert und Aufrufkettenanalyse für gezielte Refaktorisierung
• JSDoc-Checklisten automatisieren die Testdokumentation
• 86 vorgefertigte Regeln für gängige Frameworks direkt nutzbar

— Editorial Team