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#, Go, and Rust
- 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": {
"CodeStructureAnalyzer": {
"command": "uv",
"args": [
"--directory",
"/path/to/TreeSitterMcp",
"run",
"python",
"src/server.py"
]
}
}
}
MCP Tool: query
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"])
- A single file path as a string (e.g.,
include_docstrings(optional, default: false): Whether to include docstrings in the output
Single File Analysis
Example Request:
{
"name": "query",
"arguments": {
"file_path": "src/models.py",
"include_docstrings": true
}
}
Multi-File Analysis
Example Request:
{
"name": "query",
"arguments": {
"file_path": ["src/models.py", "src/config.py", "src/server.py"],
"include_docstrings": false
}
}
Output Format
The output is optimized for token efficiency and follows this schema:
Format: ### Name (Start-End, Nesting, [Parent]) | - Type | - [Parameters] | - [Return Type] | - [Docstring]
Example Output:
Format: ### `Name` (Start-End, Nesting, [Parent]) | - Type | - [Parameters] | - [Return Type] | - [Docstring]
# `src/models.py`
### `MyClass` (10-50, N:0)
- Class
- A sample class for demonstration.
### `__init__` (15-25, N:1, P: `MyClass`)
- Function
- (self, param1: str, param2: int)
- -> None
- Initialize the class.
Multi-File Output Example
Format: ### `Name` (Start-End, Nesting, [Parent]) | - Type | - [Parameters] | - [Return Type] | - [Docstring]
# `src/models.py`
### `MyClass` (10-50, N:0)
- Class
...
---
# `src/config.py`
### `get_language_from_extension` (10-20, N:0)
- Function
...
Supported Languages
| Language | File Extensions |
|---|---|
| Python | .py |
| JavaScript | .js, .mjs, .cjs |
| TypeScript | .ts, .tsx |
| Java | .java |
| C# | .cs |
| Go | .go |
| Rust | .rs |
Architecture
The server is organized into the following modules:
src/mcp_impl/server.py: MCP server implementation with tool definitionssrc/parsers/tree_sitter.py: Tree-sitter parser integrationsrc/extractors/structure.py: Code structure extraction logicsrc/formatters/markdown.py: Markdown formatting for outputsrc/config.py: Language configuration and mappingssrc/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.