# 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)

```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": {
    "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"]`)
- `include_docstrings` (optional, default: false): Whether to include docstrings in the output

#### Single File Analysis

**Example Request:**

```json
{
  "name": "query",
  "arguments": {
    "file_path": "src/models.py",
    "include_docstrings": true
  }
}
```

#### Multi-File Analysis

**Example Request:**

```json
{
  "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:**

```markdown
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

```markdown
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 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.