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

hanzo_mcp/tools/filesystem/directory_tree_paginated.py

@@ -0,0 +1,338 @@
+"""Paginated directory tree tool implementation.
+
+This module provides a paginated version of DirectoryTreeTool that supports
+MCP cursor-based pagination for large directory structures.
+"""
+
+from pathlib import Path
+from typing import Annotated, Any, Dict, List, Optional, TypedDict, Unpack, final, override
+
+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
+from hanzo_mcp.tools.common.pagination import (
+    CursorManager,
+    PaginatedResponse,
+    paginate_list
+)
+
+DirectoryPath = Annotated[
+    str,
+    Field(
+        description="The path to the directory to view",
+        title="Path",
+    ),
+]
+
+Depth = Annotated[
+    int,
+    Field(
+        default=3,
+        description="The maximum depth to traverse (0 for unlimited)",
+        title="Depth",
+    ),
+]
+
+IncludeFiltered = Annotated[
+    bool,
+    Field(
+        default=False,
+        description="Include directories that are normally filtered",
+        title="Include Filtered",
+    ),
+]
+
+PageSize = Annotated[
+    int,
+    Field(
+        default=100,
+        description="Number of entries per page",
+        title="Page Size",
+    ),
+]
+
+Cursor = Annotated[
+    Optional[str],
+    Field(
+        default=None,
+        description="Pagination cursor for continuing from previous request",
+        title="Cursor",
+    ),
+]
+
+
+class DirectoryTreePaginatedParams(TypedDict):
+    """Parameters for the paginated DirectoryTreeTool.
+
+    Attributes:
+        path: The path to the directory to view
+        depth: The maximum depth to traverse (0 for unlimited)
+        include_filtered: Include directories that are normally filtered
+        page_size: Number of entries per page
+        cursor: Pagination cursor
+    """
+
+    path: DirectoryPath
+    depth: Depth
+    include_filtered: IncludeFiltered
+    page_size: PageSize
+    cursor: Cursor
+
+
+@final
+class DirectoryTreePaginatedTool(FilesystemBaseTool):
+    """Tool for viewing directory structure as a tree with pagination support."""
+
+    @property
+    @override
+    def name(self) -> str:
+        """Get the tool name."""
+        return "directory_tree_paginated"
+
+    @property
+    @override
+    def description(self) -> str:
+        """Get the tool description."""
+        return """Get a paginated recursive tree view of files and directories.
+
+This is a paginated version of directory_tree that supports cursor-based pagination
+for large directory structures. Returns a structured view with files and subdirectories.
+
+Directories are marked with trailing slashes. Common development directories like
+.git, node_modules, and venv are noted but not traversed unless explicitly requested.
+
+Use the cursor field to continue from where the previous request left off.
+Returns nextCursor if more entries are available."""
+
+    @override
+    async def call(
+        self,
+        ctx: MCPContext,
+        **params: Unpack[DirectoryTreePaginatedParams],
+    ) -> Dict[str, Any]:
+        """Execute the tool with the given parameters.
+
+        Args:
+            ctx: MCP context
+            **params: Tool parameters
+
+        Returns:
+            Dictionary with entries and optional nextCursor
+        """
+        tool_ctx = self.create_tool_context(ctx)
+
+        # Extract parameters
+        path: DirectoryPath = params["path"]
+        depth = params.get("depth", 3)
+        include_filtered = params.get("include_filtered", False)
+        page_size = params.get("page_size", 100)
+        cursor = params.get("cursor", None)
+
+        # Validate cursor if provided
+        if cursor:
+            cursor_data = CursorManager.parse_cursor(cursor)
+            if not cursor_data:
+                await tool_ctx.error("Invalid cursor provided")
+                return {"error": "Invalid cursor"}
+
+        # Validate path parameter
+        path_validation = self.validate_path(path)
+        if path_validation.is_error:
+            await tool_ctx.error(path_validation.error_message)
+            return {"error": path_validation.error_message}
+
+        await tool_ctx.info(
+            f"Getting paginated directory tree: {path} (depth: {depth}, page_size: {page_size})"
+        )
+
+        # Check if path is allowed
+        allowed, error_msg = await self.check_path_allowed(path, tool_ctx)
+        if not allowed:
+            return {"error": error_msg}
+
+        try:
+            dir_path = Path(path)
+
+            # Check if path exists
+            exists, error_msg = await self.check_path_exists(path, tool_ctx)
+            if not exists:
+                return {"error": error_msg}
+
+            # Check if path is a directory
+            is_dir, error_msg = await self.check_is_directory(path, tool_ctx)
+            if not is_dir:
+                return {"error": error_msg}
+
+            # Define filtered directories
+            FILTERED_DIRECTORIES = {
+                ".git",
+                "node_modules",
+                ".venv",
+                "venv",
+                "__pycache__",
+                ".pytest_cache",
+                ".idea",
+                ".vs",
+                ".vscode",
+                "dist",
+                "build",
+                "target",
+                ".ruff_cache",
+                ".llm-context",
+            }
+
+            # Check if a directory should be filtered
+            def should_filter(current_path: Path) -> bool:
+                if str(current_path.absolute()) == str(dir_path.absolute()):
+                    return False
+                return (
+                    current_path.name in FILTERED_DIRECTORIES and not include_filtered
+                )
+
+            # Collect all entries in a flat list for pagination
+            all_entries: List[Dict[str, Any]] = []
+
+            # Build the tree and collect entries
+            def collect_entries(
+                current_path: Path,
+                current_depth: int = 0,
+                parent_path: str = ""
+            ) -> None:
+                """Collect entries in a flat list for pagination."""
+                if not self.is_path_allowed(str(current_path)):
+                    return
+
+                try:
+                    # Sort entries: directories first, then files alphabetically
+                    entries = sorted(
+                        current_path.iterdir(),
+                        key=lambda x: (not x.is_dir(), x.name)
+                    )
+
+                    for entry in entries:
+                        if not self.is_path_allowed(str(entry)):
+                            continue
+
+                        # Calculate relative path for display
+                        relative_path = f"{parent_path}/{entry.name}" if parent_path else entry.name
+
+                        if entry.is_dir():
+                            entry_data: Dict[str, Any] = {
+                                "path": relative_path,
+                                "type": "directory",
+                                "depth": current_depth,
+                            }
+
+                            # Check if we should filter this directory
+                            if should_filter(entry):
+                                entry_data["skipped"] = "filtered-directory"
+                                all_entries.append(entry_data)
+                                continue
+
+                            # Check depth limit
+                            if depth > 0 and current_depth >= depth:
+                                entry_data["skipped"] = "depth-limit"
+                                all_entries.append(entry_data)
+                                continue
+
+                            # Add directory entry
+                            all_entries.append(entry_data)
+
+                            # Process children recursively
+                            collect_entries(
+                                entry,
+                                current_depth + 1,
+                                relative_path
+                            )
+                        else:
+                            # Add file entry
+                            if depth <= 0 or current_depth < depth:
+                                all_entries.append({
+                                    "path": relative_path,
+                                    "type": "file",
+                                    "depth": current_depth,
+                                })
+
+                except Exception as e:
+                    await tool_ctx.warning(f"Error processing {current_path}: {str(e)}")
+
+            # Collect all entries
+            await tool_ctx.info("Collecting directory entries...")
+            collect_entries(dir_path)
+
+            # Paginate the results
+            paginated = paginate_list(all_entries, cursor, page_size)
+
+            # Format the paginated entries for display
+            formatted_entries = []
+            for entry in paginated.items:
+                indent = "  " * entry["depth"]
+                if entry["type"] == "directory":
+                    if "skipped" in entry:
+                        formatted_entries.append({
+                            "entry": f"{indent}{entry['path'].split('/')[-1]}/ [skipped - {entry['skipped']}]",
+                            "type": "directory",
+                            "skipped": entry.get("skipped")
+                        })
+                    else:
+                        formatted_entries.append({
+                            "entry": f"{indent}{entry['path'].split('/')[-1]}/",
+                            "type": "directory"
+                        })
+                else:
+                    formatted_entries.append({
+                        "entry": f"{indent}{entry['path'].split('/')[-1]}",
+                        "type": "file"
+                    })
+
+            # Build response
+            response = {
+                "entries": formatted_entries,
+                "total_collected": len(all_entries),
+                "page_size": page_size,
+                "current_page_count": len(formatted_entries)
+            }
+
+            # Add next cursor if available
+            if paginated.next_cursor:
+                response["nextCursor"] = paginated.next_cursor
+
+            await tool_ctx.info(
+                f"Returning page with {len(formatted_entries)} entries"
+                f"{' (more available)' if paginated.next_cursor else ' (end of results)'}"
+            )
+
+            return response
+
+        except Exception as e:
+            await tool_ctx.error(f"Error generating directory tree: {str(e)}")
+            return {"error": f"Error generating directory tree: {str(e)}"}
+
+    @override
+    def register(self, mcp_server: FastMCP) -> None:
+        """Register this paginated directory tree tool with the MCP server."""
+        tool_self = self
+
+        @mcp_server.tool(name=self.name, description=self.description)
+        async def directory_tree_paginated(
+            path: DirectoryPath,
+            depth: Depth = 3,
+            include_filtered: IncludeFiltered = False,
+            page_size: PageSize = 100,
+            cursor: Cursor = None,
+            ctx: MCPContext = None,
+        ) -> Dict[str, Any]:
+            return await tool_self.call(
+                ctx,
+                path=path,
+                depth=depth,
+                include_filtered=include_filtered,
+                page_size=page_size,
+                cursor=cursor,
+            )
+
+
+# Create the tool instance
+directory_tree_paginated_tool = DirectoryTreePaginatedTool()

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 = ".",