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

hanzo_mcp/tools/common/__init__.py

@@ -1 +1,18 @@
-"""Common utilities for Hanzo Dev MCP tools."""
+"""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 Dev MCP tools.
+"""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
@@ -17,7 +17,7 @@ from mcp.server.lowlevel.helper_types import ReadResourceContents
 
 @final
 class ToolContext:
-    """Enhanced context for Hanzo Dev MCP tools.
+    """Enhanced context for Hanzo MCP tools.
 
     This class wraps the MCP Context and adds additional functionality
     for tracking tool execution, progress reporting, and resource access.
@@ -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

@@ -1,4 +1,4 @@
-"""Permission system for the Hanzo Dev MCP server."""
+"""Permission system for the Hanzo MCP server."""
 
 import json
 import os
@@ -69,7 +69,9 @@ class PermissionManager:
         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 remove_allowed_path(self, path: str) -> None:
@@ -108,7 +110,9 @@ class PermissionManager:
         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 exclusions first
         if self._is_path_excluded(resolved_path):

hanzo_mcp/tools/common/session.py

@@ -0,0 +1,91 @@
+"""Session management for maintaining state across tool executions."""
+
+import os
+from pathlib import Path
+from typing import Dict, Optional, final
+
+
+@final
+class SessionManager:
+    """Manages session state across tool executions."""
+
+    _instances: Dict[str, "SessionManager"] = {}
+
+    @classmethod
+    def get_instance(cls, session_id: str) -> "SessionManager":
+        """Get or create a session manager instance for the given session ID.
+
+        Args:
+            session_id: The session ID
+
+        Returns:
+            The session manager instance
+        """
+        if session_id not in cls._instances:
+            cls._instances[session_id] = cls(session_id)
+        return cls._instances[session_id]
+
+    def __init__(self, session_id: str):
+        """Initialize the session manager.
+
+        Args:
+            session_id: The session ID
+        """
+        self.session_id = session_id
+        self._current_working_dir: Optional[Path] = None
+        self._initial_working_dir: Optional[Path] = None
+        self._environment_vars: Dict[str, str] = {}
+
+    @property
+    def current_working_dir(self) -> Path:
+        """Get the current working directory.
+
+        Returns:
+            The current working directory
+        """
+        if self._current_working_dir is None:
+            # Default to project directory if set, otherwise use current directory
+            self._current_working_dir = Path(os.getcwd())
+            self._initial_working_dir = self._current_working_dir
+        return self._current_working_dir
+
+    def set_working_dir(self, path: Path) -> None:
+        """Set the current working directory.
+
+        Args:
+            path: The path to set as the current working directory
+        """
+        self._current_working_dir = path
+
+    def reset_working_dir(self) -> None:
+        """Reset the working directory to the initial directory."""
+        if self._initial_working_dir is not None:
+            self._current_working_dir = self._initial_working_dir
+
+    def set_env_var(self, key: str, value: str) -> None:
+        """Set an environment variable.
+
+        Args:
+            key: The environment variable name
+            value: The environment variable value
+        """
+        self._environment_vars[key] = value
+
+    def get_env_var(self, key: str) -> Optional[str]:
+        """Get an environment variable.
+
+        Args:
+            key: The environment variable name
+
+        Returns:
+            The environment variable value, or None if not set
+        """
+        return self._environment_vars.get(key)
+
+    def get_env_vars(self) -> Dict[str, str]:
+        """Get all environment variables.
+
+        Returns:
+            A dictionary of environment variables
+        """
+        return self._environment_vars.copy()

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

@@ -1,4 +1,4 @@
-"""Parameter validation utilities for Hanzo Dev MCP tools.
+"""Parameter validation utilities for Hanzo MCP tools.
 
 This module provides utilities for validating parameters in tool functions.
 """

hanzo_mcp/tools/filesystem/__init__.py

@@ -1,9 +1,89 @@
-"""Filesystem tools for Hanzo Dev MCP.
+"""Filesystem tools package for Hanzo MCP.
 
-This module provides comprehensive tools for interacting with the filesystem,
-including reading, writing, editing files, directory operations, and searching.
+This package provides tools for interacting with the filesystem, including reading, writing,
+and editing files, directory navigation, and content searching.
 """
 
-from hanzo_mcp.tools.filesystem.file_operations import FileOperations
+from mcp.server.fastmcp import FastMCP
 
-__all__ = ["FileOperations"]
+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)