tree-sitter-analyzer 0.9.3__py3-none-any.whl → 0.9.5__py3-none-any.whl

tree_sitter_analyzer/utils.py

@@ -49,9 +49,15 @@ def setup_logger(
             )
             file_handler.setFormatter(formatter)
             logger.addHandler(file_handler)
-        except Exception:
-            # Never let logging configuration break runtime behavior
-            pass
+        except Exception as e:
+            # Never let logging configuration break runtime behavior; log to stderr if possible
+            if hasattr(sys, "stderr") and hasattr(sys.stderr, "write"):
+                try:
+                    sys.stderr.write(
+                        f"[logging_setup] file handler init skipped: {e}\n"
+                    )
+                except Exception:
+                    ...
 
         logger.setLevel(level)
 
@@ -107,10 +113,20 @@ def setup_safe_logging_shutdown() -> None:
                     try:
                         handler.close()
                         logger.removeHandler(handler)
-                    except Exception:
-                        pass
-        except Exception:
-            pass
+                    except Exception as e:
+                        if hasattr(sys, "stderr") and hasattr(sys.stderr, "write"):
+                            try:
+                                sys.stderr.write(
+                                    f"[logging_cleanup] handler close/remove skipped: {e}\n"
+                                )
+                            except Exception:
+                                ...
+        except Exception as e:
+            if hasattr(sys, "stderr") and hasattr(sys.stderr, "write"):
+                try:
+                    sys.stderr.write(f"[logging_cleanup] cleanup skipped: {e}\n")
+                except Exception:
+                    ...
 
     # Register cleanup function
     atexit.register(cleanup_logging)
@@ -128,32 +144,48 @@ def log_info(message: str, *args: Any, **kwargs: Any) -> None:
     """Log info message"""
     try:
         logger.info(message, *args, **kwargs)
-    except (ValueError, OSError):
-        pass  # Silently ignore I/O errors
+    except (ValueError, OSError) as e:
+        if hasattr(sys, "stderr") and hasattr(sys.stderr, "write"):
+            try:
+                sys.stderr.write(f"[log_info] suppressed: {e}\n")
+            except Exception:
+                ...
 
 
 def log_warning(message: str, *args: Any, **kwargs: Any) -> None:
     """Log warning message"""
     try:
         logger.warning(message, *args, **kwargs)
-    except (ValueError, OSError):
-        pass  # Silently ignore I/O errors
+    except (ValueError, OSError) as e:
+        if hasattr(sys, "stderr") and hasattr(sys.stderr, "write"):
+            try:
+                sys.stderr.write(f"[log_warning] suppressed: {e}\n")
+            except Exception:
+                ...
 
 
 def log_error(message: str, *args: Any, **kwargs: Any) -> None:
     """Log error message"""
     try:
         logger.error(message, *args, **kwargs)
-    except (ValueError, OSError):
-        pass  # Silently ignore I/O errors
+    except (ValueError, OSError) as e:
+        if hasattr(sys, "stderr") and hasattr(sys.stderr, "write"):
+            try:
+                sys.stderr.write(f"[log_error] suppressed: {e}\n")
+            except Exception:
+                ...
 
 
 def log_debug(message: str, *args: Any, **kwargs: Any) -> None:
     """Log debug message"""
     try:
         logger.debug(message, *args, **kwargs)
-    except (ValueError, OSError):
-        pass  # Silently ignore I/O errors
+    except (ValueError, OSError) as e:
+        if hasattr(sys, "stderr") and hasattr(sys.stderr, "write"):
+            try:
+                sys.stderr.write(f"[log_debug] suppressed: {e}\n")
+            except Exception:
+                ...
 
 
 def suppress_output(func: Any) -> Any:
@@ -175,8 +207,14 @@ def suppress_output(func: Any) -> Any:
         finally:
             try:
                 sys.stdout.close()
-            except Exception:
-                pass
+            except Exception as e:
+                if hasattr(sys, "stderr") and hasattr(sys.stderr, "write"):
+                    try:
+                        sys.stderr.write(
+                            f"[suppress_output] stdout close suppressed: {e}\n"
+                        )
+                    except Exception:
+                        ...
             sys.stdout = old_stdout
 
         return result
@@ -253,8 +291,12 @@ def log_performance(
                 detail_str = str(details)
             message += f" - {detail_str}"
         perf_logger.debug(message)  # Change to DEBUG level
-    except (ValueError, OSError):
-        pass  # Silently ignore I/O errors
+    except (ValueError, OSError) as e:
+        if hasattr(sys, "stderr") and hasattr(sys.stderr, "write"):
+            try:
+                sys.stderr.write(f"[log_performance] suppressed: {e}\n")
+            except Exception:
+                ...
 
 
 def setup_performance_logger() -> logging.Logger:

tree_sitter_analyzer-0.9.5.dist-info/METADATA

@@ -0,0 +1,567 @@
+Metadata-Version: 2.4
+Name: tree-sitter-analyzer
+Version: 0.9.5
+Summary: Extensible multi-language code analyzer framework using Tree-sitter with dynamic plugin architecture
+Project-URL: Homepage, https://github.com/aimasteracc/tree-sitter-analyzer
+Project-URL: Documentation, https://github.com/aimasteracc/tree-sitter-analyzer#readme
+Project-URL: Repository, https://github.com/aimasteracc/tree-sitter-analyzer.git
+Project-URL: Issues, https://github.com/aimasteracc/tree-sitter-analyzer/issues
+Project-URL: Changelog, https://github.com/aimasteracc/tree-sitter-analyzer/blob/main/CHANGELOG.md
+Project-URL: Bug Reports, https://github.com/aimasteracc/tree-sitter-analyzer/issues
+Project-URL: Source Code, https://github.com/aimasteracc/tree-sitter-analyzer
+Author-email: "aisheng.yu" <aimasteracc@gmail.com>
+Maintainer-email: "aisheng.yu" <aimasteracc@gmail.com>
+License: MIT
+Keywords: ai-tools,ast,code-analysis,mcp,mcp-server,model-context-protocol,multi-language,parsing,static-analysis,tree-sitter
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: cachetools>=5.0.0
+Requires-Dist: chardet>=5.0.0
+Requires-Dist: mcp>=1.12.3
+Requires-Dist: tree-sitter-cpp>=0.23.4
+Requires-Dist: tree-sitter-java>=0.23.5
+Requires-Dist: tree-sitter-javascript>=0.23.1
+Requires-Dist: tree-sitter-python>=0.23.6
+Requires-Dist: tree-sitter==0.24.0
+Provides-Extra: all-languages
+Requires-Dist: tree-sitter-c>=0.20.0; extra == 'all-languages'
+Requires-Dist: tree-sitter-cpp>=0.23.4; extra == 'all-languages'
+Requires-Dist: tree-sitter-go>=0.20.0; extra == 'all-languages'
+Requires-Dist: tree-sitter-java>=0.23.5; extra == 'all-languages'
+Requires-Dist: tree-sitter-javascript>=0.23.1; extra == 'all-languages'
+Requires-Dist: tree-sitter-python>=0.23.0; extra == 'all-languages'
+Requires-Dist: tree-sitter-rust>=0.20.0; extra == 'all-languages'
+Requires-Dist: tree-sitter-typescript>=0.20.0; extra == 'all-languages'
+Provides-Extra: c
+Requires-Dist: tree-sitter-c>=0.20.0; extra == 'c'
+Provides-Extra: cpp
+Requires-Dist: tree-sitter-cpp>=0.23.4; extra == 'cpp'
+Provides-Extra: dev
+Requires-Dist: black>=24.0.0; extra == 'dev'
+Requires-Dist: isort>=5.13.0; extra == 'dev'
+Requires-Dist: memory-profiler>=0.61.0; extra == 'dev'
+Requires-Dist: mypy>=1.17.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
+Requires-Dist: psutil<6,>=5.9.6; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.14.1; extra == 'dev'
+Requires-Dist: pytest>=8.4.1; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Requires-Dist: types-psutil>=5.9.0; extra == 'dev'
+Provides-Extra: full
+Requires-Dist: anyio>=4.0.0; extra == 'full'
+Requires-Dist: black>=24.0.0; extra == 'full'
+Requires-Dist: httpx<1.0.0,>=0.27.0; extra == 'full'
+Requires-Dist: isort>=5.13.0; extra == 'full'
+Requires-Dist: mcp>=1.12.2; extra == 'full'
+Requires-Dist: memory-profiler>=0.61.0; extra == 'full'
+Requires-Dist: mypy>=1.17.0; extra == 'full'
+Requires-Dist: pre-commit>=3.0.0; extra == 'full'
+Requires-Dist: psutil<6,>=5.9.6; extra == 'full'
+Requires-Dist: pydantic-settings>=2.2.1; extra == 'full'
+Requires-Dist: pydantic>=2.5.0; extra == 'full'
+Requires-Dist: pytest-asyncio>=1.1.0; extra == 'full'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'full'
+Requires-Dist: pytest-mock>=3.14.1; extra == 'full'
+Requires-Dist: pytest>=8.4.1; extra == 'full'
+Requires-Dist: ruff>=0.5.0; extra == 'full'
+Requires-Dist: tree-sitter-c>=0.20.0; extra == 'full'
+Requires-Dist: tree-sitter-cpp>=0.23.4; extra == 'full'
+Requires-Dist: tree-sitter-go>=0.20.0; extra == 'full'
+Requires-Dist: tree-sitter-java>=0.23.5; extra == 'full'
+Requires-Dist: tree-sitter-javascript>=0.23.1; extra == 'full'
+Requires-Dist: tree-sitter-python>=0.23.0; extra == 'full'
+Requires-Dist: tree-sitter-rust>=0.20.0; extra == 'full'
+Requires-Dist: tree-sitter-typescript>=0.20.0; extra == 'full'
+Requires-Dist: types-psutil>=5.9.0; extra == 'full'
+Provides-Extra: go
+Requires-Dist: tree-sitter-go>=0.20.0; extra == 'go'
+Provides-Extra: java
+Requires-Dist: tree-sitter-java>=0.23.5; extra == 'java'
+Provides-Extra: javascript
+Requires-Dist: tree-sitter-javascript>=0.23.1; extra == 'javascript'
+Provides-Extra: mcp
+Requires-Dist: anyio>=4.0.0; extra == 'mcp'
+Requires-Dist: httpx<1.0.0,>=0.27.0; extra == 'mcp'
+Requires-Dist: mcp>=1.12.2; extra == 'mcp'
+Requires-Dist: pydantic-settings>=2.2.1; extra == 'mcp'
+Requires-Dist: pydantic>=2.5.0; extra == 'mcp'
+Provides-Extra: popular
+Requires-Dist: tree-sitter-java>=0.23.5; extra == 'popular'
+Requires-Dist: tree-sitter-javascript>=0.23.1; extra == 'popular'
+Requires-Dist: tree-sitter-python>=0.23.0; extra == 'popular'
+Requires-Dist: tree-sitter-typescript>=0.20.0; extra == 'popular'
+Provides-Extra: python
+Requires-Dist: tree-sitter-python>=0.23.0; extra == 'python'
+Provides-Extra: rust
+Requires-Dist: tree-sitter-rust>=0.20.0; extra == 'rust'
+Provides-Extra: systems
+Requires-Dist: tree-sitter-c>=0.20.0; extra == 'systems'
+Requires-Dist: tree-sitter-cpp>=0.23.4; extra == 'systems'
+Requires-Dist: tree-sitter-go>=0.20.0; extra == 'systems'
+Requires-Dist: tree-sitter-rust>=0.20.0; extra == 'systems'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=1.1.0; extra == 'test'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
+Requires-Dist: pytest-mock>=3.14.1; extra == 'test'
+Requires-Dist: pytest>=8.4.1; extra == 'test'
+Requires-Dist: tree-sitter-cpp>=0.23.4; extra == 'test'
+Requires-Dist: tree-sitter-java>=0.23.5; extra == 'test'
+Requires-Dist: tree-sitter-javascript>=0.23.1; extra == 'test'
+Requires-Dist: tree-sitter-python>=0.23.0; extra == 'test'
+Provides-Extra: typescript
+Requires-Dist: tree-sitter-typescript>=0.20.0; extra == 'typescript'
+Provides-Extra: web
+Requires-Dist: tree-sitter-javascript>=0.23.1; extra == 'web'
+Requires-Dist: tree-sitter-typescript>=0.20.0; extra == 'web'
+Description-Content-Type: text/markdown
+
+# 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-1358%20passed-brightgreen.svg)](#quality-assurance)
+[![Coverage](https://img.shields.io/badge/coverage-74.19%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/)
+[![GitHub Stars](https://img.shields.io/github/stars/aimasteracc/tree-sitter-analyzer.svg?style=social)](https://github.com/aimasteracc/tree-sitter-analyzer)
+
+## 🚀 Break Through LLM Token Limits, Let AI Understand Code Files of Any Size
+
+> **A revolutionary code analysis tool designed for the AI era**
+
+## 📋 Table of Contents
+
+- [🚀 Break Through LLM Token Limits](#-break-through-llm-token-limits-let-ai-understand-code-files-of-any-size)
+- [📋 Table of Contents](#-table-of-contents)
+- [💡 What Makes This Special](#-what-makes-this-special)
+- [📊 Live Demo & Results](#-live-demo--results)
+- [🚀 30-Second Quick Start](#-30-second-quick-start)
+  - [🤖 For AI Users (Claude Desktop, Cursor, etc.)](#-for-ai-users-claude-desktop-cursor-etc)
+  - [💻 For Developers (CLI)](#-for-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 & Configuration](#-security--configuration)
+- [🏆 Quality Assurance](#-quality-assurance)
+- [🤖 AI Collaboration Support](#-ai-collaboration-support)
+- [📚 Documentation](#-documentation)
+- [🤝 Contributing](#-contributing)
+- [📄 License](#-license)
+
+## 💡 What Makes This Special
+
+Imagine: You have a 1,400+ line Java service class that Claude or ChatGPT can't analyze due to token limits. Now, Tree-sitter Analyzer enables AI assistants to:
+
+- ⚡ **Get complete code structure overview in 3 seconds**
+- 🎯 **Precisely extract** any line range of code snippets  
+- 📍 **Smart positioning** exact locations of classes, methods, fields
+- 🔗 **Seamless integration** with Claude Desktop, Cursor, Roo Code and other AI IDEs
+
+**No more AI helplessness due to large files!**
+
+## 📊 Live Demo & Results
+
+### ⚡ **Lightning-Fast Analysis Speed**
+```bash
+# 1419-line large Java service class analysis result (< 1 second)
+Lines: 1419 | Classes: 1 | Methods: 66 | Fields: 9 | Imports: 8
+```
+
+### 📊 **Precise Structure Tables**
+| Class Name | Type | Visibility | Line Range | Methods | Fields |
+|------------|------|------------|------------|---------|--------|
+| BigService | class | public | 17-1419 | 66 | 9 |
+
+### 🔄 **AI Assistant Three-Step Workflow**
+- **Step 1**: `check_code_scale` - Check file scale and complexity
+- **Step 2**: `analyze_code_structure` - Generate detailed structure tables
+- **Step 3**: `extract_code_section` - Extract code snippets on demand
+
+---
+
+## 🚀 30-Second Quick Start
+
+### 🤖 For AI Users (Claude Desktop, Cursor, etc.)
+
+**📦 1. One-Click Installation**
+```bash
+# macOS/Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows PowerShell
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+**⚙️ 2. Configure AI Client**
+
+**Claude Desktop Configuration:**
+
+Add the following to your config 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):**
+```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"
+      }
+    }
+  }
+}
+```
+
+**Other AI Clients:**
+- **Cursor**: Built-in MCP support, refer to Cursor documentation for configuration
+- **Roo Code**: Supports MCP protocol, check respective configuration guides
+- **Other MCP-compatible clients**: Use the same server configuration
+
+**⚠️ Configuration Notes:**
+- **Basic Configuration**: Tool will auto-detect project root (recommended)
+- **Advanced Configuration**: If you need to specify a particular directory, use absolute path to replace `/absolute/path/to/your/project`
+- **Avoid using**: Variables like `${workspaceFolder}` may not be supported in some clients
+
+**🎉 3. Restart AI client and start analyzing massive code files!**
+
+### 💻 For Developers (CLI)
+
+```bash
+# Install
+uv add "tree-sitter-analyzer[popular]"
+
+# Check file scale (1419-line large service class, instant completion)
+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
+
+### 🎯 Solving Real Pain Points
+
+**Traditional Approach Dilemmas:**
+- ❌ Large files exceed LLM token limits
+- ❌ AI cannot understand code structure
+- ❌ Manual file splitting required
+- ❌ Context loss leads to inaccurate analysis
+
+**Tree-sitter Analyzer's 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 (Copy and Use)
+
+#### 🔍 **Step 1: Check File Scale**
+
+**Prompt:**
+```
+Use MCP tool check_code_scale to analyze file scale
+Parameters: {"file_path": "examples/BigService.java"}
+```
+
+**Return Format:**
+```json
+{
+  "file_path": "examples/BigService.java",
+  "language": "java",
+  "metrics": {
+    "lines_total": 1419,
+    "lines_code": 1419,
+    "elements": {
+      "classes": 1,
+      "methods": 66,
+      "fields": 9
+    }
+  }
+}
+```
+
+#### 📊 **Step 2: Generate Structure Table**
+
+**Prompt:**
+```
+Use MCP tool analyze_code_structure to generate detailed structure
+Parameters: {"file_path": "examples/BigService.java"}
+```
+
+**Return Format:**
+- Complete Markdown table
+- Including class info, method list (with line numbers), field list
+- Method signatures, visibility, line ranges, complexity and other detailed information
+
+#### ✂️ **Step 3: Extract Code Snippets**
+
+**Prompt:**
+```
+Use MCP tool extract_code_section to extract specified code section
+Parameters: {"file_path": "examples/BigService.java", "start_line": 100, "end_line": 105}
+```
+
+**Return Format:**
+```json
+{
+  "file_path": "examples/BigService.java",
+  "range": {"start_line": 100, "end_line": 105},
+  "content": "Actual code content...",
+  "content_length": 245
+}
+```
+
+#### 💡 **Important Notes**
+- **Parameter Format**: Use snake_case (`file_path`, `start_line`, `end_line`)
+- **Path Handling**: Relative paths auto-resolve to project root
+- **Security Protection**: Tool automatically performs project boundary checks
+- **Workflow**: Recommended to use in order: Step 1 → 2 → 3
+
+### 🛠️ CLI Command Examples
+
+```bash
+# Quick analysis (1419-line large file, instant completion)
+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
+
+# Silent mode (display results only)
+uv run python -m tree_sitter_analyzer examples/BigService.java --table=full --quiet
+```
+
+---
+
+## 🛠️ Core Features
+
+### 📊 **Code Structure Analysis**
+Get insights without reading complete files:
+- Class, method, field statistics
+- Package information and import dependencies
+- Complexity metrics
+- Precise line number positioning
+
+### ✂️ **Smart Code Extraction**
+- Extract by line range precisely
+- Maintain original formatting and indentation
+- Include position metadata
+- Support efficient processing of large files
+
+### 🔗 **AI Assistant Integration**
+Deep integration via MCP protocol:
+- Claude Desktop
+- Cursor IDE  
+- Roo Code
+- Other MCP-supporting AI tools
+
+### 🌍 **Multi-Language Support**
+- **Java** - Full support, including Spring, JPA frameworks
+- **Python** - Complete support, including type annotations, decorators
+- **JavaScript/TypeScript** - Full support, including ES6+ features
+- **C/C++, Rust, Go** - Basic support
+
+---
+
+## 📦 Installation Guide
+
+### 👤 **End Users**
+```bash
+# Basic installation
+uv add tree-sitter-analyzer
+
+# Popular languages package (recommended)
+uv add "tree-sitter-analyzer[popular]"
+
+# MCP server support
+uv add "tree-sitter-analyzer[mcp]"
+
+# Full 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 & 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: Manual Project Root Specification**
+```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"}
+    }
+  }
+}
+```
+
+---
+
+## 🏆 Quality Assurance
+
+### 📊 **Quality Metrics**
+- **1,358 Tests** - 100% pass rate ✅
+- **74.54% Code Coverage** - Industry-leading level
+- **Zero Test Failures** - Complete CI/CD ready
+- **Cross-platform Compatible** - Windows, macOS, Linux
+
+### ⚡ **Latest Quality Achievements (v0.9.4)**
+- ✅ **Test Suite Completely Stable** - Fixed all historical issues
+- ✅ **Formatter Module Breakthrough** - Coverage significantly improved
+- ✅ **Error Handling Optimization** - Enterprise-grade exception handling
+- ✅ **100+ New Comprehensive Tests** - Covering critical modules
+
+### ⚙️ **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
+
+# Run specific tests
+uv run pytest tests/test_mcp_server_initialization.py -v
+```
+
+### 📈 **Coverage Highlights**
+- **Language Detector**: 98.41% (Excellent)
+- **CLI Main Entry**: 97.78% (Excellent)
+- **Error Handling**: 82.76% (Good)
+- **Security Framework**: 78%+ (Reliable)
+
+---
+
+## 🤖 AI Collaboration Support
+
+### ⚡ **Optimized for AI Development**
+
+This project supports AI-assisted development with specialized quality controls:
+
+```bash
+# AI system pre-code generation checks
+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
+
+---
+
+## 🤝 Contributing
+
+We welcome all forms of contributions! Please check the [Contributing Guide](CONTRIBUTING.md) for details.
+
+### ⭐ **Give Us a Star!**
+
+If this project helps you, please give us a ⭐ on GitHub - it's 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*
+
+**🚀 Start Now** → [30-Second Quick Start](#-30-second-quick-start)