TreeSitter MCP Server

A fast Model Context Protocol (MCP) server that analyzes source code files and extracts their structure in a markdown format optimized for LLM consumption.

Features

• Multi-language Support: Python, JavaScript, TypeScript, Java, C#, and Go
• Fast Parsing: Uses tree-sitter for efficient AST parsing
• Comprehensive Structure: Extracts classes, functions, nested elements
• Line Numbers: Tracks start and end lines for each element
• Nesting Levels: Shows the depth of nested elements
• Parameters & Return Types: Extracts function signatures
• Optional Docstrings: Configurable docstring extraction
• Multi-File Analysis: Analyze single or multiple files in one request
• Error Handling: Parses as much as possible and indicates error locations
• LLM-Optimized Output: Markdown format designed for easy LLM consumption

Installation

Using uv (Recommended)

uv sync

Using pip

pip install -r requirements.txt

Usage

Running the MCP Server

uv run python src/server.py

Or directly:

python src/server.py

MCP Configuration

Add the following to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "tree-sitter-code-structure": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/TreeSitterMcp",
        "run",
        "python",
        "src/server.py"
      ]
    }
  }
}

MCP Tool: analyze_code_structure

Analyzes the structure of one or more source code files.

Parameters:

• file_path (required): Path to the source code file(s) to analyze. Can be either:
  • A single file path as a string (e.g., "src/models.py")
  • An array of file paths (e.g., ["src/models.py", "src/config.py"])
• include_docstrings (optional, default: false): Whether to include docstrings in the output

Single File Analysis

Example Request:

{
  "name": "analyze_code_structure",
  "arguments": {
    "file_path": "src/models.py",
    "include_docstrings": true
  }
}

Multi-File Analysis

Example Request:

{
  "name": "analyze_code_structure",
  "arguments": {
    "file_path": ["src/models.py", "src/config.py", "src/server.py"],
    "include_docstrings": false
  }
}

Single File Output

# Code Structure: `src/models.py`

**Language**: Python
**Total Classes**: 3
**Total Functions**: 12
**Max Nesting Depth**: 4

## Classes

### `MyClass` (Lines 10-50, Nesting: 0)

- **Type**: Class
- **Docstring**: A sample class for demonstration.
- **Methods**:

  - `__init__` (Lines 15-25, Nesting: 1)

    - **Type**: Function
    - **Parameters**: `self`, `param1: str`, `param2: int`
    - **Return Type**: `None`
    - **Docstring**: Initialize the class.

  - `process_data` (Lines 27-45, Nesting: 1)
    - **Type**: Function
    - **Parameters**: `self`, `data: List[Dict]`
    - **Return Type**: `Dict[str, Any]`
    - **Docstring**: Process the input data.

## Functions

### `helper_function` (Lines 55-70, Nesting: 0)

- **Type**: Function
- **Parameters**: `input_data: str`, `config: Optional[Dict] = None`
- **Return Type**: `bool`
- **Docstring**: Helper function for data processing.

### `nested_function` (Lines 60-68, Nesting: 1)

- **Parent**: `helper_function`
- **Type**: Function
- **Parameters**: `item: str`
- **Return Type**: `str`

Multi-File Output

# Code Structure Analysis

**Files Analyzed**: 3
**Successful**: 3
**Failed**: 0

# Code Structure: `src/models.py`

**Language**: Python
**Total Classes**: 3
**Total Functions**: 12
**Max Nesting Depth**: 4

## Classes

### `MyClass` (Lines 10-50, Nesting: 0)

- **Type**: Class
...

---

# Code Structure: `src/config.py`

**Language**: Python
**Total Classes**: 0
**Total Functions**: 5
**Max Nesting Depth**: 2

## Functions

### `get_language_from_extension` (Lines 10-20, Nesting: 0)

- **Type**: Function
...

---

# Code Structure: `src/server.py`

**Language**: Python
**Total Classes**: 1
**Total Functions**: 8
**Max Nesting Depth**: 3

## Classes

### `Server` (Lines 5-100, Nesting: 0)

- **Type**: Class
...

Supported Languages

Architecture

The server is organized into the following modules:

• src/mcp/server.py: MCP server implementation with tool definitions
• src/parsers/tree_sitter.py: Tree-sitter parser integration
• src/extractors/structure.py: Code structure extraction logic
• src/formatters/markdown.py: Markdown formatting for output
• src/config.py: Language configuration and mappings
• src/models.py: Data models for code elements

Error Handling

The server attempts to parse as much of the file as possible, even when there are syntax errors. Errors are reported in a dedicated section:

## Parse Errors

⚠️ **Error at Line 42**: Syntax error

return self.process(item

Development

Running Tests

uv run pytest

Code Formatting

uv run black src/

Type Checking

uv run mypy src/

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.