Clang AST MCP服务器
Claude code的语义C++代码索引。通过以下方式减少代币消耗 交付精确的代码块——函数体、类大纲、调用站点-- 而不是让克劳德读取整个文件。
运作原理
- 索引 --Clang解析你的C++源文件，
类、方法）及其签名、文档注释、源代码正文和 交叉引用。存储在本地SQLite数据库中。
- 查询 --Claude Code调用MCP工具(
ast_search,ast_get_symbol等等）
只检索它需要的代码。没有文件读取，没有grep，没有glob。
先决条件
- Python 3.11+
- 李丁。 （系统包：
apt install libclang-dev或brew install llvm) - python 3叮当响 （匹配版本：
apt install python3-clang-18) - compile_commands.json 来自CMake（推荐但不是必需的）
快速开始
0.克隆到您的C++项目中
从项目根目录克隆repo并将其添加到 .gitignore 所以两者都不 该工具及其索引数据库都不会提交给您的项目：
git clone git@github.com:daveelton/clast.git
echo "clast/" >> .gitignore
./clast/bootstrap.sh1.生成compile_commands.json（如果使用CMake）
cmake -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON对于CLion:设置>构建、执行、部署>CMake--append -DCMAKE_EXPORT_COMPILE_COMMANDS=ON 转到“CMake选项”字段，然后重新生成。
2.为你的项目建立索引
有两种方法可以运行索引器：独立运行或通过CMake运行。
选项A：独立（最简单）
直接从命令行运行索引器：
cd clast
./index.sh # auto-finds compile_commands.json
./index.sh /path/to/cmake-build-debug # or specify the build dir
./index.sh --force # re-index everything当所有标头在索引之前都存在时，这很有效。如果你的项目 在构建过程中生成标头（例如JUCE的 JuceHeader.h)，先建， 然后运行 index.sh.
选项B：CMake集成
对于已生成标头的项目，将索引器集成为CMake构建 目标。这保证了索引在构建后运行，因此所有标头都存在。
添加到您的 CMakeLists.txt:
include(clast/cmake/ClastIndex.cmake)
add_clast_index(YourMainTarget)然后显式构建索引：
cmake --build cmake-build-debug --target ast-index这 ast-index 目标取决于你的主要目标，所以它会建立你的 如果需要，请先进行项目。这不是默认设置的一部分 all 目标--它 只有当你要求的时候才会跑。
3.配置克劳德代码
添加到您的项目 .mcp.json:
{
"mcpServers": {
"clang-ast": {
"command": "bash",
"args": ["-c", "./clast/.venv/bin/python3 -m clang_ast_mcp serve --db ./clast/.ast-index.db 2>>./clast/mcp.log"],
"env": {
"LIBCLANG_PATH": "/opt/homebrew/opt/llvm/lib/libclang.dylib"
}
}
}
}日志附加到 ./clast/mcp.log --使用 tail -f ./clast/mcp.log 到 实时观察工具调用、响应大小和时间。
bootstrap.sh 将提供在您的项目中附加clast说明 CLAUDE.md。如果您更喜欢手动操作，请复制以下内容 CLAUDE级添加剂.md 进入你的项目 CLAUDE.md.
MCP工具
| 工具 | 目的 | 何时使用 |
|---|---|---|
ast_search | 关键字/自然语言搜索 | “参数平滑是如何工作的？” |
ast_get_symbol | 按名称获取完整定义 | “显示MyPlugin:：processBlock” |
ast_get_outline | 类/文件大纲（无正文） | “MyPlugin的接口是什么？” |
ast_get_references | 查找呼叫站点 | “什么呼叫parameterChanged？” |
ast_get_hierarchy | 继承树 | “什么源于AudioProcessor？” |
ast_index | 重新索引项目 | 更改文件后 |
ast_status | 索引统计 | 检查索引是否已加载 |
输出格式
默认情况下，工具响应使用 紧凑的 呈现的纯文本格式 本机C++语法而不是JSON字段名，每节省约3000-5000个令牌 会议。看 docs/compact-response-format.md 了解完整的规格和原理。
要切换到JSON输出，请使用CLI标志：
python3 -m clang_ast_mcp serve --db .ast-index.db --format json或者环境变量：
AST_OUTPUT_FORMAT=json python3 -m clang_ast_mcp serve --db .ast-index.db在 .mcp.json:
{
"mcpServers": {
"clang-ast": {
"command": "bash",
"args": ["-c", "./clast/.venv/bin/python3 -m clang_ast_mcp serve --db ./clast/.ast-index.db 2>>./clast/mcp.log"],
"env": {
"AST_OUTPUT_FORMAT": "json",
"LIBCLANG_PATH": "/opt/homebrew/opt/llvm/lib/libclang.dylib"
}
}
}
}格式是服务器范围的——用不同的设置重新启动以进行切换。这 使A/B比较变得简单：在每种模式下运行一个完整的会话并进行比较 Claude Code报告中的令牌使用情况。
建筑
compile_commands.json
│
▼
┌──────────┐ ┌───────────┐ ┌──────────┐
│ libclang │────▶│ SQLite │────▶│ BM25 │
│ indexer │ │ index │ │ search │
└──────────┘ └───────────┘ └──────────┘
│
▼
┌───────────┐
│ MCP tools │◀──── Claude Code
│ (stdio) │
└───────────┘- 索引器 用途
libclang解析每个翻译单元，提取符号
使用USR（统一符号分辨率ID）进行精确的交叉引用
- 存储 是SQLite，对符号名称、USR和文件路径有索引
- 搜索 在符号名称、签名和文档注释上使用BM25关键字排名
- MCP服务器 使用FastMCP和stdio传输（克劳德代码本地）
增量重新索引
索引器跟踪文件内容哈希。跑步 ast_index 再次仅重新解析 已更改的文件。使用 --force 重新索引所有内容。
索引第三方标头
对于JUCE或类似的大型框架，只索引公共标头：
clang-ast-mcp index /path/to/JUCE/modules \
--db /path/to/your/project/.ast-index.db这使Claude可以访问JUCE类大纲和API签名，而无需 索引实现文件。
Xcode项目
Xcode不生成 compile_commands.json 本地。您或许可以使用 熊 通过拦截生成一个 实际构建期间的编译器调用：
brew install bear
bear -- xcodebuild -project Foo.xcodeproj -scheme Foo build然后运行 ./clast/index.sh 像往常一样，它将找到生成的 compile_commands.json 在项目根中。
LLM生成的代码警告Emptor
这个项目的内容主要包含LLM生成的代码，以及由此带来的所有好处和限制。