clast (Daveelton)

Clang AST MCP服务器

Claude code的语义C++代码索引。通过以下方式减少代币消耗 交付精确的代码块——函数体、类大纲、调用站点-- 而不是让克劳德读取整个文件。

运作原理

1. 索引 --Clang解析你的C++源文件，

类、方法）及其签名、文档注释、源代码正文和 交叉引用。存储在本地SQLite数据库中。

1. 查询 --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.sh

1.生成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工具

输出格式

默认情况下，工具响应使用 紧凑的 呈现的纯文本格式 本机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生成的代码，以及由此带来的所有好处和限制。