ModAST-MCP

面向 C++20/23 项目的模块感知 AST MCP 服务器。它使用持久的 clangd 进程处理常规 AST/LSP 操作，并针对 clangd 22 不将其作为符号暴露的实体（module、export module 和导入边）维护一个源码级模块索引。

运行

npm install
npm run build
node dist/index.js

服务器使用 MCP stdio 传输。在 Codex/Claude Desktop 中，将命令指向 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"]
    }
  }
}

先打开工作区：

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

mode 接受 auto、cpp 或 modules，默认为 auto。自动模式会检查模块扩展名和编译器标志，如 -x c++-module、-fmodule-output、/interface 和 /ifcOutput。纯 cpp 模式会跳过 PCM/modmap 发现，并且永远不会启用 clangd 的实验性模块支持。

workspace_open 在操作系统的临时目录下创建增强型编译数据库，并通过工作区和构建路径的哈希进行隔离。它会复用 CMake/Ninja 生成的任何 .modmap 文件。对于没有生成映射的消费翻译单元，它会根据现有 PCM 文件解析源码级导入，并创建一个包含所有已知传递 PCM 映射的缓存响应文件。对于这种快速路径，请保持 experimentalModules 关闭；仅在所需 PCM 文件不存在时才启用它。

workspace_warm 是非阻塞的；在它构建持久化 clangd 后台索引时，可调用 workspace_status。文件打开后，查询由同一个 clangd 会话提供。

开发更新与磁盘写入

工作区仅监视 compile_commands.json 中存在的文件以及已知的 .pcm 和 .modmap 工件。它不会递归监视或重新扫描仓库中的每个文件。

• 编辑受监视的源文件会更新内存中的模块图。打开的文档通过 textDocument/didChange 发送给 clangd；不会写入 ModAST 缓存文件。

• 编辑模块接口会将其模块标记为过期。AST、定义、引用和诊断响应会包含警告，直到相应的 PCM 被重建。

• PCM、modmap 和编译数据库的更改会去抖为一次工作区刷新。这处理了常规的编辑 -> Ninja/CMake 构建 -> 查询循环。

• 构建系统更新 compile_commands.json 后，workspace_refresh 会拾取新的翻译单元。

• 生成的编译数据库和响应文件使用内容比较。相同的内容永远不会被重写。workspace_status.compileDatabase 报告最近一次准备的 diskWrites 和 cacheFilesReused。

• 临时工作区缓存在打开时按 14 天 TTL、20 个非活动工作区限制和 512 MB 非活动缓存限制进行清理。活动工作区会被保留，清理结果通过 workspace_status.cacheCleanup 暴露。

• 语义查询会等待正在进行的刷新完成，因此它们针对替换后的 clangd 进程运行，而不是针对已停止的客户端。

workspace_status 还报告 sourceChanges、lastChangeAt、watchedFiles、staleModules 和 refreshes，以便 Agent 决定跨模块数据是否是最新的。

当客户端发送进度令牌时，长时间运行的工具和 workspace_open 都会发出 MCP notifications/progress。缓慢的 clangd 请求每五秒发出一次心跳。workspace_status 也可以安全地轮询：它包含 phase、progressCompleted、progressTotal、elapsedMs 以及最近 20 个人类可读的 events。

工具

• workspace_open、workspace_status、workspace_refresh、workspace_warm

• module_search、module_graph

• module_quality、format

• ast、document_symbols、workspace_symbols

• definition、references、diagnostics

行和字符参数从 1 开始。对于 Agent 使用，definition 和 references 接受 needle 加 occurrence，避免手动计算位置。

format 委托给 clangd/clang-format，并遵循项目的 .clang-format。它默认仅预览，并返回格式化文本加上 LSP 编辑。写入源文件需要 apply=true。在应用之前，服务器会验证文件是否仍与 clangd 快照匹配；并发编辑器更改会导致冲突错误，而不是被覆盖。成功写入使用同目录临时文件和原子重命名，然后同步持久化的 clangd 文档。

module_quality 使用 clangd AST 节点而不是源码正则表达式。它报告模块接口单元中的实质性函数体，忽略模板和 constexpr/consteval 定义，并在命名模块没有 .cpp、.cc 或 .cxx 实现或分区实现单元时发出警告。第二个非导出的 .cppm 不满足此架构检查。阈值和扫描并发性是可配置的。

设计说明

• clangd 的 textDocument/ast 在 clangdAst 下原样返回。

• 合成的 moduleContext 添加模块单元和导入，因为 clangd 22 对 export module ... 不返回 AST 节点，并且不将模块名称索引为工作区符号。

• 模块解析特意基于源码，并且独立于编译器供应商。clangd 进程仍然是 C++ 声明的语义权威。

• 当 transport 为 wsl 时，Windows 工作区路径仅在进程边界转换为 /mnt/<drive>/...；MCP 响应会映射回 Windows 路径。

• 关闭 MCP stdio、结束 stdin 或发送 SIGINT/SIGTERM 会关闭文件监视器并优雅地关闭 clangd。

验证

npm test 运行单元测试和生命周期测试。设置 MODAST_INTEGRATION=1 以添加实时 clangd 测试；它在 Windows 上使用 Arch WSL，在 Linux 上使用原生 clangd。GitHub Actions 在 Windows 和 Linux 上测试 Node.js 20 和 24，运行实时 Linux clangd 测试，并拒绝高严重性的生产依赖公告。