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

hanzo_mcp/tools/common/batch_tool.py

@@ -1,4 +1,4 @@
-"""Batch tool implementation for Hanzo MCP.
+"""Batch tool implementation for Hanzo AI.
 
 This module provides the BatchTool that allows for executing multiple tools in
 parallel or serial depending on their characteristics.
@@ -13,6 +13,12 @@ from pydantic import Field
 
 from hanzo_mcp.tools.common.base import BaseTool
 from hanzo_mcp.tools.common.context import create_tool_context
+from hanzo_mcp.tools.common.truncate import truncate_response, estimate_tokens
+from hanzo_mcp.tools.common.fastmcp_pagination import (
+    create_paginated_response,
+    CursorData,
+    TokenAwarePaginator
+)
 
 
 class InvocationItem(TypedDict):
@@ -54,6 +60,14 @@ Invocations = Annotated[
     ),
 ]
 
+Cursor = Annotated[
+    str | None,
+    Field(
+        description="Pagination cursor to continue from previous batch results",
+        default=None,
+    ),
+]
+
 
 class BatchToolParams(TypedDict):
     """Parameters for the BatchTool.
@@ -61,10 +75,12 @@ class BatchToolParams(TypedDict):
     Attributes:
         description: A short (3-5 word) description of the batch operation
         invocations: The list of tool invocations to execute (required -- you MUST provide at least one tool invocation)
+        cursor: Optional pagination cursor
     """
 
     description: Description
     invocations: Invocations
+    cursor: Cursor
 
 
 @final
@@ -271,13 +287,78 @@ Not available: think,write,edit,multi_edit,notebook_edit
                     {"invocation": invocation, "result": f"Error: {error_message}"}
                 )
 
-        # Format the results
-        formatted_results = self._format_results(results)
-        await tool_ctx.info(
-            f"Batch operation '{description}' completed with {len(results)} results"
+        # Extract cursor if provided
+        cursor = params.get("cursor")
+        cursor_offset = 0
+        
+        # If cursor provided, we need to resume from where we left off
+        if cursor:
+            cursor_data = CursorData.from_cursor(cursor)
+            if cursor_data and cursor_data.offset < len(results):
+                # Skip already returned results
+                cursor_offset = cursor_data.offset
+                results = results[cursor_offset:]
+        
+        # Format results
+        formatted_results = []
+        for i, result in enumerate(results):
+            invocation = result["invocation"]
+            tool_name = invocation.get("tool_name", "unknown")
+            formatted_results.append({
+                "tool": tool_name,
+                "result": result["result"],
+                "index": i + cursor_offset
+            })
+        
+        # Create paginated response with token awareness
+        paginated_response = create_paginated_response(
+            formatted_results,
+            cursor=cursor,
+            use_token_limit=True
         )
-
-        return formatted_results
+        
+        # Convert paginated response to string format for MCP
+        if isinstance(paginated_response, dict) and "items" in paginated_response:
+            # Format the items as a readable string
+            result_parts = []
+            
+            # Add header
+            result_parts.append(f"=== Batch operation: {description} ===")
+            result_parts.append(f"Total invocations: {len(invocations)}")
+            result_parts.append(f"Showing results: {len(paginated_response['items'])} of {len(results)}")
+            if paginated_response.get('hasMore'):
+                result_parts.append(f"More results available - use cursor: {paginated_response.get('nextCursor')}")
+            result_parts.append("")
+            
+            # Format each result
+            for item in paginated_response['items']:
+                result_parts.append(f"### Result {item['index'] + 1}: {item['tool']}")
+                result_content = item['result']
+                
+                # Add the result content - use multi-line code blocks for code outputs
+                if isinstance(result_content, str) and "\n" in result_content:
+                    result_parts.append(f"```\n{result_content}\n```")
+                else:
+                    result_parts.append(str(result_content))
+                result_parts.append("")
+            
+            # Join all parts
+            formatted_output = "\n".join(result_parts)
+            
+            # If there's a next cursor, we need to preserve it in the response
+            # For now, append it as a note at the end
+            if paginated_response.get('hasMore') and paginated_response.get('nextCursor'):
+                formatted_output += f"\n\n[To continue, use cursor: {paginated_response['nextCursor']}]"
+            
+            await tool_ctx.info(
+                f"Batch operation '{description}' completed with {len(paginated_response['items'])} results"
+                f"{' (more available)' if paginated_response.get('hasMore') else ''}"
+            )
+            
+            return formatted_output
+        else:
+            # Fallback if pagination didn't work as expected
+            return self._format_results(results)
 
     def _format_results(self, results: list[dict[str, dict[str, Any]]]) -> str:
         """Format the results from multiple tool invocations.
@@ -295,11 +376,21 @@ Not available: think,write,edit,multi_edit,notebook_edit
 
             # Add the result header
             formatted_parts.append(f"### Result {i + 1}: {tool_name}")
+            
+            # Truncate individual results if they're too large
+            result_content = result["result"]
+            if len(result_content) > 50000:  # If individual result > 50k chars
+                result_content = truncate_response(
+                    result_content,
+                    max_tokens=5000,  # Limit individual results to ~5k tokens
+                    truncation_message=f"\n\n[Result from {tool_name} truncated. Use the tool directly with pagination/filtering for full output.]"
+                )
+            
             # Add the result content - use multi-line code blocks for code outputs
-            if "\n" in result["result"]:
-                formatted_parts.append(f"```\n{result['result']}\n```")
+            if "\n" in result_content:
+                formatted_parts.append(f"```\n{result_content}\n```")
             else:
-                formatted_parts.append(result["result"])
+                formatted_parts.append(result_content)
             # Add a separator
             formatted_parts.append("")
 
@@ -321,8 +412,9 @@ Not available: think,write,edit,multi_edit,notebook_edit
         async def batch(
             description: Description,
             invocations: Invocations,
+            cursor: Cursor,
             ctx: MCPContext
         ) -> str:
             return await tool_self.call(
-                ctx, description=description, invocations=invocations
+                ctx, description=description, invocations=invocations, cursor=cursor
             )

hanzo_mcp/tools/common/config_tool.py

@@ -34,7 +34,7 @@ class ConfigToolParams(TypedDict, total=False):
 
 @final
 class ConfigTool(BaseTool):
-    """Tool for managing Hanzo MCP configuration dynamically."""
+    """Tool for managing Hanzo AI configuration dynamically."""
     
     def __init__(self, permission_manager: PermissionManager):
         """Initialize the configuration tool.
@@ -52,7 +52,7 @@ class ConfigTool(BaseTool):
     @property
     def description(self) -> str:
         """Get the tool description."""
-        return """Dynamically manage Hanzo MCP configuration settings through conversation.
+        return """Dynamically manage Hanzo AI configuration settings through conversation.
 
 Can get/set global settings, project-specific settings, manage MCP servers, configure tools,
 and handle project workflows. Supports dot-notation for nested settings like 'agent.enabled'.

hanzo_mcp/tools/common/context.py

@@ -1,4 +1,4 @@
-"""Enhanced Context for Hanzo MCP tools.
+"""Enhanced Context for Hanzo AI tools.
 
 This module provides an enhanced Context class that wraps the MCP Context
 and adds additional functionality specific to Hanzo tools.
@@ -17,7 +17,7 @@ from mcp.server.lowlevel.helper_types import ReadResourceContents
 
 @final
 class ToolContext:
-    """Enhanced context for Hanzo MCP tools.
+    """Enhanced context for Hanzo AI tools.
 
     This class wraps the MCP Context and adds additional functionality
     for tracking tool execution, progress reporting, and resource access.

hanzo_mcp/tools/common/context_fix.py

@@ -0,0 +1,26 @@
+"""Context handling fix for MCP tools.
+
+This module provides backward compatibility by re-exporting the
+context normalization utilities from the decorators module.
+
+DEPRECATED: Use hanzo_mcp.tools.common.decorators directly.
+"""
+
+# Re-export for backward compatibility
+from hanzo_mcp.tools.common.decorators import (
+    MockContext,
+    with_context_normalization,
+    _is_valid_context as is_valid_context,
+)
+
+# Backward compatibility function
+def normalize_context(ctx):
+    """Normalize context - backward compatibility wrapper.
+    
+    DEPRECATED: Use decorators.with_context_normalization instead.
+    """
+    if is_valid_context(ctx):
+        return ctx
+    return MockContext()
+
+__all__ = ['MockContext', 'normalize_context', 'with_context_normalization']

hanzo_mcp/tools/common/critic_tool.py

@@ -0,0 +1,196 @@
+"""Critic tool implementation.
+
+This module provides the CriticTool for Claude to engage in critical analysis and code review.
+"""
+
+from typing import Annotated, 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.common.base import BaseTool
+from hanzo_mcp.tools.common.context import create_tool_context
+
+
+Analysis = Annotated[
+    str,
+    Field(
+        description="The critical analysis to perform - code review, error detection, or improvement suggestions",
+        min_length=1,
+    ),
+]
+
+
+class CriticToolParams(TypedDict):
+    """Parameters for the CriticTool.
+
+    Attributes:
+        analysis: The critical analysis to perform
+    """
+
+    analysis: Analysis
+
+
+@final
+class CriticTool(BaseTool):
+    """Tool for Claude to engage in critical analysis and play devil's advocate."""
+
+    @property
+    @override
+    def name(self) -> str:
+        """Get the tool name.
+
+        Returns:
+            Tool name
+        """
+        return "critic"
+
+    @property
+    @override
+    def description(self) -> str:
+        """Get the tool description.
+
+        Returns:
+            Tool description
+        """
+        return """Use this tool to perform critical analysis, play devil's advocate, and ensure high standards. 
+This tool forces a critical thinking mode that reviews all code for errors, improvements, and edge cases.
+It ensures tests are run, tests pass, and maintains high quality standards.
+
+This is your inner critic that:
+- Always questions assumptions
+- Looks for potential bugs and edge cases
+- Ensures proper error handling
+- Verifies test coverage
+- Checks for performance issues
+- Reviews security implications
+- Suggests improvements and refactoring
+- Ensures code follows best practices
+- Questions design decisions
+- Looks for missing documentation
+
+Common use cases:
+1. Before finalizing any code changes - review for bugs, edge cases, and improvements
+2. After implementing a feature - critically analyze if it truly solves the problem
+3. When tests pass too easily - question if tests are comprehensive enough
+4. Before marking a task complete - ensure all quality standards are met
+5. When something seems too simple - look for hidden complexity or missing requirements
+6. After fixing a bug - analyze if the fix addresses root cause or just symptoms
+
+<critic_example>
+Code Review Analysis:
+- Implementation Issues:
+  * No error handling for network failures in API calls
+  * Missing validation for user input boundaries
+  * Race condition possible in concurrent updates
+  * Memory leak potential in event listener registration
+  
+- Test Coverage Gaps:
+  * No tests for error scenarios
+  * Missing edge case: empty array input
+  * No performance benchmarks for large datasets
+  * Integration tests don't cover authentication failures
+  
+- Security Concerns:
+  * SQL injection vulnerability in query construction
+  * Missing rate limiting on public endpoints
+  * Sensitive data logged in debug mode
+  
+- Performance Issues:
+  * O(n²) algorithm where O(n log n) is possible
+  * Database queries in a loop (N+1 problem)
+  * No caching for expensive computations
+  
+- Code Quality:
+  * Functions too long and doing multiple things
+  * Inconsistent naming conventions
+  * Missing type annotations
+  * No documentation for complex algorithms
+  
+- Design Flaws:
+  * Tight coupling between modules
+  * Hard-coded configuration values
+  * No abstraction for external dependencies
+  * Violates single responsibility principle
+
+Recommendations:
+1. Add comprehensive error handling with retry logic
+2. Implement input validation with clear error messages
+3. Use database transactions to prevent race conditions
+4. Add memory cleanup in component unmount
+5. Parameterize SQL queries to prevent injection
+6. Implement rate limiting middleware
+7. Use environment variables for sensitive config
+8. Refactor algorithm to use sorting approach
+9. Batch database queries
+10. Add memoization for expensive calculations
+</critic_example>"""
+
+    def __init__(self) -> None:
+        """Initialize the critic tool."""
+        pass
+
+    @override
+    async def call(
+        self,
+        ctx: MCPContext,
+        **params: Unpack[CriticToolParams],
+    ) -> str:
+        """Execute the tool with the given parameters.
+
+        Args:
+            ctx: MCP context
+            **params: Tool parameters
+
+        Returns:
+            Tool result
+        """
+        tool_ctx = create_tool_context(ctx)
+        tool_ctx.set_tool_info(self.name)
+
+        # Extract parameters
+        analysis = params.get("analysis")
+
+        # Validate required analysis parameter
+        if not analysis:
+            await tool_ctx.error(
+                "Parameter 'analysis' is required but was None or empty"
+            )
+            return "Error: Parameter 'analysis' is required but was None or empty"
+
+        if analysis.strip() == "":
+            await tool_ctx.error("Parameter 'analysis' cannot be empty")
+            return "Error: Parameter 'analysis' cannot be empty"
+
+        # Log the critical analysis
+        await tool_ctx.info("Critical analysis recorded")
+
+        # Return confirmation with reminder to act on the analysis
+        return """Critical analysis complete. Remember to:
+1. Address all identified issues before proceeding
+2. Run comprehensive tests to verify fixes
+3. Ensure all tests pass with proper coverage
+4. Document any design decisions or trade-offs
+5. Consider the analysis points in your implementation
+
+Continue with improvements based on this critical review."""
+
+    @override
+    def register(self, mcp_server: FastMCP) -> None:
+        """Register this critic tool with the MCP server.
+
+        Creates a wrapper function with explicitly defined parameters that match
+        the tool's parameter schema and registers it 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 critic(
+            analysis: Analysis,
+            ctx: MCPContext
+        ) -> str:
+            return await tool_self.call(ctx, analysis=analysis)

hanzo_mcp/tools/common/decorators.py

@@ -0,0 +1,208 @@
+"""Decorators for MCP tools.
+
+This module provides decorators that handle common cross-cutting concerns
+for MCP tools, such as context normalization and error handling.
+"""
+
+import functools
+import inspect
+from typing import Any, Callable, TypeVar, cast
+from collections.abc import Awaitable, Coroutine
+
+from mcp.server.fastmcp import Context as MCPContext
+
+F = TypeVar('F', bound=Callable[..., Any])
+
+
+class MockContext:
+    """Mock context for when no real context is available.
+    
+    This is used when tools are called externally through the MCP protocol
+    and the Context parameter is not properly serialized.
+    """
+    
+    def __init__(self):
+        self.request_id = "external-request"
+        self.client_id = "external-client"
+    
+    async def info(self, message: str) -> None:
+        """Mock info logging - no-op for external calls."""
+        pass
+    
+    async def debug(self, message: str) -> None:
+        """Mock debug logging - no-op for external calls."""
+        pass
+    
+    async def warning(self, message: str) -> None:
+        """Mock warning logging - no-op for external calls."""
+        pass
+    
+    async def error(self, message: str) -> None:
+        """Mock error logging - no-op for external calls."""
+        pass
+    
+    async def report_progress(self, current: int, total: int) -> None:
+        """Mock progress reporting - no-op for external calls."""
+        pass
+    
+    async def read_resource(self, uri: str) -> Any:
+        """Mock resource reading - returns empty result."""
+        return []
+
+
+def with_context_normalization(func: F) -> F:
+    """Decorator that normalizes the context parameter for MCP tools.
+    
+    This decorator intercepts the ctx parameter and ensures it's a valid
+    MCPContext object, even when called externally where it might be
+    passed as a string, dict, or None.
+    
+    Usage:
+        @server.tool()
+        @with_context_normalization
+        async def my_tool(ctx: MCPContext, param: str) -> str:
+            # ctx is guaranteed to be a valid context object
+            await ctx.info("Processing...")
+            return "result"
+    
+    Args:
+        func: The async function to decorate
+        
+    Returns:
+        The decorated function with context normalization
+    """
+    @functools.wraps(func)
+    async def wrapper(*args: Any, **kwargs: Any) -> Any:
+        # Get function signature to find ctx parameter
+        sig = inspect.signature(func)
+        params = list(sig.parameters.keys())
+        
+        # Handle ctx in kwargs
+        if 'ctx' in kwargs:
+            ctx_value = kwargs['ctx']
+            if not _is_valid_context(ctx_value):
+                kwargs['ctx'] = MockContext()
+        
+        # Handle ctx in args (positional)
+        elif 'ctx' in params:
+            ctx_index = params.index('ctx')
+            if ctx_index < len(args):
+                ctx_value = args[ctx_index]
+                if not _is_valid_context(ctx_value):
+                    args_list = list(args)
+                    args_list[ctx_index] = MockContext()
+                    args = tuple(args_list)
+        
+        # Call the original function
+        return await func(*args, **kwargs)
+    
+    return cast(F, wrapper)
+
+
+def _is_valid_context(ctx: Any) -> bool:
+    """Check if an object is a valid MCPContext.
+    
+    Args:
+        ctx: The object to check
+        
+    Returns:
+        True if ctx is a valid context object
+    """
+    # Check for required context methods
+    return (
+        hasattr(ctx, 'info') and 
+        hasattr(ctx, 'debug') and
+        hasattr(ctx, 'warning') and
+        hasattr(ctx, 'error') and
+        hasattr(ctx, 'report_progress') and
+        # Ensure they're callable
+        callable(getattr(ctx, 'info', None)) and
+        callable(getattr(ctx, 'debug', None))
+    )
+
+
+def mcp_tool(
+    server: Any,
+    name: str | None = None,
+    description: str | None = None
+) -> Callable[[F], F]:
+    """Enhanced MCP tool decorator that includes context normalization.
+    
+    This decorator combines the standard MCP tool registration with
+    automatic context normalization, providing a single-point solution
+    for all tools.
+    
+    Usage:
+        @mcp_tool(server, name="my_tool", description="Does something")
+        async def my_tool(ctx: MCPContext, param: str) -> str:
+            await ctx.info("Processing...")
+            return "result"
+    
+    Args:
+        server: The MCP server instance
+        name: Optional tool name (defaults to function name)
+        description: Optional tool description
+        
+    Returns:
+        Decorator function
+    """
+    def decorator(func: F) -> F:
+        # Apply context normalization first
+        normalized_func = with_context_normalization(func)
+        
+        # Then apply the server's tool decorator
+        if hasattr(server, 'tool'):
+            # Use the server's tool decorator
+            server_decorator = server.tool(name=name, description=description)
+            return server_decorator(normalized_func)
+        else:
+            # Fallback if server doesn't have tool method
+            return normalized_func
+    
+    return decorator
+
+
+def create_tool_handler(server: Any, tool: Any) -> Callable[[], None]:
+    """Create a standardized tool registration handler.
+    
+    This function creates a registration method that automatically applies
+    context normalization to any tool handler registered with the server.
+    
+    Usage:
+        class MyTool(BaseTool):
+            def register(self, mcp_server):
+                register = create_tool_handler(mcp_server, self)
+                register()
+    
+    Args:
+        server: The MCP server instance
+        tool: The tool instance with name, description, and handler
+        
+    Returns:
+        A function that registers the tool with context normalization
+    """
+    def register_with_normalization():
+        # Get the original register method
+        original_register = tool.__class__.register
+        
+        # Temporarily replace server.tool to wrap with normalization
+        original_tool_decorator = server.tool
+        
+        def normalized_tool_decorator(name=None, description=None):
+            def decorator(func):
+                # Apply context normalization
+                normalized = with_context_normalization(func)
+                # Apply original decorator
+                return original_tool_decorator(name=name, description=description)(normalized)
+            return decorator
+        
+        # Monkey-patch temporarily
+        server.tool = normalized_tool_decorator
+        try:
+            # Call original register
+            original_register(tool, server)
+        finally:
+            # Restore original
+            server.tool = original_tool_decorator
+    
+    return register_with_normalization