hanzo-mcp 0.6.12__py3-none-any.whl → 0.6.13__py3-none-any.whl

hanzo_mcp/tools/filesystem/__init__.py

@@ -1,4 +1,4 @@
-"""Filesystem tools package for Hanzo MCP.
+"""Filesystem tools package for Hanzo AI.
 
 This package provides tools for interacting with the filesystem, including reading, writing,
 and editing files, directory navigation, and content searching.
@@ -20,7 +20,8 @@ from hanzo_mcp.tools.filesystem.read import ReadTool
 from hanzo_mcp.tools.filesystem.write import Write
 from hanzo_mcp.tools.filesystem.batch_search import BatchSearchTool
 from hanzo_mcp.tools.filesystem.find_files import FindFilesTool
-from hanzo_mcp.tools.filesystem.unified_search import UnifiedSearchTool
+from hanzo_mcp.tools.filesystem.rules_tool import RulesTool
+from hanzo_mcp.tools.filesystem.search_tool import SearchTool
 from hanzo_mcp.tools.filesystem.watch import watch_tool
 from hanzo_mcp.tools.filesystem.diff import create_diff_tool
 
@@ -37,7 +38,8 @@ __all__ = [
     "GitSearchTool",
     "BatchSearchTool",
     "FindFilesTool",
-    "UnifiedSearchTool",
+    "RulesTool",
+    "SearchTool",
     "get_filesystem_tools",
     "register_filesystem_tools",
 ]
@@ -51,7 +53,7 @@ def get_read_only_filesystem_tools(
 
     Args:
         permission_manager: Permission manager for access control
-        project_manager: Optional project manager for unified search
+        project_manager: Optional project manager for search
 
     Returns:
         List of read-only filesystem tool instances
@@ -63,13 +65,14 @@ def get_read_only_filesystem_tools(
         SymbolsTool(permission_manager),
         GitSearchTool(permission_manager),
         FindFilesTool(permission_manager),
+        RulesTool(permission_manager),
         watch_tool,
         create_diff_tool(permission_manager),
     ]
     
-    # Add unified search if project manager is available
+    # Add search if project manager is available
     if project_manager:
-        tools.append(UnifiedSearchTool(permission_manager, project_manager))
+        tools.append(SearchTool(permission_manager, project_manager))
     
     return tools
 
@@ -79,7 +82,7 @@ def get_filesystem_tools(permission_manager: PermissionManager, project_manager=
 
     Args:
         permission_manager: Permission manager for access control
-        project_manager: Optional project manager for unified search
+        project_manager: Optional project manager for search
 
     Returns:
         List of filesystem tool instances
@@ -95,13 +98,14 @@ def get_filesystem_tools(permission_manager: PermissionManager, project_manager=
         SymbolsTool(permission_manager),
         GitSearchTool(permission_manager),
         FindFilesTool(permission_manager),
+        RulesTool(permission_manager),
         watch_tool,
         create_diff_tool(permission_manager),
     ]
     
-    # Add unified search if project manager is available
+    # Add search if project manager is available
     if project_manager:
-        tools.append(UnifiedSearchTool(permission_manager, project_manager))
+        tools.append(SearchTool(permission_manager, project_manager))
     
     return tools
 
@@ -122,7 +126,7 @@ def register_filesystem_tools(
         disable_write_tools: Whether to disable write tools (default: False)
         disable_search_tools: Whether to disable search tools (default: False)
         enabled_tools: Dictionary of individual tool enable states (default: None)
-        project_manager: Optional project manager for unified search (default: None)
+        project_manager: Optional project manager for search (default: None)
 
     Returns:
         List of registered tools
@@ -135,12 +139,13 @@ def register_filesystem_tools(
         "multi_edit": MultiEdit,
         "directory_tree": DirectoryTreeTool,
         "grep": Grep,
-        "grep_ast": SymbolsTool,  # Using correct import name
+        "symbols": SymbolsTool,  # Unified symbols tool with grep_ast functionality
         "git_search": GitSearchTool,
         "content_replace": ContentReplaceTool,
         "batch_search": BatchSearchTool,
         "find_files": FindFilesTool,
-        "unified_search": UnifiedSearchTool,
+        "rules": RulesTool,
+        "search": SearchTool,
         "watch": lambda pm: watch_tool,  # Singleton instance
         "diff": create_diff_tool,
     }
@@ -152,8 +157,8 @@ def register_filesystem_tools(
         for tool_name, enabled in enabled_tools.items():
             if enabled and tool_name in tool_classes:
                 tool_class = tool_classes[tool_name]
-                if tool_name in ["batch_search", "unified_search"]:
-                    # Batch search and unified search require project_manager
+                if tool_name in ["batch_search", "search"]:
+                    # Batch search and search require project_manager
                     tools.append(tool_class(permission_manager, project_manager))
                 elif tool_name == "watch":
                     # Watch tool is a singleton

hanzo_mcp/tools/filesystem/batch_search.py

@@ -45,7 +45,7 @@ class SearchType(Enum):
 
 @dataclass 
 class SearchResult:
-    """Unified search result combining different search types."""
+    """Search result combining different search types."""
     file_path: str
     line_number: Optional[int]
     content: str
@@ -112,11 +112,11 @@ class BatchSearchParams(TypedDict):
 
 @final
 class BatchSearchTool(FilesystemBaseTool):
-    """Unified search tool combining multiple search strategies."""
+    """Search tool combining multiple search strategies."""
     
     def __init__(self, permission_manager: PermissionManager, 
                  project_manager: Optional[ProjectVectorManager] = None):
-        """Initialize the unified search tool."""
+        """Initialize the search tool."""
         super().__init__(permission_manager)
         self.project_manager = project_manager
         

hanzo_mcp/tools/filesystem/diff.py

@@ -98,7 +98,7 @@ diff a.json b.json --ignore-whitespace"""
         
         # Generate diff
         if unified:
-            # Unified diff format
+            #  diff format
             diff_lines = list(difflib.unified_diff(
                 lines1,
                 lines2,
@@ -183,7 +183,7 @@ diff a.json b.json --ignore-whitespace"""
             unified: bool = True,
             context: int = 3,
             ignore_whitespace: bool = False,
-            show_line_numbers: bool = True,
+            show_line_numbers: bool = True
         ) -> str:
             """Handle diff tool calls."""
             return await tool_self.run(

hanzo_mcp/tools/filesystem/rules_tool.py

@@ -0,0 +1,235 @@
+"""Rules tool implementation.
+
+This module provides the RulesTool for reading local preferences from .cursor rules 
+or .claude code configuration files.
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import Annotated, TypedDict, Unpack, final, override, Optional
+
+from mcp.server.fastmcp import Context as MCPContext
+from mcp.server import FastMCP
+from pydantic import Field
+
+from hanzo_mcp.tools.filesystem.base import FilesystemBaseTool
+
+
+SearchPath = Annotated[
+    str,
+    Field(
+        description="Directory path to search for configuration files (defaults to current directory)",
+        default=".",
+    ),
+]
+
+
+class RulesToolParams(TypedDict, total=False):
+    """Parameters for the RulesTool.
+
+    Attributes:
+        path: Directory path to search for configuration files
+    """
+
+    path: str
+
+
+@final
+class RulesTool(FilesystemBaseTool):
+    """Tool for reading local preferences from configuration files."""
+
+    @property
+    @override
+    def name(self) -> str:
+        """Get the tool name.
+
+        Returns:
+            Tool name
+        """
+        return "rules"
+
+    @property
+    @override
+    def description(self) -> str:
+        """Get the tool description.
+
+        Returns:
+            Tool description
+        """
+        return """Read local preferences and rules from .cursor/rules or .claude/code configuration files.
+
+This tool searches for and reads configuration files that contain project-specific
+preferences, coding standards, and rules for AI assistants.
+
+Searches for (in order of priority):
+1. .cursorrules in current directory
+2. .cursor/rules in current directory
+3. .claude/code.md in current directory
+4. .claude/rules.md in current directory
+5. Recursively searches parent directories up to project root
+
+Usage:
+rules                    # Search from current directory
+rules --path /project    # Search from specific directory
+
+The tool returns the contents of all found configuration files to help
+understand project-specific requirements and preferences."""
+
+    @override
+    async def call(
+        self,
+        ctx: MCPContext,
+        **params: Unpack[RulesToolParams],
+    ) -> str:
+        """Execute the tool with the given parameters.
+
+        Args:
+            ctx: MCP context
+            **params: Tool parameters
+
+        Returns:
+            Tool result
+        """
+        tool_ctx = self.create_tool_context(ctx)
+        self.set_tool_context_info(tool_ctx)
+
+        # Extract parameters
+        search_path = params.get("path", ".")
+
+        # Validate path
+        path_validation = self.validate_path(search_path)
+        if not path_validation.is_valid:
+            await tool_ctx.error(f"Invalid path: {path_validation.error_message}")
+            return f"Error: Invalid path: {path_validation.error_message}"
+
+        # Check permissions
+        is_allowed, error_message = await self.check_path_allowed(search_path, tool_ctx)
+        if not is_allowed:
+            return error_message
+
+        # Check existence
+        is_exists, error_message = await self.check_path_exists(search_path, tool_ctx)
+        if not is_exists:
+            return error_message
+
+        # Convert to Path object
+        start_path = Path(search_path).resolve()
+        
+        # Configuration files to search for
+        config_files = [
+            ".cursorrules",
+            ".cursor/rules",
+            ".cursor/rules.md",
+            ".claude/code.md",
+            ".claude/rules.md",
+            ".claude/config.md",
+        ]
+        
+        found_configs = []
+        
+        # Search in current directory and parent directories
+        current_path = start_path
+        while True:
+            for config_file in config_files:
+                config_path = current_path / config_file
+                
+                # Check if file exists and we have permission
+                if config_path.exists() and config_path.is_file():
+                    try:
+                        # Check permissions for this specific file
+                        if self.is_path_allowed(str(config_path)):
+                            with open(config_path, "r", encoding="utf-8") as f:
+                                content = f.read()
+                            
+                            found_configs.append({
+                                "path": str(config_path),
+                                "relative_path": str(config_path.relative_to(start_path)),
+                                "content": content,
+                                "size": len(content)
+                            })
+                            
+                            await tool_ctx.info(f"Found configuration: {config_path}")
+                    except Exception as e:
+                        await tool_ctx.warning(f"Could not read {config_path}: {str(e)}")
+            
+            # Check if we've reached the root or a git repository root
+            if current_path.parent == current_path:
+                break
+                
+            # Check if this is a git repository root
+            if (current_path / ".git").exists():
+                # Search one more time in the git root before stopping
+                if current_path != start_path:
+                    for config_file in config_files:
+                        config_path = current_path / config_file
+                        if config_path.exists() and config_path.is_file() and str(config_path) not in [c["path"] for c in found_configs]:
+                            try:
+                                if self.is_path_allowed(str(config_path)):
+                                    with open(config_path, "r", encoding="utf-8") as f:
+                                        content = f.read()
+                                    
+                                    found_configs.append({
+                                        "path": str(config_path),
+                                        "relative_path": str(config_path.relative_to(start_path)),
+                                        "content": content,
+                                        "size": len(content)
+                                    })
+                                    
+                                    await tool_ctx.info(f"Found configuration: {config_path}")
+                            except Exception as e:
+                                await tool_ctx.warning(f"Could not read {config_path}: {str(e)}")
+                break
+                
+            # Move to parent directory
+            parent = current_path.parent
+            
+            # Check if parent is still within allowed paths
+            if not self.is_path_allowed(str(parent)):
+                await tool_ctx.info(f"Stopped at directory boundary: {parent}")
+                break
+                
+            current_path = parent
+        
+        # Format results
+        if not found_configs:
+            return f"""No configuration files found.
+
+Searched for:
+{chr(10).join('- ' + cf for cf in config_files)}
+
+Starting from: {start_path}
+
+To create project rules, create one of these files with your preferences:
+- .cursorrules: For Cursor IDE rules
+- .cursor/rules: Alternative Cursor location  
+- .claude/code.md: For Claude-specific coding preferences
+- .claude/rules.md: For general Claude interaction rules"""
+        
+        # Build output
+        output = [f"=== Found {len(found_configs)} Configuration File(s) ===\n"]
+        
+        for i, config in enumerate(found_configs, 1):
+            output.append(f"--- [{i}] {config['path']} ({config['size']} bytes) ---")
+            output.append(config['content'])
+            output.append("")  # Empty line between configs
+        
+        output.append(f"\nSearched from: {start_path}")
+        
+        return "\n".join(output)
+
+    @override
+    def register(self, mcp_server: FastMCP) -> None:
+        """Register this rules tool with the MCP server.
+
+        Args:
+            mcp_server: The FastMCP server instance
+        """
+        tool_self = self  # Create a reference to self for use in the closure
+
+        @mcp_server.tool(name=self.name, description=self.description)
+        async def rules(
+            path: SearchPath = ".",
+            ctx: MCPContext = None,
+        ) -> str:
+            return await tool_self.call(ctx, path=path)

hanzo_mcp/tools/filesystem/{unified_search.py → search_tool.py}

@@ -1,4 +1,4 @@
-"""Unified search tool that runs multiple search types in parallel.
+"""Search tool that runs multiple search types in parallel.
 
 This tool consolidates all search capabilities and runs them concurrently:
 - grep: Fast pattern/regex search using ripgrep
@@ -41,7 +41,7 @@ class SearchType(Enum):
 
 @dataclass
 class SearchResult:
-    """Unified search result from any search type."""
+    """Search result from any search type."""
     file_path: str
     line_number: Optional[int]
     content: str
@@ -133,7 +133,7 @@ IncludeContext = Annotated[
 
 
 class UnifiedSearchParams(TypedDict):
-    """Parameters for unified search."""
+    """Parameters for search."""
     pattern: Pattern
     path: SearchPath
     include: Include
@@ -147,12 +147,12 @@ class UnifiedSearchParams(TypedDict):
 
 
 @final
-class UnifiedSearchTool(FilesystemBaseTool):
-    """Unified search tool that runs multiple search types in parallel."""
+class SearchTool(FilesystemBaseTool):
+    """Search tool that runs multiple search types in parallel."""
     
     def __init__(self, permission_manager: PermissionManager, 
                  project_manager: Optional[ProjectVectorManager] = None):
-        """Initialize the unified search tool.
+        """Initialize the search tool.
         
         Args:
             permission_manager: Permission manager for access control
@@ -175,13 +175,13 @@ class UnifiedSearchTool(FilesystemBaseTool):
     @override
     def name(self) -> str:
         """Get the tool name."""
-        return "unified_search"
+        return "search"
     
     @property
     @override
     def description(self) -> str:
         """Get the tool description."""
-        return """Unified search that runs multiple search strategies in parallel.
+        return """Search that runs multiple search strategies in parallel.
 
 Automatically runs the most appropriate search types based on your pattern:
 - Pattern matching (grep) for exact text/regex
@@ -527,7 +527,7 @@ This is the recommended search tool for comprehensive results."""
         ctx: MCPContext,
         **params: Unpack[UnifiedSearchParams],
     ) -> str:
-        """Execute unified search across all enabled search types."""
+        """Execute search across all enabled search types."""
         import time
         start_time = time.time()
         
@@ -559,7 +559,7 @@ This is the recommended search tool for comprehensive results."""
         # Analyze pattern to determine best search strategies
         pattern_analysis = self._analyze_pattern(pattern)
         
-        await tool_ctx.info(f"Starting unified search for '{pattern}' in {path}")
+        await tool_ctx.info(f"Starting search for '{pattern}' in {path}")
         
         # Build list of search tasks based on enabled types and pattern analysis
         search_tasks = []
@@ -679,11 +679,11 @@ This is the recommended search tool for comprehensive results."""
     
     @override
     def register(self, mcp_server: FastMCP) -> None:
-        """Register the unified search tool with the MCP server."""
+        """Register the search tool with the MCP server."""
         tool_self = self
         
         @mcp_server.tool(name=self.name, description=self.description)
-        async def unified_search(
+        async def search(
             ctx: MCPContext,
             pattern: Pattern,
             path: SearchPath = ".",

hanzo_mcp/tools/filesystem/{symbols_unified.py → symbols_tool.py}

@@ -21,7 +21,7 @@ from hanzo_mcp.tools.filesystem.base import FilesystemBaseTool
 Action = Annotated[
     str,
     Field(
-        description="Action: search (default), index, query, list",
+        description="Action: search (default), ast, index, query, list",
         default="search",
     ),
 ]
@@ -88,7 +88,7 @@ class SymbolsParams(TypedDict, total=False):
 
 @final
 class SymbolsTool(FilesystemBaseTool):
-    """Unified tool for code symbol operations using tree-sitter."""
+    """Tool for code symbol operations using tree-sitter."""
     
     def __init__(self, permission_manager):
         """Initialize the symbols tool."""
@@ -105,13 +105,16 @@ class SymbolsTool(FilesystemBaseTool):
     @override
     def description(self) -> str:
         """Get the tool description."""
-        return """Code symbols with tree-sitter. Actions: search (default), index, query, list.
+        return """Code symbols search with tree-sitter AST. Actions: search (default), ast, index, query, list.
 
 Usage:
 symbols "function_name"
+symbols --action ast --pattern "TODO" --path ./src
 symbols --action query --symbol-type function --path ./src
 symbols --action index --path ./project
-symbols --action list --path ./src --symbol-type class"""
+symbols --action list --path ./src --symbol-type class
+
+Finds code structures (functions, classes, methods) with full context."""
 
     @override
     async def call(
@@ -129,6 +132,8 @@ symbols --action list --path ./src --symbol-type class"""
         # Route to appropriate handler
         if action == "search":
             return await self._handle_search(params, tool_ctx)
+        elif action == "ast" or action == "grep_ast":  # Support both for backward compatibility
+            return await self._handle_ast(params, tool_ctx)
         elif action == "index":
             return await self._handle_index(params, tool_ctx)
         elif action == "query":
@@ -136,7 +141,7 @@ symbols --action list --path ./src --symbol-type class"""
         elif action == "list":
             return await self._handle_list(params, tool_ctx)
         else:
-            return f"Error: Unknown action '{action}'. Valid actions: search, index, query, list"
+            return f"Error: Unknown action '{action}'. Valid actions: search, ast, index, query, list"
 
     async def _handle_search(self, params: Dict[str, Any], tool_ctx) -> str:
         """Search for pattern in code with AST context."""
@@ -222,6 +227,100 @@ symbols --action list --path ./src --symbol-type class"""
         
         return "\n".join(output)
 
+    async def _handle_ast(self, params: Dict[str, Any], tool_ctx) -> str:
+        """AST-aware grep - shows code structure context around matches."""
+        pattern = params.get("pattern")
+        if not pattern:
+            return "Error: pattern required for ast action"
+
+        path = params.get("path", ".")
+        ignore_case = params.get("ignore_case", False)
+        show_context = params.get("show_context", True)
+        limit = params.get("limit", 50)
+
+        # Validate path
+        path_validation = self.validate_path(path)
+        if not path_validation.is_valid:
+            await tool_ctx.error(f"Invalid path: {path_validation.error_message}")
+            return f"Error: Invalid path: {path_validation.error_message}"
+
+        # Check permissions
+        is_allowed, error_message = await self.check_path_allowed(path, tool_ctx)
+        if not is_allowed:
+            return error_message
+
+        # Check existence
+        is_exists, error_message = await self.check_path_exists(path, tool_ctx)
+        if not is_exists:
+            return error_message
+
+        await tool_ctx.info(f"Running AST-aware grep for '{pattern}' in {path}")
+
+        # Get files to process
+        files_to_process = self._get_source_files(path)
+        if not files_to_process:
+            return f"No source code files found in {path}"
+
+        # Process files
+        results = []
+        match_count = 0
+        
+        for file_path in files_to_process:
+            if match_count >= limit:
+                break
+
+            try:
+                with open(file_path, "r", encoding="utf-8") as f:
+                    code = f.read()
+
+                # Create TreeContext for AST parsing
+                tc = TreeContext(
+                    file_path,
+                    code,
+                    color=False,
+                    verbose=False,
+                    line_number=True,
+                )
+
+                # Find matches with case sensitivity option
+                if ignore_case:
+                    import re
+                    loi = tc.grep(pattern, ignore_case=True)
+                else:
+                    loi = tc.grep(pattern, ignore_case=False)
+
+                if loi:
+                    # Always show AST context for grep_ast
+                    tc.add_lines_of_interest(loi)
+                    tc.add_context()
+                    
+                    # Get the formatted output with structure
+                    output = tc.format()
+                    
+                    # Add section separator and file info
+                    results.append(f"\n{'='*60}")
+                    results.append(f"File: {file_path}")
+                    results.append(f"Matches: {len(loi)}")
+                    results.append(f"{'='*60}\n")
+                    results.append(output)
+                    
+                    match_count += len(loi)
+
+            except Exception as e:
+                await tool_ctx.warning(f"Could not parse {file_path}: {str(e)}")
+
+        if not results:
+            return f"No matches found for '{pattern}' in {path}"
+
+        output = [f"=== AST-aware Grep Results for '{pattern}' ==="]
+        output.append(f"Total matches: {match_count} in {len([r for r in results if '===' in str(r)])//4} files\n")
+        output.extend(results)
+
+        if match_count >= limit:
+            output.append(f"\n(Results limited to {limit} matches)")
+
+        return "\n".join(output)
+
     async def _handle_index(self, params: Dict[str, Any], tool_ctx) -> str:
         """Index symbols in a codebase."""
         path = params.get("path", ".")

hanzo_mcp/tools/filesystem/watch.py

@@ -23,16 +23,17 @@ class WatchTool(BaseTool):
         
         @server.tool(name=self.name, description=self.description)
         async def watch_handler(
+            ctx: MCPContext,
             path: str,
             pattern: str = "*",
             interval: int = 1,
             recursive: bool = True,
             exclude: str = "",
-            duration: int = 30,
+            duration: int = 30
         ) -> str:
             """Handle watch tool calls."""
             return await self.run(
-                None,
+                ctx,
                 path=path,
                 pattern=pattern,
                 interval=interval,

hanzo_mcp/tools/jupyter/__init__.py

@@ -1,4 +1,4 @@
-"""Jupyter notebook tools package for Hanzo MCP.
+"""Jupyter notebook tools package for Hanzo AI.
 
 This package provides tools for working with Jupyter notebooks (.ipynb files),
 including reading and editing notebook cells.
@@ -29,7 +29,7 @@ def get_read_only_jupyter_tools(
     Returns:
         List of Jupyter notebook tool instances
     """
-    return []  # Unified tool handles both read and write
+    return []  # Tool handles both read and write
 
 
 def get_jupyter_tools(permission_manager: PermissionManager) -> list[BaseTool]:

hanzo_mcp/tools/jupyter/jupyter.py

@@ -81,7 +81,7 @@ class NotebookParams(TypedDict, total=False):
 
 @final
 class JupyterTool(JupyterBaseTool):
-    """Unified tool for Jupyter notebook operations."""
+    """Tool for Jupyter notebook operations."""
 
     @property
     @override