ModAST-MCP

Module-aware AST MCP server for C++20/23 projects. It uses a persistent clangd process for normal AST/LSP operations and maintains a source-level module index for entities clangd 22 does not expose as symbols (module, export module, and import edges).

Run

npm install
npm run build
node dist/index.js

The server uses MCP stdio transport. In Codex/Claude Desktop, point the command at node dist/index.js.

Windows + Arch WSL

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

Open a workspace first:

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

mode accepts auto, cpp, or modules and defaults to auto. Auto mode checks module extensions and compiler flags such as -x c++-module, -fmodule-output, /interface, and /ifcOutput. Pure cpp mode skips PCM/modmap discovery and never enables clangd's experimental module support.

workspace_open creates an augmented compilation database under the operating system's temporary directory, isolated by a hash of the workspace and build paths. It reuses any .modmap files that CMake/Ninja generated. For consumer translation units without a generated map, it resolves source-level imports against existing PCM files and creates a cached response file containing all known transitive PCM mappings. Keep experimentalModules off for this fast path; enable it only when required PCM files do not exist.

workspace_warm is non-blocking; call workspace_status while it builds the persistent clangd background index. Queries are served from the same clangd session after files are opened.

Development updates and disk writes

The workspace watches only files present in compile_commands.json plus known .pcm and .modmap artifacts. It does not recursively watch or rescan every file in the repository.

• Editing a watched source updates the module graph in memory. Open documents are sent to clangd through textDocument/didChange; no ModAST cache file is written.
• Editing a module interface marks its module as stale. AST, definition, references, and diagnostics responses include a warning until the corresponding PCM is rebuilt.
• PCM, modmap, and compilation database changes are debounced into one workspace refresh. This handles the normal edit -> Ninja/CMake build -> query loop.
• New translation units are picked up by workspace_refresh after the build system updates compile_commands.json.
• Generated compilation databases and response files use content comparison. Identical content is never rewritten. workspace_status.compileDatabase reports diskWrites and cacheFilesReused for the latest preparation.
• Temporary workspace caches are pruned on open using a 14-day TTL, 20 inactive-workspace limit, and 512 MB inactive-cache limit. The active workspace is retained and cleanup results are exposed as workspace_status.cacheCleanup.
• Semantic queries wait for an in-progress refresh, so they run against the replacement clangd process rather than a stopped client.

workspace_status also reports sourceChanges, lastChangeAt, watchedFiles, staleModules, and refreshes so an Agent can decide whether cross-module data is current.

Both long-running tools and workspace_open emit MCP notifications/progress when the client sends a progress token. Slow clangd requests emit a heartbeat every five seconds. workspace_status is also safe to poll: it includes phase, progressCompleted, progressTotal, elapsedMs, and the last 20 human-readable events.

Tools

• workspace_open, workspace_status, workspace_refresh, workspace_warm
• module_search, module_graph
• module_quality, format
• ast, document_symbols, workspace_symbols
• definition, references, diagnostics

Line and character arguments are 1-based. For Agent use, definition and references accept a needle plus an occurrence, avoiding manual position calculations.

format delegates to clangd/clang-format and honors the project's .clang-format. It is preview-only by default and returns the formatted text plus LSP edits. apply=true is required to write the source. Before applying, the server verifies that the file still matches the clangd snapshot; concurrent editor changes cause a conflict error instead of being overwritten. Successful writes use a same-directory temporary file and atomic rename, then synchronize the persistent clangd document.

module_quality uses clangd AST nodes rather than source regexes. It reports substantial function bodies in module interface units, ignores templates and constexpr/consteval definitions, and warns when a named module has no .cpp, .cc, or .cxx implementation or partition implementation unit. A second non-exported .cppm does not satisfy this architecture check. Thresholds and scan concurrency are configurable.

Design notes

• clangd's textDocument/ast is returned unchanged under clangdAst.
• A synthetic moduleContext adds module units and imports because clangd 22 returns no AST node for export module ... and does not index module names as workspace symbols.
• Module parsing is deliberately source-based and independent of compiler vendor. The clangd process remains the semantic authority for C++ declarations.
• When transport is wsl, Windows workspace paths are converted to /mnt/<drive>/... only at the process boundary; MCP responses are mapped back to Windows paths.
• Closing MCP stdio, ending stdin, or sending SIGINT/SIGTERM closes file watchers and gracefully shuts down clangd.

Verification

npm test runs unit and lifecycle tests. Set MODAST_INTEGRATION=1 to add a live clangd test; it uses Arch WSL on Windows and native clangd on Linux. GitHub Actions tests Node.js 20 and 24 on Windows and Linux, runs the live Linux clangd test, and rejects high-severity production dependency advisories.