⚡ ast-mcp: Smart Context Compiler & MCP Server for AI Agents

A lightweight, zero-C-extension context compiler and Model Context Protocol (MCP) server that compresses Python codebases into high-signal AST interface skeletons, cutting prompt window consumption by 60% to 80%.

The Problem: "Fat Context" Exhaustion

LLM-driven coding agents (Antigravity, Claude, Cursor) are often fed hundreds or thousands of lines of code when analyzing a task. In real-world repositories:

• Up to 85% of source lines consist of internal function algorithms, repetitive loops, and intermediate calculations.

• Feeding raw implementations for every dependency wastes token budgets, slows inference, and dilutes the model's attention over long horizons.

Related MCP server: @penqwin/mcp

The Solution: Selective AST Interface Skeletons

ast-mcp utilizes Python's built-in ast parser to strip out function and method bodies into ... (Ellipsis), preserving:

• Class declarations, inheritances, and metaclasses

• Method and function signatures with type annotations

• Parameter default values, *args, and **kwargs

• Module, class, and method docstrings

• Global constants and type aliases

When targeting a specific focus symbol (e.g., --symbol CoreEngine), ast-mcp preserves the full implementation of the target file while delivering all auxiliary project files as ultra-compact AST skeletons.

Compression Benchmark (Tested on ast-mcp/src)

Quickstart

Installation

Requires Python 3.14+:

git clone https://github.com/your-username/ast-mcp.git
cd ast-mcp
uv pip install -e .

CLI Usage

# Compile entire directory into terminal output
ast-mcp pack src

# Focus on a specific symbol (keeps full code for target, skeletonizes rest)
ast-mcp pack src --symbol CodeSkeletonizer

# Copy compressed markdown context directly to system clipboard
ast-mcp pack src --symbol ContextPacker --copy

# Save compressed context to file
ast-mcp pack src -o context.md

MCP Server Integration

Run standalone over stdio:

ast-mcp run

Add to your MCP Client Configuration (~/.gemini/config/mcp_config.json or Claude Desktop):

{
  "mcpServers": {
    "ast-mcp": {
      "command": "/Users/iliaprosvirnikov/Downloads/ast-mcp/.venv/bin/python3",
      "args": ["-m", "src.cli", "run"]
    }
  }
}

Available MCP Tools

• get_smart_context(repo_path: str, focus_symbol: str = "") -> str: Builds a structured markdown slice of the target repository with token reduction metrics.

• get_file_skeleton(file_path: str) -> str: Generates an instant AST skeleton for an individual Python file.

License

MIT © 2026 ast-mcp contributors.