code-context-mcp

AST Codebase Intelligence, Symbol Extraction, Cyclomatic Complexity & Refactoring Analysis for LLMs & AI Coding Agents.

💡 Why This Exists & Token Efficiency

Traditional AI coding assistants dump entire raw source files into context windows, wasting tens of thousands of tokens on boilerplate, imports, and irrelevant functions. code-context-mcp introduces a claude-mem style 3-layer workflow that provides surgical code context before editing.

⚡ 3-Layer Context Workflow

1. Layer 1: Structural Scan (summarize_repository_architecture) — High-level file structure, line counts, and extensions map.
2. Layer 2: AST Symbol Outline (extract_python_ast_symbols) — Class definitions, method signatures, docstrings, and line ranges without dumping raw code.
3. Layer 3: Targeted Analysis (analyze_cyclomatic_complexity & search_code_todos_and_hotspots) — Cyclomatic complexity scores and TODO/FIXME hotspot discovery to pinpoint refactoring targets.

📊 Token Savings Comparison

🏗️ Architecture Diagram

flowchart TD
    A[AI Coding Agent / LLM] -->|1. Request Repo Summary| B[summarize_repository_architecture]
    A -->|2. Extract AST Symbols| C[extract_python_ast_symbols]
    A -->|3. Analyze Complexity| D[analyze_cyclomatic_complexity]
    A -->|4. Scan Hotspots| E[search_code_todos_and_hotspots]

    subgraph MCP Server Engine: code-context-mcp
        B --> F[AST & Static Code Parser]
        C --> F
        D --> F
        E --> F
    end

    F -->|Compact Structural Context| A

🛠️ Tools Included

1. summarize_repository_architecture: Scans directory paths, generates file structure breakdown by extension, and computes total lines of code.
2. extract_python_ast_symbols: Parses Python files into Abstract Syntax Trees (AST) to extract classes, base classes, methods, docstrings, function signatures, and line markers.
3. analyze_cyclomatic_complexity: Calculates cyclomatic complexity scores for all functions/methods to identify refactoring candidates and branch depth.
4. search_code_todos_and_hotspots: Detects code comments containing TODO, FIXME, HACK, and XXX across the codebase with exact file and line references.

🚀 Quick Start (1-Click & 1-Command Setup)

1. Claude Code CLI

claude mcp add code-context-mcp -- python -m code_context_mcp

2. Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "code-context-mcp": {
      "command": "python",
      "args": ["-m", "code_context_mcp"]
    }
  }
}

3. OpenAI Codex CLI (~/.codex/config.toml)

[mcp_servers.code-context-mcp]
command = "python"
args = ["-m", "code_context_mcp"]

4. Google Antigravity IDE (mcp_config.json)

{
  "mcpServers": {
    "code-context-mcp": {
      "command": "python",
      "args": ["-m", "code_context_mcp"]
    }
  }
}

5. Windsurf / Cline

{
  "mcpServers": {
    "code-context-mcp": {
      "command": "python",
      "args": ["-m", "code_context_mcp"]
    }
  }
}