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

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)

hanzo_mcp/tools/common/mode.py

@@ -0,0 +1,116 @@
+"""Mode system for organizing development tools based on programmer personalities."""
+
+import os
+from dataclasses import dataclass
+from typing import Dict, List, Optional, Set
+
+from hanzo_mcp.tools.common.personality import (
+    ToolPersonality,
+    register_default_personalities,
+    ensure_agent_enabled,
+    personalities
+)
+
+
+@dataclass
+class Mode(ToolPersonality):
+    """Development mode combining tool preferences and environment settings."""
+    # Inherits all fields from ToolPersonality
+    # Adds mode-specific functionality
+    
+    @property
+    def is_active(self) -> bool:
+        """Check if this mode is currently active."""
+        return ModeRegistry.get_active() == self
+
+
+class ModeRegistry:
+    """Registry for development modes."""
+    
+    _modes: Dict[str, Mode] = {}
+    _active_mode: Optional[str] = None
+    
+    @classmethod
+    def register(cls, mode: Mode) -> None:
+        """Register a development mode."""
+        # Ensure agent is enabled if API keys present
+        mode = ensure_agent_enabled(mode)
+        cls._modes[mode.name] = mode
+    
+    @classmethod
+    def get(cls, name: str) -> Optional[Mode]:
+        """Get a mode by name."""
+        return cls._modes.get(name)
+    
+    @classmethod
+    def list(cls) -> List[Mode]:
+        """List all registered modes."""
+        return list(cls._modes.values())
+    
+    @classmethod
+    def set_active(cls, name: str) -> None:
+        """Set the active mode."""
+        if name not in cls._modes:
+            raise ValueError(f"Mode '{name}' not found")
+        cls._active_mode = name
+        
+        # Apply environment variables from the mode
+        mode = cls._modes[name]
+        if mode.environment:
+            for key, value in mode.environment.items():
+                os.environ[key] = value
+    
+    @classmethod
+    def get_active(cls) -> Optional[Mode]:
+        """Get the active mode."""
+        if cls._active_mode:
+            return cls._modes.get(cls._active_mode)
+        return None
+    
+    @classmethod
+    def get_active_tools(cls) -> Set[str]:
+        """Get the set of tools from the active mode."""
+        mode = cls.get_active()
+        if mode:
+            return set(mode.tools)
+        return set()
+
+
+def register_default_modes():
+    """Register all default development modes."""
+    # Convert personalities to modes
+    for personality in personalities:
+        mode = Mode(
+            name=personality.name,
+            programmer=personality.programmer,
+            description=personality.description,
+            tools=personality.tools,
+            environment=personality.environment,
+            philosophy=personality.philosophy,
+        )
+        ModeRegistry.register(mode)
+
+
+def get_mode_from_env() -> Optional[str]:
+    """Get mode name from environment variables."""
+    # Check for HANZO_MODE, PERSONALITY, or MODE env vars
+    return (
+        os.environ.get("HANZO_MODE") or
+        os.environ.get("PERSONALITY") or
+        os.environ.get("MODE")
+    )
+
+
+def activate_mode_from_env():
+    """Activate mode based on environment variables."""
+    mode_name = get_mode_from_env()
+    if mode_name:
+        try:
+            ModeRegistry.set_active(mode_name)
+            return True
+        except ValueError:
+            # Mode not found, ignore
+            pass
+    return False
+
+

hanzo_mcp/tools/common/mode_loader.py

@@ -0,0 +1,105 @@
+"""Tool mode loader for dynamic tool configuration."""
+
+import os
+from typing import Dict, List, Optional, Set
+
+from hanzo_mcp.tools.common.mode import ModeRegistry, register_default_modes, activate_mode_from_env
+
+
+class ModeLoader:
+    """Loads and manages tool modes for dynamic configuration."""
+    
+    @staticmethod
+    def initialize_modes() -> None:
+        """Initialize the mode system with defaults."""
+        # Initialize modes
+        register_default_modes()
+        
+        # Check for mode from environment
+        activate_mode_from_env()
+        
+        # If no mode set, use default
+        if not ModeRegistry.get_active():
+            default_mode = os.environ.get("HANZO_DEFAULT_MODE", "hanzo")
+            if ModeRegistry.get(default_mode):
+                ModeRegistry.set_active(default_mode)
+    
+    @staticmethod
+    def get_enabled_tools_from_mode(
+        base_enabled_tools: Optional[Dict[str, bool]] = None,
+        force_mode: Optional[str] = None
+    ) -> Dict[str, bool]:
+        """Get enabled tools configuration from active mode.
+        
+        Args:
+            base_enabled_tools: Base configuration to merge with
+            force_mode: Force a specific mode (overrides active)
+            
+        Returns:
+            Dictionary of tool enable states
+        """
+        # Initialize if needed
+        if not ModeRegistry.list():
+            ModeLoader.initialize_modes()
+        
+        # Get mode to use
+        tools_list = None
+        
+        if force_mode:
+            # Set and get mode
+            if ModeRegistry.get(force_mode):
+                ModeRegistry.set_active(force_mode)
+                mode = ModeRegistry.get_active()
+                tools_list = mode.tools if mode else None
+        else:
+            # Check active mode
+            mode = ModeRegistry.get_active()
+            if mode:
+                tools_list = mode.tools
+        
+        if not tools_list:
+            # No active mode, return base config
+            return base_enabled_tools or {}
+        
+        # Start with base configuration
+        result = base_enabled_tools.copy() if base_enabled_tools else {}
+        
+        # Get all possible tools from registry
+        from hanzo_mcp.config.tool_config import TOOL_REGISTRY
+        all_possible_tools = set(TOOL_REGISTRY.keys())
+        
+        # Disable all tools first (clean slate for mode)
+        for tool in all_possible_tools:
+            result[tool] = False
+        
+        # Enable tools from mode
+        for tool in tools_list:
+            result[tool] = True
+        
+        # Always enable mode tool (meta)
+        result["mode"] = True
+        
+        return result
+    
+    @staticmethod
+    def get_environment_from_mode() -> Dict[str, str]:
+        """Get environment variables from active mode.
+        
+        Returns:
+            Dictionary of environment variables
+        """
+        # Check mode
+        mode = ModeRegistry.get_active()
+        if mode and mode.environment:
+            return mode.environment.copy()
+        
+        return {}
+    
+    @staticmethod
+    def apply_environment_from_mode() -> None:
+        """Apply environment variables from active mode."""
+        env_vars = ModeLoader.get_environment_from_mode()
+        for key, value in env_vars.items():
+            os.environ[key] = value
+
+

hanzo_mcp/tools/common/permissions.py

@@ -1,4 +1,4 @@
-"""Permission system for the Hanzo MCP server."""
+"""Permission system for the Hanzo AI server."""
 
 import json
 import os