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

hanzo_mcp/tools/common/forgiving_edit.py

@@ -0,0 +1,243 @@
+"""Forgiving edit helper for AI-friendly text matching."""
+
+import difflib
+import re
+from typing import List, Optional, Tuple
+
+
+class ForgivingEditHelper:
+    """Helper class to make text editing more forgiving for AI usage.
+    
+    This helper normalizes whitespace, handles partial matches, and provides
+    suggestions when exact matches fail.
+    """
+    
+    @staticmethod
+    def normalize_whitespace(text: str) -> str:
+        """Normalize whitespace while preserving structure.
+        
+        Args:
+            text: Text to normalize
+            
+        Returns:
+            Text with normalized whitespace
+        """
+        # Replace tabs with spaces for comparison
+        text = text.replace('\t', '    ')
+        
+        # Normalize multiple spaces to single space (except at line start)
+        lines = []
+        for line in text.split('\n'):
+            # Preserve indentation
+            indent = len(line) - len(line.lstrip())
+            content = line.strip()
+            if content:
+                # Normalize spaces in content
+                content = ' '.join(content.split())
+            lines.append(' ' * indent + content)
+        
+        return '\n'.join(lines)
+    
+    @staticmethod
+    def find_fuzzy_match(
+        haystack: str, 
+        needle: str,
+        threshold: float = 0.85
+    ) -> Optional[Tuple[int, int, str]]:
+        """Find a fuzzy match for the needle in the haystack.
+        
+        Args:
+            haystack: Text to search in
+            needle: Text to search for
+            threshold: Similarity threshold (0-1)
+            
+        Returns:
+            Tuple of (start_pos, end_pos, matched_text) or None
+        """
+        # First try exact match
+        if needle in haystack:
+            start = haystack.index(needle)
+            return (start, start + len(needle), needle)
+        
+        # Normalize for comparison
+        norm_haystack = ForgivingEditHelper.normalize_whitespace(haystack)
+        norm_needle = ForgivingEditHelper.normalize_whitespace(needle)
+        
+        # Try normalized exact match
+        if norm_needle in norm_haystack:
+            # Find the match in normalized text
+            norm_start = norm_haystack.index(norm_needle)
+            
+            # Map back to original text
+            # This is approximate but usually good enough
+            lines_before = norm_haystack[:norm_start].count('\n')
+            
+            # Find corresponding position in original
+            original_lines = haystack.split('\n')
+            norm_lines = norm_haystack.split('\n')
+            
+            start_pos = sum(len(line) + 1 for line in original_lines[:lines_before])
+            
+            # Find end position by counting lines in needle
+            needle_lines = norm_needle.count('\n') + 1
+            end_pos = sum(len(line) + 1 for line in original_lines[:lines_before + needle_lines])
+            
+            matched = '\n'.join(original_lines[lines_before:lines_before + needle_lines])
+            return (start_pos, end_pos - 1, matched)
+        
+        # Try fuzzy matching on lines
+        haystack_lines = haystack.split('\n')
+        needle_lines = needle.split('\n')
+        
+        if len(needle_lines) == 1:
+            # Single line - find best match
+            needle_norm = ForgivingEditHelper.normalize_whitespace(needle)
+            best_ratio = 0
+            best_match = None
+            
+            for i, line in enumerate(haystack_lines):
+                line_norm = ForgivingEditHelper.normalize_whitespace(line)
+                ratio = difflib.SequenceMatcher(None, line_norm, needle_norm).ratio()
+                
+                if ratio > best_ratio and ratio >= threshold:
+                    best_ratio = ratio
+                    start_pos = sum(len(l) + 1 for l in haystack_lines[:i])
+                    best_match = (start_pos, start_pos + len(line), line)
+            
+            return best_match
+        
+        else:
+            # Multi-line - find sequence match
+            for i in range(len(haystack_lines) - len(needle_lines) + 1):
+                candidate_lines = haystack_lines[i:i + len(needle_lines)]
+                candidate = '\n'.join(candidate_lines)
+                candidate_norm = ForgivingEditHelper.normalize_whitespace(candidate)
+                needle_norm = ForgivingEditHelper.normalize_whitespace(needle)
+                
+                ratio = difflib.SequenceMatcher(None, candidate_norm, needle_norm).ratio()
+                
+                if ratio >= threshold:
+                    start_pos = sum(len(l) + 1 for l in haystack_lines[:i])
+                    return (start_pos, start_pos + len(candidate), candidate)
+        
+        return None
+    
+    @staticmethod
+    def suggest_matches(
+        haystack: str,
+        needle: str,
+        max_suggestions: int = 3
+    ) -> List[Tuple[float, str]]:
+        """Suggest possible matches when exact match fails.
+        
+        Args:
+            haystack: Text to search in
+            needle: Text to search for
+            max_suggestions: Maximum number of suggestions
+            
+        Returns:
+            List of (similarity_score, text) tuples
+        """
+        suggestions = []
+        
+        # Normalize needle
+        needle_norm = ForgivingEditHelper.normalize_whitespace(needle)
+        needle_lines = needle.split('\n')
+        
+        if len(needle_lines) == 1:
+            # Single line - compare with all lines
+            for line in haystack.split('\n'):
+                if line.strip():  # Skip empty lines
+                    line_norm = ForgivingEditHelper.normalize_whitespace(line)
+                    ratio = difflib.SequenceMatcher(None, line_norm, needle_norm).ratio()
+                    if ratio > 0.5:  # Only reasonably similar lines
+                        suggestions.append((ratio, line))
+        
+        else:
+            # Multi-line - use sliding window
+            haystack_lines = haystack.split('\n')
+            window_size = len(needle_lines)
+            
+            for i in range(len(haystack_lines) - window_size + 1):
+                candidate_lines = haystack_lines[i:i + window_size]
+                candidate = '\n'.join(candidate_lines)
+                candidate_norm = ForgivingEditHelper.normalize_whitespace(candidate)
+                
+                ratio = difflib.SequenceMatcher(None, candidate_norm, needle_norm).ratio()
+                if ratio > 0.5:
+                    suggestions.append((ratio, candidate))
+        
+        # Sort by similarity and return top matches
+        suggestions.sort(reverse=True, key=lambda x: x[0])
+        return suggestions[:max_suggestions]
+    
+    @staticmethod
+    def create_edit_suggestion(
+        file_content: str,
+        old_string: str,
+        new_string: str
+    ) -> dict:
+        """Create a helpful edit suggestion when match fails.
+        
+        Args:
+            file_content: Current file content
+            old_string: String that couldn't be found
+            new_string: Replacement string
+            
+        Returns:
+            Dict with error message and suggestions
+        """
+        # Try fuzzy match
+        fuzzy_match = ForgivingEditHelper.find_fuzzy_match(file_content, old_string)
+        
+        if fuzzy_match:
+            _, _, matched_text = fuzzy_match
+            return {
+                "error": "Exact match not found, but found similar text",
+                "found": matched_text,
+                "suggestion": "Use this as old_string instead",
+                "confidence": "high"
+            }
+        
+        # Get suggestions
+        suggestions = ForgivingEditHelper.suggest_matches(file_content, old_string)
+        
+        if suggestions:
+            return {
+                "error": "Could not find exact or fuzzy match",
+                "suggestions": [
+                    {"similarity": f"{score:.0%}", "text": text}
+                    for score, text in suggestions
+                ],
+                "hint": "Try using one of these suggestions as old_string"
+            }
+        
+        # No good matches - provide general help
+        return {
+            "error": "Could not find any matches",
+            "hints": [
+                "Check for whitespace differences (tabs vs spaces)",
+                "Ensure you're including complete lines",
+                "Try a smaller, more unique portion of text",
+                "Use the streaming_command tool to view the file with visible whitespace"
+            ]
+        }
+    
+    @staticmethod
+    def prepare_edit_string(text: str) -> str:
+        """Prepare a string for editing by handling common issues.
+        
+        Args:
+            text: Text to prepare
+            
+        Returns:
+            Cleaned text ready for editing
+        """
+        # Remove any line number prefixes (common in AI copy-paste)
+        lines = []
+        for line in text.split('\n'):
+            # Remove common line number patterns
+            cleaned = re.sub(r'^\s*\d+[:\|\-\s]\s*', '', line)
+            lines.append(cleaned)
+        
+        return '\n'.join(lines)

hanzo_mcp/tools/common/paginated_base.py

@@ -0,0 +1,230 @@
+"""Enhanced base class with automatic pagination support.
+
+This module provides a base class that automatically handles pagination
+for all tool responses that exceed MCP token limits.
+"""
+
+import json
+from abc import abstractmethod
+from typing import Any, Dict, Optional, Union
+
+from mcp.server.fastmcp import Context as MCPContext
+
+from hanzo_mcp.tools.common.base import BaseTool, handle_connection_errors
+from hanzo_mcp.tools.common.paginated_response import paginate_if_needed
+from hanzo_mcp.tools.common.pagination import CursorManager
+
+
+class PaginatedBaseTool(BaseTool):
+    """Base class for tools with automatic pagination support.
+    
+    This base class automatically handles pagination for responses that
+    exceed MCP token limits, making all tools pagination-aware by default.
+    """
+    
+    def __init__(self):
+        """Initialize the paginated base tool."""
+        super().__init__()
+        self._supports_pagination = True
+    
+    @abstractmethod
+    async def execute(self, ctx: MCPContext, **params: Any) -> Any:
+        """Execute the tool logic and return raw results.
+        
+        This method should be implemented by subclasses to perform the
+        actual tool logic. The base class will handle pagination of
+        the returned results automatically.
+        
+        Args:
+            ctx: MCP context
+            **params: Tool parameters
+            
+        Returns:
+            Raw tool results (will be paginated if needed)
+        """
+        pass
+    
+    @handle_connection_errors
+    async def call(self, ctx: MCPContext, **params: Any) -> Union[str, Dict[str, Any]]:
+        """Execute the tool with automatic pagination support.
+        
+        This method wraps the execute() method and automatically handles
+        pagination if the response exceeds token limits.
+        
+        Args:
+            ctx: MCP context
+            **params: Tool parameters including optional 'cursor'
+            
+        Returns:
+            Tool result, potentially paginated
+        """
+        # Extract cursor if provided
+        cursor = params.pop("cursor", None)
+        
+        # Validate cursor if provided
+        if cursor and not CursorManager.parse_cursor(cursor):
+            return {"error": "Invalid cursor provided", "code": -32602}
+        
+        # Check if this is a continuation request
+        if cursor:
+            # For continuation, check if we have cached results
+            cursor_data = CursorManager.parse_cursor(cursor)
+            if cursor_data and "tool" in cursor_data and cursor_data["tool"] != self.name:
+                return {"error": "Cursor is for a different tool", "code": -32602}
+        
+        # Execute the tool
+        try:
+            result = await self.execute(ctx, **params)
+        except Exception as e:
+            # Format errors consistently
+            return {"error": str(e), "type": type(e).__name__}
+        
+        # Handle pagination automatically
+        if self._supports_pagination:
+            paginated_result = paginate_if_needed(result, cursor)
+            
+            # If pagination occurred, add tool info to help with continuation
+            if isinstance(paginated_result, dict) and "nextCursor" in paginated_result:
+                # Enhance the cursor with tool information
+                if "nextCursor" in paginated_result:
+                    cursor_data = CursorManager.parse_cursor(paginated_result["nextCursor"])
+                    if cursor_data:
+                        cursor_data["tool"] = self.name
+                        cursor_data["params"] = params  # Store params for continuation
+                        paginated_result["nextCursor"] = CursorManager.create_cursor(cursor_data)
+            
+            return paginated_result
+        else:
+            # Return raw result if pagination is disabled
+            return result
+    
+    def disable_pagination(self):
+        """Disable automatic pagination for this tool.
+        
+        Some tools may want to handle their own pagination logic.
+        """
+        self._supports_pagination = False
+    
+    def enable_pagination(self):
+        """Re-enable automatic pagination for this tool."""
+        self._supports_pagination = True
+
+
+class PaginatedFileSystemTool(PaginatedBaseTool):
+    """Base class for filesystem tools with pagination support."""
+    
+    def __init__(self, permission_manager):
+        """Initialize filesystem tool with pagination.
+        
+        Args:
+            permission_manager: Permission manager for access control
+        """
+        super().__init__()
+        self.permission_manager = permission_manager
+    
+    def is_path_allowed(self, path: str) -> bool:
+        """Check if a path is allowed according to permission settings.
+        
+        Args:
+            path: Path to check
+            
+        Returns:
+            True if the path is allowed, False otherwise
+        """
+        return self.permission_manager.is_path_allowed(path)
+
+
+def migrate_tool_to_paginated(tool_class):
+    """Decorator to migrate existing tools to use pagination.
+    
+    This decorator can be applied to existing tool classes to add
+    automatic pagination support without modifying their code.
+    
+    Usage:
+        @migrate_tool_to_paginated
+        class MyTool(BaseTool):
+            ...
+    """
+    class PaginatedWrapper(PaginatedBaseTool):
+        def __init__(self, *args, **kwargs):
+            super().__init__()
+            self._wrapped_tool = tool_class(*args, **kwargs)
+            
+        @property
+        def name(self):
+            return self._wrapped_tool.name
+            
+        @property  
+        def description(self):
+            # Add pagination info to description
+            desc = self._wrapped_tool.description
+            if not "pagination" in desc.lower():
+                desc += "\n\nThis tool supports automatic pagination. If the response is too large, it will be split across multiple requests. Use the returned cursor to continue."
+            return desc
+            
+        async def execute(self, ctx: MCPContext, **params: Any) -> Any:
+            # Call the wrapped tool's call method
+            return await self._wrapped_tool.call(ctx, **params)
+            
+        def register(self, mcp_server):
+            # Need to create a new registration that includes cursor parameter
+            tool_self = self
+            
+            # Get the original registration function
+            original_register = self._wrapped_tool.register
+            
+            # Create a new registration that adds cursor support
+            def register_with_pagination(server):
+                # First register the original tool
+                original_register(server)
+                
+                # Then override with pagination support
+                import inspect
+                
+                # Get the registered function
+                tool_func = None
+                for name, func in server._tools.items():
+                    if name == self.name:
+                        tool_func = func
+                        break
+                
+                if tool_func:
+                    # Get original signature
+                    sig = inspect.signature(tool_func)
+                    params = list(sig.parameters.values())
+                    
+                    # Add cursor parameter if not present
+                    has_cursor = any(p.name == "cursor" for p in params)
+                    if not has_cursor:
+                        from typing import Optional
+                        import inspect
+                        
+                        # Create new parameter with cursor
+                        cursor_param = inspect.Parameter(
+                            "cursor",
+                            inspect.Parameter.KEYWORD_ONLY,
+                            default=None,
+                            annotation=Optional[str]
+                        )
+                        
+                        # Insert before ctx parameter
+                        new_params = []
+                        for p in params:
+                            if p.name == "ctx":
+                                new_params.append(cursor_param)
+                            new_params.append(p)
+                        
+                        # Create wrapper function
+                        async def paginated_wrapper(**kwargs):
+                            return await tool_self.call(kwargs.get("ctx"), **kwargs)
+                        
+                        # Update registration
+                        server._tools[self.name] = paginated_wrapper
+            
+            register_with_pagination(mcp_server)
+    
+    # Set the class name
+    PaginatedWrapper.__name__ = f"Paginated{tool_class.__name__}"
+    PaginatedWrapper.__qualname__ = f"Paginated{tool_class.__qualname__}"
+    
+    return PaginatedWrapper