# 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)
```bash
uv sync
```
### Using pip
```bash
pip install -r requirements.txt
```
## Usage
### Running the MCP Server
```bash
uv run python src/server.py
```
Or directly:
```bash
python src/server.py
```
### MCP Configuration
Add the following to your MCP client configuration (e.g., Claude Desktop):
```json
{
"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:**
```json
{
"name": "analyze_code_structure",
"arguments": {
"file_path": "src/models.py",
"include_docstrings": true
}
}
```
#### Multi-File Analysis
**Example Request:**
```json
{
"name": "analyze_code_structure",
"arguments": {
"file_path": ["src/models.py", "src/config.py", "src/server.py"],
"include_docstrings": false
}
}
```
#### Single File Output
```markdown
# 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
```markdown
# 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
| Language | File Extensions |
| ---------- | --------------- |
| Python | .py |
| JavaScript | .js, .mjs, .cjs |
| TypeScript | .ts, .tsx |
| Java | .java |
| C# | .cs |
| Go | .go |
## 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:
```markdown
## Parse Errors
⚠️ **Error at Line 42**: Syntax error
```
return self.process(item
```
```
## Development
### Running Tests
```bash
uv run pytest
```
### Code Formatting
```bash
uv run black src/
```
### Type Checking
```bash
uv run mypy src/
```
## License
MIT License
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
