ModAST-MCP
Provides tools for analyzing C++20/23 projects, including module-aware AST queries, symbol navigation, definitions, references, diagnostics, and code formatting.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ModAST-MCP Update the workspace and explain why the net module interface is stale."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.jsThe server uses MCP stdio transport. In Codex/Claude Desktop, point the command at node dist/index.js.
Related MCP server: clangd-mcp
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_refreshafter the build system updatescompile_commands.json.Generated compilation databases and response files use content comparison. Identical content is never rewritten.
workspace_status.compileDatabasereportsdiskWritesandcacheFilesReusedfor 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_warmmodule_search,module_graphmodule_quality,formatast,document_symbols,workspace_symbolsdefinition,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/astis returned unchanged underclangdAst.A synthetic
moduleContextadds module units and imports because clangd 22 returns no AST node forexport 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
transportiswsl, 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.
Available Tools
14 toolsastA
Return clangd's detailed AST plus synthetic module context for module declarations/imports.
Inputs: file (required), endLine, startLine, endCharacter, +1 more.
definitionB
Find a declaration/definition across module BMIs. Position values are 1-based; needle is often easier for agents.
Inputs: file (required), line, needle, character, +2 more.
diagnosticsB
Parse a file and return clangd diagnostics after module resolution.
Inputs: file (required).
document_symbolsB
List declarations in a C++ source or module unit using clangd's hierarchical symbol view.
Inputs: file (required).
formatA
Format C++/module source with clangd. Preview is the default; apply=true explicitly writes the file and updates clangd.
Inputs: file (required), apply, tabSize, insertSpaces.
module_graphC
Resolve a module to interface units, imports, dependencies, and importing translation units.
Inputs: name (required), transitive.
module_qualityA
Use clangd AST to find non-trivial definitions in module interfaces and verify matching .cpp implementation units.
Inputs: file, concurrency, minBodyLines, minStatements.
module_searchA
Search named C++ modules and partitions, including entities clangd does not expose as symbols.
Inputs: query (required).
referencesB
Find indexed references to a declaration across module units and translation units.
Inputs: file (required), line, needle, character, +2 more.
workspace_openA
Open a C++ workspace and start one persistent module-aware clangd process.
Inputs: root (required), buildDirectory (required), mode, transport, +3 more.
workspace_refreshB
Reload compile commands and rebuilt PCM/modmap artifacts, restarting clangd without rewriting unchanged cache files.
Inputs: reason.
workspace_statusA
Return clangd readiness, warmup progress, module counts, PCM/modmap coverage, and recent errors.
Inputs: no named parameters.
workspace_symbolsB
Search clangd symbols and named C++ modules in one request.
Inputs: query (required).
workspace_warmA
Start non-blocking AST warmup. Poll workspace_status; other MCP tools remain available.
Inputs: files, limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
The tools sort into recognizable groups: workspace lifecycle, module graph/quality, AST/symbol queries, navigation, and diagnostics. There is some boundary overlap between module_search and workspace_symbols, and between ast and document_symbols, but the descriptions are usually enough to steer an agent to the right tool.
The naming is readable and uniformly snake_case, but is not strongly consistent: workspace_open and workspace_refresh are verb-focused, while ast, definition, references, diagnostics, module_quality, and document_symbols follow different naming styles. The workspace_* and module_* prefixes help, but there is no single predictable verb_noun pattern across the surface.
14 tools is reasonable for a C++ module-aware clangd server covering workspace lifecycle, module graph analysis, AST inspection, formatting, navigation, and diagnostics. It is on the larger side, but each tool addresses a meaningful aspect of the domain rather than introducing pure redundancy.
The tool surface covers workspace readiness, module discovery and dependency resolution, AST/symbol queries, formatting, cross-file navigation, and diagnostics. Minor gaps include a way to close/discard a workspace and any MCP-level operation to modify module units, but these do not block core read/build/analyze workflows.
Maintenance
Related MCP Connectors
Lean 4 MCP server: compile, prove theorems, and formalize math with Mathlib.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Repository knowledge graph MCP server for codebase understanding and debugging.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides C++ code intelligence tools for AI agents via the Model Context Protocol, enabling symbol navigation, type information, and diagnostics.950Mozilla Public 2.0
- AlicenseAqualityDmaintenanceMCP server for C/C++ code analysis using clangd and clang tools, providing diagnostics, symbol search, include analysis, function listing, and code formatting.5MIT
- AlicenseNot gradedqualityBmaintenanceA persistent code-intelligence MCP server that builds a queryable knowledge graph of your codebase, enabling AI assistants to perform cross-file structural reasoning, dependency analysis, and blast radius detection.9MIT
- AlicenseNot gradedqualityDmaintenanceMulti-language code intelligence MCP server providing structured code analysis including symbol search, references, hierarchies, and change impact. Supports 25 languages with persistent indexing and LSP integration.52 npmMIT