hanzo-mcp 0.7.7__py3-none-any.whl → 0.8.0__py3-none-any.whl

hanzo_mcp/tools/common/paginated_base.py

@@ -4,107 +4,114 @@ 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 typing import Any, Dict, 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
+from hanzo_mcp.tools.common.paginated_response import paginate_if_needed
 
 
 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:
+            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"])
+                    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)
-            
+                        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
@@ -112,22 +119,22 @@ class PaginatedBaseTool(BaseTool):
 
 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
         """
@@ -136,95 +143,96 @@ class PaginatedFileSystemTool(PaginatedBaseTool):
 
 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  
+
+        @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
-                        
+                        from typing import Optional
+
                         # Create new parameter with cursor
                         cursor_param = inspect.Parameter(
                             "cursor",
                             inspect.Parameter.KEYWORD_ONLY,
                             default=None,
-                            annotation=Optional[str]
+                            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
+
+    return PaginatedWrapper

hanzo_mcp/tools/common/paginated_response.py

@@ -5,30 +5,31 @@ when they exceed token limits.
 """
 
 import json
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Dict, List, Union, Optional
+
 from hanzo_mcp.tools.common.truncate import estimate_tokens
 from hanzo_mcp.tools.common.pagination import CursorManager
 
 
 class AutoPaginatedResponse:
     """Automatically paginate responses that exceed token limits."""
-    
+
     # MCP token limit with safety buffer
     MAX_TOKENS = 20000  # Leave 5k buffer from 25k limit
-    
+
     @staticmethod
     def create_response(
         content: Union[str, Dict[str, Any], List[Any]],
         cursor: Optional[str] = None,
-        max_tokens: int = MAX_TOKENS
+        max_tokens: int = MAX_TOKENS,
     ) -> Dict[str, Any]:
         """Create a response that automatically paginates if too large.
-        
+
         Args:
             content: The content to return
             cursor: Optional cursor from request
             max_tokens: Maximum tokens allowed in response
-            
+
         Returns:
             Dict with content and optional nextCursor
         """
@@ -54,12 +55,10 @@ class AutoPaginatedResponse:
             return AutoPaginatedResponse._handle_string_response(
                 str(content), cursor, max_tokens
             )
-    
+
     @staticmethod
     def _handle_string_response(
-        content: str,
-        cursor: Optional[str],
-        max_tokens: int
+        content: str, cursor: Optional[str], max_tokens: int
     ) -> Dict[str, Any]:
         """Handle pagination for string responses."""
         # Parse cursor to get offset
@@ -68,28 +67,28 @@ class AutoPaginatedResponse:
             cursor_data = CursorManager.parse_cursor(cursor)
             if cursor_data and "offset" in cursor_data:
                 offset = cursor_data["offset"]
-        
+
         # For strings, paginate by lines
-        lines = content.split('\n')
-        
+        lines = content.split("\n")
+
         if offset >= len(lines):
             return {"content": "", "message": "No more content"}
-        
+
         # Build response line by line, checking tokens
         result_lines = []
         current_tokens = 0
         line_index = offset
-        
+
         # Add header if this is a continuation
         if offset > 0:
             header = f"[Continued from line {offset + 1}]\n"
             current_tokens = estimate_tokens(header)
             result_lines.append(header)
-        
+
         while line_index < len(lines):
             line = lines[line_index]
             line_tokens = estimate_tokens(line + "\n")
-            
+
             # Check if adding this line would exceed limit
             if current_tokens + line_tokens > max_tokens:
                 # Need to paginate
@@ -99,38 +98,34 @@ class AutoPaginatedResponse:
                     result_lines.append(truncated_line)
                     line_index += 1
                 break
-            
+
             result_lines.append(line)
             current_tokens += line_tokens
             line_index += 1
-        
+
         # Build response
-        response = {
-            "content": '\n'.join(result_lines)
-        }
-        
+        response = {"content": "\n".join(result_lines)}
+
         # Add pagination info
         if line_index < len(lines):
             response["nextCursor"] = CursorManager.create_offset_cursor(line_index)
             response["pagination_info"] = {
                 "current_lines": f"{offset + 1}-{line_index}",
                 "total_lines": len(lines),
-                "has_more": True
+                "has_more": True,
             }
         else:
             response["pagination_info"] = {
                 "current_lines": f"{offset + 1}-{len(lines)}",
                 "total_lines": len(lines),
-                "has_more": False
+                "has_more": False,
             }
-        
+
         return response
-    
+
     @staticmethod
     def _handle_list_response(
-        items: List[Any],
-        cursor: Optional[str],
-        max_tokens: int
+        items: List[Any], cursor: Optional[str], max_tokens: int
     ) -> Dict[str, Any]:
         """Handle pagination for list responses."""
         # Parse cursor to get offset
@@ -139,28 +134,28 @@ class AutoPaginatedResponse:
             cursor_data = CursorManager.parse_cursor(cursor)
             if cursor_data and "offset" in cursor_data:
                 offset = cursor_data["offset"]
-        
+
         if offset >= len(items):
             return {"items": [], "message": "No more items"}
-        
+
         # Build response item by item, checking tokens
         result_items = []
         current_tokens = 100  # Base overhead
         item_index = offset
-        
+
         # Add header if continuation
         header_obj = {}
         if offset > 0:
             header_obj["continuation_from"] = offset
             current_tokens += 50
-        
+
         while item_index < len(items):
             item = items[item_index]
-            
+
             # Estimate tokens for this item
             item_str = json.dumps(item) if not isinstance(item, str) else item
             item_tokens = estimate_tokens(item_str)
-            
+
             # Check if adding this item would exceed limit
             if current_tokens + item_tokens > max_tokens:
                 if not result_items:
@@ -169,22 +164,22 @@ class AutoPaginatedResponse:
                         truncated = item[:5000] + "... [truncated]"
                         result_items.append(truncated)
                     else:
-                        result_items.append({"error": "Item too large", "index": item_index})
+                        result_items.append(
+                            {"error": "Item too large", "index": item_index}
+                        )
                     item_index += 1
                 break
-            
+
             result_items.append(item)
             current_tokens += item_tokens
             item_index += 1
-        
+
         # Build response
-        response = {
-            "items": result_items
-        }
-        
+        response = {"items": result_items}
+
         if header_obj:
             response.update(header_obj)
-        
+
         # Add pagination info
         if item_index < len(items):
             response["nextCursor"] = CursorManager.create_offset_cursor(item_index)
@@ -192,70 +187,66 @@ class AutoPaginatedResponse:
                 "returned_items": len(result_items),
                 "total_items": len(items),
                 "has_more": True,
-                "next_index": item_index
+                "next_index": item_index,
             }
         else:
             response["pagination_info"] = {
                 "returned_items": len(result_items),
                 "total_items": len(items),
-                "has_more": False
+                "has_more": False,
             }
-        
+
         return response
-    
+
     @staticmethod
     def _handle_dict_response(
-        content: Dict[str, Any],
-        cursor: Optional[str],
-        max_tokens: int
+        content: Dict[str, Any], cursor: Optional[str], max_tokens: int
     ) -> Dict[str, Any]:
         """Handle pagination for dict responses."""
         # For dicts, check if it's too large as-is
         content_str = json.dumps(content, indent=2)
         content_tokens = estimate_tokens(content_str)
-        
+
         if content_tokens <= max_tokens:
             # Fits within limit
             return content
-        
+
         # Too large - need to paginate
         # Strategy: Convert to key-value pairs and paginate
         items = list(content.items())
         offset = 0
-        
+
         if cursor:
             cursor_data = CursorManager.parse_cursor(cursor)
             if cursor_data and "offset" in cursor_data:
                 offset = cursor_data["offset"]
-        
+
         if offset >= len(items):
             return {"content": {}, "message": "No more content"}
-        
+
         # Build paginated dict
         result = {}
         current_tokens = 100  # Base overhead
-        
+
         for i in range(offset, len(items)):
             key, value = items[i]
-            
+
             # Estimate tokens for this entry
             entry_str = json.dumps({key: value})
             entry_tokens = estimate_tokens(entry_str)
-            
+
             if current_tokens + entry_tokens > max_tokens:
                 if not result:
                     # Single entry too large
                     result[key] = "[Value too large - use specific key access]"
                 break
-            
+
             result[key] = value
             current_tokens += entry_tokens
-        
+
         # Wrap in response
-        response = {
-            "content": result
-        }
-        
+        response = {"content": result}
+
         # Add pagination info
         processed = offset + len(result)
         if processed < len(items):
@@ -263,45 +254,47 @@ class AutoPaginatedResponse:
             response["pagination_info"] = {
                 "keys_returned": len(result),
                 "total_keys": len(items),
-                "has_more": True
+                "has_more": True,
             }
         else:
             response["pagination_info"] = {
                 "keys_returned": len(result),
                 "total_keys": len(items),
-                "has_more": False
+                "has_more": False,
             }
-        
+
         return response
 
 
 def paginate_if_needed(
-    response: Any,
-    cursor: Optional[str] = None,
-    force_pagination: bool = False
+    response: Any, cursor: Optional[str] = None, force_pagination: bool = False
 ) -> Union[str, Dict[str, Any]]:
     """Wrap a response with automatic pagination if needed.
-    
+
     Args:
         response: The response to potentially paginate
         cursor: Optional cursor from request
         force_pagination: Force pagination even for small responses
-        
+
     Returns:
         Original response if small enough, otherwise paginated dict
     """
     # Quick check - if response is already paginated, return as-is
-    if isinstance(response, dict) and ("nextCursor" in response or "pagination_info" in response):
+    if isinstance(response, dict) and (
+        "nextCursor" in response or "pagination_info" in response
+    ):
         return response
-    
+
     # For small responses, don't paginate unless forced
     if not force_pagination:
         try:
-            response_str = json.dumps(response) if not isinstance(response, str) else response
+            response_str = (
+                json.dumps(response) if not isinstance(response, str) else response
+            )
             if len(response_str) < 10000:  # Quick heuristic
                 return response
-        except:
+        except Exception:
             pass
-    
+
     # Create paginated response
-    return AutoPaginatedResponse.create_response(response, cursor)
+    return AutoPaginatedResponse.create_response(response, cursor)