ModAST-MCP

Modulbewusster AST-MCP-Server für C++20/23-Projekte. Er verwendet einen persistenten clangd-Prozess für normale AST/LSP-Operationen und pflegt einen Modulindex auf Quellebene für Entitäten, die clangd 22 nicht als Symbole bereitstellt (module, export module und Importkanten).

Run

npm install
npm run build
node dist/index.js

Der Server verwendet MCP-stdio-Transport. In Codex/Claude Desktop zeigen Sie den Befehl auf node dist/index.js.

Related MCP server: clangd-mcp-server

Windows + Arch WSL

{
  "mcpServers": {
    "modast": {
      "command": "node",
      "args": ["D:/runtime/mcp/ModAST-MCP/dist/index.js"]
    }
  }
}

Öffnen Sie zuerst einen Arbeitsbereich:

{
  "root": "E:/github/cnetmod",
  "buildDirectory": "E:/github/cnetmod/cmake-build-release-wsl",
  "transport": "wsl",
  "wslDistro": "Arch",
  "experimentalModules": false
}

mode akzeptiert auto, cpp oder modules und ist standardmäßig auf auto eingestellt. Der Auto-Modus prüft Modulerweiterungen und Compiler-Flags wie -x c++-module, -fmodule-output, /interface und /ifcOutput. Der reine cpp-Modus überspringt die PCM/modmap-Erkennung und aktiviert niemals die experimentelle Modulunterstützung von clangd.

workspace_open erstellt eine erweiterte Compilation Database im temporären Verzeichnis des Betriebssystems, isoliert durch einen Hash der Arbeitsbereichs- und Build-Pfade. Es verwendet alle .modmap-Dateien wieder, die CMake/Ninja generiert haben. Für Consumer-Übersetzungseinheiten ohne generierte Zuordnung löst es Importe auf Quellebene gegen vorhandene PCM-Dateien auf und erstellt eine zwischengespeicherte Response-Datei mit allen bekannten transitiven PCM-Zuordnungen. Lassen Sie experimentalModules für diesen schnellen Pfad deaktiviert; aktivieren Sie es nur, wenn die erforderlichen PCM-Dateien nicht vorhanden sind.

workspace_warm ist nicht blockierend; rufen Sie workspace_status auf, während es den persistenten clangd-Hintergrundindex aufbaut. Abfragen werden nach dem Öffnen der Dateien aus derselben clangd-Sitzung bedient.

Entwicklungsaktualisierungen und Datenträgerschreibvorgänge

Der Arbeitsbereich überwacht nur Dateien, die in compile_commands.json vorhanden sind, sowie bekannte .pcm- und .modmap-Artefakte. Er überwacht oder scannt nicht rekursiv jede Datei im Repository.

• Das Bearbeiten einer überwachten Quelle aktualisiert den Modulgraphen im Speicher. Geöffnete Dokumente werden über textDocument/didChange an clangd gesendet; es wird keine ModAST-Cache-Datei geschrieben.

• Das Bearbeiten einer Modulschnittstelle markiert ihr Modul als veraltet. AST-, Definitions-, Referenz- und Diagnoseantworten enthalten eine Warnung, bis das entsprechende PCM neu erstellt wurde.

• PCM-, modmap- und Compilation-Database-Änderungen werden zu einer Arbeitsbereichsaktualisierung entprellt. Dies behandelt die normale Schleife Bearbeiten -> Ninja/CMake-Build -> Abfrage.

• Neue Übersetzungseinheiten werden von workspace_refresh übernommen, nachdem das Build-System compile_commands.json aktualisiert hat.

• Generierte Compilation Databases und Response-Dateien verwenden Inhaltsvergleich. Identischer Inhalt wird nie neu geschrieben. workspace_status.compileDatabase meldet diskWrites und cacheFilesReused für die letzte Vorbereitung.

• Temporäre Arbeitsbereichs-Caches werden beim Öffnen bereinigt, mit einer TTL von 14 Tagen, einem Limit von 20 inaktiven Arbeitsbereichen und einem Limit von 512 MB für inaktive Caches. Der aktive Arbeitsbereich wird beibehalten und die Bereinigungsergebnisse werden als workspace_status.cacheCleanup bereitgestellt.

• Semantische Abfragen warten auf eine laufende Aktualisierung, sodass sie gegen den Ersatz-clangd-Prozess statt gegen einen gestoppten Client ausgeführt werden.

workspace_status meldet außerdem sourceChanges, lastChangeAt, watchedFiles, staleModules und refreshes, damit ein Agent entscheiden kann, ob modulübergreifende Daten aktuell sind.

Sowohl langlaufende Tools als auch workspace_open senden MCP-notifications/progress, wenn der Client ein Fortschritts-Token sendet. Langsame clangd-Anfragen senden alle fünf Sekunden einen Heartbeat. workspace_status ist auch sicher abzufragen: Es enthält phase, progressCompleted, progressTotal, elapsedMs und die letzten 20 menschenlesbaren events.

Werkzeuge

• workspace_open, workspace_status, workspace_refresh, workspace_warm

• module_search, module_graph

• module_quality, format

• ast, document_symbols, workspace_symbols

• definition, references, diagnostics

Zeilen- und Zeichenargumente sind 1-basiert. Für die Agent-Nutzung akzeptieren definition und references eine needle plus ein occurrence, wodurch manuelle Positionsberechnungen vermieden werden.

format delegiert an clangd/clang-format und respektiert die .clang-format-Datei des Projekts. Es ist standardmäßig nur als Vorschau verfügbar und gibt den formatierten Text plus LSP-Bearbeitungen zurück. apply=true ist erforderlich, um die Quelle zu schreiben. Vor dem Anwenden prüft der Server, ob die Datei noch mit dem clangd-Snapshot übereinstimmt; gleichzeitige Editor-Änderungen verursachen einen Konfliktfehler, anstatt überschrieben zu werden. Erfolgreiche Schreibvorgänge verwenden eine temporäre Datei im selben Verzeichnis und atomares Umbenennen und synchronisieren dann das persistente clangd-Dokument.

module_quality verwendet clangd-AST-Knoten statt Quell-Regexen. Es meldet umfangreiche Funktionsrümpfe in Modulschnittstelleneinheiten, ignoriert Templates und constexpr/consteval-Definitionen und warnt, wenn ein benanntes Modul keine .cpp-, .cc- oder .cxx-Implementierung oder Partitionsimplementierungseinheit hat. Eine zweite nicht exportierte .cppm-Datei erfüllt diese Architekturprüfung nicht. Schwellenwerte und Scan-Parallelität sind konfigurierbar.

Designhinweise

• Das textDocument/ast von clangd wird unverändert unter clangdAst zurückgegeben.

• Ein synthetischer moduleContext fügt Moduleinheiten und Importe hinzu, da clangd 22 keinen AST-Knoten für export module ... zurückgibt und Modulnamen nicht als Arbeitsbereichssymbole indiziert.

• Die Modulanalyse ist bewusst quellenbasiert und unabhängig vom Compiler-Hersteller. Der clangd-Prozess bleibt die semantische Autorität für C++-Deklarationen.

• Wenn transport wsl ist, werden Windows-Arbeitsbereichspfade nur an der Prozessgrenze in /mnt/<drive>/... umgewandelt; MCP-Antworten werden zurück auf Windows-Pfade abgebildet.

• Das Schließen von MCP-stdio, das Beenden von stdin oder das Senden von SIGINT/SIGTERM schließt Dateiüberwacher und fährt clangd ordnungsgemäß herunter.

Verifizierung

npm test führt Unit- und Lebenszyklustests aus. Setzen Sie MODAST_INTEGRATION=1, um einen Live-clangd-Test hinzuzufügen; er verwendet Arch WSL unter Windows und natives clangd unter Linux. GitHub Actions testet Node.js 20 und 24 unter Windows und Linux, führt den Live-Linux-clangd-Test aus und lehnt Sicherheitshinweise mit hoher Schwere für Produktionsabhängigkeiten ab.