C+
Search

C++ MCP Server: libclang AST Code Analysis

Analyze C++ code with an MCP server using libclang AST parsing to find classes, navigate inheritance, trace calls, and explore code relationships.

View on GitHub
Quick Install
npx -y @kandrwmrtn/cplusplus_mcp

Overview

This project implements an MCP (Model Context Protocol) server for C++ code analysis using libclang’s AST. It parses C++ codebases to extract structural information—classes, methods, inheritance relationships, call sites—and exposes that information to MCP-aware clients. The server is intended for use in code-understanding integrations, refactoring tools, visualization UIs, or any automated workflow that needs an up-to-date, queryable representation of a C++ project.

Using libclang gives robust, compiler-aware parsing (headers, templates, macros) and produces an abstract syntax tree (AST) that the server walks to build indexes and relationship graphs. The MCP server provides back-end services for searches, navigation (e.g., find subclasses or callers), and trace queries across translation units without requiring a full language server or IDE integration.

Features

  • AST-based analysis using libclang to accurately reflect compiler semantics
  • Class and method discovery across translation units
  • Inheritance navigation: find base classes, derived classes, virtual overrides
  • Call tracing: call graph traversal to find callers and callees
  • Cross-file relationship exploration (fields, typedefs, template instantiations)
  • Incremental indexing and re-scan support for active development
  • Exposes analysis results over the MCP (Model Context Protocol) for client integrations

Installation / Configuration

Prerequisites (example for Debian/Ubuntu):

sudo apt update
sudo apt install -y build-essential cmake clang libclang-dev git

Clone and build:

git clone https://github.com/kandrwmrtn/cplusplus_mcp.git
cd cplusplus_mcp
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

Common runtime configuration (example):

  • LIBCLANG path: point the server to your libclang shared library if it’s not in a standard location (e.g., /usr/lib/llvm-12/lib/libclang.so).
  • Source root: the top-level directory of the C++ project to analyze.
  • Compilation database: a compile_commands.json is recommended so libclang can parse files with the right flags.

Example run command (adjust flags to your build):

# Example: run the MCP server, serving the given source root
./mcp_server --source-root /path/to/project \
             --compile-commands /path/to/project/build/compile_commands.json \
             --libclang /usr/lib/llvm-12/lib/libclang.so \
             --port 4000

Environment variable option:

export LIBCLANG_PATH=/usr/lib/llvm-12/lib/libclang.so
./mcp_server --source-root /path/to/project --port 4000

If your project uses a custom build system, generate compile_commands.json (CMake: -DCMAKE_EXPORT_COMPILE_COMMANDS=ON, or use Bear for other builds).

Available Tools / Resources

The server exposes several built-in analysis tools (available as MCP tools/resources). Typical tools include:

Tool namePurposeInputOutput
class_searchFind classes by name or patternname or regexlist of class symbols with locations
inheritanceNavigate base/derived relationshipsclass symbolbase/derived class lists
call_tracerTrace callers or calleesfunction symbol, depth limitcall graph nodes/edges
ast_dumpDump AST nodes for a file or symbolfile path or symbolstructured AST fragment
indexerBuild/update project indexsource rootinternal indexes for queries

These tools are typically invoked by sending MCP requests (JSON-based messages) to the server and receiving structured JSON responses. The exact MCP message formats follow the project’s protocol schema; clients should consult the server’s protocol documentation or example client implementations in the repository.

Use Cases

  • Find all subclasses of a base class before a refactor:
    • Use the inheritance tool to enumerate derived classes, including indirect derivations across translation units.
  • Trace who calls a particular function or method:
    • Use call_tracer to find direct callers; increase depth to see callers-of-callers when evaluating downstream impacts.
  • Locate class usages and relationships for design reviews:
    • Use class_search + ast_dump to inspect field types, template instantiations, and typedefs referencing a class.
  • Integrate with visualization tools:
    • Use the server as a back-end for graph visualizers to display inheritance trees or call graphs for large codebases.
  • Automated audits and change impact analysis:
    • Programmatically query the MCP server to gather lists of affected symbols for CI checks or security scanning.

Quick Examples

Conceptual examples (MCP messages are JSON over TCP/HTTP depending on deployment):

Find classes matching “Manager”:

{ "tool": "class_search", "query": "Manager", "limit": 50 }

Trace callers of MyNamespace::doWork with depth 2:

{ "tool": "call_tracer", "symbol": "MyNamespace::doWork", "direction": "callers", "depth": 2 }

The server will return structured JSON containing symbol identifiers, source locations, and relationship edges suitable for client-side presentation.

If you are integrating this server into tooling, start by building the project, ensuring libclang is reachable, provide a compile_commands.json for accurate parsing, and use the example client messages in the repository to explore available MCP interactions.

Tags:search