AST MCP Server

An MCP (Model Context Protocol) server that provides code structure and semantic analysis capabilities through Abstract Syntax Trees (AST) and Abstract Semantic Graphs (ASG).

Features

Parse code into Abstract Syntax Trees (AST)
Generate Abstract Semantic Graphs (ASG) from code
Analyze code structure and complexity
Support for multiple programming languages (Python, JavaScript, TypeScript, Go, Rust, C/C++, Java)
Compatible with Claude Desktop and other MCP clients
Incremental parsing for faster processing of large files
Enhanced scope handling and more complete semantic analysis
AST diffing to identify changes between code versions
Resource caching for improved performance

Installation

Prerequisites

Python 3.9 or higher
uv package manager (recommended) or pip

Using uv (Recommended)

Clone this repository:

git clone https://github.com/angrysky56/ast-mcp-server.git
cd ast-mcp-server

Install the project and dependencies:

# Install the project in development mode with all dependencies
uv sync

# Or install with specific optional dependencies
uv sync --extra dev  # Development tools
uv sync --extra testing  # Testing dependencies
uv sync --extra docs  # Documentation tools

Build the tree-sitter parsers:

uv run build-parsers

Using pip (Alternative)

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

# Build parsers
python build_parsers.py

Usage with Claude Desktop

Configure Claude Desktop to use the server by editing your configuration file:

Location of config file:

macOS: ~/Library/Application Support/claude-desktop/claude_desktop_config.json
Linux: ~/.config/claude-desktop/claude_desktop_config.json
Windows: %APPDATA%\claude-desktop\claude_desktop_config.json

Add the AST MCP server configuration:

{
  "mcpServers": {
    "AstAnalyzer": {
      "command": "uv",
      "args": [
        "--directory",
        "/home/ty/Repositories/ai_workspace/ast-mcp-server/ast_mcp_server",
        "run",
        "server.py"
      ]
    }
  }
}

Important: Replace /absolute/path/to/ast-mcp-server with the actual absolute path on your system.

Restart Claude Desktop to load the new MCP server.
In Claude Desktop, you can now use the AST-based code analysis tools by referencing code files or pasting code snippets.

Development

Development Environment Setup

# Install with development dependencies
uv sync --extra dev

# Install pre-commit hooks (optional)
uv run pre-commit install

Running in Development Mode

To run the server in development mode with the MCP inspector:

# Using uv
uv run --extra dev -- -m mcp dev server.py

# Or using the development script
./dev_server.sh

Testing

# Run all tests
uv run --extra testing pytest

# Run tests with coverage
uv run --extra testing pytest --cov=ast_mcp_server --cov-report=html

# Run specific tests
uv run --extra testing pytest tests/test_specific.py

Code Quality

# Format code
uv run black .
uv run isort .

# Lint code
uv run flake8 .

# Type checking
uv run mypy ast_mcp_server/

Available Tools

The server provides the following tools for code analysis:

Basic Tools

parse_to_ast: Parse code into an Abstract Syntax Tree
generate_asg: Generate an Abstract Semantic Graph from code
analyze_code: Analyze code structure and complexity
supported_languages: Get the list of supported programming languages

Caching Tools

parse_and_cache: Parse code into an AST and cache it for resource access
generate_and_cache_asg: Generate an ASG and cache it for resource access
analyze_and_cache: Analyze code and cache the results for resource access

Enhanced Tools

parse_to_ast_incremental: Parse code with incremental support for faster processing
generate_enhanced_asg: Generate an enhanced ASG with better scope handling
diff_ast: Find differences between two versions of code
find_node_at_position: Locate a specific node at a given line and column
parse_and_cache_incremental: Parse code incrementally and cache the results
generate_and_cache_enhanced_asg: Generate an enhanced ASG and cache it
ast_diff_and_cache: Generate an AST diff and cache it

Adding Language Support

To add support for additional programming languages:

Install the corresponding tree-sitter language package:

uv add tree-sitter-<language>

Update the LANGUAGE_MODULES dictionary in build_parsers.py and ast_mcp_server/tools.py.
Build the parsers:

uv run build-parsers

Currently Supported Languages

Python (tree-sitter-python)
JavaScript (tree-sitter-javascript)
TypeScript (tree-sitter-typescript)
Go (tree-sitter-go)
Rust (tree-sitter-rust)
C (tree-sitter-c)
C++ (tree-sitter-cpp)
Java (tree-sitter-java)

How It Works

The AST MCP Server connects with Claude Desktop through the Model Context Protocol (MCP):

Initialization: Claude Desktop starts the server using uv run with the appropriate working directory
Language Loading: The server loads tree-sitter language modules for parsing various programming languages
MCP Registration: It registers tools and resources with the MCP protocol
Analysis: Claude can access these tools to analyze code you share in the chat
Caching: Results are cached locally for improved performance

All tool execution happens locally on your machine, with results returned to Claude for interpretation and assistance.

Configuration Files

pyproject.toml: Project metadata, dependencies, and tool configuration
claude_desktop_config.json: Example Claude Desktop configuration
dev_server.sh: Development server script
.gitignore: Git ignore rules

Directory Structure

ast-mcp-server/
├── ast_mcp_server/          # Main package
│   ├── __init__.py
│   ├── tools.py             # Core AST/ASG tools
│   ├── enhanced_tools.py    # Enhanced analysis features
│   ├── resources.py         # MCP resource handlers
│   └── parsers/             # Tree-sitter parser cache
├── examples/                # Usage examples
├── tests/                   # Test suite
├── server.py                # Main server entry point
├── build_parsers.py         # Parser setup script
├── pyproject.toml           # Project configuration
└── README.md               # This file

Troubleshooting

Parser Issues

If you encounter parser-related errors:

# Rebuild parsers
uv run build-parsers

# Check for missing language packages
uv add tree-sitter-python tree-sitter-javascript

Claude Desktop Connection Issues

Verify the absolute path in your Claude Desktop configuration
Ensure uv is in your system PATH
Check Claude Desktop logs for error messages
Restart Claude Desktop after configuration changes

Performance Issues

Use incremental parsing tools for large files
Enable caching for repeated analysis
Consider analyzing smaller code sections

Contributing

Fork the repository
Create a feature branch: git checkout -b feature-name
Make your changes with proper tests
Run the test suite: uv run pytest
Submit a pull request

Development Guidelines

Follow PEP 8 style guidelines (enforced by black and flake8)
Add type hints to all public functions
Include docstrings for all modules, classes, and functions
Write tests for new functionality
Update documentation as needed

License

MIT License - see LICENSE file for details.

Changelog

v0.2.0

Added pyproject.toml configuration
Improved uv compatibility
Enhanced caching system
Added incremental parsing support
Expanded language support
Better error handling and logging

v0.1.0

Initial release
Basic AST/ASG parsing
Claude Desktop integration
Support for Python and JavaScript

MCP Servers