hanzo-mcp 0.1.20__py3-none-any.whl

hanzo_mcp/tools/common/permissions.py

@@ -0,0 +1,253 @@
+"""Permission system for the Hanzo MCP server."""
+
+import json
+import os
+from collections.abc import Awaitable, Callable
+from pathlib import Path
+from typing import Any, TypeVar, final
+
+# Define type variables for better type annotations
+T = TypeVar("T")
+P = TypeVar("P")
+
+
+@final
+class PermissionManager:
+    """Manages permissions for file and command operations."""
+
+    def __init__(self) -> None:
+        """Initialize the permission manager."""
+        # Allowed paths
+        self.allowed_paths: set[Path] = set(
+            [Path("/tmp").resolve(), Path("/var").resolve()]
+        )
+
+        # Excluded paths
+        self.excluded_paths: set[Path] = set()
+        self.excluded_patterns: list[str] = []
+
+        # Default excluded patterns
+        self._add_default_exclusions()
+
+    def _add_default_exclusions(self) -> None:
+        """Add default exclusions for sensitive files and directories."""
+        # Sensitive directories
+        sensitive_dirs: list[str] = [
+            # ".git" is now allowed by default
+            ".ssh",
+            ".gnupg",
+            ".config",
+            "node_modules",
+            "__pycache__",
+            ".venv",
+            "venv",
+            "env",
+            ".idea",
+            ".vscode",
+            ".DS_Store",
+        ]
+        self.excluded_patterns.extend(sensitive_dirs)
+
+        # Sensitive file patterns
+        sensitive_patterns: list[str] = [
+            ".env",
+            "*.key",
+            "*.pem",
+            "*.crt",
+            "*password*",
+            "*secret*",
+            "*.sqlite",
+            "*.db",
+            "*.sqlite3",
+            "*.log",
+        ]
+        self.excluded_patterns.extend(sensitive_patterns)
+
+    def add_allowed_path(self, path: str) -> None:
+        """Add a path to the allowed paths.
+
+        Args:
+            path: The path to allow
+        """
+        resolved_path: Path = Path(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 path to remove
+        """
+        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:
+        """Exclude a path from allowed operations.
+
+        Args:
+            path: The path to exclude
+        """
+        resolved_path: Path = Path(path).resolve()
+        self.excluded_paths.add(resolved_path)
+
+    def add_exclusion_pattern(self, pattern: str) -> None:
+        """Add an exclusion pattern.
+
+        Args:
+            pattern: The pattern to exclude
+        """
+        self.excluded_patterns.append(pattern)
+
+    def is_path_allowed(self, path: str) -> bool:
+        """Check if a path is allowed.
+
+        Args:
+            path: The path to check
+
+        Returns:
+            True if the path is allowed, False otherwise
+        """
+        resolved_path: Path = Path(path).resolve()
+
+        # Check exclusions first
+        if self._is_path_excluded(resolved_path):
+            return False
+
+        # Check if the path is within any allowed path
+        for allowed_path in self.allowed_paths:
+            try:
+                resolved_path.relative_to(allowed_path)
+                return True
+            except ValueError:
+                continue
+
+        return False
+
+    def _is_path_excluded(self, path: Path) -> bool:
+        """Check if a path is excluded.
+
+        Args:
+            path: The path to check
+
+        Returns:
+            True if the path is excluded, False otherwise
+        """
+
+        # Check exact excluded paths
+        if path in self.excluded_paths:
+            return True
+
+        # Check excluded patterns
+        path_str: str = str(path)
+
+        # Get path parts to check for exact directory/file name matches
+        path_parts = path_str.split(os.sep)
+
+        for pattern in self.excluded_patterns:
+            # 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 matches exactly
+                if pattern in path_parts:
+                    return True
+
+        return False
+
+    def to_json(self) -> str:
+        """Convert the permission manager to a JSON string.
+
+        Returns:
+            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 permission manager from a JSON string.
+
+        Args:
+            json_str: The JSON string
+
+        Returns:
+            A new PermissionManager instance
+        """
+        data: dict[str, Any] = json.loads(json_str)
+
+        manager = cls()
+
+        for path in data.get("allowed_paths", []):
+            manager.add_allowed_path(path)
+
+        for path in data.get("excluded_paths", []):
+            manager.exclude_path(path)
+
+        manager.excluded_patterns = data.get("excluded_patterns", [])
+
+        return manager
+
+
+class PermissibleOperation:
+    """A decorator for operations that require permission."""
+
+    def __init__(
+        self,
+        permission_manager: PermissionManager,
+        operation: str,
+        get_path_fn: Callable[[list[Any], dict[str, Any]], str] | None = None,
+    ) -> None:
+        """Initialize the permissible operation.
+
+        Args:
+            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
+        )
+
+    def __call__(
+        self, func: Callable[..., Awaitable[T]]
+    ) -> Callable[..., Awaitable[T]]:
+        """Decorate the function.
+
+        Args:
+            func: The function to decorate
+
+        Returns:
+            The decorated function
+        """
+
+        async def wrapper(*args: Any, **kwargs: Any) -> T:
+            # 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 to first argument
+                path = args[0] if args else next(iter(kwargs.values()), None)
+
+            if not isinstance(path, str):
+                raise ValueError(f"Invalid path type: {type(path)}")
+
+            # Check permission
+            if not self.permission_manager.is_path_allowed(path):
+                raise PermissionError(
+                    f"Operation '{self.operation}' not allowed for path: {path}"
+                )
+
+            # Call the function
+            return await func(*args, **kwargs)
+
+        return wrapper

hanzo_mcp/tools/common/thinking_tool.py

@@ -0,0 +1,123 @@
+"""Thinking tool implementation.
+
+This module provides the ThinkingTool for Claude to engage in structured thinking.
+"""
+
+from typing import Any, final, override
+
+from mcp.server.fastmcp import Context as MCPContext
+from mcp.server.fastmcp import FastMCP
+
+from hanzo_mcp.tools.common.base import BaseTool
+from hanzo_mcp.tools.common.context import create_tool_context
+
+
+@final
+class ThinkingTool(BaseTool):
+    """Tool for Claude to engage in structured thinking."""
+    
+    @property
+    @override
+    def name(self) -> str:
+        """Get the tool name.
+        
+        Returns:
+            Tool name
+        """
+        return "think"
+        
+    @property
+    @override
+    def description(self) -> str:
+        """Get the tool description.
+        
+        Returns:
+            Tool description
+        """
+        return """Use the tool to think about something.
+
+It will not obtain new information or make any changes to the repository, but just log the thought. Use it when complex reasoning or brainstorming is needed. For example, if you explore the repo and discover the source of a bug, call this tool to brainstorm several unique ways of fixing the bug, and assess which change(s) are likely to be simplest and most effective. Alternatively, if you receive some test results, call this tool to brainstorm ways to fix the failing tests."""
+        
+    @property
+    @override
+    def parameters(self) -> dict[str, Any]:
+        """Get the parameter specifications for the tool.
+        
+        Returns:
+            Parameter specifications
+        """
+        return {
+            "properties": {
+                "thought": {
+                    "title": "Thought",
+                    "type": "string"
+                }
+            },
+            "required": ["thought"],
+            "title": "thinkArguments",
+            "type": "object"
+        }
+        
+    @property
+    @override
+    def required(self) -> list[str]:
+        """Get the list of required parameter names.
+        
+        Returns:
+            List of required parameter names
+        """
+        return ["thought"]
+        
+    def __init__(self) -> None:
+        """Initialize the thinking tool."""
+        pass
+        
+    @override
+    async def call(self, ctx: MCPContext, **params: Any) -> 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
+        thought = params.get("thought")
+        
+        # Validate required thought parameter
+        if not thought:
+            await tool_ctx.error(
+                "Parameter 'thought' is required but was None or empty"
+            )
+            return "Error: Parameter 'thought' is required but was None or empty"
+
+        if thought.strip() == "":
+            await tool_ctx.error("Parameter 'thought' cannot be empty")
+            return "Error: Parameter 'thought' cannot be empty"
+
+        # Log the thought but don't take action
+        await tool_ctx.info("Thinking process recorded")
+
+        # Return confirmation
+        return "I've recorded your thinking process. You can continue with your next action based on this analysis."
+        
+    @override
+    def register(self, mcp_server: FastMCP) -> None:
+        """Register this thinking 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.mcp_description)
+        async def think(thought: str, ctx: MCPContext) -> str:
+            return await tool_self.call(ctx, thought=thought)

hanzo_mcp/tools/common/validation.py

@@ -0,0 +1,124 @@
+"""Parameter validation utilities for Hanzo MCP tools.
+
+This module provides utilities for validating parameters in tool functions.
+"""
+
+from typing import Any, TypeVar, final
+
+T = TypeVar("T")
+
+
+@final
+class ValidationResult:
+    """Result of a parameter validation."""
+
+    def __init__(self, is_valid: bool, error_message: str = ""):
+        """Initialize a validation result.
+
+        Args:
+            is_valid: Whether the parameter is valid
+            error_message: Optional error message for invalid parameters
+        """
+        self.is_valid: bool = is_valid
+        self.error_message: str = error_message
+
+    @property
+    def is_error(self) -> bool:
+        """Check if the validation resulted in an error.
+
+        Returns:
+            True if there was a validation error, False otherwise
+        """
+        return not self.is_valid
+
+
+def validate_parameter(
+    parameter: Any, parameter_name: str, allow_empty: bool = False
+) -> ValidationResult:
+    """Validate a single parameter.
+
+    Args:
+        parameter: The parameter value to validate
+        parameter_name: The name of the parameter (for error messages)
+        allow_empty: Whether to allow empty strings, lists, etc.
+
+    Returns:
+        A ValidationResult indicating whether the parameter is valid
+    """
+    # Check for None
+    if parameter is None:
+        return ValidationResult(
+            is_valid=False,
+            error_message=f"Parameter '{parameter_name}' is required but was None",
+        )
+
+    # Check for empty strings
+    if isinstance(parameter, str) and not allow_empty and parameter.strip() == "":
+        return ValidationResult(
+            is_valid=False,
+            error_message=f"Parameter '{parameter_name}' is required but was empty string",
+        )
+
+    # Check for empty collections
+    if (
+        isinstance(parameter, (list, tuple, dict, set))
+        and not allow_empty
+        and len(parameter) == 0
+    ):
+        return ValidationResult(
+            is_valid=False,
+            error_message=f"Parameter '{parameter_name}' is required but was empty {type(parameter).__name__}",
+        )
+
+    # Parameter is valid
+    return ValidationResult(is_valid=True)
+
+
+def validate_path_parameter(
+    path: str | None, parameter_name: str = "path"
+) -> ValidationResult:
+    """Validate a path parameter.
+
+    Args:
+        path: The path parameter to validate
+        parameter_name: The name of the parameter (for error messages)
+
+    Returns:
+        A ValidationResult indicating whether the parameter is valid
+    """
+    # Check for None
+    if path is None:
+        return ValidationResult(
+            is_valid=False,
+            error_message=f"Path parameter '{parameter_name}' is required but was None",
+        )
+
+    # Check for empty path
+    if path.strip() == "":
+        return ValidationResult(
+            is_valid=False,
+            error_message=f"Path parameter '{parameter_name}' is required but was empty string",
+        )
+
+    # Path is valid
+    return ValidationResult(is_valid=True)
+
+
+def validate_parameters(**kwargs: Any) -> ValidationResult:
+    """Validate multiple parameters.
+
+    Accepts keyword arguments where the key is the parameter name and the value is the parameter value.
+
+    Args:
+        **kwargs: Parameters to validate as name=value pairs
+
+    Returns:
+        A ValidationResult for the first invalid parameter, or a valid result if all are valid
+    """
+    for name, value in kwargs.items():
+        result = validate_parameter(value, name)
+        if result.is_error:
+            return result
+
+    # All parameters are valid
+    return ValidationResult(is_valid=True)

hanzo_mcp/tools/filesystem/__init__.py

@@ -0,0 +1,89 @@
+"""Filesystem tools package for Hanzo MCP.
+
+This package provides tools for interacting with the filesystem, including reading, writing,
+and editing files, directory navigation, and content searching.
+"""
+
+from mcp.server.fastmcp import FastMCP
+
+from hanzo_mcp.tools.common.base import BaseTool, ToolRegistry
+from hanzo_mcp.tools.common.context import DocumentContext
+from hanzo_mcp.tools.common.permissions import PermissionManager
+from hanzo_mcp.tools.filesystem.content_replace import ContentReplaceTool
+from hanzo_mcp.tools.filesystem.directory_tree import DirectoryTreeTool
+from hanzo_mcp.tools.filesystem.edit_file import EditFileTool
+from hanzo_mcp.tools.filesystem.get_file_info import GetFileInfoTool
+from hanzo_mcp.tools.filesystem.read_files import ReadFilesTool
+from hanzo_mcp.tools.filesystem.search_content import SearchContentTool
+from hanzo_mcp.tools.filesystem.write_file import WriteFileTool
+
+# Export all tool classes
+__all__ = [
+    "ReadFilesTool",
+    "WriteFileTool",
+    "EditFileTool",
+    "DirectoryTreeTool",
+    "GetFileInfoTool",
+    "SearchContentTool",
+    "ContentReplaceTool",
+    "get_filesystem_tools",
+    "register_filesystem_tools",
+]
+
+def get_read_only_filesystem_tools(
+            document_context: DocumentContext, permission_manager: PermissionManager
+) -> list[BaseTool]:
+    """Create instances of read-only filesystem tools.
+    
+    Args:
+        document_context: Document context for tracking file contents
+        permission_manager: Permission manager for access control
+
+    Returns:
+        List of read-only filesystem tool instances
+    """
+    return [
+        ReadFilesTool(document_context, permission_manager),
+        DirectoryTreeTool(document_context, permission_manager),
+        GetFileInfoTool(document_context, permission_manager),
+        SearchContentTool(document_context, permission_manager),
+    ]
+
+
+def get_filesystem_tools(
+    document_context: DocumentContext, permission_manager: PermissionManager
+) -> list[BaseTool]:
+    """Create instances of all filesystem tools.
+    
+    Args:
+        document_context: Document context for tracking file contents
+        permission_manager: Permission manager for access control
+        
+    Returns:
+        List of filesystem tool instances
+    """
+    return [
+        ReadFilesTool(document_context, permission_manager),
+        WriteFileTool(document_context, permission_manager),
+        EditFileTool(document_context, permission_manager),
+        DirectoryTreeTool(document_context, permission_manager),
+        GetFileInfoTool(document_context, permission_manager),
+        SearchContentTool(document_context, permission_manager),
+        ContentReplaceTool(document_context, permission_manager),
+    ]
+
+
+def register_filesystem_tools(
+    mcp_server: FastMCP,
+    document_context: DocumentContext,
+    permission_manager: PermissionManager,
+) -> None:
+    """Register all filesystem tools with the MCP server.
+    
+    Args:
+        mcp_server: The FastMCP server instance
+        document_context: Document context for tracking file contents
+        permission_manager: Permission manager for access control
+    """
+    tools = get_filesystem_tools(document_context, permission_manager)
+    ToolRegistry.register_tools(mcp_server, tools)

hanzo_mcp/tools/filesystem/base.py

@@ -0,0 +1,113 @@
+"""Base functionality for filesystem tools.
+
+This module provides common functionality for filesystem tools including path handling,
+error formatting, and shared utilities for file operations.
+"""
+
+from abc import ABC
+from pathlib import Path
+from typing import Any
+
+from mcp.server.fastmcp import Context as MCPContext
+
+from hanzo_mcp.tools.common.base import FileSystemTool
+from hanzo_mcp.tools.common.context import ToolContext, create_tool_context
+
+
+class FilesystemBaseTool(FileSystemTool,ABC):
+    """Enhanced base class for all filesystem tools.
+    
+    Provides additional utilities specific to filesystem operations beyond
+    the base functionality in FileSystemTool.
+    """
+    
+    async def check_path_allowed(self, path: str, tool_ctx: Any, error_prefix: str = "Error") -> tuple[bool, str]:
+        """Check if a path is allowed and log an error if not.
+        
+        Args:
+            path: Path to check
+            tool_ctx: Tool context for logging
+            error_prefix: Prefix for error messages
+            
+        Returns:
+            tuple of (is_allowed, error_message)
+        """
+        if not self.is_path_allowed(path):
+            message = f"Access denied - path outside allowed directories: {path}"
+            await tool_ctx.error(message)
+            return False, f"{error_prefix}: {message}"
+        return True, ""
+        
+    async def check_path_exists(self, path: str, tool_ctx: Any, error_prefix: str = "Error") -> tuple[bool, str]:
+        """Check if a path exists and log an error if not.
+        
+        Args:
+            path: Path to check
+            tool_ctx: Tool context for logging
+            error_prefix: Prefix for error messages
+            
+        Returns:
+            tuple of (exists, error_message)
+        """
+        file_path = Path(path)
+        if not file_path.exists():
+            message = f"Path does not exist: {path}"
+            await tool_ctx.error(message)
+            return False, f"{error_prefix}: {message}"
+        return True, ""
+        
+    async def check_is_file(self, path: str, tool_ctx: Any, error_prefix: str = "Error") -> tuple[bool, str]:
+        """Check if a path is a file and log an error if not.
+        
+        Args:
+            path: Path to check
+            tool_ctx: Tool context for logging
+            error_prefix: Prefix for error messages
+            
+        Returns:
+            tuple of (is_file, error_message)
+        """
+        file_path = Path(path)
+        if not file_path.is_file():
+            message = f"Path is not a file: {path}"
+            await tool_ctx.error(message)
+            return False, f"{error_prefix}: {message}"
+        return True, ""
+        
+    async def check_is_directory(self, path: str, tool_ctx: Any, error_prefix: str = "Error") -> tuple[bool, str]:
+        """Check if a path is a directory and log an error if not.
+        
+        Args:
+            path: Path to check
+            tool_ctx: Tool context for logging
+            error_prefix: Prefix for error messages
+            
+        Returns:
+            tuple of (is_directory, error_message)
+        """
+        dir_path = Path(path)
+        if not dir_path.is_dir():
+            message = f"Path is not a directory: {path}"
+            await tool_ctx.error(message)
+            return False, f"{error_prefix}: {message}"
+        return True, ""
+        
+    def create_tool_context(self, ctx: MCPContext) -> ToolContext:
+        """Create a tool context with the tool name.
+        
+        Args:
+            ctx: MCP context
+            
+        Returns:
+            Tool context
+        """
+        tool_ctx = create_tool_context(ctx)
+        return tool_ctx
+        
+    def set_tool_context_info(self, tool_ctx: ToolContext) -> None:
+        """Set the tool info on the context.
+        
+        Args:
+            tool_ctx: Tool context
+        """
+        tool_ctx.set_tool_info(self.name)