Code Intelligence MCP Server

Hybrid ctags + clangd code intelligence for C/C++ projects, exposed as an MCP server. Gives AI coding assistants (Claude, Copilot, Gemini) instant symbol lookup and precision type information.

Architecture

Two tiers of intelligence, automatically selected:

Tier	Backend	Speed	Tools
Tier 1	Universal Ctags	Instant (~0.1s)	find_definition, find_references, list_symbols, search_symbol, rebuild_index
Tier 2	clangd LSP	Slower (~1-5s)	hover_info, class_hierarchy, call_hierarchy

Tier 1 builds a JSON symbol index from ctags output and keeps it cached. Tier 2 launches clangd as a subprocess and communicates via LSP protocol. Both tiers are optional — the server works with just ctags, just clangd, or both.

Quick Start

# Install
pip install -e .

# Run (from your project root)
code-intel

# Or configure as an MCP server

MCP Configuration

Add to your MCP client config (Claude Code, Antigravity, etc.):

{
  "mcpServers": {
    "codeintel": {
      "command": "python",
      "args": ["-m", "code_intel_server"],
      "cwd": "/path/to/your/project",
      "env": {
        "PROJECT_ROOT": "/path/to/your/project",
        "SOURCE_DIR": "src",
        "PYTHONUTF8": "1"
      }
    }
  }
}

Environment Variables

Variable	Default	Purpose
PROJECT_ROOT	. (cwd)	Root of the C/C++ project
SOURCE_DIR	src	Subdirectory containing source files (ctags scans here)
COMPILE_COMMANDS_DIR	./build	Directory containing compile_commands.json (for clangd)
CLANGD_PATH	clangd	Path to the clangd binary
CTAGS_PATH	ctags	Path to the Universal Ctags binary

Tools

Tier 1 (ctags — instant)

• find_definition — Find where a symbol is defined. Supports qualified names (MyNamespace::MyClass), optional kind filter.
• find_references — Find all references to a symbol across the codebase. Uses ctags scope/signature matching.
• list_symbols — List all symbols in a specific file, optionally filtered by kind.
• search_symbol — Fuzzy search for symbols by name pattern (substring or glob).
• rebuild_index — Force a full ctags re-scan (normally auto-detects staleness).

Tier 2 (clangd — precision)

• hover_info — Get full type information, documentation, and value for a symbol at a specific file:line location.
• class_hierarchy — Show base classes and derived classes for a type.
• call_hierarchy — Show what calls a function and what it calls.

Requirements

• Python 3.10+
• Universal Ctags — for Tier 1 (install via package manager or from source)
• clangd — for Tier 2 (optional, usually bundled with LLVM/Clang)
• FastMCP — Python MCP framework

How It Works

1. On first run, ctags scans SOURCE_DIR/ recursively and builds a JSON symbol index
2. The index is cached at .cache/code_intel/tags.json for instant restarts
3. Staleness is auto-detected by comparing file mtimes against cache age
4. clangd is launched on-demand when Tier 2 tools are called, using compile_commands.json for accurate type resolution
5. All results are returned as structured JSON via MCP tool responses

Performance

Tested on a 15,000-commit C++ project (~500K lines):

• Index build: ~3 seconds (cached restart: instant)
• Symbol lookup: <100ms
• clangd hover: 1-5 seconds (depends on TU complexity)

License

MIT