tree-sitter-analyzer

Name	tree-sitter-analyzer JSON
Version	1.6.0 JSON
	download
home_page	None
Summary	Extensible multi-language code analyzer framework using Tree-sitter with dynamic plugin architecture
upload_time	2025-10-06 14:47:13
maintainer	None
docs_url	None
author	None
requires_python	>=3.10
license	MIT
keywords	ai-tools ast code-analysis mcp mcp-server model-context-protocol multi-language parsing static-analysis tree-sitter
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # Tree-sitter Analyzer

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-1893%20passed-brightgreen.svg)](#quality-assurance)
[![Coverage](https://img.shields.io/badge/coverage-71.48%25-green.svg)](#quality-assurance)
[![Quality](https://img.shields.io/badge/quality-enterprise%20grade-blue.svg)](#quality-assurance)
[![PyPI](https://img.shields.io/pypi/v/tree-sitter-analyzer.svg)](https://pypi.org/project/tree-sitter-analyzer/)
[![Version](https://img.shields.io/badge/version-1.6.0-blue.svg)](https://github.com/aimasteracc/tree-sitter-analyzer/releases)
[![GitHub Stars](https://img.shields.io/github/stars/aimasteracc/tree-sitter-analyzer.svg?style=social)](https://github.com/aimasteracc/tree-sitter-analyzer)

## 🚀 Break LLM Token Limits, Let AI Understand Code Files of Any Size

> **Revolutionary Code Analysis Tool Designed for the AI Era**

## 📋 Table of Contents

- [🚀 Break LLM Token Limits](#-break-llm-token-limits-let-ai-understand-code-files-of-any-size)
- [📋 Table of Contents](#-table-of-contents)
- [💡 Unique Features](#-unique-features)
- [📊 Real-time Demo and Results](#-real-time-demo-and-results)
- [🚀 30-Second Quick Start](#-30-second-quick-start)
  - [🤖 AI Users (Claude Desktop, Cursor, etc.)](#-ai-users-claude-desktop-cursor-etc)
  - [💻 Developers (CLI)](#-developers-cli)
- [❓ Why Choose Tree-sitter Analyzer](#-why-choose-tree-sitter-analyzer)
- [📖 Practical Usage Examples](#-practical-usage-examples)
- [🛠️ Core Features](#️-core-features)
- [📦 Installation Guide](#-installation-guide)
- [🔒 Security and Configuration](#-security-and-configuration)
- [🏆 Quality Assurance](#-quality-assurance)
- [🤖 AI Collaboration Support](#-ai-collaboration-support)
- [📚 Documentation](#-documentation)
- [🤝 Contributing](#-contributing)
- [📄 License](#-license)

## 💡 Unique Features

Imagine this: you have a Java service class with over 1400 lines, and Claude or ChatGPT can't analyze it due to token limits. Now, Tree-sitter Analyzer enables AI assistants to:

- ⚡ **Get complete code structure overview in 3 seconds**
- 🎯 **Accurate extraction** of code snippets from any line range
- 📍 **Smart positioning** of exact locations for classes, methods, and fields
- 🔗 **Seamless integration** with Claude Desktop, Cursor, Roo Code, and other AI IDEs
- 🏗️ **Unified element management** - All code elements (classes, methods, fields, imports) in a unified system

**No more AI being helpless with large files!**

## 📊 Real-time Demo and Results

### ⚡ **Lightning-fast Analysis Speed**
```bash
# Analysis result of 1419-line large Java service class (< 1 second)
Lines: 1419 | Classes: 1 | Methods: 66 | Fields: 9 | Imports: 8 | Packages: 1
Total Elements: 85 | Complexity: 348 (avg: 5.27, max: 15)
```

### 📊 **Precise Structure Table**
| Class Name | Type | Visibility | Line Range | Method Count | Field Count |
|------------|------|------------|------------|--------------|-------------|
| BigService | class | public | 17-1419 | 66 | 9 |

### 🔄 **AI Assistant SMART Workflow**
- **S**: `set_project_path` - Setup project root directory
- **M**: `list_files`, `search_content`, `find_and_grep` - Map target files with precision
- **A**: `analyze_code_structure` - Analyze core structure with unified elements (supports file output)
- **R**: `extract_code_section` - Retrieve essential code snippets on demand
- **T**: Advanced dependency tracing (when needed)

---

## 🆕 New CLI Commands (v1.3.8+)

### 🔧 **Standalone CLI Tools for File System Operations**

Tree-sitter Analyzer now provides dedicated CLI commands that wrap powerful MCP tools for file system operations:

> **💡 Usage Note**: In development environments, use `uv run` prefix to execute CLI commands:
> - `uv run list-files` instead of `list-files`
> - `uv run search-content` instead of `search-content`
> - `uv run find-and-grep` instead of `find-and-grep`
>
> After installing from PyPI, these commands will be available directly in your PATH.

#### 📁 **`list-files`** - File Discovery with fd
```bash
# List all Java files in current directory
uv run list-files . --extensions java

# Find test files with specific naming patterns
uv run list-files src --pattern "test_*" --extensions java --types f

# Find large files modified in the last week
uv run list-files . --types f --size "+1k" --changed-within "1week"

# Find service classes with specific naming patterns
uv run list-files src --pattern "*Service*" --extensions java --output-format json
```

#### 🔍 **`search-content`** - Content Search with ripgrep
```bash
# Search for class definitions in Java files
uv run search-content --roots . --query "class.*extends" --include-globs "*.java"

# Find TODO comments with context
uv run search-content --roots src --query "TODO|FIXME" --context-before 2 --context-after 2

# Search in specific files with case-insensitive matching
uv run search-content --files file1.java file2.java --query "public.*method" --case insensitive
```

#### 🎯 **`find-and-grep`** - Two-Stage Search (fd → ripgrep)
```bash
# Find Java files first, then search for Spring annotations
uv run find-and-grep --roots . --query "@SpringBootApplication" --extensions java

# Combined file filtering and content search with limits
uv run find-and-grep --roots src --query "import.*spring" --extensions java --file-limit 10 --max-count 5

# Advanced search with multiple filters
uv run find-and-grep --roots . --query "public.*static.*void" --extensions java --types f --size "+500" --output-format json
```

### 🛡️ **Security & Safety Features**
- **Project Boundary Detection**: All commands automatically detect and respect project boundaries
- **Input Validation**: Comprehensive parameter validation and sanitization
- **Error Handling**: Graceful error handling with informative messages
- **Resource Limits**: Built-in limits to prevent resource exhaustion

### 📊 **Output Formats**
- **JSON**: Structured output for programmatic processing
- **Text**: Human-readable output for terminal use
- **Quiet Mode**: Suppress non-essential output for scripting

---

## 🚀 30-Second Quick Start

### 🤖 AI Users (Claude Desktop, Cursor, etc.)

**📋 0. Prerequisites (for Advanced MCP Tools)**
For advanced file search and content analysis features, install these tools first:
```bash
# Install fd and ripgrep (see Prerequisites section for detailed instructions)
# macOS
brew install fd ripgrep

# Windows (using winget - recommended)
winget install sharkdp.fd BurntSushi.ripgrep.MSVC

# Windows (alternative methods)
# choco install fd ripgrep
# scoop install fd ripgrep

# Ubuntu/Debian
sudo apt install fd-find ripgrep
```

**📦 1. One-click Installation**
```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**⚙️ 2. AI Client Configuration**

**Claude Desktop Configuration:**

Add the following to your configuration file:
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/claude/claude_desktop_config.json`

**Basic Configuration (Recommended):**
```json
{
  "mcpServers": {
    "tree-sitter-analyzer": {
      "command": "uv",
      "args": [
        "run", "--with", "tree-sitter-analyzer[mcp]",
        "python", "-m", "tree_sitter_analyzer.mcp.server"
      ]
    }
  }
}
```

**Advanced Configuration (Specify Project Root Directory):**
```json
{
  "mcpServers": {
    "tree-sitter-analyzer": {
      "command": "uv",
      "args": [
        "run", "--with", "tree-sitter-analyzer[mcp]",
        "python", "-m", "tree_sitter_analyzer.mcp.server"
      ],
      "env": {
        "TREE_SITTER_PROJECT_ROOT": "/absolute/path/to/your/project",
        "TREE_SITTER_OUTPUT_PATH": "/absolute/path/to/output/directory"
      }
    }
  }
}
```

**Other AI Clients:**
- **Cursor**: Built-in MCP support, refer to Cursor documentation for configuration
- **Roo Code**: Supports MCP protocol, check corresponding configuration guides
- **Other MCP-compatible clients**: Use the same server configuration

**⚠️ Configuration Notes:**
- **Basic Configuration**: Tool automatically detects project root directory (recommended)
- **Advanced Configuration**: If you need to specify a particular directory, replace `/absolute/path/to/your/project` with an absolute path
- **Avoid Using**: Variables like `${workspaceFolder}` may not be supported in some clients

**🎉 3. Restart AI client and start analyzing large code files!**

### 💻 Developers (CLI)

```bash
# Installation
uv add "tree-sitter-analyzer[popular]"

# Check file size (1419-line large service class, completed instantly)
uv run python -m tree_sitter_analyzer examples/BigService.java --advanced --output-format=text

# Generate structure table (1 class, 66 methods, clearly displayed)
uv run python -m tree_sitter_analyzer examples/BigService.java --table=full

# Precise code extraction
uv run python -m tree_sitter_analyzer examples/BigService.java --partial-read --start-line 100 --end-line 105
```

---

## ❓ Why Choose Tree-sitter Analyzer

### 🎯 Solve Real Pain Points

**Traditional Method Difficulties:**
- ❌ Large files exceed LLM token limits
- ❌ AI cannot understand code structure
- ❌ Need to manually split files
- ❌ Context loss leads to inaccurate analysis

**Tree-sitter Analyzer Breakthrough:**
- ✅ **Smart Analysis**: Understand structure without reading complete files
- ✅ **Precise Positioning**: Accurate line-by-line code extraction
- ✅ **AI Native**: Optimized for LLM workflows
- ✅ **Multi-language Support**: Java, Python, JavaScript/TypeScript, etc.

## 📖 Practical Usage Examples

### 💬 AI IDE Prompts (SMART Analysis Workflow)

> **✅ Test Verification Status:** All prompts below have been tested and verified in real environments, ensuring 100% availability
>
> **🎯 SMART Analysis Workflow:**
> - **S** - Setup project (set_project_path)
> - **M** - Map target files (precision pattern matching)
> - **A** - Analyze core structure (analyze_code_structure with optional file output)
> - **R** - Retrieve essential code (extract_code_section)
> - **T** - Trace dependencies (when needed)
>
> **⚠️ Important Notes:**
> - Follow SMART workflow sequence for optimal results
> - For files within the project, use **relative paths** (e.g., `examples/BigService.java`)
> - For files outside the project, use **absolute paths** (e.g., `C:\git-public\tree-sitter-analyzer\examples\BigService.java`)
> - All tools support both Windows and Unix style paths
> - Project path should point to your code repository root directory

#### 🔧 **S - Setup Project (Required First Step)**

**Option 1: Configure in MCP Settings**
```json
{
  "mcpServers": {
    "tree-sitter-analyzer": {
      "command": "uv",
      "args": ["run", "python", "-m", "tree_sitter_analyzer.mcp.server"],
      "env": {
        "TREE_SITTER_PROJECT_ROOT": "/path/to/your/project",
        "TREE_SITTER_OUTPUT_PATH": "/path/to/output/directory"
      }
    }
  }
}
```

**Option 2: Tell AI Directly (Recommended, More Natural)**

**Method 1: Explicit Setup Request**
```
Please help me set the project root directory, the path is: C:\git-public\tree-sitter-analyzer
```

**Method 2: Provide Project Information**
```
My project is at: C:\git-public\tree-sitter-analyzer
Please set this path as the project root
```

**Method 3: Simple Statement**
```
Project path: C:\git-public\tree-sitter-analyzer
```

**AI will automatically call the appropriate tool to set the path, no need to remember complex command formats**

**⚠️ Important Notes:**
- After setting project path, you can use relative paths to reference files within the project
- Example: `examples/BigService.java` instead of full paths
- Once project path is successfully set, all subsequent analysis commands will automatically use this root directory

#### 🗺️ **M - Map Target Files (Precision Pattern Matching)**

> **📋 Prerequisites:** This step requires `fd` and `ripgrep` tools to be installed. See [Prerequisites](#prerequisites) section for installation instructions.

**Smart File Discovery:**
```
Find all Python files in the project
```

```
List all Java files larger than 10KB
```

```
Find configuration files (*.json, *.yaml, *.toml) in the project
```

**Intelligent Content Search:**
```
Search for "def authenticate" in all Python files with context
```

```
Find all TODO comments in source files
```

```
Search for "class.*Service" patterns in all files, case insensitive
```

**Combined Discovery & Search:**
```
Find all Python files and search for "async def" functions
```

```
Search for "class.*Service" in all source files
```

**Return Format:**
```json
{
  "success": true,
  "results": [
    {
      "file": "tree_sitter_analyzer/core/query_service.py",
      "line": 20,
      "text": "class QueryService:",
      "matches": [[0, 18]]
    }
  ],
  "count": 25,
  "meta": {
    "searched_file_count": 256,
    "truncated": false,
    "fd_elapsed_ms": 225,
    "rg_elapsed_ms": 2969
  }
}
```

#### 🔍 **A - Analyze Core Structure**

**Method 1: Explicit Analysis Request**
```
Please help me analyze this file: examples/BigService.java
```

**Method 2: Describe Analysis Needs**
```
I want to understand the size and structure of this Java file: examples/BigService.java
```

**Method 3: Simple Request**
```
Analyze this file: examples/BigService.java
```

**Alternative using absolute path:**
```
Please analyze this file: C:\git-public\tree-sitter-analyzer\examples\BigService.java
```

**💡 Tip: After setting project path, using relative paths is recommended, more concise and convenient**

**Return Format:**
```json
{
  "file_path": "examples/BigService.java",
  "language": "java",
  "metrics": {
    "lines_total": 1419,
    "lines_code": 907,
    "lines_comment": 246,
    "lines_blank": 267,
    "elements": {
      "classes": 1,
      "methods": 66,
      "fields": 9,
      "imports": 8,
      "packages": 1,
      "total": 85
    },
    "complexity": {
      "total": 348,
      "average": 5.27,
      "max": 15
    }
  }
}
```

#### 📊 **R - Retrieve Essential Code**

**Method 1: Explicit Table Request**
```
Please generate a detailed structure table for this file: examples/BigService.java
```

**Method 2: Describe Table Needs**
```
I want to see the complete structure of this Java file, including all classes, methods, and fields: examples/BigService.java
```

**Method 3: Simple Request**
```
Generate structure table: examples/BigService.java
```

**Alternative using absolute path:**
```
Please generate a detailed structure table: C:\git-public\tree-sitter-analyzer\examples\BigService.java
```

**💡 Tip: After setting project path, using relative paths is recommended, more concise and convenient**

**Return Format:**
- Complete Markdown table
- Including class information, method list (with line numbers), field list
- Method signatures, visibility, line ranges, complexity, and other detailed information

#### ✂️ **Precise Code Extraction**

**Method 1: Explicit Extraction Request**
```
Please extract lines 93-105 of this file: examples/BigService.java
```

**Method 2: Describe Extraction Needs**
```
I want to see the code content from lines 93 to 105 of this Java file: examples/BigService.java
```

**Method 3: Simple Request**
```
Extract lines 93-105: examples/BigService.java
```

**Alternative using absolute path:**
```
Please extract code snippet: C:\git-public\tree-sitter-analyzer\examples\BigService.java, lines 93-105
```

**💡 Tip: After setting project path, using relative paths is recommended, more concise and convenient**

**Return Format:**
```json
{
  "file_path": "examples/BigService.java",
  "range": {
    "start_line": 93,
    "end_line": 105,
    "start_column": null,
    "end_column": null
  },
  "content": "    private void checkMemoryUsage() {\n        Runtime runtime = Runtime.getRuntime();\n        long totalMemory = runtime.totalMemory();\n        long freeMemory = runtime.freeMemory();\n        long usedMemory = totalMemory - freeMemory;\n\n        System.out.println(\"Total Memory: \" + totalMemory);\n        System.out.println(\"Free Memory: \" + freeMemory);\n        System.out.println(\"Used Memory: \" + usedMemory);\n\n        if (usedMemory > totalMemory * 0.8) {\n            System.out.println(\"WARNING: High memory usage detected!\");\n        }\n",
  "content_length": 542
}
```

#### 🔗 **T - Trace Dependencies (Advanced Analysis)**

**Error Handling Enhancement (v0.9.7):**
- Improved `@handle_mcp_errors` decorator with tool name recognition
- Better error context for easier debugging and troubleshooting
- Enhanced file path security validation

**Find Specific Methods:**
```
Please help me find the main method in this file: examples/BigService.java
```

**Find Authentication-related Methods:**
```
I want to find all authentication-related methods: examples/BigService.java
```

**Find Public Methods with No Parameters:**
```
Please help me find all public getter methods with no parameters: examples/BigService.java
```

**Return Format:**
```json
{
  "success": true,
  "results": [
    {
      "capture_name": "method",
      "node_type": "method_declaration",
      "start_line": 1385,
      "end_line": 1418,
      "content": "public static void main(String[] args) {\n        System.out.println(\"BigService Demo Application\");\n        System.out.println(\"==========================\");\n\n        BigService service = new BigService();\n\n        // Test basic functions\n        System.out.println(\"\\n--- Testing Basic Functions ---\");\n        service.authenticateUser(\"testuser\", \"password123\");\n        service.createSession(\"testuser\");\n\n        // Test customer management\n        System.out.println(\"\\n--- Testing Customer Management ---\");\n        service.updateCustomerName(\"CUST001\", \"New Customer Name\");\n        Map<String, Object> customerInfo = service.getCustomerInfo(\"CUST001\");\n\n        // Test report generation\n        System.out.println(\"\\n--- Testing Report Generation ---\");\n        Map<String, Object> reportParams = new HashMap<>();\n        reportParams.put(\"start_date\", \"2024-01-01\");\n        reportParams.put(\"end_date\", \"2024-12-31\");\n        service.generateReport(\"sales\", reportParams);\n\n        // Test performance monitoring\n        System.out.println(\"\\n--- Testing Performance Monitoring ---\");\n        service.monitorPerformance();\n\n        // Test security check\n        System.out.println(\"\\n--- Testing Security Check ---\");\n        service.performSecurityCheck();\n\n        System.out.println(\"\\n--- Demo Completed ---\");\n        System.out.println(\"BigService demo application finished successfully.\");\n    }"
    }
  ],
  "count": 1,
  "file_path": "examples/BigService.java",
  "language": "java",
  "query": "methods"
}
```


#### 💡 **SMART Workflow Best Practices**
- **Natural Language**: Tell AI directly in natural language what you want, no need to remember complex parameter formats
- **Sequential Flow**: Follow S→M→A→R→T sequence for optimal analysis results
- **Path Processing**: After setting project path, relative paths automatically resolve to project root directory
- **Security Protection**: Tool automatically performs project boundary checks to ensure security
- **Smart Understanding**: AI automatically understands your needs and calls appropriate tools
- **Performance**: All MCP tools are optimized for speed with built-in timeouts and result limits
- **Dependency Tracing**: Use T step only when you need to understand complex relationships between code elements

### 🛠️ CLI Command Examples

```bash
# Quick analysis (1419-line large file, completed instantly)
uv run python -m tree_sitter_analyzer examples/BigService.java --advanced --output-format=text

# Detailed structure table (66 methods clearly displayed)
uv run python -m tree_sitter_analyzer examples/BigService.java --table=full

# Precise code extraction (memory usage monitoring code snippet)
uv run python -m tree_sitter_analyzer examples/BigService.java --partial-read --start-line 100 --end-line 105

# Multi-language support test (Python file)
uv run python -m tree_sitter_analyzer examples/sample.py --table=full

# Small file quick analysis (54-line Java file)
uv run python -m tree_sitter_analyzer examples/MultiClass.java --advanced

# Silent mode (only show results)
uv run python -m tree_sitter_analyzer examples/BigService.java --table=full --quiet

# 🔍 Query Filter Examples (v0.9.6+)
# Find specific methods
uv run python -m tree_sitter_analyzer examples/BigService.java --query-key methods --filter "name=main"

# Find authentication-related methods
uv run python -m tree_sitter_analyzer examples/BigService.java --query-key methods --filter "name=~auth*"

# Find public methods with no parameters
uv run python -m tree_sitter_analyzer examples/BigService.java --query-key methods --filter "params=0,public=true"

# Find static methods
uv run python -m tree_sitter_analyzer examples/BigService.java --query-key methods --filter "static=true"

# View filter syntax help
uv run python -m tree_sitter_analyzer --filter-help

# 🆕 New CLI Commands (v1.3.8+)
# File listing with fd functionality
uv run list-files . --extensions java --output-format json

# Content search with ripgrep functionality
uv run search-content --roots . --query "class.*extends" --include-globs "*.java" --output-format text

# Two-stage search: find files first, then search content
uv run find-and-grep --roots . --query "public.*method" --extensions java --output-format json

# Advanced file filtering
uv run list-files . --types f --size "+1k" --changed-within "1week" --hidden --output-format text

# Content search with context
uv run search-content --roots src --query "TODO|FIXME" --context-before 2 --context-after 2 --output-format json

# Combined file and content search with limits
uv run find-and-grep --roots . --query "import.*spring" --extensions java --file-limit 10 --max-count 5 --output-format text
```

---

## 🏗️ Architecture Improvements (v1.2.0+)

### 🔄 **Unified Element Management System**

Tree-sitter Analyzer now features a revolutionary unified architecture that integrates all code elements into a unified system:

#### **Before (Traditional Architecture):**
- Independent collections of classes, methods, fields, and imports
- Inconsistent data structures across different analysis modes
- Complex maintenance and potential inconsistencies

#### **After (Unified Architecture):**
- **Single `elements` list**: All code elements (classes, methods, fields, imports, packages) unified
- **Consistent element types**: Each element has an `element_type` attribute for easy identification
- **Simplified API**: Clearer interfaces and reduced complexity
- **Better maintainability**: Single source of truth for all code elements

#### **Benefits:**
- ✅ **Consistency**: Unified data structures across all analysis modes
- ✅ **Simplicity**: Easier to use and understand
- ✅ **Extensibility**: Easy to add new element types
- ✅ **Performance**: Optimized memory usage and processing
- ✅ **Backward compatibility**: Existing APIs continue to work seamlessly

#### **Supported Element Types:**
- `class` - Classes and interfaces
- `function` - Methods and functions
- `variable` - Fields and variables
- `import` - Import statements
- `package` - Package declarations

---

## 🛠️ Core Features

### 📊 **Code Structure Analysis**
Get insights without reading complete files:
- Class, method, and field statistics
- Package information and import dependencies
- Complexity metrics
- Precise line number positioning

### ✂️ **Smart Code Extraction**
- Precise extraction by line range
- Maintains original format and indentation
- Includes position metadata
- Supports efficient processing of large files

### 🔍 **Advanced Query Filtering**
Powerful code element query and filtering system:
- **Exact matching**: `--filter "name=main"` to find specific methods
- **Pattern matching**: `--filter "name=~auth*"` to find authentication-related methods
- **Parameter filtering**: `--filter "params=2"` to find methods with specific parameter counts
- **Modifier filtering**: `--filter "static=true,public=true"` to find static public methods
- **Compound conditions**: `--filter "name=~get*,params=0,public=true"` to combine multiple conditions
- **CLI/MCP consistency**: Same filtering syntax used in command line and AI assistants

### 🔗 **AI Assistant Integration**
Deep integration through MCP protocol:
- Claude Desktop
- Cursor IDE
- Roo Code
- Other MCP-compatible AI tools

### 🔍 **Advanced File Search & Content Analysis (v1.2.4+)**
Powerful file discovery and content search capabilities powered by fd and ripgrep:

#### **📋 Prerequisites**
To use the advanced MCP tools (ListFilesTool, SearchContentTool, FindAndGrepTool), you need to install the following command-line tools:

**Install fd (fast file finder):**
```bash
# macOS (using Homebrew)
brew install fd

# Windows (using winget - recommended)
winget install sharkdp.fd

# Windows (using Chocolatey)
choco install fd

# Windows (using Scoop)
scoop install fd

# Ubuntu/Debian
sudo apt install fd-find

# CentOS/RHEL/Fedora
sudo dnf install fd-find

# Arch Linux
sudo pacman -S fd
```

**Install ripgrep (fast text search):**
```bash
# macOS (using Homebrew)
brew install ripgrep

# Windows (using winget - recommended)
winget install BurntSushi.ripgrep.MSVC

# Windows (using Chocolatey)
choco install ripgrep

# Windows (using Scoop)
scoop install ripgrep

# Ubuntu/Debian
sudo apt install ripgrep

# CentOS/RHEL/Fedora
sudo dnf install ripgrep

# Arch Linux
sudo pacman -S ripgrep
```

**Verify Installation:**
```bash
# Check fd installation
fd --version

# Check ripgrep installation
rg --version
```

> **⚠️ Important:** Without these tools installed, the advanced MCP file search and content analysis features will not work. The basic MCP tools (analyze_code_structure, extract_code_section, etc.) will continue to work normally.

### 📁 **File Output Support (v1.5.1+)**

The `analyze_code_structure` tool now supports saving analysis results to files with automatic format detection:

#### **🎯 Key Features:**
- **Automatic Extension Detection**: Based on content type (JSON → `.json`, CSV → `.csv`, Markdown → `.md`, Text → `.txt`)
- **Smart Output Path**: Uses `TREE_SITTER_OUTPUT_PATH` environment variable or project root as fallback
- **Security Validation**: Ensures output files are written to safe, authorized locations
- **Content Type Detection**: Automatically detects content format and applies appropriate file extension

#### **📋 Usage Examples:**

**Basic File Output:**
```json
{
  "tool": "analyze_code_structure",
  "arguments": {
    "file_path": "src/BigService.java",
    "output_file": "service_analysis"
  }
}
```

**With Format Control:**
```json
{
  "tool": "analyze_code_structure", 
  "arguments": {
    "file_path": "src/BigService.java",
    "format_type": "csv",
    "output_file": "service_data"
  }
}
```

#### **🔧 Environment Configuration:**
```json
{
  "env": {
    "TREE_SITTER_PROJECT_ROOT": "/path/to/your/project",
    "TREE_SITTER_OUTPUT_PATH": "/path/to/output/directory"
  }
}
```

**Output Path Priority:**
1. `TREE_SITTER_OUTPUT_PATH` environment variable (highest priority)
2. Project root directory (from `TREE_SITTER_PROJECT_ROOT` or auto-detected)
3. Current working directory (fallback)

#### **🗂️ ListFilesTool - Smart File Discovery**
- **Advanced filtering**: File type, size, modification time, extension-based filtering
- **Pattern matching**: Glob patterns and regex support for flexible file discovery
- **Metadata enrichment**: File size, modification time, directory status, and extension information
- **Performance optimized**: Built on fd for lightning-fast file system traversal

#### **🔎 SearchContentTool - Intelligent Content Search**
- **Regex & literal search**: Flexible pattern matching with case sensitivity controls
- **Context-aware results**: Configurable before/after context lines for better understanding
- **Multiple output formats**: Standard results, count-only, summary, and grouped by file
- **Encoding support**: Handle files with different text encodings
- **Performance limits**: Built-in timeout and result limits for responsive operation

#### **🎯 FindAndGrepTool - Combined Discovery & Search**
- **Two-stage workflow**: First discover files with fd, then search content with ripgrep
- **Comprehensive filtering**: Combine file discovery filters with content search patterns
- **Advanced options**: Multiline patterns, word boundaries, fixed strings, and case controls
- **Rich metadata**: File discovery timing, search timing, and result statistics
- **Token optimization**: Path optimization and result grouping to minimize AI token usage

#### **✨ Key Benefits:**
- 🚀 **Enterprise-grade reliability**: 50+ comprehensive test cases ensuring stability
- 🎯 **Token-efficient**: Multiple output formats optimized for AI assistant interactions
- 🔧 **Highly configurable**: Extensive parameter support for precise control
- 📊 **Performance monitoring**: Built-in timing and result statistics
- 🛡️ **Error resilient**: Comprehensive error handling and validation

### 🌍 **Multi-language Support**
- **Java** - Full support, including Spring, JPA frameworks
- **Python** - Full support, including type annotations, decorators
- **JavaScript** - 🆕 **Enterprise-grade support**, including modern ES6+ features, React/Vue/Angular frameworks, JSX, async functions, generators, arrow functions, classes, module systems
- **TypeScript** - Full support, including type annotations, interfaces
- **C/C++, Rust, Go** - Basic support

---

## 🆕 JavaScript Enterprise Support (v1.5.0+)

### 🚀 **Modern JavaScript Complete Support**

Tree-sitter Analyzer now provides enterprise-level JavaScript support at the same level as Java, including:

#### **📋 Core Language Features**
- **Function Types**: Traditional functions, arrow functions, async functions, generator functions
- **Class System**: ES6 classes, inheritance, static methods, getters/setters, constructors
- **Variable Declarations**: var, let, const, destructuring assignment, template literals
- **Module System**: ES6 import/export, CommonJS require/module.exports
- **Modern Features**: Spread/rest operators, Promises, async/await

#### **🎨 Framework & Ecosystem**
- **React Support**: JSX syntax, component analysis, Hook recognition, lifecycle methods
- **Vue.js Support**: Single-file components, template syntax, reactive data
- **Angular Support**: Components, services, dependency injection pattern recognition
- **Node.js Support**: Server-side patterns, Express routing, middleware

#### **🔍 Advanced Analysis Capabilities**
- **JSDoc Extraction**: Complete documentation comment parsing and type information
- **Complexity Analysis**: Cyclomatic complexity calculation and code quality metrics
- **Framework Detection**: Automatic recognition of React, Vue, Angular project types
- **Export Analysis**: Module export mapping and dependency relationship tracking

#### **💼 Enterprise Features**
- **Table Formatting**: Dedicated JavaScript table formatter for clear code structure display
- **Performance Optimization**: Caching mechanisms, iterative traversal, efficient large file handling
- **Error Handling**: Robust exception handling and detailed error reporting
- **Type Safety**: TypeScript-style type annotation support

### 📊 **JavaScript Analysis Examples**

```bash
# Analyze modern JavaScript files
uv run python -m tree_sitter_analyzer examples/ModernJavaScript.js --language javascript --advanced

# Generate detailed structure tables
uv run python -m tree_sitter_analyzer examples/ModernJavaScript.js --language javascript --table full

# Analyze React components
uv run python -m tree_sitter_analyzer examples/ReactComponent.jsx --language javascript --table full

# Query specific function types
uv run python -m tree_sitter_analyzer examples/ModernJavaScript.js --language javascript --query-key async_function
```

### 🎯 **Supported JavaScript Query Types**
- `function_declaration` - Traditional function declarations
- `arrow_function` - Arrow functions
- `async_function` - Async functions
- `generator_function` - Generator functions
- `class_declaration` - Class declarations
- `variable_declaration` - Variable declarations
- `import_statement` - Import statements
- `export_statement` - Export statements
- `jsx_element` - JSX elements
- `method_definition` - Method definitions

### 🏗️ **AI Assistant JavaScript Workflow**

```
I want to analyze the structure of this JavaScript file: examples/ModernJavaScript.js
```

**Example Response Format:**
```json
{
  "file_path": "examples/ModernJavaScript.js",
  "language": "javascript",
  "element_count": 24,
  "elements": [
    {
      "name": "fetchUserData",
      "type": "function",
      "start_line": 208,
      "end_line": 211,
      "is_async": true,
      "framework_type": "vanilla"
    },
    {
      "name": "ModernComponent",
      "type": "class",
      "start_line": 31,
      "end_line": 200,
      "is_react_component": true,
      "framework_type": "react"
    }
  ],
  "success": true
}
```

---

## 📦 Installation Guide

### 👤 **End Users**
```bash
# Basic installation
uv add tree-sitter-analyzer

# Popular language packages (recommended)
uv add "tree-sitter-analyzer[popular]"

# MCP server support
uv add "tree-sitter-analyzer[mcp]"

# Complete installation
uv add "tree-sitter-analyzer[all,mcp]"
```

### 👨‍💻 **Developers**
```bash
git clone https://github.com/aimasteracc/tree-sitter-analyzer.git
cd tree-sitter-analyzer
uv sync --extra all --extra mcp
```

---

## 🔒 Security and Configuration

### 🛡️ **Project Boundary Protection**

Tree-sitter Analyzer automatically detects and protects project boundaries:

- **Auto-detection**: Based on `.git`, `pyproject.toml`, `package.json`, etc.
- **CLI control**: `--project-root /path/to/project`
- **MCP integration**: `TREE_SITTER_PROJECT_ROOT=/path/to/project` or use auto-detection
- **Security guarantee**: Only analyze files within project boundaries

**Recommended MCP Configuration:**

**Option 1: Auto-detection (Recommended)**
```json
{
  "mcpServers": {
    "tree-sitter-analyzer": {
      "command": "uv",
      "args": ["run", "--with", "tree-sitter-analyzer[mcp]", "python", "-m", "tree_sitter_analyzer.mcp.server"]
    }
  }
}
```

**Option 2: Manually specify project root directory**
```json
{
  "mcpServers": {
    "tree-sitter-analyzer": {
      "command": "uv",
      "args": ["run", "--with", "tree-sitter-analyzer[mcp]", "python", "-m", "tree_sitter_analyzer.mcp.server"],
      "env": {
        "TREE_SITTER_PROJECT_ROOT": "/path/to/your/project",
        "TREE_SITTER_OUTPUT_PATH": "/path/to/output/directory"
      }
    }
  }
}
```

---

## 🏆 Quality Assurance

### 📊 **Quality Metrics**
- **1,893 tests** - 100% pass rate ✅
- **71.48% code coverage** - Industry-leading level
- **Zero test failures** - Fully CI/CD ready
- **Cross-platform compatibility** - Windows, macOS, Linux

### ⚡ **Latest Quality Achievements (v1.6.0)**
- ✅ **Cross-platform path compatibility** - Fixed Windows short path names and macOS symbolic link differences
- ✅ **Windows environment** - Implemented robust path normalization using Windows API
- ✅ **macOS environment** - Fixed `/var` vs `/private/var` symbolic link differences
- ✅ **Comprehensive test coverage** - 1797 tests, 74.45% coverage
- ✅ **GitFlow implementation** - Professional development/release branch strategy. See [GitFlow documentation](GITFLOW.md) for details.

### ⚙️ **Running Tests**
```bash
# Run all tests
uv run pytest tests/ -v

# Generate coverage report
uv run pytest tests/ --cov=tree_sitter_analyzer --cov-report=html --cov-report=term-missing

# Run specific tests
uv run pytest tests/test_mcp_server_initialization.py -v
```

### 📈 **Coverage Highlights**
- **Language detector**: 98.41% (Excellent)
- **CLI main entry**: 94.36% (Excellent)
- **Query filtering system**: 96.06% (Excellent)
- **MCP fd/rg tools**: 93.04% (Excellent) - *Enhanced in v1.3.2 with cache format compatibility fix*
- **Query service**: 86.25% (Good)
- **Error handling**: 82.76% (Good)

---

## 🤖 AI Collaboration Support

### ⚡ **Optimized for AI Development**

This project supports AI-assisted development with dedicated quality control:

```bash
# AI system code generation pre-check
uv run python check_quality.py --new-code-only
uv run python llm_code_checker.py --check-all

# AI-generated code review
uv run python llm_code_checker.py path/to/new_file.py
```

📖 **Detailed Guides**:
- [AI Collaboration Guide](AI_COLLABORATION_GUIDE.md)
- [LLM Coding Guidelines](LLM_CODING_GUIDELINES.md)

---

## 📚 Documentation

- **[User MCP Setup Guide](MCP_SETUP_USERS.md)** - Simple configuration guide
- **[Developer MCP Setup Guide](MCP_SETUP_DEVELOPERS.md)** - Local development configuration
- **[Project Root Configuration](PROJECT_ROOT_CONFIG.md)** - Complete configuration reference
- **[API Documentation](docs/api.md)** - Detailed API reference
- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute
- **[Takeover and Training Guide](training/README.md)** - System onboarding materials for new members/maintainers

---

## 💝 Sponsors & Acknowledgments

We are grateful to our sponsors who make this project possible:

### 🌟 **Special Thanks**

**[@o93](https://github.com/o93)** - *Primary Sponsor & Supporter*
- 🚀 **MCP Tools Enhancement**: Sponsored the comprehensive MCP fd/ripgrep tools development
- 🧪 **Testing Infrastructure**: Enabled enterprise-grade test coverage (50+ comprehensive test cases)
- 🔧 **Quality Assurance**: Supported bug fixes and performance improvements
- 💡 **Innovation Support**: Made early release of advanced file search and content analysis features possible

*"Thanks to @o93's generous support, we were able to deliver powerful MCP tools that revolutionize how AI assistants interact with codebases. This sponsorship directly enabled the development of ListFilesTool, SearchContentTool, and FindAndGrepTool with comprehensive test coverage."*

### 🤝 **Become a Sponsor**

Your support helps us:
- 🔬 Develop new features and tools
- 🧪 Maintain comprehensive test coverage
- 📚 Create better documentation
- 🚀 Accelerate development cycles

**[💖 Sponsor this project](https://github.com/sponsors/aimasteracc)** to help us continue building amazing tools for the developer community!

---

## 🤝 Contributing

We welcome all forms of contributions! Please see [Contributing Guide](CONTRIBUTING.md) for details.

### ⭐ **Give Us a Star!**

If this project has been helpful to you, please give us a ⭐ on GitHub - this is the greatest support for us!

---

## 📄 License

MIT License - See [LICENSE](LICENSE) file for details.

---

**🎯 Built for developers dealing with large codebases and AI assistants**

*Let every line of code be understood by AI, let every project break through token limits*

---

## ✅ Prompt Testing Verification

All AI prompts in this document have been thoroughly tested in real environments, ensuring:

- **100% Availability** - All prompts work correctly
- **Multi-language Support** - Supports Java, Python, JavaScript and other mainstream languages
- **Path Compatibility** - Both relative and absolute paths are fully supported
- **Windows/Linux Compatibility** - Cross-platform path formats are automatically handled
- **Real-time Verification** - Tested using real code files

**Test Environment:**
- Operating System: Windows 10
- Project: tree-sitter-analyzer v1.6.0
- Test Files: BigService.java (1419 lines), sample.py (256 lines), MultiClass.java (54 lines)
- Test Coverage: 1797 tests passed, 74.45% coverage
- Test Tools: All MCP tools (check_code_scale, analyze_code_structure, extract_code_section, query_code, list_files, search_content, find_and_grep)

**🚀 Start Now** → [30-Second Quick Start](#-30-second-quick-start)

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "tree-sitter-analyzer",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": "\"aisheng.yu\" <aimasteracc@gmail.com>",
    "keywords": "ai-tools, ast, code-analysis, mcp, mcp-server, model-context-protocol, multi-language, parsing, static-analysis, tree-sitter",
    "author": null,
    "author_email": "\"aisheng.yu\" <aimasteracc@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/9a/80/4fb170471dd726c1f1a507432b75a1bfd2b87c2d87a1110569a9d8105503/tree_sitter_analyzer-1.6.0.tar.gz",
    "platform": null,
    "description": "# Tree-sitter Analyzer\n\n[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![Tests](https://img.shields.io/badge/tests-1893%20passed-brightgreen.svg)](#quality-assurance)\n[![Coverage](https://img.shields.io/badge/coverage-71.48%25-green.svg)](#quality-assurance)\n[![Quality](https://img.shields.io/badge/quality-enterprise%20grade-blue.svg)](#quality-assurance)\n[![PyPI](https://img.shields.io/pypi/v/tree-sitter-analyzer.svg)](https://pypi.org/project/tree-sitter-analyzer/)\n[![Version](https://img.shields.io/badge/version-1.6.0-blue.svg)](https://github.com/aimasteracc/tree-sitter-analyzer/releases)\n[![GitHub Stars](https://img.shields.io/github/stars/aimasteracc/tree-sitter-analyzer.svg?style=social)](https://github.com/aimasteracc/tree-sitter-analyzer)\n\n## \ud83d\ude80 Break LLM Token Limits, Let AI Understand Code Files of Any Size\n\n> **Revolutionary Code Analysis Tool Designed for the AI Era**\n\n## \ud83d\udccb Table of Contents\n\n- [\ud83d\ude80 Break LLM Token Limits](#-break-llm-token-limits-let-ai-understand-code-files-of-any-size)\n- [\ud83d\udccb Table of Contents](#-table-of-contents)\n- [\ud83d\udca1 Unique Features](#-unique-features)\n- [\ud83d\udcca Real-time Demo and Results](#-real-time-demo-and-results)\n- [\ud83d\ude80 30-Second Quick Start](#-30-second-quick-start)\n  - [\ud83e\udd16 AI Users (Claude Desktop, Cursor, etc.)](#-ai-users-claude-desktop-cursor-etc)\n  - [\ud83d\udcbb Developers (CLI)](#-developers-cli)\n- [\u2753 Why Choose Tree-sitter Analyzer](#-why-choose-tree-sitter-analyzer)\n- [\ud83d\udcd6 Practical Usage Examples](#-practical-usage-examples)\n- [\ud83d\udee0\ufe0f Core Features](#\ufe0f-core-features)\n- [\ud83d\udce6 Installation Guide](#-installation-guide)\n- [\ud83d\udd12 Security and Configuration](#-security-and-configuration)\n- [\ud83c\udfc6 Quality Assurance](#-quality-assurance)\n- [\ud83e\udd16 AI Collaboration Support](#-ai-collaboration-support)\n- [\ud83d\udcda Documentation](#-documentation)\n- [\ud83e\udd1d Contributing](#-contributing)\n- [\ud83d\udcc4 License](#-license)\n\n## \ud83d\udca1 Unique Features\n\nImagine this: you have a Java service class with over 1400 lines, and Claude or ChatGPT can't analyze it due to token limits. Now, Tree-sitter Analyzer enables AI assistants to:\n\n- \u26a1 **Get complete code structure overview in 3 seconds**\n- \ud83c\udfaf **Accurate extraction** of code snippets from any line range\n- \ud83d\udccd **Smart positioning** of exact locations for classes, methods, and fields\n- \ud83d\udd17 **Seamless integration** with Claude Desktop, Cursor, Roo Code, and other AI IDEs\n- \ud83c\udfd7\ufe0f **Unified element management** - All code elements (classes, methods, fields, imports) in a unified system\n\n**No more AI being helpless with large files!**\n\n## \ud83d\udcca Real-time Demo and Results\n\n### \u26a1 **Lightning-fast Analysis Speed**\n```bash\n# Analysis result of 1419-line large Java service class (< 1 second)\nLines: 1419 | Classes: 1 | Methods: 66 | Fields: 9 | Imports: 8 | Packages: 1\nTotal Elements: 85 | Complexity: 348 (avg: 5.27, max: 15)\n```\n\n### \ud83d\udcca **Precise Structure Table**\n| Class Name | Type | Visibility | Line Range | Method Count | Field Count |\n|------------|------|------------|------------|--------------|-------------|\n| BigService | class | public | 17-1419 | 66 | 9 |\n\n### \ud83d\udd04 **AI Assistant SMART Workflow**\n- **S**: `set_project_path` - Setup project root directory\n- **M**: `list_files`, `search_content`, `find_and_grep` - Map target files with precision\n- **A**: `analyze_code_structure` - Analyze core structure with unified elements (supports file output)\n- **R**: `extract_code_section` - Retrieve essential code snippets on demand\n- **T**: Advanced dependency tracing (when needed)\n\n---\n\n## \ud83c\udd95 New CLI Commands (v1.3.8+)\n\n### \ud83d\udd27 **Standalone CLI Tools for File System Operations**\n\nTree-sitter Analyzer now provides dedicated CLI commands that wrap powerful MCP tools for file system operations:\n\n> **\ud83d\udca1 Usage Note**: In development environments, use `uv run` prefix to execute CLI commands:\n> - `uv run list-files` instead of `list-files`\n> - `uv run search-content` instead of `search-content`\n> - `uv run find-and-grep` instead of `find-and-grep`\n>\n> After installing from PyPI, these commands will be available directly in your PATH.\n\n#### \ud83d\udcc1 **`list-files`** - File Discovery with fd\n```bash\n# List all Java files in current directory\nuv run list-files . --extensions java\n\n# Find test files with specific naming patterns\nuv run list-files src --pattern \"test_*\" --extensions java --types f\n\n# Find large files modified in the last week\nuv run list-files . --types f --size \"+1k\" --changed-within \"1week\"\n\n# Find service classes with specific naming patterns\nuv run list-files src --pattern \"*Service*\" --extensions java --output-format json\n```\n\n#### \ud83d\udd0d **`search-content`** - Content Search with ripgrep\n```bash\n# Search for class definitions in Java files\nuv run search-content --roots . --query \"class.*extends\" --include-globs \"*.java\"\n\n# Find TODO comments with context\nuv run search-content --roots src --query \"TODO|FIXME\" --context-before 2 --context-after 2\n\n# Search in specific files with case-insensitive matching\nuv run search-content --files file1.java file2.java --query \"public.*method\" --case insensitive\n```\n\n#### \ud83c\udfaf **`find-and-grep`** - Two-Stage Search (fd \u2192 ripgrep)\n```bash\n# Find Java files first, then search for Spring annotations\nuv run find-and-grep --roots . --query \"@SpringBootApplication\" --extensions java\n\n# Combined file filtering and content search with limits\nuv run find-and-grep --roots src --query \"import.*spring\" --extensions java --file-limit 10 --max-count 5\n\n# Advanced search with multiple filters\nuv run find-and-grep --roots . --query \"public.*static.*void\" --extensions java --types f --size \"+500\" --output-format json\n```\n\n### \ud83d\udee1\ufe0f **Security & Safety Features**\n- **Project Boundary Detection**: All commands automatically detect and respect project boundaries\n- **Input Validation**: Comprehensive parameter validation and sanitization\n- **Error Handling**: Graceful error handling with informative messages\n- **Resource Limits**: Built-in limits to prevent resource exhaustion\n\n### \ud83d\udcca **Output Formats**\n- **JSON**: Structured output for programmatic processing\n- **Text**: Human-readable output for terminal use\n- **Quiet Mode**: Suppress non-essential output for scripting\n\n---\n\n## \ud83d\ude80 30-Second Quick Start\n\n### \ud83e\udd16 AI Users (Claude Desktop, Cursor, etc.)\n\n**\ud83d\udccb 0. Prerequisites (for Advanced MCP Tools)**\nFor advanced file search and content analysis features, install these tools first:\n```bash\n# Install fd and ripgrep (see Prerequisites section for detailed instructions)\n# macOS\nbrew install fd ripgrep\n\n# Windows (using winget - recommended)\nwinget install sharkdp.fd BurntSushi.ripgrep.MSVC\n\n# Windows (alternative methods)\n# choco install fd ripgrep\n# scoop install fd ripgrep\n\n# Ubuntu/Debian\nsudo apt install fd-find ripgrep\n```\n\n**\ud83d\udce6 1. One-click Installation**\n```bash\n# macOS/Linux\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Windows PowerShell\npowershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n```\n\n**\u2699\ufe0f 2. AI Client Configuration**\n\n**Claude Desktop Configuration:**\n\nAdd the following to your configuration file:\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Linux**: `~/.config/claude/claude_desktop_config.json`\n\n**Basic Configuration (Recommended):**\n```json\n{\n  \"mcpServers\": {\n    \"tree-sitter-analyzer\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\", \"--with\", \"tree-sitter-analyzer[mcp]\",\n        \"python\", \"-m\", \"tree_sitter_analyzer.mcp.server\"\n      ]\n    }\n  }\n}\n```\n\n**Advanced Configuration (Specify Project Root Directory):**\n```json\n{\n  \"mcpServers\": {\n    \"tree-sitter-analyzer\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\", \"--with\", \"tree-sitter-analyzer[mcp]\",\n        \"python\", \"-m\", \"tree_sitter_analyzer.mcp.server\"\n      ],\n      \"env\": {\n        \"TREE_SITTER_PROJECT_ROOT\": \"/absolute/path/to/your/project\",\n        \"TREE_SITTER_OUTPUT_PATH\": \"/absolute/path/to/output/directory\"\n      }\n    }\n  }\n}\n```\n\n**Other AI Clients:**\n- **Cursor**: Built-in MCP support, refer to Cursor documentation for configuration\n- **Roo Code**: Supports MCP protocol, check corresponding configuration guides\n- **Other MCP-compatible clients**: Use the same server configuration\n\n**\u26a0\ufe0f Configuration Notes:**\n- **Basic Configuration**: Tool automatically detects project root directory (recommended)\n- **Advanced Configuration**: If you need to specify a particular directory, replace `/absolute/path/to/your/project` with an absolute path\n- **Avoid Using**: Variables like `${workspaceFolder}` may not be supported in some clients\n\n**\ud83c\udf89 3. Restart AI client and start analyzing large code files!**\n\n### \ud83d\udcbb Developers (CLI)\n\n```bash\n# Installation\nuv add \"tree-sitter-analyzer[popular]\"\n\n# Check file size (1419-line large service class, completed instantly)\nuv run python -m tree_sitter_analyzer examples/BigService.java --advanced --output-format=text\n\n# Generate structure table (1 class, 66 methods, clearly displayed)\nuv run python -m tree_sitter_analyzer examples/BigService.java --table=full\n\n# Precise code extraction\nuv run python -m tree_sitter_analyzer examples/BigService.java --partial-read --start-line 100 --end-line 105\n```\n\n---\n\n## \u2753 Why Choose Tree-sitter Analyzer\n\n### \ud83c\udfaf Solve Real Pain Points\n\n**Traditional Method Difficulties:**\n- \u274c Large files exceed LLM token limits\n- \u274c AI cannot understand code structure\n- \u274c Need to manually split files\n- \u274c Context loss leads to inaccurate analysis\n\n**Tree-sitter Analyzer Breakthrough:**\n- \u2705 **Smart Analysis**: Understand structure without reading complete files\n- \u2705 **Precise Positioning**: Accurate line-by-line code extraction\n- \u2705 **AI Native**: Optimized for LLM workflows\n- \u2705 **Multi-language Support**: Java, Python, JavaScript/TypeScript, etc.\n\n## \ud83d\udcd6 Practical Usage Examples\n\n### \ud83d\udcac AI IDE Prompts (SMART Analysis Workflow)\n\n> **\u2705 Test Verification Status:** All prompts below have been tested and verified in real environments, ensuring 100% availability\n>\n> **\ud83c\udfaf SMART Analysis Workflow:**\n> - **S** - Setup project (set_project_path)\n> - **M** - Map target files (precision pattern matching)\n> - **A** - Analyze core structure (analyze_code_structure with optional file output)\n> - **R** - Retrieve essential code (extract_code_section)\n> - **T** - Trace dependencies (when needed)\n>\n> **\u26a0\ufe0f Important Notes:**\n> - Follow SMART workflow sequence for optimal results\n> - For files within the project, use **relative paths** (e.g., `examples/BigService.java`)\n> - For files outside the project, use **absolute paths** (e.g., `C:\\git-public\\tree-sitter-analyzer\\examples\\BigService.java`)\n> - All tools support both Windows and Unix style paths\n> - Project path should point to your code repository root directory\n\n#### \ud83d\udd27 **S - Setup Project (Required First Step)**\n\n**Option 1: Configure in MCP Settings**\n```json\n{\n  \"mcpServers\": {\n    \"tree-sitter-analyzer\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"python\", \"-m\", \"tree_sitter_analyzer.mcp.server\"],\n      \"env\": {\n        \"TREE_SITTER_PROJECT_ROOT\": \"/path/to/your/project\",\n        \"TREE_SITTER_OUTPUT_PATH\": \"/path/to/output/directory\"\n      }\n    }\n  }\n}\n```\n\n**Option 2: Tell AI Directly (Recommended, More Natural)**\n\n**Method 1: Explicit Setup Request**\n```\nPlease help me set the project root directory, the path is: C:\\git-public\\tree-sitter-analyzer\n```\n\n**Method 2: Provide Project Information**\n```\nMy project is at: C:\\git-public\\tree-sitter-analyzer\nPlease set this path as the project root\n```\n\n**Method 3: Simple Statement**\n```\nProject path: C:\\git-public\\tree-sitter-analyzer\n```\n\n**AI will automatically call the appropriate tool to set the path, no need to remember complex command formats**\n\n**\u26a0\ufe0f Important Notes:**\n- After setting project path, you can use relative paths to reference files within the project\n- Example: `examples/BigService.java` instead of full paths\n- Once project path is successfully set, all subsequent analysis commands will automatically use this root directory\n\n#### \ud83d\uddfa\ufe0f **M - Map Target Files (Precision Pattern Matching)**\n\n> **\ud83d\udccb Prerequisites:** This step requires `fd` and `ripgrep` tools to be installed. See [Prerequisites](#prerequisites) section for installation instructions.\n\n**Smart File Discovery:**\n```\nFind all Python files in the project\n```\n\n```\nList all Java files larger than 10KB\n```\n\n```\nFind configuration files (*.json, *.yaml, *.toml) in the project\n```\n\n**Intelligent Content Search:**\n```\nSearch for \"def authenticate\" in all Python files with context\n```\n\n```\nFind all TODO comments in source files\n```\n\n```\nSearch for \"class.*Service\" patterns in all files, case insensitive\n```\n\n**Combined Discovery & Search:**\n```\nFind all Python files and search for \"async def\" functions\n```\n\n```\nSearch for \"class.*Service\" in all source files\n```\n\n**Return Format:**\n```json\n{\n  \"success\": true,\n  \"results\": [\n    {\n      \"file\": \"tree_sitter_analyzer/core/query_service.py\",\n      \"line\": 20,\n      \"text\": \"class QueryService:\",\n      \"matches\": [[0, 18]]\n    }\n  ],\n  \"count\": 25,\n  \"meta\": {\n    \"searched_file_count\": 256,\n    \"truncated\": false,\n    \"fd_elapsed_ms\": 225,\n    \"rg_elapsed_ms\": 2969\n  }\n}\n```\n\n#### \ud83d\udd0d **A - Analyze Core Structure**\n\n**Method 1: Explicit Analysis Request**\n```\nPlease help me analyze this file: examples/BigService.java\n```\n\n**Method 2: Describe Analysis Needs**\n```\nI want to understand the size and structure of this Java file: examples/BigService.java\n```\n\n**Method 3: Simple Request**\n```\nAnalyze this file: examples/BigService.java\n```\n\n**Alternative using absolute path:**\n```\nPlease analyze this file: C:\\git-public\\tree-sitter-analyzer\\examples\\BigService.java\n```\n\n**\ud83d\udca1 Tip: After setting project path, using relative paths is recommended, more concise and convenient**\n\n**Return Format:**\n```json\n{\n  \"file_path\": \"examples/BigService.java\",\n  \"language\": \"java\",\n  \"metrics\": {\n    \"lines_total\": 1419,\n    \"lines_code\": 907,\n    \"lines_comment\": 246,\n    \"lines_blank\": 267,\n    \"elements\": {\n      \"classes\": 1,\n      \"methods\": 66,\n      \"fields\": 9,\n      \"imports\": 8,\n      \"packages\": 1,\n      \"total\": 85\n    },\n    \"complexity\": {\n      \"total\": 348,\n      \"average\": 5.27,\n      \"max\": 15\n    }\n  }\n}\n```\n\n#### \ud83d\udcca **R - Retrieve Essential Code**\n\n**Method 1: Explicit Table Request**\n```\nPlease generate a detailed structure table for this file: examples/BigService.java\n```\n\n**Method 2: Describe Table Needs**\n```\nI want to see the complete structure of this Java file, including all classes, methods, and fields: examples/BigService.java\n```\n\n**Method 3: Simple Request**\n```\nGenerate structure table: examples/BigService.java\n```\n\n**Alternative using absolute path:**\n```\nPlease generate a detailed structure table: C:\\git-public\\tree-sitter-analyzer\\examples\\BigService.java\n```\n\n**\ud83d\udca1 Tip: After setting project path, using relative paths is recommended, more concise and convenient**\n\n**Return Format:**\n- Complete Markdown table\n- Including class information, method list (with line numbers), field list\n- Method signatures, visibility, line ranges, complexity, and other detailed information\n\n#### \u2702\ufe0f **Precise Code Extraction**\n\n**Method 1: Explicit Extraction Request**\n```\nPlease extract lines 93-105 of this file: examples/BigService.java\n```\n\n**Method 2: Describe Extraction Needs**\n```\nI want to see the code content from lines 93 to 105 of this Java file: examples/BigService.java\n```\n\n**Method 3: Simple Request**\n```\nExtract lines 93-105: examples/BigService.java\n```\n\n**Alternative using absolute path:**\n```\nPlease extract code snippet: C:\\git-public\\tree-sitter-analyzer\\examples\\BigService.java, lines 93-105\n```\n\n**\ud83d\udca1 Tip: After setting project path, using relative paths is recommended, more concise and convenient**\n\n**Return Format:**\n```json\n{\n  \"file_path\": \"examples/BigService.java\",\n  \"range\": {\n    \"start_line\": 93,\n    \"end_line\": 105,\n    \"start_column\": null,\n    \"end_column\": null\n  },\n  \"content\": \"    private void checkMemoryUsage() {\\n        Runtime runtime = Runtime.getRuntime();\\n        long totalMemory = runtime.totalMemory();\\n        long freeMemory = runtime.freeMemory();\\n        long usedMemory = totalMemory - freeMemory;\\n\\n        System.out.println(\\\"Total Memory: \\\" + totalMemory);\\n        System.out.println(\\\"Free Memory: \\\" + freeMemory);\\n        System.out.println(\\\"Used Memory: \\\" + usedMemory);\\n\\n        if (usedMemory > totalMemory * 0.8) {\\n            System.out.println(\\\"WARNING: High memory usage detected!\\\");\\n        }\\n\",\n  \"content_length\": 542\n}\n```\n\n#### \ud83d\udd17 **T - Trace Dependencies (Advanced Analysis)**\n\n**Error Handling Enhancement (v0.9.7):**\n- Improved `@handle_mcp_errors` decorator with tool name recognition\n- Better error context for easier debugging and troubleshooting\n- Enhanced file path security validation\n\n**Find Specific Methods:**\n```\nPlease help me find the main method in this file: examples/BigService.java\n```\n\n**Find Authentication-related Methods:**\n```\nI want to find all authentication-related methods: examples/BigService.java\n```\n\n**Find Public Methods with No Parameters:**\n```\nPlease help me find all public getter methods with no parameters: examples/BigService.java\n```\n\n**Return Format:**\n```json\n{\n  \"success\": true,\n  \"results\": [\n    {\n      \"capture_name\": \"method\",\n      \"node_type\": \"method_declaration\",\n      \"start_line\": 1385,\n      \"end_line\": 1418,\n      \"content\": \"public static void main(String[] args) {\\n        System.out.println(\\\"BigService Demo Application\\\");\\n        System.out.println(\\\"==========================\\\");\\n\\n        BigService service = new BigService();\\n\\n        // Test basic functions\\n        System.out.println(\\\"\\\\n--- Testing Basic Functions ---\\\");\\n        service.authenticateUser(\\\"testuser\\\", \\\"password123\\\");\\n        service.createSession(\\\"testuser\\\");\\n\\n        // Test customer management\\n        System.out.println(\\\"\\\\n--- Testing Customer Management ---\\\");\\n        service.updateCustomerName(\\\"CUST001\\\", \\\"New Customer Name\\\");\\n        Map<String, Object> customerInfo = service.getCustomerInfo(\\\"CUST001\\\");\\n\\n        // Test report generation\\n        System.out.println(\\\"\\\\n--- Testing Report Generation ---\\\");\\n        Map<String, Object> reportParams = new HashMap<>();\\n        reportParams.put(\\\"start_date\\\", \\\"2024-01-01\\\");\\n        reportParams.put(\\\"end_date\\\", \\\"2024-12-31\\\");\\n        service.generateReport(\\\"sales\\\", reportParams);\\n\\n        // Test performance monitoring\\n        System.out.println(\\\"\\\\n--- Testing Performance Monitoring ---\\\");\\n        service.monitorPerformance();\\n\\n        // Test security check\\n        System.out.println(\\\"\\\\n--- Testing Security Check ---\\\");\\n        service.performSecurityCheck();\\n\\n        System.out.println(\\\"\\\\n--- Demo Completed ---\\\");\\n        System.out.println(\\\"BigService demo application finished successfully.\\\");\\n    }\"\n    }\n  ],\n  \"count\": 1,\n  \"file_path\": \"examples/BigService.java\",\n  \"language\": \"java\",\n  \"query\": \"methods\"\n}\n```\n\n\n#### \ud83d\udca1 **SMART Workflow Best Practices**\n- **Natural Language**: Tell AI directly in natural language what you want, no need to remember complex parameter formats\n- **Sequential Flow**: Follow S\u2192M\u2192A\u2192R\u2192T sequence for optimal analysis results\n- **Path Processing**: After setting project path, relative paths automatically resolve to project root directory\n- **Security Protection**: Tool automatically performs project boundary checks to ensure security\n- **Smart Understanding**: AI automatically understands your needs and calls appropriate tools\n- **Performance**: All MCP tools are optimized for speed with built-in timeouts and result limits\n- **Dependency Tracing**: Use T step only when you need to understand complex relationships between code elements\n\n### \ud83d\udee0\ufe0f CLI Command Examples\n\n```bash\n# Quick analysis (1419-line large file, completed instantly)\nuv run python -m tree_sitter_analyzer examples/BigService.java --advanced --output-format=text\n\n# Detailed structure table (66 methods clearly displayed)\nuv run python -m tree_sitter_analyzer examples/BigService.java --table=full\n\n# Precise code extraction (memory usage monitoring code snippet)\nuv run python -m tree_sitter_analyzer examples/BigService.java --partial-read --start-line 100 --end-line 105\n\n# Multi-language support test (Python file)\nuv run python -m tree_sitter_analyzer examples/sample.py --table=full\n\n# Small file quick analysis (54-line Java file)\nuv run python -m tree_sitter_analyzer examples/MultiClass.java --advanced\n\n# Silent mode (only show results)\nuv run python -m tree_sitter_analyzer examples/BigService.java --table=full --quiet\n\n# \ud83d\udd0d Query Filter Examples (v0.9.6+)\n# Find specific methods\nuv run python -m tree_sitter_analyzer examples/BigService.java --query-key methods --filter \"name=main\"\n\n# Find authentication-related methods\nuv run python -m tree_sitter_analyzer examples/BigService.java --query-key methods --filter \"name=~auth*\"\n\n# Find public methods with no parameters\nuv run python -m tree_sitter_analyzer examples/BigService.java --query-key methods --filter \"params=0,public=true\"\n\n# Find static methods\nuv run python -m tree_sitter_analyzer examples/BigService.java --query-key methods --filter \"static=true\"\n\n# View filter syntax help\nuv run python -m tree_sitter_analyzer --filter-help\n\n# \ud83c\udd95 New CLI Commands (v1.3.8+)\n# File listing with fd functionality\nuv run list-files . --extensions java --output-format json\n\n# Content search with ripgrep functionality\nuv run search-content --roots . --query \"class.*extends\" --include-globs \"*.java\" --output-format text\n\n# Two-stage search: find files first, then search content\nuv run find-and-grep --roots . --query \"public.*method\" --extensions java --output-format json\n\n# Advanced file filtering\nuv run list-files . --types f --size \"+1k\" --changed-within \"1week\" --hidden --output-format text\n\n# Content search with context\nuv run search-content --roots src --query \"TODO|FIXME\" --context-before 2 --context-after 2 --output-format json\n\n# Combined file and content search with limits\nuv run find-and-grep --roots . --query \"import.*spring\" --extensions java --file-limit 10 --max-count 5 --output-format text\n```\n\n---\n\n## \ud83c\udfd7\ufe0f Architecture Improvements (v1.2.0+)\n\n### \ud83d\udd04 **Unified Element Management System**\n\nTree-sitter Analyzer now features a revolutionary unified architecture that integrates all code elements into a unified system:\n\n#### **Before (Traditional Architecture):**\n- Independent collections of classes, methods, fields, and imports\n- Inconsistent data structures across different analysis modes\n- Complex maintenance and potential inconsistencies\n\n#### **After (Unified Architecture):**\n- **Single `elements` list**: All code elements (classes, methods, fields, imports, packages) unified\n- **Consistent element types**: Each element has an `element_type` attribute for easy identification\n- **Simplified API**: Clearer interfaces and reduced complexity\n- **Better maintainability**: Single source of truth for all code elements\n\n#### **Benefits:**\n- \u2705 **Consistency**: Unified data structures across all analysis modes\n- \u2705 **Simplicity**: Easier to use and understand\n- \u2705 **Extensibility**: Easy to add new element types\n- \u2705 **Performance**: Optimized memory usage and processing\n- \u2705 **Backward compatibility**: Existing APIs continue to work seamlessly\n\n#### **Supported Element Types:**\n- `class` - Classes and interfaces\n- `function` - Methods and functions\n- `variable` - Fields and variables\n- `import` - Import statements\n- `package` - Package declarations\n\n---\n\n## \ud83d\udee0\ufe0f Core Features\n\n### \ud83d\udcca **Code Structure Analysis**\nGet insights without reading complete files:\n- Class, method, and field statistics\n- Package information and import dependencies\n- Complexity metrics\n- Precise line number positioning\n\n### \u2702\ufe0f **Smart Code Extraction**\n- Precise extraction by line range\n- Maintains original format and indentation\n- Includes position metadata\n- Supports efficient processing of large files\n\n### \ud83d\udd0d **Advanced Query Filtering**\nPowerful code element query and filtering system:\n- **Exact matching**: `--filter \"name=main\"` to find specific methods\n- **Pattern matching**: `--filter \"name=~auth*\"` to find authentication-related methods\n- **Parameter filtering**: `--filter \"params=2\"` to find methods with specific parameter counts\n- **Modifier filtering**: `--filter \"static=true,public=true\"` to find static public methods\n- **Compound conditions**: `--filter \"name=~get*,params=0,public=true\"` to combine multiple conditions\n- **CLI/MCP consistency**: Same filtering syntax used in command line and AI assistants\n\n### \ud83d\udd17 **AI Assistant Integration**\nDeep integration through MCP protocol:\n- Claude Desktop\n- Cursor IDE\n- Roo Code\n- Other MCP-compatible AI tools\n\n### \ud83d\udd0d **Advanced File Search & Content Analysis (v1.2.4+)**\nPowerful file discovery and content search capabilities powered by fd and ripgrep:\n\n#### **\ud83d\udccb Prerequisites**\nTo use the advanced MCP tools (ListFilesTool, SearchContentTool, FindAndGrepTool), you need to install the following command-line tools:\n\n**Install fd (fast file finder):**\n```bash\n# macOS (using Homebrew)\nbrew install fd\n\n# Windows (using winget - recommended)\nwinget install sharkdp.fd\n\n# Windows (using Chocolatey)\nchoco install fd\n\n# Windows (using Scoop)\nscoop install fd\n\n# Ubuntu/Debian\nsudo apt install fd-find\n\n# CentOS/RHEL/Fedora\nsudo dnf install fd-find\n\n# Arch Linux\nsudo pacman -S fd\n```\n\n**Install ripgrep (fast text search):**\n```bash\n# macOS (using Homebrew)\nbrew install ripgrep\n\n# Windows (using winget - recommended)\nwinget install BurntSushi.ripgrep.MSVC\n\n# Windows (using Chocolatey)\nchoco install ripgrep\n\n# Windows (using Scoop)\nscoop install ripgrep\n\n# Ubuntu/Debian\nsudo apt install ripgrep\n\n# CentOS/RHEL/Fedora\nsudo dnf install ripgrep\n\n# Arch Linux\nsudo pacman -S ripgrep\n```\n\n**Verify Installation:**\n```bash\n# Check fd installation\nfd --version\n\n# Check ripgrep installation\nrg --version\n```\n\n> **\u26a0\ufe0f Important:** Without these tools installed, the advanced MCP file search and content analysis features will not work. The basic MCP tools (analyze_code_structure, extract_code_section, etc.) will continue to work normally.\n\n### \ud83d\udcc1 **File Output Support (v1.5.1+)**\n\nThe `analyze_code_structure` tool now supports saving analysis results to files with automatic format detection:\n\n#### **\ud83c\udfaf Key Features:**\n- **Automatic Extension Detection**: Based on content type (JSON \u2192 `.json`, CSV \u2192 `.csv`, Markdown \u2192 `.md`, Text \u2192 `.txt`)\n- **Smart Output Path**: Uses `TREE_SITTER_OUTPUT_PATH` environment variable or project root as fallback\n- **Security Validation**: Ensures output files are written to safe, authorized locations\n- **Content Type Detection**: Automatically detects content format and applies appropriate file extension\n\n#### **\ud83d\udccb Usage Examples:**\n\n**Basic File Output:**\n```json\n{\n  \"tool\": \"analyze_code_structure\",\n  \"arguments\": {\n    \"file_path\": \"src/BigService.java\",\n    \"output_file\": \"service_analysis\"\n  }\n}\n```\n\n**With Format Control:**\n```json\n{\n  \"tool\": \"analyze_code_structure\", \n  \"arguments\": {\n    \"file_path\": \"src/BigService.java\",\n    \"format_type\": \"csv\",\n    \"output_file\": \"service_data\"\n  }\n}\n```\n\n#### **\ud83d\udd27 Environment Configuration:**\n```json\n{\n  \"env\": {\n    \"TREE_SITTER_PROJECT_ROOT\": \"/path/to/your/project\",\n    \"TREE_SITTER_OUTPUT_PATH\": \"/path/to/output/directory\"\n  }\n}\n```\n\n**Output Path Priority:**\n1. `TREE_SITTER_OUTPUT_PATH` environment variable (highest priority)\n2. Project root directory (from `TREE_SITTER_PROJECT_ROOT` or auto-detected)\n3. Current working directory (fallback)\n\n#### **\ud83d\uddc2\ufe0f ListFilesTool - Smart File Discovery**\n- **Advanced filtering**: File type, size, modification time, extension-based filtering\n- **Pattern matching**: Glob patterns and regex support for flexible file discovery\n- **Metadata enrichment**: File size, modification time, directory status, and extension information\n- **Performance optimized**: Built on fd for lightning-fast file system traversal\n\n#### **\ud83d\udd0e SearchContentTool - Intelligent Content Search**\n- **Regex & literal search**: Flexible pattern matching with case sensitivity controls\n- **Context-aware results**: Configurable before/after context lines for better understanding\n- **Multiple output formats**: Standard results, count-only, summary, and grouped by file\n- **Encoding support**: Handle files with different text encodings\n- **Performance limits**: Built-in timeout and result limits for responsive operation\n\n#### **\ud83c\udfaf FindAndGrepTool - Combined Discovery & Search**\n- **Two-stage workflow**: First discover files with fd, then search content with ripgrep\n- **Comprehensive filtering**: Combine file discovery filters with content search patterns\n- **Advanced options**: Multiline patterns, word boundaries, fixed strings, and case controls\n- **Rich metadata**: File discovery timing, search timing, and result statistics\n- **Token optimization**: Path optimization and result grouping to minimize AI token usage\n\n#### **\u2728 Key Benefits:**\n- \ud83d\ude80 **Enterprise-grade reliability**: 50+ comprehensive test cases ensuring stability\n- \ud83c\udfaf **Token-efficient**: Multiple output formats optimized for AI assistant interactions\n- \ud83d\udd27 **Highly configurable**: Extensive parameter support for precise control\n- \ud83d\udcca **Performance monitoring**: Built-in timing and result statistics\n- \ud83d\udee1\ufe0f **Error resilient**: Comprehensive error handling and validation\n\n### \ud83c\udf0d **Multi-language Support**\n- **Java** - Full support, including Spring, JPA frameworks\n- **Python** - Full support, including type annotations, decorators\n- **JavaScript** - \ud83c\udd95 **Enterprise-grade support**, including modern ES6+ features, React/Vue/Angular frameworks, JSX, async functions, generators, arrow functions, classes, module systems\n- **TypeScript** - Full support, including type annotations, interfaces\n- **C/C++, Rust, Go** - Basic support\n\n---\n\n## \ud83c\udd95 JavaScript Enterprise Support (v1.5.0+)\n\n### \ud83d\ude80 **Modern JavaScript Complete Support**\n\nTree-sitter Analyzer now provides enterprise-level JavaScript support at the same level as Java, including:\n\n#### **\ud83d\udccb Core Language Features**\n- **Function Types**: Traditional functions, arrow functions, async functions, generator functions\n- **Class System**: ES6 classes, inheritance, static methods, getters/setters, constructors\n- **Variable Declarations**: var, let, const, destructuring assignment, template literals\n- **Module System**: ES6 import/export, CommonJS require/module.exports\n- **Modern Features**: Spread/rest operators, Promises, async/await\n\n#### **\ud83c\udfa8 Framework & Ecosystem**\n- **React Support**: JSX syntax, component analysis, Hook recognition, lifecycle methods\n- **Vue.js Support**: Single-file components, template syntax, reactive data\n- **Angular Support**: Components, services, dependency injection pattern recognition\n- **Node.js Support**: Server-side patterns, Express routing, middleware\n\n#### **\ud83d\udd0d Advanced Analysis Capabilities**\n- **JSDoc Extraction**: Complete documentation comment parsing and type information\n- **Complexity Analysis**: Cyclomatic complexity calculation and code quality metrics\n- **Framework Detection**: Automatic recognition of React, Vue, Angular project types\n- **Export Analysis**: Module export mapping and dependency relationship tracking\n\n#### **\ud83d\udcbc Enterprise Features**\n- **Table Formatting**: Dedicated JavaScript table formatter for clear code structure display\n- **Performance Optimization**: Caching mechanisms, iterative traversal, efficient large file handling\n- **Error Handling**: Robust exception handling and detailed error reporting\n- **Type Safety**: TypeScript-style type annotation support\n\n### \ud83d\udcca **JavaScript Analysis Examples**\n\n```bash\n# Analyze modern JavaScript files\nuv run python -m tree_sitter_analyzer examples/ModernJavaScript.js --language javascript --advanced\n\n# Generate detailed structure tables\nuv run python -m tree_sitter_analyzer examples/ModernJavaScript.js --language javascript --table full\n\n# Analyze React components\nuv run python -m tree_sitter_analyzer examples/ReactComponent.jsx --language javascript --table full\n\n# Query specific function types\nuv run python -m tree_sitter_analyzer examples/ModernJavaScript.js --language javascript --query-key async_function\n```\n\n### \ud83c\udfaf **Supported JavaScript Query Types**\n- `function_declaration` - Traditional function declarations\n- `arrow_function` - Arrow functions\n- `async_function` - Async functions\n- `generator_function` - Generator functions\n- `class_declaration` - Class declarations\n- `variable_declaration` - Variable declarations\n- `import_statement` - Import statements\n- `export_statement` - Export statements\n- `jsx_element` - JSX elements\n- `method_definition` - Method definitions\n\n### \ud83c\udfd7\ufe0f **AI Assistant JavaScript Workflow**\n\n```\nI want to analyze the structure of this JavaScript file: examples/ModernJavaScript.js\n```\n\n**Example Response Format:**\n```json\n{\n  \"file_path\": \"examples/ModernJavaScript.js\",\n  \"language\": \"javascript\",\n  \"element_count\": 24,\n  \"elements\": [\n    {\n      \"name\": \"fetchUserData\",\n      \"type\": \"function\",\n      \"start_line\": 208,\n      \"end_line\": 211,\n      \"is_async\": true,\n      \"framework_type\": \"vanilla\"\n    },\n    {\n      \"name\": \"ModernComponent\",\n      \"type\": \"class\",\n      \"start_line\": 31,\n      \"end_line\": 200,\n      \"is_react_component\": true,\n      \"framework_type\": \"react\"\n    }\n  ],\n  \"success\": true\n}\n```\n\n---\n\n## \ud83d\udce6 Installation Guide\n\n### \ud83d\udc64 **End Users**\n```bash\n# Basic installation\nuv add tree-sitter-analyzer\n\n# Popular language packages (recommended)\nuv add \"tree-sitter-analyzer[popular]\"\n\n# MCP server support\nuv add \"tree-sitter-analyzer[mcp]\"\n\n# Complete installation\nuv add \"tree-sitter-analyzer[all,mcp]\"\n```\n\n### \ud83d\udc68\u200d\ud83d\udcbb **Developers**\n```bash\ngit clone https://github.com/aimasteracc/tree-sitter-analyzer.git\ncd tree-sitter-analyzer\nuv sync --extra all --extra mcp\n```\n\n---\n\n## \ud83d\udd12 Security and Configuration\n\n### \ud83d\udee1\ufe0f **Project Boundary Protection**\n\nTree-sitter Analyzer automatically detects and protects project boundaries:\n\n- **Auto-detection**: Based on `.git`, `pyproject.toml`, `package.json`, etc.\n- **CLI control**: `--project-root /path/to/project`\n- **MCP integration**: `TREE_SITTER_PROJECT_ROOT=/path/to/project` or use auto-detection\n- **Security guarantee**: Only analyze files within project boundaries\n\n**Recommended MCP Configuration:**\n\n**Option 1: Auto-detection (Recommended)**\n```json\n{\n  \"mcpServers\": {\n    \"tree-sitter-analyzer\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--with\", \"tree-sitter-analyzer[mcp]\", \"python\", \"-m\", \"tree_sitter_analyzer.mcp.server\"]\n    }\n  }\n}\n```\n\n**Option 2: Manually specify project root directory**\n```json\n{\n  \"mcpServers\": {\n    \"tree-sitter-analyzer\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--with\", \"tree-sitter-analyzer[mcp]\", \"python\", \"-m\", \"tree_sitter_analyzer.mcp.server\"],\n      \"env\": {\n        \"TREE_SITTER_PROJECT_ROOT\": \"/path/to/your/project\",\n        \"TREE_SITTER_OUTPUT_PATH\": \"/path/to/output/directory\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## \ud83c\udfc6 Quality Assurance\n\n### \ud83d\udcca **Quality Metrics**\n- **1,893 tests** - 100% pass rate \u2705\n- **71.48% code coverage** - Industry-leading level\n- **Zero test failures** - Fully CI/CD ready\n- **Cross-platform compatibility** - Windows, macOS, Linux\n\n### \u26a1 **Latest Quality Achievements (v1.6.0)**\n- \u2705 **Cross-platform path compatibility** - Fixed Windows short path names and macOS symbolic link differences\n- \u2705 **Windows environment** - Implemented robust path normalization using Windows API\n- \u2705 **macOS environment** - Fixed `/var` vs `/private/var` symbolic link differences\n- \u2705 **Comprehensive test coverage** - 1797 tests, 74.45% coverage\n- \u2705 **GitFlow implementation** - Professional development/release branch strategy. See [GitFlow documentation](GITFLOW.md) for details.\n\n### \u2699\ufe0f **Running Tests**\n```bash\n# Run all tests\nuv run pytest tests/ -v\n\n# Generate coverage report\nuv run pytest tests/ --cov=tree_sitter_analyzer --cov-report=html --cov-report=term-missing\n\n# Run specific tests\nuv run pytest tests/test_mcp_server_initialization.py -v\n```\n\n### \ud83d\udcc8 **Coverage Highlights**\n- **Language detector**: 98.41% (Excellent)\n- **CLI main entry**: 94.36% (Excellent)\n- **Query filtering system**: 96.06% (Excellent)\n- **MCP fd/rg tools**: 93.04% (Excellent) - *Enhanced in v1.3.2 with cache format compatibility fix*\n- **Query service**: 86.25% (Good)\n- **Error handling**: 82.76% (Good)\n\n---\n\n## \ud83e\udd16 AI Collaboration Support\n\n### \u26a1 **Optimized for AI Development**\n\nThis project supports AI-assisted development with dedicated quality control:\n\n```bash\n# AI system code generation pre-check\nuv run python check_quality.py --new-code-only\nuv run python llm_code_checker.py --check-all\n\n# AI-generated code review\nuv run python llm_code_checker.py path/to/new_file.py\n```\n\n\ud83d\udcd6 **Detailed Guides**:\n- [AI Collaboration Guide](AI_COLLABORATION_GUIDE.md)\n- [LLM Coding Guidelines](LLM_CODING_GUIDELINES.md)\n\n---\n\n## \ud83d\udcda Documentation\n\n- **[User MCP Setup Guide](MCP_SETUP_USERS.md)** - Simple configuration guide\n- **[Developer MCP Setup Guide](MCP_SETUP_DEVELOPERS.md)** - Local development configuration\n- **[Project Root Configuration](PROJECT_ROOT_CONFIG.md)** - Complete configuration reference\n- **[API Documentation](docs/api.md)** - Detailed API reference\n- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute\n- **[Takeover and Training Guide](training/README.md)** - System onboarding materials for new members/maintainers\n\n---\n\n## \ud83d\udc9d Sponsors & Acknowledgments\n\nWe are grateful to our sponsors who make this project possible:\n\n### \ud83c\udf1f **Special Thanks**\n\n**[@o93](https://github.com/o93)** - *Primary Sponsor & Supporter*\n- \ud83d\ude80 **MCP Tools Enhancement**: Sponsored the comprehensive MCP fd/ripgrep tools development\n- \ud83e\uddea **Testing Infrastructure**: Enabled enterprise-grade test coverage (50+ comprehensive test cases)\n- \ud83d\udd27 **Quality Assurance**: Supported bug fixes and performance improvements\n- \ud83d\udca1 **Innovation Support**: Made early release of advanced file search and content analysis features possible\n\n*\"Thanks to @o93's generous support, we were able to deliver powerful MCP tools that revolutionize how AI assistants interact with codebases. This sponsorship directly enabled the development of ListFilesTool, SearchContentTool, and FindAndGrepTool with comprehensive test coverage.\"*\n\n### \ud83e\udd1d **Become a Sponsor**\n\nYour support helps us:\n- \ud83d\udd2c Develop new features and tools\n- \ud83e\uddea Maintain comprehensive test coverage\n- \ud83d\udcda Create better documentation\n- \ud83d\ude80 Accelerate development cycles\n\n**[\ud83d\udc96 Sponsor this project](https://github.com/sponsors/aimasteracc)** to help us continue building amazing tools for the developer community!\n\n---\n\n## \ud83e\udd1d Contributing\n\nWe welcome all forms of contributions! Please see [Contributing Guide](CONTRIBUTING.md) for details.\n\n### \u2b50 **Give Us a Star!**\n\nIf this project has been helpful to you, please give us a \u2b50 on GitHub - this is the greatest support for us!\n\n---\n\n## \ud83d\udcc4 License\n\nMIT License - See [LICENSE](LICENSE) file for details.\n\n---\n\n**\ud83c\udfaf Built for developers dealing with large codebases and AI assistants**\n\n*Let every line of code be understood by AI, let every project break through token limits*\n\n---\n\n## \u2705 Prompt Testing Verification\n\nAll AI prompts in this document have been thoroughly tested in real environments, ensuring:\n\n- **100% Availability** - All prompts work correctly\n- **Multi-language Support** - Supports Java, Python, JavaScript and other mainstream languages\n- **Path Compatibility** - Both relative and absolute paths are fully supported\n- **Windows/Linux Compatibility** - Cross-platform path formats are automatically handled\n- **Real-time Verification** - Tested using real code files\n\n**Test Environment:**\n- Operating System: Windows 10\n- Project: tree-sitter-analyzer v1.6.0\n- Test Files: BigService.java (1419 lines), sample.py (256 lines), MultiClass.java (54 lines)\n- Test Coverage: 1797 tests passed, 74.45% coverage\n- Test Tools: All MCP tools (check_code_scale, analyze_code_structure, extract_code_section, query_code, list_files, search_content, find_and_grep)\n\n**\ud83d\ude80 Start Now** \u2192 [30-Second Quick Start](#-30-second-quick-start)\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Extensible multi-language code analyzer framework using Tree-sitter with dynamic plugin architecture",
    "version": "1.6.0",
    "project_urls": {
        "Bug Reports": "https://github.com/aimasteracc/tree-sitter-analyzer/issues",
        "Changelog": "https://github.com/aimasteracc/tree-sitter-analyzer/blob/main/CHANGELOG.md",
        "Documentation": "https://github.com/aimasteracc/tree-sitter-analyzer#readme",
        "Homepage": "https://github.com/aimasteracc/tree-sitter-analyzer",
        "Issues": "https://github.com/aimasteracc/tree-sitter-analyzer/issues",
        "Repository": "https://github.com/aimasteracc/tree-sitter-analyzer.git",
        "Source Code": "https://github.com/aimasteracc/tree-sitter-analyzer"
    },
    "split_keywords": [
        "ai-tools",
        " ast",
        " code-analysis",
        " mcp",
        " mcp-server",
        " model-context-protocol",
        " multi-language",
        " parsing",
        " static-analysis",
        " tree-sitter"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "d0ae3fe1b66b536d65aca1fe9b6c4b0e73979eed22d5f9871bbc9f8060f67040",
                "md5": "73bebd31dd1d7cf11c534c24b00d1ff5",
                "sha256": "535c5e77ade72408dd3567507c090eadb6ee45ad2bf242bbaa45e735526fcedf"
            },
            "downloads": -1,
            "filename": "tree_sitter_analyzer-1.6.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "73bebd31dd1d7cf11c534c24b00d1ff5",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 266923,
            "upload_time": "2025-10-06T14:47:12",
            "upload_time_iso_8601": "2025-10-06T14:47:12.009341Z",
            "url": "https://files.pythonhosted.org/packages/d0/ae/3fe1b66b536d65aca1fe9b6c4b0e73979eed22d5f9871bbc9f8060f67040/tree_sitter_analyzer-1.6.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "9a804fb170471dd726c1f1a507432b75a1bfd2b87c2d87a1110569a9d8105503",
                "md5": "032668522d882887f0a30e68ca878e4b",
                "sha256": "0104302a35ffc7855087479c95ca2a9c5524f00cb8d6882838897775660d16d9"
            },
            "downloads": -1,
            "filename": "tree_sitter_analyzer-1.6.0.tar.gz",
            "has_sig": false,
            "md5_digest": "032668522d882887f0a30e68ca878e4b",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 594324,
            "upload_time": "2025-10-06T14:47:13",
            "upload_time_iso_8601": "2025-10-06T14:47:13.992951Z",
            "url": "https://files.pythonhosted.org/packages/9a/80/4fb170471dd726c1f1a507432b75a1bfd2b87c2d87a1110569a9d8105503/tree_sitter_analyzer-1.6.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-10-06 14:47:13",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "aimasteracc",
    "github_project": "tree-sitter-analyzer",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "tree-sitter-analyzer"
}