Clang AST MCP Server

Semantic C++ code index for Claude Code. Reduces token consumption by delivering precise code chunks — function bodies, class outlines, call sites — instead of making Claude read entire files.

How it works

1. Index — Clang parses your C++ source files, extracting symbols (functions, classes, methods) with their signatures, doc comments, source bodies, and cross-references. Stored in a local SQLite database.

2. Query — Claude Code calls MCP tools (ast_search, ast_get_symbol, etc.) to retrieve just the code it needs. No file reading, no grep, no glob.

Prerequisites

• Python 3.11+
• libclang (system package: apt install libclang-dev or brew install llvm)
• python3-clang (matching version: apt install python3-clang-18)
• compile_commands.json from CMake (recommended but not required)

Quick start

0. Clone into your C++ project

From your project root, clone the repo and add it to .gitignore so neither the tool nor its index database get committed to your project:

git clone git@github.com:daveelton/clast.git
echo "clast/" >> .gitignore
./clast/bootstrap.sh

1. Generate compile_commands.json (if using CMake)

cmake -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

For CLion: Settings > Build, Execution, Deployment > CMake — append -DCMAKE_EXPORT_COMPILE_COMMANDS=ON to the "CMake options" field, then rebuild.

2. Index your project

There are two ways to run the indexer: standalone or via CMake.

Option A: Standalone (simplest)

Run the indexer directly from the command line:

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

This works well when all headers exist before indexing. If your project generates headers during the build (e.g. JUCE's JuceHeader.h), build first, then run index.sh.

Option B: CMake integration

For projects with generated headers, integrate the indexer as a CMake build target. This guarantees the index runs after the build, so all headers exist.

Add to your CMakeLists.txt:

include(clast/cmake/ClastIndex.cmake)
add_clast_index(YourMainTarget)

The ast-index target is part of the default ALL build, so the index is updated automatically every time you build. The indexer is incremental (content-hash based), so no-change builds add negligible overhead.

3. Configure Claude Code

Add to your project's .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"
      }
    }
  }
}

Logs are appended to ./clast/mcp.log — use tail -f ./clast/mcp.log to watch tool calls, response sizes, and timing in real time.

bootstrap.sh will offer to append clast instructions to your project's CLAUDE.md. If you prefer to do it manually, copy the contents of CLAUDE-CLAST-ADDITION.md into your project's CLAUDE.md.

MCP Tools

Output format

By default, tool responses use a compact plain-text format that renders native C++ syntax instead of JSON field names, saving ~3,000-5,000 tokens per session. See docs/compact-response-format.md for the full specification and rationale.

To switch to JSON output, use the CLI flag:

python3 -m clang_ast_mcp serve --db .ast-index.db --format json

Or the environment variable:

AST_OUTPUT_FORMAT=json python3 -m clang_ast_mcp serve --db .ast-index.db

In .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"
      }
    }
  }
}

The format is server-wide — restart with a different setting to switch. This makes A/B comparison straightforward: run a full session in each mode and compare token usage from Claude Code's reporting.

Architecture

compile_commands.json
        │
        ▼
  ┌──────────┐     ┌───────────┐     ┌──────────┐
  │ libclang │────▶│  SQLite   │────▶│   BM25   │
  │ indexer  │     │   index   │     │  search  │
  └──────────┘     └───────────┘     └──────────┘
                         │
                         ▼
                   ┌───────────┐
                   │ MCP tools │◀──── Claude Code
                   │  (stdio)  │
                   └───────────┘

• Indexer uses libclang to parse each translation unit, extracting symbols with USRs (Unified Symbol Resolution IDs) for precise cross-referencing
• Storage is SQLite with indexes on symbol names, USRs, and file paths
• Search uses BM25 keyword ranking over symbol names, signatures, and doc comments
• MCP server uses FastMCP with stdio transport (local to Claude Code)

Incremental re-indexing

The indexer tracks file content hashes. Running ast_index again only re-parses files that have changed. Use --force to re-index everything.

Indexing third-party headers

For JUCE or similar large frameworks, index only the public headers:

clang-ast-mcp index /path/to/JUCE/modules \
  --db /path/to/your/project/.ast-index.db

This gives Claude access to JUCE class outlines and API signatures without indexing implementation files.

Advanced topics

Manual CMake index target

If you prefer to run the indexer on demand rather than on every build, pass EXCLUDE_FROM_ALL:

include(clast/cmake/ClastIndex.cmake)
add_clast_index(YourMainTarget EXCLUDE_FROM_ALL)

Then build the index explicitly:

cmake --build cmake-build-debug --target ast-index

The ast-index target depends on your main target, so it will build your project first if needed.

Xcode projects

Xcode doesn't produce compile_commands.json natively. You may be able to use Bear to generate one by intercepting compiler calls during a real build:

brew install bear
bear -- xcodebuild -project Foo.xcodeproj -scheme Foo build

Then run ./clast/index.sh as usual — it will find the generated compile_commands.json in the project root.

LLM Generated Code Caveat Emptor

The content of this project contains largely LLM-generated code with all the benefits and limitations that entails.