hanzo-mcp 0.6.12__py3-none-any.whl → 0.7.0__py3-none-any.whl

hanzo_mcp/__init__.py

@@ -1,4 +1,4 @@
-"""Hanzo MCP - Implementation of Hanzo capabilities using MCP."""
+"""Hanzo AI - Implementation of Hanzo capabilities using MCP."""
 
 # Configure FastMCP logging globally for stdio transport
 import os
@@ -9,4 +9,4 @@ if os.environ.get("HANZO_MCP_TRANSPORT") == "stdio":
     except ImportError:
         pass
 
-__version__ = "0.6.12"
+__version__ = "0.6.13"

hanzo_mcp/analytics/__init__.py

@@ -0,0 +1,5 @@
+"""Analytics module for Hanzo MCP using PostHog."""
+
+from .posthog_analytics import Analytics, track_event, track_tool_usage, track_error
+
+__all__ = ["Analytics", "track_event", "track_tool_usage", "track_error"]

hanzo_mcp/analytics/posthog_analytics.py

@@ -0,0 +1,364 @@
+"""PostHog analytics integration for Hanzo MCP.
+
+This module provides analytics tracking for:
+- Tool usage and performance
+- Error tracking and debugging
+- Feature adoption and user behavior
+- A/B testing and feature flags
+"""
+
+import os
+import time
+import functools
+import traceback
+from typing import Dict, Any, Optional, Callable, TypeVar
+from datetime import datetime
+import platform
+import asyncio
+from dataclasses import dataclass
+
+# Try to import PostHog, but make it optional
+try:
+    from posthog import Posthog
+    POSTHOG_AVAILABLE = True
+except ImportError:
+    POSTHOG_AVAILABLE = False
+    Posthog = None
+
+
+F = TypeVar('F', bound=Callable[..., Any])
+
+
+@dataclass
+class AnalyticsConfig:
+    """Configuration for analytics."""
+    api_key: Optional[str] = None
+    host: str = "https://us.i.posthog.com"
+    enabled: bool = True
+    debug: bool = False
+    capture_errors: bool = True
+    capture_performance: bool = True
+    distinct_id: Optional[str] = None
+    
+
+class Analytics:
+    """Main analytics class for Hanzo MCP."""
+    
+    def __init__(self, config: Optional[AnalyticsConfig] = None):
+        """Initialize analytics with configuration."""
+        self.config = config or AnalyticsConfig()
+        self._client = None
+        
+        # Load from environment if not provided
+        if not self.config.api_key:
+            self.config.api_key = os.environ.get("POSTHOG_API_KEY")
+            
+        if not self.config.distinct_id:
+            # Use machine ID or generate one
+            self.config.distinct_id = self._get_distinct_id()
+            
+        # Initialize PostHog if available and configured
+        if POSTHOG_AVAILABLE and self.config.api_key and self.config.enabled:
+            self._client = Posthog(
+                self.config.api_key,
+                host=self.config.host,
+                debug=self.config.debug,
+                enable_exception_autocapture=self.config.capture_errors
+            )
+    
+    def _get_distinct_id(self) -> str:
+        """Get a distinct ID for this installation."""
+        # Try to get from environment
+        distinct_id = os.environ.get("HANZO_DISTINCT_ID")
+        if distinct_id:
+            return distinct_id
+            
+        # Use hostname + username as fallback
+        import socket
+        import getpass
+        hostname = socket.gethostname()
+        username = getpass.getuser()
+        return f"{hostname}:{username}"
+    
+    def is_enabled(self) -> bool:
+        """Check if analytics is enabled."""
+        return bool(self._client and self.config.enabled)
+    
+    def capture(self, event: str, properties: Optional[Dict[str, Any]] = None) -> None:
+        """Capture an analytics event."""
+        if not self.is_enabled():
+            return
+            
+        try:
+            # Add common properties
+            props = {
+                "timestamp": datetime.utcnow().isoformat(),
+                "platform": platform.system(),
+                "python_version": platform.python_version(),
+                "mcp_version": "0.6.13",  # TODO: Get from package
+                **(properties or {})
+            }
+            
+            self._client.capture(
+                self.config.distinct_id,
+                event,
+                properties=props
+            )
+        except Exception as e:
+            if self.config.debug:
+                print(f"Analytics error: {e}")
+    
+    def identify(self, properties: Optional[Dict[str, Any]] = None) -> None:
+        """Identify the current user/installation."""
+        if not self.is_enabled():
+            return
+            
+        try:
+            self._client.identify(
+                self.config.distinct_id,
+                properties=properties or {}
+            )
+        except Exception as e:
+            if self.config.debug:
+                print(f"Analytics identify error: {e}")
+    
+    def track_tool_usage(self, 
+                        tool_name: str,
+                        duration_ms: Optional[float] = None,
+                        success: bool = True,
+                        error: Optional[str] = None,
+                        metadata: Optional[Dict[str, Any]] = None) -> None:
+        """Track tool usage event."""
+        properties = {
+            "tool_name": tool_name,
+            "success": success,
+            **(metadata or {})
+        }
+        
+        if duration_ms is not None:
+            properties["duration_ms"] = duration_ms
+            
+        if error:
+            properties["error"] = str(error)
+            
+        self.capture("tool_used", properties)
+    
+    def track_error(self,
+                   error: Exception,
+                   context: Optional[Dict[str, Any]] = None) -> None:
+        """Track an error event."""
+        if not self.config.capture_errors:
+            return
+            
+        properties = {
+            "error_type": type(error).__name__,
+            "error_message": str(error),
+            "error_traceback": traceback.format_exc(),
+            **(context or {})
+        }
+        
+        self.capture("error_occurred", properties)
+    
+    def feature_enabled(self, flag_key: str, default: bool = False) -> bool:
+        """Check if a feature flag is enabled."""
+        if not self.is_enabled():
+            return default
+            
+        try:
+            return self._client.feature_enabled(
+                flag_key,
+                self.config.distinct_id,
+                default=default
+            )
+        except Exception:
+            return default
+    
+    def get_feature_flag(self, flag_key: str, default: Any = None) -> Any:
+        """Get feature flag value."""
+        if not self.is_enabled():
+            return default
+            
+        try:
+            return self._client.get_feature_flag(
+                flag_key,
+                self.config.distinct_id,
+                default=default
+            )
+        except Exception:
+            return default
+    
+    def flush(self) -> None:
+        """Flush any pending events."""
+        if self.is_enabled():
+            try:
+                self._client.flush()
+            except Exception:
+                pass
+    
+    def shutdown(self) -> None:
+        """Shutdown analytics client."""
+        if self.is_enabled():
+            try:
+                self._client.shutdown()
+            except Exception:
+                pass
+
+
+# Global analytics instance
+_analytics = None
+
+
+def get_analytics() -> Analytics:
+    """Get or create the global analytics instance."""
+    global _analytics
+    if _analytics is None:
+        _analytics = Analytics()
+    return _analytics
+
+
+def track_event(event: str, properties: Optional[Dict[str, Any]] = None) -> None:
+    """Track a custom event."""
+    get_analytics().capture(event, properties)
+
+
+def track_tool_usage(tool_name: str, **kwargs) -> None:
+    """Track tool usage."""
+    get_analytics().track_tool_usage(tool_name, **kwargs)
+
+
+def track_error(error: Exception, context: Optional[Dict[str, Any]] = None) -> None:
+    """Track an error."""
+    get_analytics().track_error(error, context)
+
+
+def with_analytics(tool_name: str):
+    """Decorator to track tool usage with analytics."""
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            start_time = time.time()
+            error = None
+            try:
+                result = await func(*args, **kwargs)
+                return result
+            except Exception as e:
+                error = e
+                track_error(e, {"tool": tool_name})
+                raise
+            finally:
+                duration_ms = (time.time() - start_time) * 1000
+                track_tool_usage(
+                    tool_name,
+                    duration_ms=duration_ms,
+                    success=error is None,
+                    error=str(error) if error else None
+                )
+        
+        @functools.wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            start_time = time.time()
+            error = None
+            try:
+                result = func(*args, **kwargs)
+                return result
+            except Exception as e:
+                error = e
+                track_error(e, {"tool": tool_name})
+                raise
+            finally:
+                duration_ms = (time.time() - start_time) * 1000
+                track_tool_usage(
+                    tool_name,
+                    duration_ms=duration_ms,
+                    success=error is None,
+                    error=str(error) if error else None
+                )
+        
+        # Return appropriate wrapper based on function type
+        if asyncio.iscoroutinefunction(func):
+            return async_wrapper
+        else:
+            return sync_wrapper
+    
+    return decorator
+
+
+def feature_flag(flag_key: str, default: bool = False):
+    """Decorator to conditionally enable features based on flags."""
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            if get_analytics().feature_enabled(flag_key, default):
+                return func(*args, **kwargs)
+            else:
+                raise NotImplementedError(f"Feature '{flag_key}' is not enabled")
+        return wrapper
+    return decorator
+
+
+# Tool usage context manager
+class ToolUsageTracker:
+    """Context manager for tracking tool usage."""
+    
+    def __init__(self, tool_name: str, metadata: Optional[Dict[str, Any]] = None):
+        self.tool_name = tool_name
+        self.metadata = metadata or {}
+        self.start_time = None
+        self.error = None
+    
+    def __enter__(self):
+        self.start_time = time.time()
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        duration_ms = (time.time() - self.start_time) * 1000
+        success = exc_type is None
+        
+        if exc_type:
+            self.error = str(exc_val)
+            track_error(exc_val, {"tool": self.tool_name, **self.metadata})
+        
+        track_tool_usage(
+            self.tool_name,
+            duration_ms=duration_ms,
+            success=success,
+            error=self.error,
+            metadata=self.metadata
+        )
+        
+        # Don't suppress exceptions
+        return False
+
+
+# Async context manager version
+class AsyncToolUsageTracker:
+    """Async context manager for tracking tool usage."""
+    
+    def __init__(self, tool_name: str, metadata: Optional[Dict[str, Any]] = None):
+        self.tool_name = tool_name
+        self.metadata = metadata or {}
+        self.start_time = None
+        self.error = None
+    
+    async def __aenter__(self):
+        self.start_time = time.time()
+        return self
+    
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        duration_ms = (time.time() - self.start_time) * 1000
+        success = exc_type is None
+        
+        if exc_type:
+            self.error = str(exc_val)
+            track_error(exc_val, {"tool": self.tool_name, **self.metadata})
+        
+        track_tool_usage(
+            self.tool_name,
+            duration_ms=duration_ms,
+            success=success,
+            error=self.error,
+            metadata=self.metadata
+        )
+        
+        # Don't suppress exceptions
+        return False

hanzo_mcp/cli.py

@@ -1,4 +1,4 @@
-"""Command-line interface for the Hanzo MCP server."""
+"""Command-line interface for the Hanzo AI server."""
 
 import argparse
 import json
@@ -13,7 +13,7 @@ from hanzo_mcp.server import HanzoMCPServer
 
 
 def main() -> None:
-    """Run the CLI for the Hanzo MCP server."""
+    """Run the CLI for the Hanzo AI server."""
     
     # Pre-parse arguments to check transport type early
     import sys
@@ -157,8 +157,8 @@ def main() -> None:
         "--port",
         dest="port",
         type=int,
-        default=3000,
-        help="Port for SSE server (default: 3000)",
+        default=8888,
+        help="Port for SSE server (default: 8888)",
     )
 
     _ = parser.add_argument(
@@ -324,7 +324,7 @@ def install_claude_desktop_config(
     disable_write_tools: bool = False,
     disable_search_tools: bool = False,
     host: str = "127.0.0.1",
-    port: int = 3000,
+    port: int = 8888,
 ) -> None:
     """Install the server configuration in Claude Desktop.
 

hanzo_mcp/cli_enhanced.py

@@ -1,4 +1,4 @@
-"""Enhanced command-line interface for the Hanzo MCP server with full tool configuration."""
+"""Enhanced command-line interface for the Hanzo AI server with full tool configuration."""
 
 import argparse
 import json
@@ -15,7 +15,7 @@ from hanzo_mcp.server import HanzoMCPServer
 def create_parser() -> argparse.ArgumentParser:
     """Create the argument parser with all tool configuration options."""
     parser = argparse.ArgumentParser(
-        description="Hanzo MCP server with comprehensive tool configuration",
+        description="Hanzo AI server with comprehensive tool configuration",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""
 Tool Configuration:
@@ -59,8 +59,8 @@ Examples:
     server_group.add_argument(
         "--port",
         type=int,
-        default=3000,
-        help="Port for SSE server (default: 3000)",
+        default=8888,
+        help="Port for SSE server (default: 8888)",
     )
     server_group.add_argument(
         "--log-level",
@@ -242,7 +242,7 @@ def apply_cli_overrides(args: argparse.Namespace) -> Dict[str, Any]:
         server_config["name"] = args.name
     if hasattr(args, 'host') and args.host != "127.0.0.1":
         server_config["host"] = args.host
-    if hasattr(args, 'port') and args.port != 3000:
+    if hasattr(args, 'port') and args.port != 8888:
         server_config["port"] = args.port
     if hasattr(args, 'transport') and args.transport != "stdio":
         server_config["transport"] = args.transport
@@ -346,7 +346,7 @@ def apply_cli_overrides(args: argparse.Namespace) -> Dict[str, Any]:
 def list_tools(settings: HanzoMCPSettings) -> None:
     """List all tools and their current status."""
     logger = logging.getLogger(__name__)
-    logger.info("Hanzo MCP Tools Status:")
+    logger.info("Hanzo AI Tools Status:")
     logger.info("=" * 50)
     
     categories = {}
@@ -371,7 +371,7 @@ def list_tools(settings: HanzoMCPSettings) -> None:
 
 
 def main() -> None:
-    """Run the enhanced CLI for the Hanzo MCP server."""
+    """Run the enhanced CLI for the Hanzo AI server."""
     parser = create_parser()
     args = parser.parse_args()
 

hanzo_mcp/cli_plugin.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""CLI for managing Hanzo MCP plugins."""
+
+import argparse
+import sys
+from pathlib import Path
+
+from hanzo_mcp.tools.common.plugin_loader import create_plugin_template, list_plugin_tools
+
+
+def main():
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="Hanzo MCP Plugin Manager",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Create a new plugin template
+  hanzo-plugin create mytool
+  
+  # List installed plugins
+  hanzo-plugin list
+  
+  # Create plugin in specific directory
+  hanzo-plugin create mytool --output /path/to/plugins
+"""
+    )
+    
+    subparsers = parser.add_subparsers(dest="command", help="Command to run")
+    
+    # Create command
+    create_parser = subparsers.add_parser("create", help="Create a new plugin template")
+    create_parser.add_argument("name", help="Name of the tool (e.g., 'mytool')")
+    create_parser.add_argument(
+        "--output", "-o",
+        type=Path,
+        default=Path.home() / ".hanzo" / "plugins",
+        help="Output directory for the plugin (default: ~/.hanzo/plugins)"
+    )
+    
+    # List command
+    list_parser = subparsers.add_parser("list", help="List installed plugins")
+    
+    args = parser.parse_args()
+    
+    if args.command == "create":
+        # Create plugin template
+        output_dir = args.output / args.name
+        try:
+            create_plugin_template(output_dir, args.name)
+            print(f"\n✅ Plugin template created successfully!")
+            print(f"\nTo use your plugin:")
+            print(f"1. Edit the tool implementation in {output_dir / f'{args.name}_tool.py'}")
+            print(f"2. Restart Hanzo MCP to load the plugin")
+            print(f"3. Add '{args.name}' to your mode's tool list")
+        except Exception as e:
+            print(f"❌ Error creating plugin: {e}", file=sys.stderr)
+            sys.exit(1)
+    
+    elif args.command == "list":
+        # List installed plugins
+        try:
+            from hanzo_mcp.tools.common.plugin_loader import load_user_plugins
+            plugins = load_user_plugins()
+            
+            if not plugins:
+                print("No plugins installed.")
+                print("\nPlugin directories:")
+                print("  ~/.hanzo/plugins/")
+                print("  ./.hanzo/plugins/")
+                print("  $HANZO_PLUGIN_PATH")
+            else:
+                print(f"Installed plugins ({len(plugins)}):")
+                for name, plugin in plugins.items():
+                    print(f"\n  {name}:")
+                    print(f"    Source: {plugin.source_path}")
+                    if plugin.metadata:
+                        print(f"    Version: {plugin.metadata.get('version', 'unknown')}")
+                        print(f"    Author: {plugin.metadata.get('author', 'unknown')}")
+                        print(f"    Description: {plugin.metadata.get('description', '')}")
+        except Exception as e:
+            print(f"❌ Error listing plugins: {e}", file=sys.stderr)
+            sys.exit(1)
+    
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

hanzo_mcp/config/__init__.py

@@ -1,4 +1,4 @@
-"""Configuration management for Hanzo MCP.
+"""Configuration management for Hanzo AI.
 
 This module provides a comprehensive configuration system that supports:
 - CLI arguments for individual tool control