Architecture Overview
June 30, 2026 · View on GitHub
This document describes the architecture of Tree-sitter Analyzer, including its plugin system, MCP integration, and core components.
High-Level Architecture
┌─────────────────────────────────────────────────────────────────────────┐
│ User Interfaces │
├────────────────────┬────────────────────┬───────────────────────────────┤
│ CLI Interface │ MCP Server │ Python API │
│ (tree-sitter- │ (AI Assistant │ (Direct Import) │
│ analyzer) │ Integration) │ │
└────────┬───────────┴────────┬───────────┴────────────┬──────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Core Engine │
├─────────────────────────────────────────────────────────────────────────┤
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌─────────────┐ │
│ │ Analyzer │ │ Query │ │ Formatter │ │ Cache │ │
│ │ Engine │ │ Engine │ │ Registry │ │ Service │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬──────┘ │
│ │ │ │ │ │
└─────────┼─────────────────┼─────────────────┼─────────────────┼─────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Language Plugins │
├────────┬────────┬────────┬────────┬────────┬────────┬────────┬─────────┤
│ Java │ Python │ TS │ SQL │ HTML │ CSS │ Rust │ ... │
└────────┴────────┴────────┴────────┴────────┴────────┴────────┴─────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Tree-sitter Parsers │
└─────────────────────────────────────────────────────────────────────────┘
Core Components
1. Analyzer Engine
The analyzer engine is the central component that orchestrates code analysis.
Location: tree_sitter_analyzer/core/analysis_engine.py
Responsibilities:
- Parse source code using tree-sitter
- Extract code elements (classes, methods, functions, etc.)
- Calculate metrics (lines, complexity, etc.)
- Coordinate with language plugins
Key Classes:
UnifiedAnalysisEngine: Main analysis orchestratorAnalysisResult: Container for analysis resultsElementExtractor: Base class for element extraction
2. Language Plugins
Each supported language has a dedicated plugin that understands its syntax and semantics.
Location: tree_sitter_analyzer/languages/ (plugin implementations);
tree_sitter_analyzer/plugins/ contains only the abstract base class (LanguagePlugin) and the plugin manager/registry.
Plugin Structure:
languages/
├── java_plugin.py # Java language support
├── python_plugin.py # Python language support
├── typescript_plugin.py # TypeScript/JavaScript support
├── sql_plugin.py # SQL support
├── html_plugin.py # HTML support
├── css_plugin.py # CSS support
├── rust_plugin.py # Rust support
├── go_plugin.py # Go support
├── kotlin_plugin.py # Kotlin support
└── ...
plugins/
├── base_plugin.py # Abstract base class (LanguagePlugin ABC)
└── ... # Plugin manager / registry
Plugin Responsibilities:
- Define language-specific tree-sitter queries
- Map AST nodes to code elements
- Provide language-specific formatting
- Handle language idioms and patterns
3. Formatter Registry
The formatter system provides flexible output formatting.
Location: tree_sitter_analyzer/formatters/
Components:
FormatterRegistry: Central registry for formattersBaseFormatter: Abstract formatter interface- Language-specific formatters (Java, SQL, HTML, etc.)
Output Formats:
| Format | Description |
|---|---|
full | Comprehensive table with all details |
compact | Abbreviated summary |
csv | Machine-readable CSV |
json | Structured JSON |
text | Human-readable text |
html | HTML-specific format |
4. Query Engine
The query engine enables targeted code element extraction.
Location: tree_sitter_analyzer/core/query.py
Features:
- Predefined query keys (methods, classes, functions, etc.)
- Custom tree-sitter query support
- Filter expressions for result refinement
5. Cache Service
The cache service optimizes repeated operations.
Location: tree_sitter_analyzer/core/cache_service.py
Capabilities:
- Analysis result caching
- File modification detection
- Memory-efficient storage
MCP Integration
MCP Server Architecture
┌─────────────────────────────────────────────────────────────┐
│ MCP Server │
│ (tree_sitter_analyzer/mcp/server.py) │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Tool Registry │ │
│ ├─────────────────────────────────────────────────────┤ │
│ │ 8 facade tools (each with action= parameter): │ │
│ │ • search • nav • structure • health │ │
│ │ • edit • project • index • viz │ │
│ │ + set_project_path (standalone infrastructure) │ │
│ │ See docs/CODEMAPS/mcp-tools.md for action lists. │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Resource Registry │ │
│ ├─────────────────────────────────────────────────────┤ │
│ │ • code://file/{path} - File content access │ │
│ │ • code://stats/{type} - Project statistics │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Security Layer │ │
│ ├─────────────────────────────────────────────────────┤ │
│ │ • Project boundary validation │ │
│ │ • Path traversal prevention │ │
│ │ • Input sanitization │ │
│ │ • Error message filtering │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
MCP Tool Classes
Location: tree_sitter_analyzer/mcp/tools/
The public surface is 8 facade tools + set_project_path. Each facade delegates to inner tool classes (approximately 74 total). For the full action-to-tool mapping see docs/CODEMAPS/mcp-tools.md.
| Facade | Purpose |
|---|---|
search | Symbol/content/grep/query/batch/chain/DSL search |
nav | Call-graph navigation, context, callers/callees, impact |
structure | AST outline, analyze, read, class tree, explore |
health | Project/file health, patterns, heatmap, deps, test_gap |
edit | Edit safety, guard, impact, refactor, constraints, PR review |
project | Project overview, files, smart context, workflow |
index | CodeGraph index lifecycle (status/build/sync) |
viz | UML / graph diagrams + similarity |
set_project_path | Project boundary setting (standalone, not a facade) |
External Tool Integration
┌──────────────────┐ ┌──────────────────┐
│ fd │ │ ripgrep │
│ (file search) │ │ (content search) │
└────────┬─────────┘ └────────┬─────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────┐
│ External Tool Wrapper │
│ (tree_sitter_analyzer/tools/external/) │
├─────────────────────────────────────────────┤
│ • Process execution │
│ • Output parsing │
│ • Error handling │
│ • Result normalization │
└─────────────────────────────────────────────┘
Data Models
Code Elements
Location: tree_sitter_analyzer/models/
# Base element types
CodeElement # Generic code element
ClassElement # Class/interface/struct
MethodElement # Method/function
FieldElement # Field/property/variable
ImportElement # Import/include statement
PackageElement # Package/namespace/module
# Specialized elements
MarkupElement # HTML elements
StyleElement # CSS rules
SQLElement # Database objects
Analysis Results
AnalysisResult:
- file_path: str
- language: str
- metrics: FileMetrics
- elements: List[CodeElement]
- errors: List[AnalysisError]
FileMetrics:
- lines_total: int
- lines_code: int
- lines_comment: int
- lines_blank: int
- complexity: ComplexityMetrics
Security Architecture
Project Boundary Protection
┌─────────────────────────────────────────┐
│ Security Validator │
├─────────────────────────────────────────┤
│ │
│ Request │
│ │ │
│ ▼ │
│ ┌────────────────────────────────┐ │
│ │ Path Normalization │ │
│ │ (resolve symlinks, canonize) │ │
│ └──────────────┬─────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────┐ │
│ │ Boundary Check │ │
│ │ (is path within project?) │ │
│ └──────────────┬─────────────────┘ │
│ │ │
│ ┌────┴────┐ │
│ │ Valid? │ │
│ └────┬────┘ │
│ Yes │ No │
│ │ │ │ │
│ ▼ │ ▼ │
│ ┌─────────┐ │ ┌─────────┐ │
│ │ Allow │ │ │ Reject │ │
│ └─────────┘ │ └─────────┘ │
│ │ │
└─────────────────┴───────────────────────┘
Input Validation
- Path traversal prevention (
../detection) - Null byte injection detection
- Unicode normalization attack prevention
- Maximum path length enforcement
- File extension validation
Error Sanitization
Error responses automatically remove:
- Passwords and tokens
- Full file system paths
- Stack traces (in production)
- Internal configuration details
Performance Optimization
Caching Strategy
┌─────────────────────────────────────────┐
│ Request │
│ │ │
│ ▼ │
│ ┌───────────────┐ │
│ │ Cache Check │ │
│ └───────┬───────┘ │
│ │ │
│ Hit │ Miss │
│ │ │ │ │
│ ▼ │ ▼ │
│ ┌──────────┐ │ ┌──────────┐ │
│ │ Return │ │ │ Analyze │ │
│ │ Cached │ │ │ & Cache │ │
│ └──────────┘ │ └──────────┘ │
│ │ │
└────────────────┴────────────────────────┘
Token Optimization
Five levels of token optimization:
| Level | Options | Token Reduction |
|---|---|---|
| 1 | count_only=true | ~70% |
| 2 | summary_only=true | ~80% |
| 3 | suppress_output=true + output_file | ~95% |
| 4 | group_by_file=true | ~60% |
| 5 | total_only=true | ~90% |
Extension Points
Adding a New Language
- Create plugin file:
languages/ - Implement
BasePlugininterface - Define tree-sitter queries
- Register with
PluginRegistry - Create formatter if needed
- Add tests
See New Language Support Checklist for detailed guidance.
Adding a New MCP Tool
- Create tool class in
mcp/tools/ - Implement
BaseToolinterface - Define input/output schemas
- Register with MCP server
- Add documentation
- Add tests
Adding a New Output Format
- Create formatter in
formatters/ - Implement
BaseFormatterinterface - Register with
FormatterRegistry - Add CLI option if needed
- Add tests
Directory Structure
tree_sitter_analyzer/
├── __init__.py
├── __main__.py # CLI entry point
├── core/
│ ├── analysis_engine.py # Main analyzer
│ ├── cache_service.py # Caching
│ ├── query.py # Query engine
│ └── language_detector.py # Language detection
├── models/
│ ├── elements.py # Code element models
│ ├── results.py # Analysis result models
│ └── metrics.py # Metric models
├── plugins/
│ ├── base_plugin.py # Plugin base class
│ ├── java_plugin.py
│ ├── python_plugin.py
│ └── ...
├── formatters/
│ ├── base_formatter.py # Formatter base class
│ ├── registry.py # Formatter registry
│ ├── java_formatter.py
│ └── ...
├── mcp/
│ ├── server.py # MCP server
│ ├── tools/ # MCP tool implementations
│ └── resources/ # MCP resource handlers
├── services/
│ ├── file_service.py # File operations
│ └── security_service.py # Security validation
└── tools/
└── external/ # External tool wrappers
├── fd_wrapper.py
└── ripgrep_wrapper.py
Related Documentation
- Installation Guide - Setup instructions
- CLI Reference - Command-line usage
- MCP Tools Specification - API details
- Features Overview - Language support
- SMART Workflow - Usage methodology
- Contributing Guide - Development guidelines