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

hanzo_mcp/tools/common/__init__.py

@@ -1,10 +1,11 @@
-"""Common utilities for Hanzo MCP tools."""
+"""Common utilities for Hanzo AI tools."""
 
 from mcp.server import FastMCP
 
 from hanzo_mcp.tools.common.base import BaseTool, ToolRegistry
 from hanzo_mcp.tools.common.batch_tool import BatchTool
 from hanzo_mcp.tools.common.thinking_tool import ThinkingTool
+from hanzo_mcp.tools.common.critic_tool import CriticTool
 
 
 def register_thinking_tool(
@@ -20,6 +21,19 @@ def register_thinking_tool(
     return [thinking_tool]
 
 
+def register_critic_tool(
+    mcp_server: FastMCP,
+) -> list[BaseTool]:
+    """Register critic tool with the MCP server.
+
+    Args:
+        mcp_server: The FastMCP server instance
+    """
+    critic_tool = CriticTool()
+    ToolRegistry.register_tool(mcp_server, critic_tool)
+    return [critic_tool]
+
+
 def register_batch_tool(mcp_server: FastMCP, tools: dict[str, BaseTool]) -> None:
     """Register batch tool with the MCP server.
 

hanzo_mcp/tools/common/base.py

@@ -1,7 +1,7 @@
-"""Base classes for Hanzo MCP tools.
+"""Base classes for Hanzo AI tools.
 
 This module provides abstract base classes that define interfaces and common functionality
-for all tools used in Hanzo MCP. These abstractions help ensure consistent tool
+for all tools used in Hanzo AI. These abstractions help ensure consistent tool
 behavior and provide a foundation for tool registration and management.
 """
 
@@ -62,7 +62,7 @@ def handle_connection_errors(
 
 
 class BaseTool(ABC):
-    """Abstract base class for all Hanzo MCP tools.
+    """Abstract base class for all Hanzo AI tools.
 
     This class defines the core interface that all tools must implement, ensuring
     consistency in how tools are registered, documented, and called.
@@ -156,7 +156,7 @@ class FileSystemTool(BaseTool, ABC):
 
 @final
 class ToolRegistry:
-    """Registry for Hanzo MCP tools.
+    """Registry for Hanzo AI tools.
 
     Provides functionality for registering tool implementations with an MCP server,
     handling the conversion between tool classes and MCP tool functions.

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.

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

hanzo_mcp/tools/common/enhanced_base.py

@@ -0,0 +1,106 @@
+"""Enhanced base classes for MCP tools with automatic context handling.
+
+This module provides enhanced base classes that automatically handle
+context normalization and other cross-cutting concerns, ensuring
+consistent behavior across all tools.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, get_type_hints, get_args, get_origin
+import inspect
+
+from mcp.server import FastMCP
+from mcp.server.fastmcp import Context as MCPContext
+
+from hanzo_mcp.tools.common.base import BaseTool
+from hanzo_mcp.tools.common.decorators import with_context_normalization
+
+
+class EnhancedBaseTool(BaseTool, ABC):
+    """Enhanced base class for MCP tools with automatic context normalization.
+    
+    This base class automatically wraps the tool registration to include
+    context normalization, ensuring that all tools handle external calls
+    properly without requiring manual decoration or copy-pasted code.
+    """
+    
+    def register(self, mcp_server: FastMCP) -> None:
+        """Register this tool with automatic context normalization.
+        
+        This method automatically applies context normalization to the tool
+        handler, ensuring it works properly when called externally.
+        
+        Args:
+            mcp_server: The FastMCP server instance
+        """
+        # Get the tool method from the subclass
+        tool_method = self._create_tool_handler()
+        
+        # Apply context normalization decorator
+        normalized_method = with_context_normalization(tool_method)
+        
+        # Register with the server
+        mcp_server.tool(
+            name=self.name,
+            description=self.description
+        )(normalized_method)
+    
+    @abstractmethod
+    def _create_tool_handler(self) -> Any:
+        """Create the tool handler function.
+        
+        Subclasses must implement this to return an async function
+        that will be registered as the tool handler.
+        
+        Returns:
+            An async function that handles tool calls
+        """
+        pass
+
+
+class AutoRegisterTool(BaseTool, ABC):
+    """Base class that automatically generates tool handlers from the call method.
+    
+    This base class inspects the call method signature and automatically
+    creates a properly typed tool handler with context normalization.
+    """
+    
+    def register(self, mcp_server: FastMCP) -> None:
+        """Register this tool with automatic handler generation.
+        
+        This method inspects the call method signature and automatically
+        creates a tool handler with the correct parameters and types.
+        
+        Args:
+            mcp_server: The FastMCP server instance
+        """
+        # Get the call method signature
+        call_method = self.call
+        sig = inspect.signature(call_method)
+        
+        # Get type hints for proper typing
+        hints = get_type_hints(call_method)
+        
+        # Create a dynamic handler function
+        tool_self = self
+        
+        # Build the handler dynamically based on the call signature
+        params = list(sig.parameters.items())
+        
+        # Skip 'self' and 'ctx' parameters
+        tool_params = [(name, param) for name, param in params 
+                      if name not in ('self', 'ctx')]
+        
+        # Create the handler function dynamically
+        async def handler(ctx: MCPContext, **kwargs: Any) -> Any:
+            # Call the tool's call method with the context and parameters
+            return await tool_self.call(ctx, **kwargs)
+        
+        # Apply context normalization
+        normalized_handler = with_context_normalization(handler)
+        
+        # Register with the server
+        mcp_server.tool(
+            name=self.name,
+            description=self.description
+        )(normalized_handler)