hanzo-mcp 0.8.15__py3-none-any.whl → 0.9.1__py3-none-any.whl

hanzo_mcp/tools/common/auto_timeout.py

@@ -0,0 +1,234 @@
+"""Universal auto-timeout and backgrounding for all MCP tools.
+
+This module provides automatic timeout and backgrounding for any MCP tool operation
+that takes longer than the configured threshold (default: 2 minutes).
+"""
+
+import asyncio
+import functools
+import json
+import time
+import uuid
+import os
+from pathlib import Path
+from typing import Any, Callable, Optional, Tuple
+from collections.abc import Awaitable
+
+from mcp.server.fastmcp import Context as MCPContext
+from .timeout_parser import parse_timeout, format_timeout
+
+
+class MCPToolTimeoutManager:
+    """Manager for MCP tool timeouts and backgrounding."""
+    
+    # Default timeout before auto-backgrounding (2 minutes)
+    DEFAULT_TIMEOUT = 120.0
+    
+    # Environment variable to configure timeout
+    TIMEOUT_ENV_VAR = "HANZO_MCP_TOOL_TIMEOUT"
+    
+    def __init__(self, process_manager: Optional[Any] = None):
+        """Initialize the timeout manager.
+
+        Args:
+            process_manager: Process manager for tracking background operations
+        """
+        if process_manager is None:
+            # Lazy import to avoid circular imports
+            try:
+                from hanzo_mcp.tools.shell.base_process import ProcessManager
+                self.process_manager = ProcessManager()
+            except ImportError:
+                # If ProcessManager is not available, disable backgrounding
+                self.process_manager = None
+        else:
+            self.process_manager = process_manager
+        
+        # Get timeout from environment or use default
+        env_timeout = os.getenv(self.TIMEOUT_ENV_VAR)
+        if env_timeout:
+            try:
+                self.timeout = parse_timeout(env_timeout)
+            except ValueError:
+                self.timeout = self.DEFAULT_TIMEOUT
+        else:
+            self.timeout = self.DEFAULT_TIMEOUT
+    
+    def _get_timeout_for_tool(self, tool_name: str) -> float:
+        """Get timeout setting for a specific tool.
+        
+        Args:
+            tool_name: Name of the tool
+            
+        Returns:
+            Timeout in seconds
+        """
+        # Check for tool-specific timeout
+        env_var = f"HANZO_MCP_{tool_name.upper()}_TIMEOUT"
+        tool_timeout = os.getenv(env_var)
+        if tool_timeout:
+            try:
+                return parse_timeout(tool_timeout)
+            except ValueError:
+                pass
+        
+        return self.timeout
+    
+    async def _background_tool_execution(
+        self,
+        tool_func: Callable,
+        tool_name: str,
+        ctx: MCPContext,
+        process_id: str,
+        log_file: Path,
+        **params: Any
+    ) -> None:
+        """Execute tool in background and log results.
+        
+        Args:
+            tool_func: The tool function to execute
+            tool_name: Name of the tool
+            ctx: MCP context
+            process_id: Process identifier
+            log_file: Log file path
+            **params: Tool parameters
+        """
+        try:
+            # Log start
+            with open(log_file, "a") as f:
+                f.write(f"=== Background execution started for {tool_name} ===\\n")
+                f.write(f"Parameters: {json.dumps(params, indent=2, default=str)}\\n")
+                f.write(f"Started at: {time.strftime('%Y-%m-%d %H:%M:%S')}\\n\\n")
+            
+            # Execute the tool
+            result = await tool_func(ctx, **params)
+            
+            # Log completion
+            with open(log_file, "a") as f:
+                f.write(f"\\n\\n=== Tool execution completed ===\\n")
+                f.write(f"Completed at: {time.strftime('%Y-%m-%d %H:%M:%S')}\\n")
+                f.write(f"Result length: {len(str(result))} characters\\n")
+                f.write("\\n=== RESULT ===\\n")
+                f.write(str(result))
+                f.write("\\n=== END RESULT ===\\n")
+            
+            # Mark as completed
+            self.process_manager.mark_completed(process_id, 0)
+            
+        except Exception as e:
+            # Log error
+            with open(log_file, "a") as f:
+                f.write(f"\\n\\n=== Tool execution failed ===\\n")
+                f.write(f"Failed at: {time.strftime('%Y-%m-%d %H:%M:%S')}\\n")
+                f.write(f"Error: {str(e)}\\n")
+                f.write(f"Error type: {type(e).__name__}\\n")
+            
+            self.process_manager.mark_completed(process_id, 1)
+
+
+def with_auto_timeout(tool_name: str, timeout_manager: Optional[MCPToolTimeoutManager] = None):
+    """Decorator to add automatic timeout and backgrounding to MCP tools.
+    
+    Args:
+        tool_name: Name of the tool (for logging and process tracking)
+        timeout_manager: Optional timeout manager instance
+        
+    Returns:
+        Decorator function
+    """
+    if timeout_manager is None:
+        timeout_manager = MCPToolTimeoutManager()
+    
+    def decorator(func: Callable[..., Awaitable[Any]]) -> Callable[..., Awaitable[Any]]:
+        @functools.wraps(func)
+        async def wrapper(ctx: MCPContext, **params: Any) -> Any:
+            # Fast path for tests - skip timeout logic
+            if os.getenv("HANZO_MCP_FAST_TESTS") == "1":
+                return await func(ctx, **params)
+            
+            # Get tool-specific timeout
+            tool_timeout = timeout_manager._get_timeout_for_tool(tool_name)
+            
+            # Create task for the tool execution
+            tool_task = asyncio.create_task(func(ctx, **params))
+            
+            try:
+                # Wait for completion with timeout
+                result = await asyncio.wait_for(tool_task, timeout=tool_timeout)
+                return result
+                
+            except asyncio.TimeoutError:
+                # Tool timed out - background it
+                process_id = f"{tool_name}_{uuid.uuid4().hex[:8]}"
+                log_file = timeout_manager.process_manager.create_log_file(process_id)
+                
+                # Start background execution
+                asyncio.create_task(
+                    timeout_manager._background_tool_execution(
+                        func, tool_name, ctx, process_id, log_file, **params
+                    )
+                )
+                
+                # Return backgrounding message
+                timeout_formatted = format_timeout(tool_timeout)
+                return (
+                    f"Operation automatically backgrounded after {timeout_formatted}\\n"
+                    f"Process ID: {process_id}\\n"
+                    f"Log file: {log_file}\\n\\n"
+                    f"Use 'process --action logs --id {process_id}' to view results\\n"
+                    f"Use 'process --action kill --id {process_id}' to cancel\\n\\n"
+                    f"The {tool_name} operation is continuing in the background..."
+                )
+                
+        return wrapper
+    return decorator
+
+
+# Global timeout manager instance
+_global_timeout_manager = None
+
+
+def get_global_timeout_manager() -> MCPToolTimeoutManager:
+    """Get the global timeout manager instance.
+    
+    Returns:
+        Global timeout manager
+    """
+    global _global_timeout_manager
+    if _global_timeout_manager is None:
+        _global_timeout_manager = MCPToolTimeoutManager()
+    return _global_timeout_manager
+
+
+def set_global_timeout(timeout_seconds: float) -> None:
+    """Set the global timeout for all MCP tools.
+    
+    Args:
+        timeout_seconds: Timeout in seconds
+    """
+    manager = get_global_timeout_manager()
+    manager.timeout = timeout_seconds
+
+
+def set_tool_timeout(tool_name: str, timeout_seconds: float) -> None:
+    """Set timeout for a specific tool via environment variable.
+    
+    Args:
+        tool_name: Name of the tool
+        timeout_seconds: Timeout in seconds
+    """
+    env_var = f"HANZO_MCP_{tool_name.upper()}_TIMEOUT"
+    os.environ[env_var] = str(timeout_seconds)
+
+
+# Convenience decorator using global manager
+def auto_timeout(tool_name: str):
+    """Convenience decorator using the global timeout manager.
+    
+    Args:
+        tool_name: Name of the tool
+        
+    Returns:
+        Decorator function
+    """
+    return with_auto_timeout(tool_name, get_global_timeout_manager())

hanzo_mcp/tools/common/base.py

@@ -11,6 +11,8 @@ from typing import Any, Callable, final
 from collections.abc import Awaitable
 
 from mcp.server import FastMCP
+
+from hanzo_mcp.tools.common.auto_timeout import auto_timeout
 from mcp.server.fastmcp import Context as MCPContext
 
 from hanzo_mcp.tools.common.validation import (
@@ -88,6 +90,8 @@ class BaseTool(ABC):
         pass
 
     @abstractmethod
+    @auto_timeout("base")
+
     async def call(self, ctx: MCPContext, **params: Any) -> Any:
         """Execute the tool with the given parameters.
 

hanzo_mcp/tools/common/batch_tool.py

@@ -9,6 +9,8 @@ from typing import Any, Unpack, Annotated, TypedDict, final, override
 
 from pydantic import Field
 from mcp.server import FastMCP
+
+from hanzo_mcp.tools.common.auto_timeout import auto_timeout
 from mcp.server.fastmcp import Context as MCPContext
 
 from hanzo_mcp.tools.common.base import BaseTool
@@ -154,6 +156,9 @@ Not available: think,write,edit,multi_edit,notebook_edit
         self.tools = tools
 
     @override
+    @auto_timeout("batch")
+
+
     async def call(
         self,
         ctx: MCPContext,

hanzo_mcp/tools/common/config_tool.py

@@ -5,6 +5,8 @@ from typing import Any, Dict, Unpack, Optional, TypedDict, final
 
 from mcp.server.fastmcp import Context as MCPContext
 
+from hanzo_mcp.tools.common.auto_timeout import auto_timeout
+
 from hanzo_mcp.config.settings import (
     ProjectConfig,
     MCPServerConfig,
@@ -62,6 +64,9 @@ Perfect for AI-driven configuration where users can say things like:
 
 Automatically detects projects based on LLM.md files and manages .hanzo/ directories."""
 
+    @auto_timeout("config")
+
+
     async def call(
         self,
         ctx: MCPContext,

hanzo_mcp/tools/common/critic_tool.py

@@ -7,6 +7,8 @@ from typing import Unpack, Annotated, TypedDict, final, override
 
 from pydantic import Field
 from mcp.server import FastMCP
+
+from hanzo_mcp.tools.common.auto_timeout import auto_timeout
 from mcp.server.fastmcp import Context as MCPContext
 
 from hanzo_mcp.tools.common.base import BaseTool
@@ -131,6 +133,9 @@ Recommendations:
         pass
 
     @override
+    @auto_timeout("critic")
+
+
     async def call(
         self,
         ctx: MCPContext,

hanzo_mcp/tools/common/paginated_base.py

@@ -9,6 +9,8 @@ from typing import Any, Dict, Union
 
 from mcp.server.fastmcp import Context as MCPContext
 
+from hanzo_mcp.tools.common.auto_timeout import auto_timeout
+
 from hanzo_mcp.tools.common.base import BaseTool, handle_connection_errors
 from hanzo_mcp.tools.common.pagination import CursorManager
 from hanzo_mcp.tools.common.paginated_response import paginate_if_needed
@@ -44,6 +46,8 @@ class PaginatedBaseTool(BaseTool):
         pass
 
     @handle_connection_errors
+    @auto_timeout("paginated_base")
+
     async def call(self, ctx: MCPContext, **params: Any) -> Union[str, Dict[str, Any]]:
         """Execute the tool with automatic pagination support.
 

hanzo_mcp/tools/common/stats.py

@@ -7,6 +7,8 @@ from datetime import datetime
 import psutil
 from mcp.server.fastmcp import Context as MCPContext
 
+from hanzo_mcp.tools.common.auto_timeout import auto_timeout
+
 from hanzo_mcp.tools.common.base import BaseTool
 from hanzo_mcp.tools.mcp.mcp_add import McpAddTool
 from hanzo_mcp.tools.common.context import create_tool_context
@@ -57,6 +59,9 @@ Example:
 """
 
     @override
+    @auto_timeout("stats")
+
+
     async def call(
         self,
         ctx: MCPContext,

hanzo_mcp/tools/common/thinking_tool.py

@@ -7,6 +7,8 @@ from typing import Unpack, Annotated, TypedDict, final, override
 
 from pydantic import Field
 from mcp.server import FastMCP
+
+from hanzo_mcp.tools.common.auto_timeout import auto_timeout
 from mcp.server.fastmcp import Context as MCPContext
 
 from hanzo_mcp.tools.common.base import BaseTool
@@ -93,6 +95,9 @@ Feature Implementation Planning
         pass
 
     @override
+    @auto_timeout("thinking")
+
+
     async def call(
         self,
         ctx: MCPContext,

hanzo_mcp/tools/common/timeout_parser.py

@@ -0,0 +1,103 @@
+"""Human-readable timeout parsing utilities."""
+
+import re
+from typing import Union
+
+
+def parse_timeout(timeout_str: Union[str, int, float]) -> float:
+    """Parse timeout from human-readable string or numeric value.
+
+    Supports formats like:
+    - "2min", "5m", "120s", "30sec", "1.5h", "0.5hr"
+    - 120 (seconds as number)
+    - "120" (seconds as string)
+
+    Args:
+        timeout_str: Timeout value as string or number
+
+    Returns:
+        Timeout in seconds as float
+
+    Raises:
+        ValueError: If format is not recognized
+    """
+    if isinstance(timeout_str, (int, float)):
+        return float(timeout_str)
+
+    if isinstance(timeout_str, str):
+        # Handle pure numeric strings
+        try:
+            return float(timeout_str)
+        except ValueError:
+            pass
+
+        # Handle human-readable formats
+        timeout_str = timeout_str.lower().strip()
+
+        # Regex patterns for different time units
+        patterns = [
+            # Hours: 1h, 1.5hr, 2hour, 3hours
+            (r'^(\d*\.?\d+)\s*h(?:r|our|ours)?$', 3600),
+            # Minutes: 2m, 5min, 10mins, 1.5minute
+            (r'^(\d*\.?\d+)\s*m(?:in|ins|inute|inutes)?$', 60),
+            # Seconds: 30s, 120sec, 45secs, 60second, 90seconds
+            (r'^(\d*\.?\d+)\s*s(?:ec|ecs|econd|econds)?$', 1),
+        ]
+
+        for pattern, multiplier in patterns:
+            match = re.match(pattern, timeout_str)
+            if match:
+                value = float(match.group(1))
+                return value * multiplier
+
+        # If no pattern matches, raise error
+        raise ValueError(
+            f"Invalid timeout format: '{timeout_str}'. "
+            f"Supported formats: 2min, 5m, 120s, 30sec, 1.5h, 0.5hr, or numeric seconds."
+        )
+
+    raise ValueError(f"Unsupported timeout type: {type(timeout_str)}")
+
+
+def format_timeout(seconds: float) -> str:
+    """Format timeout seconds into human-readable string.
+
+    Args:
+        seconds: Timeout in seconds
+
+    Returns:
+        Human-readable string like "2m", "90s", "1.5h"
+    """
+    if seconds >= 3600:  # >= 1 hour
+        hours = seconds / 3600
+        if hours.is_integer():
+            return f"{int(hours)}h"
+        else:
+            return f"{hours:.1f}h"
+    elif seconds >= 60:  # >= 1 minute
+        minutes = seconds / 60
+        if minutes.is_integer():
+            return f"{int(minutes)}m"
+        else:
+            return f"{minutes:.1f}m"
+    else:  # < 1 minute
+        if seconds.is_integer():
+            return f"{int(seconds)}s"
+        else:
+            return f"{seconds:.1f}s"
+
+
+# Test the parser
+if __name__ == "__main__":
+    test_cases = [
+        "2min", "5m", "120s", "30sec", "1.5h", "0.5hr",
+        "90", 120, 3600.0, "1hour", "2hours", "30seconds"
+    ]
+
+    for case in test_cases:
+        try:
+            result = parse_timeout(case)
+            formatted = format_timeout(result)
+            print(f"{case} -> {result}s ({formatted})")
+        except ValueError as e:
+            print(f"{case} -> ERROR: {e}")

hanzo_mcp/tools/common/tool_disable.py

@@ -5,6 +5,8 @@ from typing import Unpack, Annotated, TypedDict, final, override
 from pydantic import Field
 from mcp.server.fastmcp import Context as MCPContext
 
+from hanzo_mcp.tools.common.auto_timeout import auto_timeout
+
 from hanzo_mcp.tools.common.base import BaseTool
 from hanzo_mcp.tools.common.context import create_tool_context
 from hanzo_mcp.tools.common.tool_enable import ToolEnableTool
@@ -72,6 +74,9 @@ Use 'tool_enable' to re-enable disabled tools.
 """
 
     @override
+    @auto_timeout("tool_disable")
+
+
     async def call(
         self,
         ctx: MCPContext,

hanzo_mcp/tools/common/tool_enable.py

@@ -7,6 +7,8 @@ from pathlib import Path
 from pydantic import Field
 from mcp.server.fastmcp import Context as MCPContext
 
+from hanzo_mcp.tools.common.auto_timeout import auto_timeout
+
 from hanzo_mcp.tools.common.base import BaseTool
 from hanzo_mcp.tools.common.context import create_tool_context
 
@@ -119,6 +121,9 @@ Use 'tool_list' to see all available tools and their status.
 """
 
     @override
+    @auto_timeout("tool_enable")
+
+
     async def call(
         self,
         ctx: MCPContext,

hanzo_mcp/tools/common/tool_list.py

@@ -5,6 +5,8 @@ from typing import Unpack, Optional, Annotated, TypedDict, final, override
 from pydantic import Field
 from mcp.server.fastmcp import Context as MCPContext
 
+from hanzo_mcp.tools.common.auto_timeout import auto_timeout
+
 from hanzo_mcp.tools.common.base import BaseTool
 from hanzo_mcp.tools.common.context import create_tool_context
 from hanzo_mcp.tools.common.tool_enable import ToolEnableTool
@@ -158,6 +160,9 @@ Use 'tool_enable' and 'tool_disable' to change tool status.
 """
 
     @override
+    @auto_timeout("tool_list")
+
+
     async def call(
         self,
         ctx: MCPContext,

hanzo_mcp/tools/config/config_tool.py

@@ -9,6 +9,8 @@ from pathlib import Path
 from pydantic import Field
 from mcp.server.fastmcp import Context as MCPContext
 
+from hanzo_mcp.tools.common.auto_timeout import auto_timeout
+
 from hanzo_mcp.config import load_settings, save_settings
 from hanzo_mcp.tools.common.base import BaseTool
 from hanzo_mcp.tools.common.permissions import PermissionManager
@@ -104,6 +106,9 @@ config --action list
 config --action toggle index.scope --path ./project"""
 
     @override
+    @auto_timeout("config")
+
+
     async def call(
         self,
         ctx: MCPContext,

hanzo_mcp/tools/config/mode_tool.py

@@ -3,6 +3,8 @@
 from typing import Optional, override
 
 from mcp.server import FastMCP
+
+from hanzo_mcp.tools.common.auto_timeout import auto_timeout
 from mcp.server.fastmcp import Context as MCPContext
 
 from hanzo_mcp.tools.common.base import BaseTool
@@ -310,6 +312,9 @@ mode --action current"""
             """Handle mode tool calls."""
             return await tool_self.run(ctx, action=action, name=name)
 
+    @auto_timeout("mode")
+
+
     async def call(self, ctx: MCPContext, **params) -> str:
         """Call the tool with arguments."""
         return await self.run(ctx, action=params.get("action", "list"), name=params.get("name"))

hanzo_mcp/tools/database/graph.py

@@ -15,6 +15,8 @@ from typing import (
 from pydantic import Field
 from mcp.server.fastmcp import Context as MCPContext
 
+from hanzo_mcp.tools.common.auto_timeout import auto_timeout
+
 from hanzo_mcp.tools.common.base import BaseTool
 from hanzo_mcp.tools.common.permissions import PermissionManager
 from hanzo_mcp.tools.database.database_manager import DatabaseManager
@@ -146,6 +148,9 @@ graph --action search --pattern "John" --node-type User
 """
 
     @override
+    @auto_timeout("graph")
+
+
     async def call(
         self,
         ctx: MCPContext,

hanzo_mcp/tools/database/graph_add.py

@@ -6,6 +6,8 @@ from typing import Unpack, Optional, Annotated, TypedDict, final, override
 from pydantic import Field
 from mcp.server.fastmcp import Context as MCPContext
 
+from hanzo_mcp.tools.common.auto_timeout import auto_timeout
+
 from hanzo_mcp.tools.common.base import BaseTool
 from hanzo_mcp.tools.common.context import create_tool_context
 from hanzo_mcp.tools.common.permissions import PermissionManager
@@ -137,6 +139,9 @@ Examples:
 """
 
     @override
+    @auto_timeout("graph_add")
+
+
     async def call(
         self,
         ctx: MCPContext,

hanzo_mcp/tools/database/graph_query.py

@@ -15,6 +15,8 @@ from collections import deque
 from pydantic import Field
 from mcp.server.fastmcp import Context as MCPContext
 
+from hanzo_mcp.tools.common.auto_timeout import auto_timeout
+
 from hanzo_mcp.tools.common.base import BaseTool
 from hanzo_mcp.tools.common.context import create_tool_context
 from hanzo_mcp.tools.common.permissions import PermissionManager
@@ -147,6 +149,9 @@ Examples:
 """
 
     @override
+    @auto_timeout("graph_query")
+
+
     async def call(
         self,
         ctx: MCPContext,

hanzo_mcp/tools/database/graph_remove.py

@@ -5,6 +5,8 @@ from typing import Unpack, Optional, Annotated, TypedDict, final, override
 from pydantic import Field
 from mcp.server.fastmcp import Context as MCPContext
 
+from hanzo_mcp.tools.common.auto_timeout import auto_timeout
+
 from hanzo_mcp.tools.common.base import BaseTool
 from hanzo_mcp.tools.common.context import create_tool_context
 from hanzo_mcp.tools.common.permissions import PermissionManager
@@ -116,6 +118,9 @@ Examples:
 """
 
     @override
+    @auto_timeout("graph_remove")
+
+
     async def call(
         self,
         ctx: MCPContext,

hanzo_mcp/tools/database/graph_search.py

@@ -7,6 +7,8 @@ from typing import Unpack, Optional, Annotated, TypedDict, final, override
 from pydantic import Field
 from mcp.server.fastmcp import Context as MCPContext
 
+from hanzo_mcp.tools.common.auto_timeout import auto_timeout
+
 from hanzo_mcp.tools.common.base import BaseTool
 from hanzo_mcp.tools.common.context import create_tool_context
 from hanzo_mcp.tools.common.permissions import PermissionManager
@@ -117,6 +119,9 @@ Examples:
 """
 
     @override
+    @auto_timeout("graph_search")
+
+
     async def call(
         self,
         ctx: MCPContext,

hanzo_mcp/tools/database/graph_stats.py

@@ -7,6 +7,8 @@ from collections import defaultdict
 from pydantic import Field
 from mcp.server.fastmcp import Context as MCPContext
 
+from hanzo_mcp.tools.common.auto_timeout import auto_timeout
+
 from hanzo_mcp.tools.common.base import BaseTool
 from hanzo_mcp.tools.common.context import create_tool_context
 from hanzo_mcp.tools.common.permissions import PermissionManager
@@ -97,6 +99,9 @@ Examples:
 """
 
     @override
+    @auto_timeout("graph_stats")
+
+
     async def call(
         self,
         ctx: MCPContext,