hanzo-mcp 0.2.0__tar.gz → 0.3.3__tar.gz

{hanzo_mcp-0.2.0 → hanzo_mcp-0.3.3}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: hanzo-mcp
-Version: 0.2.0
+Version: 0.3.3
 Summary: MCP implementation of Hanzo capabilities
 Author-email: Hanzo Industries Inc <dev@hanzo.ai>
 License: MIT
 Project-URL: Homepage, https://github.com/hanzoai/mcp
 Project-URL: Bug Tracker, https://github.com/hanzoai/mcp/issues
-Project-URL: Documentation, https://github.com/hanzoai/mcp/blob/main/README.md
+Project-URL: Documentation, https://github.com/hanzoai/mcp/tree/main/docs
 Keywords: mcp,claude,hanzo,code,agent
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
@@ -25,6 +25,9 @@ Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
 Requires-Dist: ruff>=0.1.0; extra == "dev"
 Requires-Dist: black>=23.3.0; extra == "dev"
+Requires-Dist: sphinx>=8.0.0; extra == "dev"
+Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "dev"
+Requires-Dist: myst-parser>=2.0.0; extra == "dev"
 Provides-Extra: test
 Requires-Dist: pytest>=7.0.0; extra == "test"
 Requires-Dist: pytest-cov>=4.1.0; extra == "test"
@@ -93,7 +96,7 @@ uv pip install hanzo-mcp
 pip install hanzo-mcp
 ```
 
-For detailed installation and configuration instructions, please refer to [INSTALL.md](./doc/INSTALL.md).
+For detailed installation and configuration instructions, please refer to the [documentation](./docs/).
 
 Of course, you can also read [USEFUL_PROMPTS](./doc/USEFUL_PROMPTS.md) for some inspiration on how to use hanzo-mcp.
 
@@ -106,6 +109,20 @@ This implementation follows best practices for securing access to your filesyste
 - Input validation and sanitization
 - Proper error handling and reporting
 
+## Documentation
+
+Comprehensive documentation is available in the [docs](./docs/) directory. You can build and view the documentation locally:
+
+```bash
+# Build the documentation
+make docs
+
+# Start a local server to view the documentation
+make docs-serve
+```
+
+Then open http://localhost:8000/ in your browser to view the documentation.
+
 ## Development
 
 ### Setup Development Environment

{hanzo_mcp-0.2.0 → hanzo_mcp-0.3.3}/README.md

@@ -52,7 +52,7 @@ uv pip install hanzo-mcp
 pip install hanzo-mcp
 ```
 
-For detailed installation and configuration instructions, please refer to [INSTALL.md](./doc/INSTALL.md).
+For detailed installation and configuration instructions, please refer to the [documentation](./docs/).
 
 Of course, you can also read [USEFUL_PROMPTS](./doc/USEFUL_PROMPTS.md) for some inspiration on how to use hanzo-mcp.
 
@@ -65,6 +65,20 @@ This implementation follows best practices for securing access to your filesyste
 - Input validation and sanitization
 - Proper error handling and reporting
 
+## Documentation
+
+Comprehensive documentation is available in the [docs](./docs/) directory. You can build and view the documentation locally:
+
+```bash
+# Build the documentation
+make docs
+
+# Start a local server to view the documentation
+make docs-serve
+```
+
+Then open http://localhost:8000/ in your browser to view the documentation.
+
 ## Development
 
 ### Setup Development Environment

{hanzo_mcp-0.2.0 → hanzo_mcp-0.3.3}/hanzo_mcp/__init__.py

@@ -1,3 +1,3 @@
 """Hanzo MCP - Implementation of Hanzo capabilities using MCP."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.3"

{hanzo_mcp-0.2.0 → hanzo_mcp-0.3.3}/hanzo_mcp/cli.py

@@ -1,20 +1,42 @@
-"""Command-line interface for the Hanzo MCP server."""
+"""Command-line interface for the Hanzo MCP server.
+
+Includes logging configuration and enhanced error handling.
+"""
 
 import argparse
 import json
+import logging
 import os
 import sys
 from pathlib import Path
 from typing import Any, cast
 
+from hanzo_mcp import __version__
+from hanzo_mcp.tools.common.logging_config import setup_logging
+
 from hanzo_mcp.server import HanzoServer
 
 
 def main() -> None:
     """Run the CLI for the Hanzo MCP server."""
+    # Initialize logger
+    logger = logging.getLogger(__name__)
+    
+    # Check if 'version' is the first argument
+    if len(sys.argv) > 1 and sys.argv[1] == 'version':
+        print(f"hanzo-mcp {__version__}")
+        return
+        
     parser = argparse.ArgumentParser(
         description="MCP server implementing Hanzo capabilities"
     )
+    
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+        help="Show the current version and exit"
+    )
 
     _ = parser.add_argument(
         "--transport",
@@ -23,6 +45,19 @@ def main() -> None:
         help="Transport protocol to use (default: stdio)",
     )
 
+    _ = parser.add_argument(
+        "--port",
+        type=int,
+        default=3001,
+        help="Port to use for SSE transport (default: 3001)",
+    )
+
+    _ = parser.add_argument(
+        "--host",
+        default="0.0.0.0",
+        help="Host to bind to for SSE transport (default: 0.0.0.0)",
+    )
+
     _ = parser.add_argument(
         "--name",
         default="claude-code",
@@ -39,26 +74,26 @@ def main() -> None:
     _ = parser.add_argument(
         "--project-dir", dest="project_dir", help="Set the project directory to analyze"
     )
-    
+
     _ = parser.add_argument(
         "--agent-model",
         dest="agent_model",
         help="Specify the model name in LiteLLM format (e.g., 'openai/gpt-4o', 'anthropic/claude-3-sonnet')"
     )
-    
+
     _ = parser.add_argument(
         "--agent-max-tokens",
         dest="agent_max_tokens",
         type=int,
         help="Specify the maximum tokens for agent responses"
     )
-    
+
     _ = parser.add_argument(
         "--agent-api-key",
         dest="agent_api_key",
         help="Specify the API key for the LLM provider (for development/testing only)"
     )
-    
+
     _ = parser.add_argument(
         "--agent-max-iterations",
         dest="agent_max_iterations",
@@ -66,7 +101,7 @@ def main() -> None:
         default=10,
         help="Maximum number of iterations for agent (default: 10)"
     )
-    
+
     _ = parser.add_argument(
         "--agent-max-tool-uses",
         dest="agent_max_tool_uses",
@@ -74,7 +109,7 @@ def main() -> None:
         default=30,
         help="Maximum number of total tool uses for agent (default: 30)"
     )
-    
+
     _ = parser.add_argument(
         "--enable-agent-tool",
         dest="enable_agent_tool",
@@ -82,7 +117,31 @@ def main() -> None:
         default=False,
         help="Enable the agent tool (disabled by default)"
     )
+
+    _ = parser.add_argument(
+        "--log-level",
+        dest="log_level",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
+        default="INFO",
+        help="Set the logging level (default: INFO)"
+    )
+
+    _ = parser.add_argument(
+        "--disable-file-logging",
+        dest="disable_file_logging",
+        action="store_true",
+        default=False,
+        help="Disable logging to file (logs to console only)"
+    )
     
+    _ = parser.add_argument(
+        "--enable-console-logging",
+        dest="enable_console_logging",
+        action="store_true",
+        default=False,
+        help="Enable logging to console (stdout/stderr). By default, logs to file only."
+    )
+
     _ = parser.add_argument(
         "--disable-write-tools",
         dest="disable_write_tools",
@@ -103,6 +162,8 @@ def main() -> None:
     name: str = cast(str, args.name)
     install: bool = cast(bool, args.install)
     transport: str = cast(str, args.transport)
+    port: int = cast(int, args.port)
+    host: str = cast(str, args.host)
     project_dir: str | None = cast(str | None, args.project_dir)
     agent_model: str | None = cast(str | None, args.agent_model)
     agent_max_tokens: int | None = cast(int | None, args.agent_max_tokens)
@@ -111,17 +172,37 @@ def main() -> None:
     agent_max_tool_uses: int = cast(int, args.agent_max_tool_uses)
     enable_agent_tool: bool = cast(bool, args.enable_agent_tool)
     disable_write_tools: bool = cast(bool, args.disable_write_tools)
+    log_level: str = cast(str, args.log_level)
+    disable_file_logging: bool = cast(bool, args.disable_file_logging)
+    enable_console_logging: bool = cast(bool, args.enable_console_logging)
     allowed_paths: list[str] = (
         cast(list[str], args.allowed_paths) if args.allowed_paths else []
     )
 
+    # Setup logging
+    # Ensure absolutely NO logging when using stdio transport to avoid protocol corruption
+    # For sse transport, use file logging by default and console logging only if explicitly requested
+    # Only set up logging if not using stdio transport or explicitly requested
+    if transport != "stdio" or (enable_console_logging or not disable_file_logging):
+        setup_logging(
+            log_level=log_level,
+            log_to_file=not disable_file_logging and transport != "stdio",  # Disable file logging for stdio transport
+            log_to_console=enable_console_logging and transport != "stdio",  # Only enable console logging if requested AND not using stdio
+            transport=transport,  # Pass the transport to ensure it's properly handled
+            testing="pytest" in sys.modules
+        )
+        logger.debug(f"Hanzo MCP CLI started with arguments: {args}")
+    # No logging setup at all for stdio transport unless explicitly requested
+
+
     if install:
-        install_claude_desktop_config(name, allowed_paths, disable_write_tools)
+        install_claude_desktop_config(name, allowed_paths, host, port)
         return
 
     # If no allowed paths are specified, use the user's home directory
     if not allowed_paths:
         allowed_paths = [str(Path.home())]
+        logger.info(f"No allowed paths specified, using home directory: {allowed_paths[0]}")
 
     # If project directory is specified, add it to allowed paths
     if project_dir and project_dir not in allowed_paths:
@@ -139,26 +220,48 @@ def main() -> None:
     elif allowed_paths:
         project_dir = allowed_paths[0]
 
-    # Run the server
-    server = HanzoServer(
-        name=name, 
-        allowed_paths=allowed_paths,
-        project_dir=project_dir,  # Pass project_dir for initial working directory
-        agent_model=agent_model,
-        agent_max_tokens=agent_max_tokens,
-        agent_api_key=agent_api_key,
-        agent_max_iterations=agent_max_iterations,
-        agent_max_tool_uses=agent_max_tool_uses,
-        enable_agent_tool=enable_agent_tool,
-        disable_write_tools=disable_write_tools
-    )
-    # Transport will be automatically cast to Literal['stdio', 'sse'] by the server
-    server.run(transport=transport)
+    # Run the server - only log if not using stdio transport or logging is explicitly enabled
+    if transport != "stdio" or (enable_console_logging or not disable_file_logging):
+        logger.info(f"Starting Hanzo MCP server with name: {name}")
+        logger.debug(f"Allowed paths: {allowed_paths}")
+        logger.debug(f"Project directory: {project_dir}")
+
+    try:
+        server = HanzoServer(
+            name=name,
+            allowed_paths=allowed_paths,
+            project_dir=project_dir,  # Pass project_dir for initial working directory
+            agent_model=agent_model,
+            agent_max_tokens=agent_max_tokens,
+            agent_api_key=agent_api_key,
+            agent_max_iterations=agent_max_iterations,
+            agent_max_tool_uses=agent_max_tool_uses,
+            enable_agent_tool=enable_agent_tool,
+            disable_write_tools=disable_write_tools,
+            host=host,
+            port=port
+        )
+        
+        # Only log if not using stdio transport or logging is explicitly enabled
+        if transport != "stdio" or (enable_console_logging or not disable_file_logging):
+            logger.info(f"Server initialized successfully, running with transport: {transport}")
+            
+        # Transport will be automatically cast to Literal['stdio', 'sse'] by the server
+        server.run(transport=transport)
+    except Exception as e:
+        # Only log if not using stdio transport or logging is explicitly enabled
+        if transport != "stdio" or (enable_console_logging or not disable_file_logging):
+            logger.error(f"Error starting server: {str(e)}")
+            logger.exception("Server startup failed with exception:")
+        # For stdio transport, we want a clean exception without any logging
+        # Re-raise the exception for proper error handling
+        raise
 
 
 def install_claude_desktop_config(
     name: str = "claude-code", allowed_paths: list[str] | None = None,
-    disable_write_tools: bool = False
+    disable_write_tools: bool = False,
+    host: str = "0.0.0.0", port: int = 3001
 ) -> None:
     """Install the server configuration in Claude Desktop.
 
@@ -168,6 +271,8 @@ def install_claude_desktop_config(
         disable_write_tools: Whether to disable write/edit tools (file writing, editing, notebook editing)
                           to use IDE tools instead. Note: Shell commands can still modify files.
                           (default: False)
+        host: Host to bind to for SSE transport (default: '0.0.0.0')
+        port: Port to use for SSE transport (default: 3001)
     """
     # Find the Claude Desktop config directory
     home: Path = Path.home()
@@ -197,11 +302,19 @@ def install_claude_desktop_config(
     else:
         # Allow home directory by default
         args.extend(["--allow-path", str(home)])
-        
+
+    # Add host and port
+    args.extend(["--host", host])
+    args.extend(["--port", str(port)])
+
     # Add disable_write_tools flag if specified
     if disable_write_tools:
         args.append("--disable-write-tools")
 
+    # Add host and port
+    args.extend(["--host", host])
+    args.extend(["--port", str(port)])
+
     # Create config object
     config: dict[str, Any] = {
         "mcpServers": {name: {"command": str(script_path), "args": args}}

{hanzo_mcp-0.2.0 → hanzo_mcp-0.3.3}/hanzo_mcp/server.py

@@ -1,4 +1,7 @@
-"""MCP server implementing Hanzo capabilities."""
+"""MCP server implementing Hanzo capabilities.
+
+Includes improved error handling and debugging for tool execution.
+"""
 
 from typing import Literal, cast, final
 
@@ -13,7 +16,10 @@ from hanzo_mcp.tools.shell.command_executor import CommandExecutor
 
 @final
 class HanzoServer:
-    """MCP server implementing Hanzo capabilities."""
+    """MCP server implementing Hanzo capabilities.
+
+Includes improved error handling and debugging for tool execution.
+"""
 
     def __init__(
         self,
@@ -28,6 +34,8 @@ class HanzoServer:
         agent_max_tool_uses: int = 30,
         enable_agent_tool: bool = False,
         disable_write_tools: bool = False,
+        host: str = "0.0.0.0",
+        port: int = 3001,
     ):
         """Initialize the Hanzo server.
 
@@ -43,6 +51,8 @@ class HanzoServer:
             agent_max_tool_uses: Maximum number of total tool uses for agent (default: 30)
             enable_agent_tool: Whether to enable the agent tool (default: False)
             disable_write_tools: Whether to disable write/edit tools (default: False)
+            host: Host to bind to for SSE transport (default: '0.0.0.0')
+            port: Port to use for SSE transport (default: 3001)
         """
         self.mcp = mcp_instance if mcp_instance is not None else FastMCP(name)
 
@@ -55,7 +65,7 @@ class HanzoServer:
             permission_manager=self.permission_manager,
             verbose=False,  # Set to True for debugging
         )
-        
+
         # If project_dir is specified, set it as initial working directory for all sessions
         if project_dir:
             initial_session_id = name  # Use server name as default session ID
@@ -83,7 +93,11 @@ class HanzoServer:
         self.agent_max_tool_uses = agent_max_tool_uses
         self.enable_agent_tool = enable_agent_tool
         self.disable_write_tools = disable_write_tools
-        
+
+        # Store network options
+        self.host = host
+        self.port = port
+
         # Register all tools
         register_all_tools(
             mcp_server=self.mcp,
@@ -111,6 +125,14 @@ class HanzoServer:
             self.permission_manager.add_allowed_path(path)
             self.document_context.add_allowed_path(path)
 
+        # If using SSE, set the port and host in the environment variables
+        if transport == "sse":
+            import os
+            # Set environment variables for FastMCP settings
+            os.environ["FASTMCP_PORT"] = str(self.port)
+            os.environ["FASTMCP_HOST"] = self.host
+            print(f"Starting SSE server on {self.host}:{self.port}")
+
         # Run the server
         transport_type = cast(Literal["stdio", "sse"], transport)
         self.mcp.run(transport=transport_type)

hanzo_mcp-0.3.3/hanzo_mcp/tools/agent/base_provider.py

@@ -0,0 +1,73 @@
+"""Base model provider for agent delegation.
+
+Defines the interface for model providers.
+"""
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+
+class BaseModelProvider(ABC):
+    """Base class for model providers."""
+    
+    @abstractmethod
+    async def initialize(self) -> None:
+        """Initialize the provider."""
+        pass
+        
+    @abstractmethod
+    async def load_model(self, model_name: str, identifier: Optional[str] = None) -> str:
+        """Load a model.
+        
+        Args:
+            model_name: The name of the model to load
+            identifier: Optional identifier for the model instance
+            
+        Returns:
+            The identifier for the loaded model
+        """
+        pass
+        
+    @abstractmethod
+    async def generate(
+        self,
+        model_id: str,
+        prompt: str,
+        system_prompt: Optional[str] = None,
+        max_tokens: int = 4096,
+        temperature: float = 0.7,
+        top_p: float = 0.95,
+        stop_sequences: Optional[List[str]] = None,
+    ) -> Tuple[str, Dict[str, Any]]:
+        """Generate a response from the model.
+        
+        Args:
+            model_id: The identifier of the model to use
+            prompt: The prompt to send to the model
+            system_prompt: Optional system prompt to send to the model
+            max_tokens: Maximum number of tokens to generate
+            temperature: Sampling temperature
+            top_p: Top-p sampling parameter
+            stop_sequences: Optional list of strings that will stop generation
+            
+        Returns:
+            A tuple of (generated text, metadata)
+        """
+        pass
+        
+    @abstractmethod
+    async def unload_model(self, model_id: str) -> None:
+        """Unload a model.
+        
+        Args:
+            model_id: The identifier of the model to unload
+        """
+        pass
+        
+    @abstractmethod
+    async def shutdown(self) -> None:
+        """Shutdown the provider."""
+        pass

hanzo_mcp-0.3.3/hanzo_mcp/tools/agent/litellm_provider.py

@@ -0,0 +1,45 @@
+"""LiteLLM provider for agent delegation.
+
+Enables the use of various cloud LLM providers via LiteLLM.
+"""
+
+import asyncio
+import logging
+import json
+from typing import Any, Dict, List, Optional, Tuple
+
+from hanzo_mcp.tools.agent.base_provider import BaseModelProvider
+
+logger = logging.getLogger(__name__)
+
+# Define model capabilities
+DEFAULT_MAX_TOKENS = 4096
+DEFAULT_CONTEXT_WINDOW = 8192
+
+
+class LiteLLMProvider(BaseModelProvider):
+    """Provider for cloud models via LiteLLM."""
+
+    def __init__(self):
+        """Initialize the LiteLLM provider."""
+        self.models = {}
+        self.initialized = False
+        
+    async def initialize(self) -> None:
+        """Initialize the LiteLLM provider."""
+        if self.initialized:
+            return
+            
+        try:
+            # Import LiteLLM
+            import litellm
+            self.litellm = litellm
+            self.initialized = True
+            logger.info("LiteLLM provider initialized successfully")
+        except ImportError:
+            logger.error("Failed to import LiteLLM")
+            logger.error("Install LiteLLM with 'pip install litellm'")
+        except Exception as e:
+            logger.error(f"Failed to initialize LiteLLM provider: {str(e)}")
+            
+    async def load_model(self, model_name: str, identifier: Optional[str] = None