tree-sitter-analyzer 0.9.5__tar.gz → 0.9.7__tar.gz

{tree_sitter_analyzer-0.9.5 → tree_sitter_analyzer-0.9.7}/CHANGELOG.md

@@ -1,4 +1,181 @@
 # Changelog
+## [0.9.7] - 2025-01-17
+
+### 🛠️ Error Handling Improvements
+
+#### 🔧 MCP Tool Enhancements
+- **Enhanced Error Decorator**: Improved `@handle_mcp_errors` decorator with tool name identification
+- **Better Error Context**: Added tool name "query_code" to error handling for improved debugging
+- **Security Validation**: Enhanced file path security validation in query tool
+
+#### 🧪 Code Quality
+- **Pre-commit Hooks**: All code quality checks passed including black, ruff, bandit, and isort
+- **Mixed Line Endings**: Fixed mixed line ending issues in query_tool.py
+- **Type Safety**: Maintained existing type annotations and code structure
+
+#### 📚 Documentation
+- **Updated Examples**: Enhanced error handling documentation
+- **Security Guidelines**: Improved security validation documentation
+
+## [0.9.6] - 2025-01-17
+
+### 🎉 New Feature: Advanced Query Filtering System
+
+#### 🚀 Major Features
+
+##### Smart Query Filtering
+- **Precise Method Search**: Find specific methods using `--filter "name=main"`
+- **Pattern Matching**: Use wildcards like `--filter "name=~auth*"` for authentication-related methods
+- **Parameter Filtering**: Filter by parameter count with `--filter "params=0"`
+- **Modifier Filtering**: Search by visibility and modifiers like `--filter "static=true,public=true"`
+- **Compound Conditions**: Combine multiple filters with `--filter "name=~get*,params=0,public=true"`
+
+##### Unified Architecture
+- **QueryService**: New unified query service eliminates code duplication between CLI and MCP
+- **QueryFilter**: Powerful filtering engine supporting multiple criteria
+- **Consistent API**: Same filtering syntax works in both command line and AI assistants
+
+#### 🛠️ Technical Improvements
+
+##### New Core Components
+- `core/query_service.py`: Unified query execution service
+- `core/query_filter.py`: Advanced result filtering system
+- `cli/commands/query_command.py`: Enhanced CLI query command
+- `mcp/tools/query_tool.py`: New MCP query tool with filtering support
+
+##### Enhanced CLI
+- Added `--filter` argument for query result filtering
+- Added `--filter-help` command to display filter syntax help
+- Improved query command to use unified QueryService
+
+##### MCP Protocol Extensions
+- New `query_code` tool for AI assistants
+- Full filtering support in MCP environment
+- Consistent with CLI filtering syntax
+
+#### 📚 Documentation Updates
+
+##### README Updates
+- **Chinese (README_zh.md)**: Added comprehensive query filtering examples
+- **English (README.md)**: Complete documentation with usage examples
+- **Japanese (README_ja.md)**: Full translation with feature explanations
+
+##### Training Materials
+- Updated `training/01_onboarding.md` with new feature demonstrations
+- Enhanced `training/02_architecture_map.md` with architecture improvements
+- Cross-platform examples for Windows, Linux, and macOS
+
+#### 🧪 Comprehensive Testing
+
+##### Test Coverage
+- **QueryService Tests**: 13 comprehensive unit tests
+- **QueryFilter Tests**: 29 detailed filtering tests  
+- **CLI Integration Tests**: 11 real-world usage scenarios
+- **MCP Tool Tests**: 9 tool definition and functionality tests
+
+##### Test Categories
+- Unit tests for core filtering logic
+- Integration tests with real Java files
+- Edge case handling (overloaded methods, generics, annotations)
+- Error handling and validation
+
+#### 🎯 Usage Examples
+
+##### Command Line Interface
+```bash
+# Find specific method
+uv run python -m tree_sitter_analyzer examples/BigService.java --query-key methods --filter "name=main"
+
+# Find authentication 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"
+
+# View filter syntax help
+uv run python -m tree_sitter_analyzer --filter-help
+```
+
+##### AI Assistant (MCP)
+```json
+{
+  "tool": "query_code",
+  "arguments": {
+    "file_path": "examples/BigService.java",
+    "query_key": "methods",
+    "filter": "name=main"
+  }
+}
+```
+
+#### 🔧 Filter Syntax Reference
+
+##### Supported Filters
+- **name**: Method/function name matching
+  - Exact: `name=main`
+  - Pattern: `name=~auth*` (supports wildcards)
+- **params**: Parameter count filtering
+  - Example: `params=0`, `params=2`
+- **Modifiers**: Visibility and static modifiers
+  - `static=true/false`
+  - `public=true/false`
+  - `private=true/false`
+  - `protected=true/false`
+
+##### Combining Filters
+Use commas for AND logic: `name=~get*,params=0,public=true`
+
+#### 🏗️ Architecture Benefits
+
+##### Code Quality
+- **DRY Principle**: Eliminated duplication between CLI and MCP
+- **Single Responsibility**: Clear separation of concerns
+- **Extensibility**: Easy to add new filter types
+- **Maintainability**: Centralized query logic
+
+##### Performance
+- **Efficient Filtering**: Post-query filtering for optimal performance
+- **Memory Optimized**: Filter after parsing, not during
+- **Scalable**: Works efficiently with large codebases
+
+#### 🚦 Quality Assurance
+
+##### Code Standards
+- **Type Safety**: Full MyPy type annotations
+- **Code Style**: Black formatting, Ruff linting
+- **Documentation**: Comprehensive docstrings and examples
+- **Testing**: 62 new tests with 100% pass rate
+
+##### Platform Support
+- **Windows**: PowerShell examples and testing
+- **Linux/macOS**: Bash examples and compatibility
+- **Codespaces**: Full support for GitHub Codespaces
+
+#### 🎯 Impact
+
+##### Productivity Gains
+- **Faster Code Navigation**: Find specific methods in seconds
+- **Enhanced Code Analysis**: AI assistants can understand code structure better
+- **Reduced Token Usage**: Extract only relevant methods for LLM analysis
+
+##### Integration Benefits
+- **IDE Support**: Works with Cursor, Claude Desktop, Roo Code
+- **CLI Flexibility**: Powerful command-line filtering
+- **API Consistency**: Same functionality across all interfaces
+
+#### 📝 Technical Details
+- **Files Changed**: 15+ core files
+- **New Files**: 6 new modules and test files
+- **Lines Added**: 2000+ lines of code and tests
+- **Documentation**: 500+ lines of updated documentation
+
+#### ✅ Migration Notes
+- All existing CLI and MCP functionality remains compatible
+- New filtering features are additive and optional
+- No breaking changes to existing APIs
+
+---
+
 ## [0.9.5] - 2025-01-15
 
 ### 🚀 CI/CD Stability & Cross-Platform Compatibility

{tree_sitter_analyzer-0.9.5 → tree_sitter_analyzer-0.9.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tree-sitter-analyzer
-Version: 0.9.5
+Version: 0.9.7
 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
@@ -137,10 +137,11 @@ Description-Content-Type: text/markdown
 
 [![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)
+[![Tests](https://img.shields.io/badge/tests-1420%20passed-brightgreen.svg)](#quality-assurance)
+[![Coverage](https://img.shields.io/badge/coverage-74.36%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-0.9.7-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 Through LLM Token Limits, Let AI Understand Code Files of Any Size
@@ -359,11 +360,54 @@ Parameters: {"file_path": "examples/BigService.java", "start_line": 100, "end_li
 }
 ```
 
+#### 🔍 **Step 4: Smart Query Filtering (v0.9.6+)**
+
+**Enhanced Error Handling (v0.9.7):**
+- Improved `@handle_mcp_errors` decorator with tool name identification
+- Better error context for debugging and troubleshooting
+- Enhanced security validation for file paths
+
+**Find specific methods:**
+```
+Use MCP tool query_code to precisely find code elements
+Parameters: {"file_path": "examples/BigService.java", "query_key": "methods", "filter": "name=main"}
+```
+
+**Find authentication-related methods:**
+```
+Use MCP tool query_code to find authentication methods
+Parameters: {"file_path": "examples/BigService.java", "query_key": "methods", "filter": "name=~auth*"}
+```
+
+**Find parameterless public methods:**
+```
+Use MCP tool query_code to find getter methods
+Parameters: {"file_path": "examples/BigService.java", "query_key": "methods", "filter": "params=0,public=true"}
+```
+
+**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) { ... }"
+    }
+  ],
+  "count": 1
+}
+```
+
 #### 💡 **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
+- **Workflow**: Recommended to use in order: Step 1 → 2 → 4 (Query Filtering) → 3 (Precise Extraction)
+- **Filter Syntax**: Supports `name=value`, `name=~pattern*`, `params=number`, `static/public/private=true/false`
 
 ### 🛠️ CLI Command Examples
 
@@ -379,6 +423,22 @@ uv run python -m tree_sitter_analyzer examples/BigService.java --partial-read --
 
 # Silent mode (display results only)
 uv run python -m tree_sitter_analyzer examples/BigService.java --table=full --quiet
+
+# 🔍 Query filtering 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 parameterless public methods
+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
 ```
 
 ---
@@ -398,6 +458,15 @@ Get insights without reading complete files:
 - Include position metadata
 - Support efficient processing of large files
 
+### 🔍 **Advanced Query Filtering**
+Powerful code element querying and filtering system:
+- **Exact matching**: `--filter "name=main"` Find specific methods
+- **Pattern matching**: `--filter "name=~auth*"` Find authentication-related methods  
+- **Parameter filtering**: `--filter "params=2"` Find methods with specific parameter counts
+- **Modifier filtering**: `--filter "static=true,public=true"` Find static public methods
+- **Compound conditions**: `--filter "name=~get*,params=0,public=true"` Combine multiple conditions
+- **CLI/MCP consistency**: Same filtering syntax in command line and AI assistants
+
 ### 🔗 **AI Assistant Integration**
 Deep integration via MCP protocol:
 - Claude Desktop
@@ -482,16 +551,16 @@ Tree-sitter Analyzer automatically detects and protects project boundaries:
 ## 🏆 Quality Assurance
 
 ### 📊 **Quality Metrics**
-- **1,358 Tests** - 100% pass rate ✅
-- **74.54% Code Coverage** - Industry-leading level
+- **1,420 Tests** - 100% pass rate ✅
+- **74.36% 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
+### ⚡ **Latest Quality Achievements (v0.9.6)**
+- ✅ **Smart Query Filtering System** - 62 new tests all passed
+- ✅ **Unified Architecture Design** - QueryService eliminates code duplication
+- ✅ **CI Test Fixes** - All platforms test stable
+- ✅ **Multi-language Documentation** - Complete updates in EN/ZH/JA
 
 ### ⚙️ **Running Tests**
 ```bash
@@ -507,9 +576,10 @@ uv run pytest tests/test_mcp_server_initialization.py -v
 
 ### 📈 **Coverage Highlights**
 - **Language Detector**: 98.41% (Excellent)
-- **CLI Main Entry**: 97.78% (Excellent)
+- **CLI Main Entry**: 94.36% (Excellent)
+- **Query Filtering System**: 96.06% (Excellent)
+- **Query Service**: 86.25% (Good)
 - **Error Handling**: 82.76% (Good)
-- **Security Framework**: 78%+ (Reliable)
 
 ---
 

{tree_sitter_analyzer-0.9.5 → tree_sitter_analyzer-0.9.7}/README.md

@@ -2,10 +2,11 @@
 
 [![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)
+[![Tests](https://img.shields.io/badge/tests-1420%20passed-brightgreen.svg)](#quality-assurance)
+[![Coverage](https://img.shields.io/badge/coverage-74.36%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-0.9.7-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 Through LLM Token Limits, Let AI Understand Code Files of Any Size
@@ -224,11 +225,54 @@ Parameters: {"file_path": "examples/BigService.java", "start_line": 100, "end_li
 }
 ```
 
+#### 🔍 **Step 4: Smart Query Filtering (v0.9.6+)**
+
+**Enhanced Error Handling (v0.9.7):**
+- Improved `@handle_mcp_errors` decorator with tool name identification
+- Better error context for debugging and troubleshooting
+- Enhanced security validation for file paths
+
+**Find specific methods:**
+```
+Use MCP tool query_code to precisely find code elements
+Parameters: {"file_path": "examples/BigService.java", "query_key": "methods", "filter": "name=main"}
+```
+
+**Find authentication-related methods:**
+```
+Use MCP tool query_code to find authentication methods
+Parameters: {"file_path": "examples/BigService.java", "query_key": "methods", "filter": "name=~auth*"}
+```
+
+**Find parameterless public methods:**
+```
+Use MCP tool query_code to find getter methods
+Parameters: {"file_path": "examples/BigService.java", "query_key": "methods", "filter": "params=0,public=true"}
+```
+
+**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) { ... }"
+    }
+  ],
+  "count": 1
+}
+```
+
 #### 💡 **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
+- **Workflow**: Recommended to use in order: Step 1 → 2 → 4 (Query Filtering) → 3 (Precise Extraction)
+- **Filter Syntax**: Supports `name=value`, `name=~pattern*`, `params=number`, `static/public/private=true/false`
 
 ### 🛠️ CLI Command Examples
 
@@ -244,6 +288,22 @@ uv run python -m tree_sitter_analyzer examples/BigService.java --partial-read --
 
 # Silent mode (display results only)
 uv run python -m tree_sitter_analyzer examples/BigService.java --table=full --quiet
+
+# 🔍 Query filtering 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 parameterless public methods
+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
 ```
 
 ---
@@ -263,6 +323,15 @@ Get insights without reading complete files:
 - Include position metadata
 - Support efficient processing of large files
 
+### 🔍 **Advanced Query Filtering**
+Powerful code element querying and filtering system:
+- **Exact matching**: `--filter "name=main"` Find specific methods
+- **Pattern matching**: `--filter "name=~auth*"` Find authentication-related methods  
+- **Parameter filtering**: `--filter "params=2"` Find methods with specific parameter counts
+- **Modifier filtering**: `--filter "static=true,public=true"` Find static public methods
+- **Compound conditions**: `--filter "name=~get*,params=0,public=true"` Combine multiple conditions
+- **CLI/MCP consistency**: Same filtering syntax in command line and AI assistants
+
 ### 🔗 **AI Assistant Integration**
 Deep integration via MCP protocol:
 - Claude Desktop
@@ -347,16 +416,16 @@ Tree-sitter Analyzer automatically detects and protects project boundaries:
 ## 🏆 Quality Assurance
 
 ### 📊 **Quality Metrics**
-- **1,358 Tests** - 100% pass rate ✅
-- **74.54% Code Coverage** - Industry-leading level
+- **1,420 Tests** - 100% pass rate ✅
+- **74.36% 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
+### ⚡ **Latest Quality Achievements (v0.9.6)**
+- ✅ **Smart Query Filtering System** - 62 new tests all passed
+- ✅ **Unified Architecture Design** - QueryService eliminates code duplication
+- ✅ **CI Test Fixes** - All platforms test stable
+- ✅ **Multi-language Documentation** - Complete updates in EN/ZH/JA
 
 ### ⚙️ **Running Tests**
 ```bash
@@ -372,9 +441,10 @@ uv run pytest tests/test_mcp_server_initialization.py -v
 
 ### 📈 **Coverage Highlights**
 - **Language Detector**: 98.41% (Excellent)
-- **CLI Main Entry**: 97.78% (Excellent)
+- **CLI Main Entry**: 94.36% (Excellent)
+- **Query Filtering System**: 96.06% (Excellent)
+- **Query Service**: 86.25% (Good)
 - **Error Handling**: 82.76% (Good)
-- **Security Framework**: 78%+ (Reliable)
 
 ---
 

{tree_sitter_analyzer-0.9.5 → tree_sitter_analyzer-0.9.7}/README_ja.md

@@ -2,10 +2,11 @@
 
 [![Pythonバージョン](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)
 [![ライセンス](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
-[![テスト](https://img.shields.io/badge/tests-1358%20passed-brightgreen.svg)](#品質保証)
-[![カバレッジ](https://img.shields.io/badge/coverage-74.19%25-green.svg)](#品質保証)
+[![テスト](https://img.shields.io/badge/tests-1420%20passed-brightgreen.svg)](#品質保証)
+[![カバレッジ](https://img.shields.io/badge/coverage-74.36%25-green.svg)](#品質保証)
 [![品質](https://img.shields.io/badge/quality-enterprise%20grade-blue.svg)](#品質保証)
 [![PyPI](https://img.shields.io/pypi/v/tree-sitter-analyzer.svg)](https://pypi.org/project/tree-sitter-analyzer/)
+[![バージョン](https://img.shields.io/badge/version-0.9.7-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)
 
 ## 🚀 LLMトークン制限を突破し、AIにあらゆるサイズのコードファイルを理解させる
@@ -224,11 +225,54 @@ MCPツールextract_code_sectionを使用して指定されたコードセクシ
 }
 ```
 
+#### 🔍 **ステップ4: スマートクエリフィルタリング（v0.9.6+）**
+
+**エラーハンドリングの強化（v0.9.7）：**
+- ツール名識別を追加した`@handle_mcp_errors`デコレータの改善
+- デバッグとトラブルシューティングのためのより良いエラーコンテキスト
+- ファイルパスのセキュリティ検証の強化
+
+**特定のメソッドを検索：**
+```
+MCPツールquery_codeを使用してコード要素を正確に検索
+パラメーター: {"file_path": "examples/BigService.java", "query_key": "methods", "filter": "name=main"}
+```
+
+**認証関連メソッドを検索：**
+```
+MCPツールquery_codeを使用して認証メソッドを検索
+パラメーター: {"file_path": "examples/BigService.java", "query_key": "methods", "filter": "name=~auth*"}
+```
+
+**パラメーターなしのパブリックメソッドを検索：**
+```
+MCPツールquery_codeを使用してgetterメソッドを検索
+パラメーター: {"file_path": "examples/BigService.java", "query_key": "methods", "filter": "params=0,public=true"}
+```
+
+**戻り値の形式：**
+```json
+{
+  "success": true,
+  "results": [
+    {
+      "capture_name": "method",
+      "node_type": "method_declaration",
+      "start_line": 1385,
+      "end_line": 1418,
+      "content": "public static void main(String[] args) { ... }"
+    }
+  ],
+  "count": 1
+}
+```
+
 #### 💡 **重要な注意事項**
 - **パラメーター形式**: スネークケースを使用（`file_path`、`start_line`、`end_line`）
 - **パス処理**: 相対パスは自動的にプロジェクトルートに解決
 - **セキュリティ保護**: ツールは自動的にプロジェクト境界チェックを実行
-- **ワークフロー**: 順序通りの使用を推奨：ステップ1 → 2 → 3
+- **ワークフロー**: 順序通りの使用を推奨：ステップ1 → 2 → 4（クエリフィルタリング）→ 3（正確な抽出）
+- **フィルター構文**: `name=値`、`name=~パターン*`、`params=数字`、`static/public/private=true/false`をサポート
 
 ### 🛠️ CLIコマンド例
 
@@ -244,6 +288,22 @@ uv run python -m tree_sitter_analyzer examples/BigService.java --partial-read --
 
 # サイレントモード（結果のみ表示）
 uv run python -m tree_sitter_analyzer examples/BigService.java --table=full --quiet
+
+# 🔍 クエリフィルタリング例（v0.9.6+）
+# 特定のメソッドを検索
+uv run python -m tree_sitter_analyzer examples/BigService.java --query-key methods --filter "name=main"
+
+# 認証関連メソッドを検索
+uv run python -m tree_sitter_analyzer examples/BigService.java --query-key methods --filter "name=~auth*"
+
+# パラメーターなしのパブリックメソッドを検索
+uv run python -m tree_sitter_analyzer examples/BigService.java --query-key methods --filter "params=0,public=true"
+
+# 静的メソッドを検索
+uv run python -m tree_sitter_analyzer examples/BigService.java --query-key methods --filter "static=true"
+
+# フィルター構文ヘルプを表示
+uv run python -m tree_sitter_analyzer --filter-help
 ```
 
 ---
@@ -263,6 +323,15 @@ uv run python -m tree_sitter_analyzer examples/BigService.java --table=full --qu
 - 位置メタデータを含む
 - 大ファイルの効率的な処理をサポート
 
+### 🔍 **高度なクエリフィルタリング**
+強力なコード要素クエリとフィルタリングシステム：
+- **完全一致**: `--filter "name=main"` 特定のメソッドを検索
+- **パターンマッチング**: `--filter "name=~auth*"` 認証関連メソッドを検索  
+- **パラメーターフィルタリング**: `--filter "params=2"` 特定のパラメーター数のメソッドを検索
+- **修飾子フィルタリング**: `--filter "static=true,public=true"` 静的パブリックメソッドを検索
+- **複合条件**: `--filter "name=~get*,params=0,public=true"` 複数の条件を組み合わせ
+- **CLI/MCP一貫性**: コマンドラインとAIアシスタントで同じフィルタリング構文
+
 ### 🔗 **AIアシスタント統合**
 MCPプロトコルを通じた深い統合：
 - Claude Desktop
@@ -347,16 +416,16 @@ Tree-sitter Analyzerは自動的にプロジェクト境界を検出・保護：
 ## 🏆 品質保証
 
 ### 📊 **品質メトリクス**
-- **1,358テスト** - 100%合格率 ✅
-- **74.54%コードカバレッジ** - 業界最高レベル
+- **1,420テスト** - 100%合格率 ✅
+- **74.36%コードカバレッジ** - 業界最高レベル
 - **ゼロテスト失敗** - 完全なCI/CD対応
 - **クロスプラットフォーム対応** - Windows、macOS、Linux
 
-### ⚡ **最新の品質成果（v0.9.4）**
-- ✅ **テストスイート完全安定化** - すべての歴史的問題を修正
-- ✅ **フォーマッターモジュールブレークスルー** - カバレッジ大幅向上
-- ✅ **エラーハンドリング最適化** - エンタープライズグレードの例外処理
-- ✅ **100+新総合テスト** - 重要なモジュールをカバー
+### ⚡ **最新の品質成果（v0.9.6）**
+- ✅ **スマートクエリフィルタリングシステム** - 62の新しいテストすべて合格
+- ✅ **統合アーキテクチャ設計** - QueryServiceによるコード重複の排除
+- ✅ **CIテスト修正** - すべてのプラットフォームでテスト安定化
+- ✅ **多言語ドキュメンテーション** - 中英日三言語の完全更新
 
 ### ⚙️ **テスト実行**
 ```bash
@@ -372,9 +441,10 @@ uv run pytest tests/test_mcp_server_initialization.py -v
 
 ### 📈 **カバレッジハイライト**
 - **言語検出器**: 98.41%（優秀）
-- **CLIメインエントリ**: 97.78%（優秀）
+- **CLIメインエントリ**: 94.36%（優秀）
+- **クエリフィルタリングシステム**: 96.06%（優秀）
+- **クエリサービス**: 86.25%（良好）
 - **エラーハンドリング**: 82.76%（良好）
-- **セキュリティフレームワーク**: 78%+（信頼性）
 
 ---