# wrale/mcp-server-tree-sitter architecture

> Architecture diagram of the GitHub repository wrale/mcp-server-tree-sitter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wrale/mcp-server-tree-sitter
- Repository: https://github.com/wrale/mcp-server-tree-sitter

## Overview

##### Project Type & Purpose
- This is a Python-based MCP (Model Context Protocol) microservice/server that exposes code-analysis capabilities (AST traversal, search, symbol extraction, dependency analysis, caching, etc.) via the MCP protocol.
- It is intended to be run as a standalone server process (e.g., via `python -m mcp_server_tree_sitter.server` or `mcp-server-tree-sitter`) and to be consumed by clients such as Claude Desktop or the MCP CLI.

##### File-Structure Analysis
- Top‐level:
- `src/mcp_server_tree_sitter/` – main Python package
- `scripts/` – helper shell scripts
- `docs/` – design, CLI, config, logging, diagnostics guides
- `Makefile`, CI workflows, `pyproject.toml` – build & release
- `src/mcp_server_tree_sitter/` sub-packages:
- `__main__.py` / `server.py` – entry points for CLI vs. server
- `api.py` – public functions for direct Python usage
- `bootstrap/` – early initialization (logging, env)
- `config.py` – YAML/env var loading & precedence
- `di.py` – dependency‐injection container for singletons
- `cache/` – parse-tree caching module
- `capabilities/` – MCP server capability declarations
- `language/` – registry of supported languages + query templates
- `models/` – AST, project, cursor abstractions
- `prompts/` – prebuilt MCP prompts (code_review, explain_code…)
- `tools/` – core code-analysis operations (search, AST ops, file I/O)
- `utils/` – file system, path, security, Tree-sitter helper functions
- `logging_config.py` + `bootstrap/logging_bootstrap.py` – log setup
- `context.py` – per‐request context management
- `exceptions.py` – domain‐specific errors

##### README Insights
- Core functionality invoked via MCP endpoints: `get_ast`, `get_symbols`, `find_text`, `run_query`, etc.
- Uses in‐memory singletons for state persistence (project registry, parser cache).
- Configurable via CLI flags, Makefile targets, Python API, YAML files, or env vars.
- Supports integration via MCP CLI (`mcp install …`) or manual JSON config in Claude Desktop.

a. Main Components
- Client Layer:
- MCP CLI (third‐party)
- Claude Desktop UI (MCP protocol client)
- Server Layer (`mcp_server_tree_sitter.server`):
- Entry point / CLI parser
- HTTP/WebSocket or stdio-based MCP protocol handler
- Capability negotiator
- Request dispatcher
- Core Modules (inside DI container):
- Config Manager
- Logging Manager
- Project Registry (manages registered projects)
- Language Registry (loads/parses tree-sitter grammars)
- Parser Cache (stores parse trees with TTL)
- Context Manager (manages per‐request state)
- Tools & Handlers (search, AST ops, symbol extraction)
- Prompts Module (generates MCP prompts)
- External Dependencies:
- File System (source files)
- Tree-sitter native libraries
- YAML/JSON config stores
b. Relationships & Data Flows
- Clients send MCP requests → Server Entry → Capability Layer → Dispatcher
- Dispatcher retrieves Config & Context → invokes specific Tool (e.g., get_ast)
- Tool asks Language Registry for parser → Parser Cache → Tree-sitter
- Tree-sitter parses file from File System → AST model returned
- Tool processes AST (cursor, models) → builds MCP response → sent back to client
c. Architectural Patterns
- Dependency Injection for singletons & testability
- Modular “Tools” approach for each feature (search, registry, diagnostics)
- Separation of concerns: bootstrap, config, logging, API, server, tools, models
- In‐memory caching with configurable TTL
- Protocol adapter layer (MCP) decouples client transport from business logic
d. Key Technologies
- Python 3.10+
- Tree-sitter parsers (via tree-sitter-language-pack)
- YAML / environment‐variable config
- In‐process DI container (`di.py`)
- Standard logging module with custom bootstrap
- Makefile / CI workflows for automation

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer" 
        style ClientLayer fill:#D0E8FF,stroke:#333,stroke-width:1px
        CLI["MCP CLI"]:::client
        Claude["Claude Desktop UI"]:::client
    end

    %% Protocol / Server Layer
    subgraph "Protocol Layer" 
        style ProtocolLayer fill:#DFFFD0,stroke:#333,stroke-width:1px
        EntryCLI["__main__.py\n(Entry Point CLI)"]:::protocol
        click EntryCLI "https://github.com/wrale/mcp-server-tree-sitter/blob/main/src/mcp_server_tree_sitter/__main__.py"
        ServerEntry["server.py\n(Server Entry)"]:::protocol
        click ServerEntry "https://github.com/wrale/mcp-server-tree-sitter/blob/main/src/mcp_server_tree_sitter/server.py"
        API["api.py\n(Public Python API)"]:::protocol
        click API "https://github.com/wrale/mcp-server-tree-sitter/blob/main/src/mcp_server_tree_sitter/api.py"
        Capabilities["server_capabilities.py\n(Capability Declarations)"]:::protocol
        click Capabilities "https://github.com/wrale/mcp-server-tree-sitter/blob/main/src/mcp_server_tree_sitter/capabilities/server_capabilities.py"
        Dispatcher["Request Dispatcher"]:::protocol
    end

    %% Dependency Injection Layer
    subgraph "DI Container" 
        style DIContainer fill:#FFE4B2,stroke:#333,stroke-width:1px
        DI["di.py\n(DI Container)"]:::di
        click DI "https://github.com/wrale/mcp-server-tree-sitter/blob/main/src/mcp_server_tree_sitter/di.py"
    end

    %% Core Modules
    subgraph "Core Modules" 
        style CoreModules fill:#FFE4B2,stroke:#333,stroke-width:1px
        Config["config.py\n(Configuration Manager)"]:::core
        click Config "https://github.com/wrale/mcp-server-tree-sitter/blob/main/src/mcp_server_tree_sitter/config.py"
        LoggingBootstrap["logging_bootstrap.py\n(Bootstrap Logging)"]:::core
        click LoggingBootstrap "https://github.com/wrale/mcp-server-tree-sitter/blob/main/src/mcp_server_tree_sitter/bootstrap/logging_bootstrap.py"
        LoggingConfig["logging_config.py\n(Logging Config)"]:::core
        click LoggingConfig "https://github.com/wrale/mcp-server-tree-sitter/blob/main/src/mcp_server_tree_sitter/logging_config.py"
        ProjectRegistry["Project Registry"]:::core
        LanguageRegistry["registry.py\n(Language Registry)"]:::core
        click LanguageRegistry "https://github.com/wrale/mcp-server-tree-sitter/blob/main/src/mcp_server_tree_sitter/language/registry.py"
        QueryTemplates["query_templates.py\n(Query Templates)"]:::core
        click QueryTemplates "https://github.com/wrale/mcp-server-tree-sitter/blob/main/src/mcp_server_tree_sitter/language/query_templates.py"
        PythonTemplate["python.py\n(Python Templates)"]:::core
        click PythonTemplate "https://github.com/wrale/mcp-server-tree-sitter/blob/main/src/mcp_server_tree_sitter/language/templates/python.py"
        ParserCache["parser_cache.py\n(Parser Cache)"]:::core
        click ParserCache "https://github.com/wrale/mcp-server-tree-sitter/blob/main/src/mcp_server_tree_sitter/cache/parser_cache.py"
        ContextMgr["context.py\n(Context Manager)"]:::core
        click ContextMgr "https://github.com/wrale/mcp-server-tree-sitter/blob/main/src/mcp_server_tree_sitter/context.py"
        Exceptions["exceptions.py\n(Exceptions)"]:::core
        click Exceptions "https://github.com/wrale/mcp-server-tree-sitter/blob/main/src/mcp_server_tree_sitter/exceptions.py"
        Prompts["code_patterns.py\n(Prompts Module)"]:::core
        click Prompts "https://github.com/wrale/mcp-server-tree-sitter/blob/main/src/mcp_server_tree_sitter/prompts/code_patterns.py"
    end

    %% Tools Modules
    subgraph "Tools & Operations" 
        style Tools fill:#FFD2A6,stroke:#333,stroke-width:1px
        Search["search.py\n(Search)"]:::tool
        click Search "https://github.com/wrale/mcp-server-tree-sitter/blob/main/src/mcp_server_tree_sitter/tools/search.py"
        ASTOps["ast_operations.py\n(AST Operations)"]:::tool
        click ASTOps "https://github.com/wrale/mcp-server-tree-sitter/blob/main/src/mcp_server_tree_sitter/tools/ast_operations.py"
        FileIO["file_operations.py\n(File I/O)"]:::tool
        click FileIO "https://github.com/wrale/mcp-server-tree-sitter/blob/main/src/mcp_server_tree_sitter/tools/file_operations.py"
        Registration["registration.py\n(Project Registration)"]:::tool
        click Registration "https://github.com/wrale/mcp-server-tree-sitter/blob/main/src/mcp_server_tree_sitter/tools/registration.py"
        QueryBuilder["query_builder.py\n(Query Builder)"]:::tool
        click QueryBuilder "https://github.com/wrale/mcp-server-tree-sitter/blob/main/src/mcp_server_tree_sitter/tools/query_builder.py"
        AnalysisUtils["analysis.py\n(Analysis Utilities)"]:::tool
        click AnalysisUtils "https://github.com/wrale/mcp-server-tree-sitter/blob/main/src/mcp_server_tree_sitter/tools/analysis.py"
        DebugTools["debug.py\n(Debug Tools)"]:::tool
        click DebugTools "https://github.com/wrale/mcp-server-tree-sitter/blob/main/src/mcp_server_tree_sitter/tools/debug.py"
        ProjectTools["project.py\n(Project Tools)"]:::tool
        click ProjectTools "https://github.com/wrale/mcp-server-tree-sitter/blob/main/src/mcp_server_tree_sitter/tools/project.py"
    end

    %% Infrastructure
    subgraph "Infrastructure" 
        style Infra fill:#E0D0FF,stroke:#333,stroke-width:1px
        FS["File System"]:::infra
        TS["Tree-sitter\nNative Libraries"]:::infra
        ConfigStore["YAML/JSON\nConfig Store"]:::infra
    end

    %% Relationships
    CLI -->|Sends MCP Request| EntryCLI
    Claude -->|Sends MCP Request| ServerEntry
    EntryCLI -->|Initializes| DI
    ServerEntry -->|Initializes| DI
    DI -->|Injects| Config
    DI -->|Injects| LoggingBootstrap
    DI -->|Injects| LoggingConfig
    DI -->|Registers| ProjectRegistry
    DI -->|Registers| LanguageRegistry
    DI -->|Registers| ParserCache
    DI -->|Registers| ContextMgr

    ServerEntry -->|Negotiate| Capabilities
    Capabilities -->|Provide| Dispatcher
    Dispatcher -->|Loads| Config
    Dispatcher -->|Creates| ContextMgr
    Dispatcher -->|Dispatch| Search
    Dispatcher -->|Dispatch| ASTOps
    Dispatcher -->|Dispatch| FileIO
    Dispatcher -->|Dispatch| Registration
    Dispatcher -->|Dispatch| QueryBuilder
    Dispatcher -->|Dispatch| AnalysisUtils
    Dispatcher -->|Dispatch| DebugTools
    Dispatcher -->|Dispatch| ProjectTools

    Search -->|Uses| LanguageRegistry
    ASTOps -->|Uses| ParserCache
    FileIO -->|Reads/Writes| FS
    ParserCache -->|Fetch/Store| FS
    LanguageRegistry -->|Loads| Templates
    LanguageRegistry -->|Uses| QueryTemplates
    QueryTemplates -->|Defines| Prompts
    Prompts -->|Generate| Dispatcher

    ASTOps -->|Calls| TS
    ASTOps -->|Parses| FS

    %% Styles
    classDef client fill:#D0E8FF,stroke:#333;
    classDef protocol fill:#DFFFD0,stroke:#333;
    classDef di fill:#FFE4B2,stroke:#333;
    classDef core fill:#FFE4B2,stroke:#333;
    classDef tool fill:#FFD2A6,stroke:#333;
    classDef infra fill:#E0D0FF,stroke:#333;
```
