hanzo-mcp 0.1.25__py3-none-any.whl → 0.1.30__py3-none-any.whl

hanzo_mcp/tools/common/__init__.py

@@ -1 +1,18 @@
 """Common utilities for Hanzo MCP tools."""
+
+from mcp.server.fastmcp import FastMCP
+
+from hanzo_mcp.tools.common.base import ToolRegistry
+from hanzo_mcp.tools.common.thinking_tool import ThinkingTool
+
+
+def register_thinking_tool(
+    mcp_server: FastMCP,
+) -> None:
+    """Register all thinking tools with the MCP server. 
+    
+    Args:
+        mcp_server: The FastMCP server instance
+    """
+    thinking_tool = ThinkingTool()
+    ToolRegistry.register_tool(mcp_server, thinking_tool)

hanzo_mcp/tools/common/base.py

@@ -0,0 +1,216 @@
+"""Base classes for Hanzo MCP 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
+behavior and provide a foundation for tool registration and management.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, final
+
+from mcp.server.fastmcp import Context as MCPContext
+from mcp.server.fastmcp import FastMCP
+
+from hanzo_mcp.tools.common.context import DocumentContext 
+from hanzo_mcp.tools.common.permissions import PermissionManager
+from hanzo_mcp.tools.common.validation import ValidationResult, validate_path_parameter
+
+
+class BaseTool(ABC):
+    """Abstract base class for all Hanzo MCP tools.
+    
+    This class defines the core interface that all tools must implement, ensuring
+    consistency in how tools are registered, documented, and called.
+    """
+    
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Get the tool name.
+        
+        Returns:
+            The tool name as it will appear in the MCP server
+        """
+        pass
+        
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """Get the tool description.
+        
+        Returns:
+            Detailed description of the tool's purpose and usage
+        """
+        pass
+        
+    @property
+    def mcp_description(self) -> str:
+        """Get the complete tool description for MCP.
+        
+        This method combines the tool description with parameter descriptions.
+        
+        Returns:
+            Complete tool description including parameter details
+        """
+        # Start with the base description
+        desc = self.description.strip()
+        
+        # Add parameter descriptions section if there are parameters
+        if self.parameters and "properties" in self.parameters:
+            # Add Args section header
+            desc += "\n\nArgs:"
+            
+            # Get the properties dictionary
+            properties = self.parameters["properties"]
+            
+            # Add each parameter description
+            for param_name, param_info in properties.items():
+                # Get the title if available, otherwise use the parameter name and capitalize it
+                if "title" in param_info:
+                    title = param_info["title"]
+                else:
+                    # Convert snake_case to Title Case
+                    title = " ".join(word.capitalize() for word in param_name.split("_"))
+                
+                # Check if the parameter is required
+                required = param_name in self.required
+                required_text = "" if required else " (optional)"
+                
+                # Add the parameter description line
+                desc += f"\n    {param_name}: {title}{required_text}"
+        
+        # Add Returns section
+        desc += "\n\nReturns:\n    "
+        
+        # Add a generic return description based on the tool's purpose
+        # This could be enhanced with more specific return descriptions
+        if "read" in self.name or "get" in self.name or "search" in self.name:
+            desc += f"{self.name.replace('_', ' ').capitalize()} results"
+        elif "write" in self.name or "edit" in self.name or "create" in self.name:
+            desc += "Result of the operation"
+        else:
+            desc += "Tool execution results"
+            
+        return desc
+        
+    @property
+    @abstractmethod
+    def parameters(self) -> dict[str, Any]:
+        """Get the parameter specifications for the tool.
+        
+        Returns:
+            Dictionary containing parameter specifications in JSON Schema format
+        """
+        pass
+        
+    @property
+    @abstractmethod
+    def required(self) -> list[str]:
+        """Get the list of required parameter names.
+        
+        Returns:
+            List of parameter names that are required for the tool
+        """
+        pass
+        
+    @abstractmethod
+    async def call(self, ctx: MCPContext, **params: Any) -> str:
+        """Execute the tool with the given parameters.
+        
+        Args:
+            ctx: MCP context for the tool call
+            **params: Tool parameters provided by the caller
+            
+        Returns:
+            Tool execution result as a string
+        """
+        pass
+        
+    @abstractmethod
+    def register(self, mcp_server: FastMCP) -> None:
+        """Register this tool with the MCP server.
+        
+        This method must be implemented by each tool class to create a wrapper function
+        with explicitly defined parameters that calls this tool's call method.
+        The wrapper function is then registered with the MCP server.
+        
+        Args:
+            mcp_server: The FastMCP server instance
+        """
+        pass
+
+
+class FileSystemTool(BaseTool,ABC):
+    """Base class for filesystem-related tools.
+    
+    Provides common functionality for working with files and directories,
+    including permission checking and path validation.
+    """
+    
+    def __init__(
+        self, 
+        document_context: DocumentContext, 
+        permission_manager: PermissionManager
+    ) -> None:
+        """Initialize filesystem tool.
+        
+        Args:
+            document_context: Document context for tracking file contents
+            permission_manager: Permission manager for access control
+        """
+        self.document_context:DocumentContext = document_context
+        self.permission_manager:PermissionManager = permission_manager
+        
+    def validate_path(self, path: str, param_name: str = "path") -> ValidationResult:
+        """Validate a path parameter.
+        
+        Args:
+            path: Path to validate
+            param_name: Name of the parameter (for error messages)
+            
+        Returns:
+            Validation result containing validation status and error message if any
+        """
+        return validate_path_parameter(path, param_name)
+        
+    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
+        """
+        return self.permission_manager.is_path_allowed(path)
+
+
+@final
+class ToolRegistry:
+    """Registry for Hanzo MCP tools.
+    
+    Provides functionality for registering tool implementations with an MCP server,
+    handling the conversion between tool classes and MCP tool functions.
+    """
+    
+    @staticmethod
+    def register_tool(mcp_server: FastMCP, tool: BaseTool) -> None:
+        """Register a tool with the MCP server.
+        
+        Args:
+            mcp_server: The FastMCP server instance
+            tool: The tool to register
+        """
+        # Use the tool's register method which handles all the details
+        tool.register(mcp_server)
+            
+    @staticmethod
+    def register_tools(mcp_server: FastMCP, tools: list[BaseTool]) -> None:
+        """Register multiple tools with the MCP server.
+        
+        Args:
+            mcp_server: The FastMCP server instance
+            tools: List of tools to register
+        """
+        for tool in tools:
+            ToolRegistry.register_tool(mcp_server, tool)

hanzo_mcp/tools/common/context.py

@@ -1,7 +1,7 @@
 """Enhanced Context for Hanzo MCP tools.
 
 This module provides an enhanced Context class that wraps the MCP Context
-and adds additional functionality specific to Claude Code tools.
+and adds additional functionality specific to Hanzo tools.
 """
 
 import json
@@ -179,7 +179,9 @@ class DocumentContext:
         Args:
             path: The path to allow
         """
-        resolved_path: Path = Path(path).resolve()
+        # Expand user path (e.g., ~/ or $HOME)
+        expanded_path = os.path.expanduser(path)
+        resolved_path: Path = Path(expanded_path).resolve()
         self.allowed_paths.add(resolved_path)
 
     def is_path_allowed(self, path: str) -> bool:
@@ -191,7 +193,9 @@ class DocumentContext:
         Returns:
             True if the path is allowed, False otherwise
         """
-        resolved_path: Path = Path(path).resolve()
+        # Expand user path (e.g., ~/ or $HOME)
+        expanded_path = os.path.expanduser(path)
+        resolved_path: Path = Path(expanded_path).resolve()
 
         # Check if the path is within any allowed path
         for allowed_path in self.allowed_paths:

hanzo_mcp/tools/common/permissions.py

@@ -11,65 +11,29 @@ T = TypeVar("T")
 P = TypeVar("P")
 
 
-def normalize_path(path: str) -> Path:
-    """Normalize a path with proper user directory expansion.
-
-    This utility function handles path normalization with proper handling of
-    tilde (~) for home directory expansion and ensures consistent path handling
-    across the application.
-
-    Args:
-        path: The path to normalize (can include ~ for home directory)
-
-    Returns:
-        A normalized Path object with user directories expanded and resolved to
-        its absolute canonical form.
-    """
-    # Expand the user directory, handling the tilde (~) if present.
-    expanded_path = os.path.expanduser(path)
-    # Resolve the expanded path to its absolute form.
-    resolved_path = Path(expanded_path).resolve()
-    return resolved_path
-
-
 @final
 class PermissionManager:
-    """Manages permissions for file and command operations.
-
-    This class is responsible for tracking allowed file system paths as well as
-    paths and patterns that should be excluded from permitted operations.
-    """
+    """Manages permissions for file and command operations."""
 
     def __init__(self) -> None:
-        """Initialize the permission manager with default allowed and excluded paths.
-
-        Allowed paths are those where operations (read, write, execute, etc.) are permitted,
-        while excluded paths and patterns represent paths and file patterns that are sensitive
-        and should be disallowed.
-        """
-        # Allowed paths: operations are permitted on these paths.
+        """Initialize the permission manager."""
+        # Allowed paths
         self.allowed_paths: set[Path] = set(
             [Path("/tmp").resolve(), Path("/var").resolve()]
         )
 
-        # Excluded paths: specific paths that are explicitly disallowed.
+        # Excluded paths
         self.excluded_paths: set[Path] = set()
-
-        # Excluded patterns: patterns for sensitive directories and file names.
         self.excluded_patterns: list[str] = []
 
-        # Add default exclusions for sensitive files and directories.
+        # Default excluded patterns
         self._add_default_exclusions()
 
     def _add_default_exclusions(self) -> None:
-        """Add default exclusions for sensitive files and directories.
-
-        This method populates the excluded_patterns list with common sensitive
-        directories (e.g., .ssh, .gnupg) and file patterns (e.g., *.key, *.log)
-        that should be excluded from allowed operations.
-        """
-        # Sensitive directories (Note: .git is allowed by default)
+        """Add default exclusions for sensitive files and directories."""
+        # Sensitive directories
         sensitive_dirs: list[str] = [
+            # ".git" is now allowed by default
             ".ssh",
             ".gnupg",
             ".config",
@@ -100,64 +64,63 @@ class PermissionManager:
         self.excluded_patterns.extend(sensitive_patterns)
 
     def add_allowed_path(self, path: str) -> None:
-        """Add a new path to the allowed paths.
+        """Add a path to the allowed paths.
 
         Args:
-            path: The file system path to add to the allowed list.
+            path: The path to allow
         """
-        resolved_path: Path = normalize_path(path)
+        # Expand user path (e.g., ~/ or $HOME)
+        expanded_path = os.path.expanduser(path)
+        resolved_path: Path = Path(expanded_path).resolve()
         self.allowed_paths.add(resolved_path)
 
     def remove_allowed_path(self, path: str) -> None:
         """Remove a path from the allowed paths.
 
         Args:
-            path: The file system path to remove from the allowed list.
+            path: The path to remove
         """
-        resolved_path: Path = normalize_path(path)
+        resolved_path: Path = Path(path).resolve()
         if resolved_path in self.allowed_paths:
             self.allowed_paths.remove(resolved_path)
 
     def exclude_path(self, path: str) -> None:
-        """Add a path to the exclusion list.
+        """Exclude a path from allowed operations.
 
         Args:
-            path: The file system path to explicitly exclude from operations.
+            path: The path to exclude
         """
-        resolved_path: Path = normalize_path(path)
+        resolved_path: Path = Path(path).resolve()
         self.excluded_paths.add(resolved_path)
 
     def add_exclusion_pattern(self, pattern: str) -> None:
-        """Add a new exclusion pattern.
+        """Add an exclusion pattern.
 
         Args:
-            pattern: A string pattern that matches file or directory names to exclude.
+            pattern: The pattern to exclude
         """
         self.excluded_patterns.append(pattern)
 
     def is_path_allowed(self, path: str) -> bool:
-        """Determine if a given path is allowed for operations.
-
-        The method normalizes the input path and then checks it against the list
-        of excluded paths and patterns. If the path is not excluded and is a
-        subpath of one of the allowed base paths, the method returns True.
+        """Check if a path is allowed.
 
         Args:
-            path: The file system path to check.
+            path: The path to check
 
         Returns:
-            True if the path is allowed for operations, False otherwise.
+            True if the path is allowed, False otherwise
         """
-        resolved_path: Path = normalize_path(path)
+        # Expand user path (e.g., ~/ or $HOME)
+        expanded_path = os.path.expanduser(path)
+        resolved_path: Path = Path(expanded_path).resolve()
 
-        # First, check if the path matches any excluded paths or patterns.
+        # Check exclusions first
         if self._is_path_excluded(resolved_path):
             return False
 
-        # Check if the normalized path is within any allowed path.
+        # Check if the path is within any allowed path
         for allowed_path in self.allowed_paths:
             try:
-                # relative_to will succeed if resolved_path is a subpath of allowed_path.
                 resolved_path.relative_to(allowed_path)
                 return True
             except ValueError:
@@ -166,74 +129,63 @@ class PermissionManager:
         return False
 
     def _is_path_excluded(self, path: Path) -> bool:
-        """Determine if a normalized path should be excluded.
-
-        The method checks two conditions:
-          1. If the path exactly matches an entry in the excluded_paths set.
-          2. If the path string contains any of the excluded patterns, either as a
-             suffix for wildcard patterns (e.g., "*.log") or as an exact match
-             within any of the path's components.
+        """Check if a path is excluded.
 
         Args:
-            path: The normalized path to check.
+            path: The path to check
 
         Returns:
-            True if the path is excluded, False otherwise.
+            True if the path is excluded, False otherwise
         """
-        # Direct match: Check if the path is in the explicitly excluded paths set.
+
+        # Check exact excluded paths
         if path in self.excluded_paths:
             return True
 
-        # Convert the path to a string for pattern matching.
+        # Check excluded patterns
         path_str: str = str(path)
 
-        # Split the path into its individual components (directories and file name).
+        # Get path parts to check for exact directory/file name matches
         path_parts = path_str.split(os.sep)
 
-        # Iterate over each exclusion pattern to see if it matches.
         for pattern in self.excluded_patterns:
-            # If the pattern starts with a wildcard, perform a suffix match.
+            # Handle wildcard patterns (e.g., "*.log")
             if pattern.startswith("*"):
                 if path_str.endswith(pattern[1:]):
                     return True
             else:
-                # For non-wildcard patterns, check if any path component exactly matches the pattern.
+                # For non-wildcard patterns, check if any path component matches exactly
                 if pattern in path_parts:
                     return True
 
         return False
 
     def to_json(self) -> str:
-        """Serialize the permission manager's configuration to a JSON string.
-
-        The JSON representation includes the allowed paths, excluded paths, and
-        excluded patterns, which can be used to restore the configuration later.
+        """Convert the permission manager to a JSON string.
 
         Returns:
-            A JSON string representing the current state of the permission manager.
+            A JSON string representation of the permission manager
         """
         data: dict[str, Any] = {
             "allowed_paths": [str(p) for p in self.allowed_paths],
             "excluded_paths": [str(p) for p in self.excluded_paths],
             "excluded_patterns": self.excluded_patterns,
         }
+
         return json.dumps(data)
 
     @classmethod
     def from_json(cls, json_str: str) -> "PermissionManager":
-        """Create a PermissionManager instance from a JSON string.
-
-        The JSON string should represent a configuration with allowed paths,
-        excluded paths, and exclusion patterns. This method rehydrates the state
-        accordingly.
+        """Create a permission manager from a JSON string.
 
         Args:
-            json_str: The JSON string containing the permission manager configuration.
+            json_str: The JSON string
 
         Returns:
-            A new PermissionManager instance with configuration loaded from the JSON string.
+            A new PermissionManager instance
         """
         data: dict[str, Any] = json.loads(json_str)
+
         manager = cls()
 
         for path in data.get("allowed_paths", []):
@@ -243,16 +195,12 @@ class PermissionManager:
             manager.exclude_path(path)
 
         manager.excluded_patterns = data.get("excluded_patterns", [])
+
         return manager
 
 
 class PermissibleOperation:
-    """A decorator for operations that require permission checks.
-
-    This decorator uses a PermissionManager instance to enforce that a given
-    operation (e.g., read, write, execute) is permitted on a provided file system
-    path before allowing the decorated function to execute.
-    """
+    """A decorator for operations that require permission."""
 
     def __init__(
         self,
@@ -260,54 +208,50 @@ class PermissibleOperation:
         operation: str,
         get_path_fn: Callable[[list[Any], dict[str, Any]], str] | None = None,
     ) -> None:
-        """Initialize the PermissibleOperation decorator.
+        """Initialize the permissible operation.
 
         Args:
-            permission_manager: The PermissionManager instance used for permission checks.
-            operation: A string representing the operation type (e.g., 'read', 'write').
-            get_path_fn: Optional function to extract the file system path from the function's
-                         arguments. If not provided, defaults to using the first positional argument
-                         or the first value from keyword arguments.
+            permission_manager: The permission manager
+            operation: The operation type (read, write, execute, etc.)
+            get_path_fn: Optional function to extract the path from args and kwargs
         """
         self.permission_manager: PermissionManager = permission_manager
         self.operation: str = operation
-        self.get_path_fn: Callable[[list[Any], dict[str, Any]], str] | None = get_path_fn
+        self.get_path_fn: Callable[[list[Any], dict[str, Any]], str] | None = (
+            get_path_fn
+        )
 
     def __call__(
         self, func: Callable[..., Awaitable[T]]
     ) -> Callable[..., Awaitable[T]]:
-        """Decorate the function to enforce permission checks before execution.
-
-        This method wraps the original asynchronous function, extracting a file system path
-        from its arguments and using the PermissionManager to verify if the specified operation
-        is allowed on that path. If permission is denied, a PermissionError is raised.
+        """Decorate the function.
 
         Args:
-            func: The asynchronous function to decorate.
+            func: The function to decorate
 
         Returns:
-            An asynchronous function that includes permission checks prior to calling the original function.
+            The decorated function
         """
+
         async def wrapper(*args: Any, **kwargs: Any) -> T:
-            # Extract the file system path using the provided get_path_fn if available.
+            # Extract the path
             if self.get_path_fn:
+                # Pass args as a list and kwargs as a dict to the path function
                 path = self.get_path_fn(list(args), kwargs)
             else:
-                # Default extraction: use the first positional argument if available,
-                # otherwise use the first keyword argument value.
+                # Default to first argument
                 path = args[0] if args else next(iter(kwargs.values()), None)
 
-            # Ensure that the extracted path is a string.
             if not isinstance(path, str):
-                raise ValueError(f"Invalid path type: {type(path)}. Expected a string.")
+                raise ValueError(f"Invalid path type: {type(path)}")
 
-            # Check if the operation is allowed on the specified path.
+            # Check permission
             if not self.permission_manager.is_path_allowed(path):
                 raise PermissionError(
                     f"Operation '{self.operation}' not allowed for path: {path}"
                 )
 
-            # Execute the original function if the permission check passes.
+            # Call the function
             return await func(*args, **kwargs)
 
         return wrapper