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

hanzo_mcp/tools/common/plugin_loader.py

@@ -0,0 +1,287 @@
+"""Plugin loader for custom user tools."""
+
+import importlib.util
+import inspect
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional, Type, Any
+from dataclasses import dataclass
+
+from .base import BaseTool
+from .context import ToolContext
+
+
+@dataclass
+class ToolPlugin:
+    """Represents a loaded tool plugin."""
+    name: str
+    tool_class: Type[BaseTool]
+    source_path: Path
+    metadata: Optional[Dict[str, Any]] = None
+
+
+class PluginLoader:
+    """Loads custom tool plugins from user directories."""
+    
+    def __init__(self):
+        self.plugins: Dict[str, ToolPlugin] = {}
+        self.plugin_dirs: List[Path] = []
+        self._setup_plugin_directories()
+    
+    def _setup_plugin_directories(self):
+        """Set up standard plugin directories."""
+        # User's home directory plugins
+        home_plugins = Path.home() / ".hanzo" / "plugins"
+        home_plugins.mkdir(parents=True, exist_ok=True)
+        self.plugin_dirs.append(home_plugins)
+        
+        # Project-local plugins
+        project_plugins = Path.cwd() / ".hanzo" / "plugins"
+        if project_plugins.exists():
+            self.plugin_dirs.append(project_plugins)
+        
+        # Environment variable for additional paths
+        if custom_paths := os.environ.get("HANZO_PLUGIN_PATH"):
+            for path in custom_paths.split(":"):
+                plugin_dir = Path(path)
+                if plugin_dir.exists():
+                    self.plugin_dirs.append(plugin_dir)
+    
+    def load_plugins(self) -> Dict[str, ToolPlugin]:
+        """Load all plugins from configured directories."""
+        for plugin_dir in self.plugin_dirs:
+            if not plugin_dir.exists():
+                continue
+                
+            # Look for Python files
+            for py_file in plugin_dir.glob("*.py"):
+                if py_file.name.startswith("_"):
+                    continue
+                    
+                try:
+                    self._load_plugin_file(py_file)
+                except Exception as e:
+                    print(f"Failed to load plugin {py_file}: {e}")
+            
+            # Look for plugin packages
+            for package_dir in plugin_dir.iterdir():
+                if package_dir.is_dir() and (package_dir / "__init__.py").exists():
+                    try:
+                        self._load_plugin_package(package_dir)
+                    except Exception as e:
+                        print(f"Failed to load plugin package {package_dir}: {e}")
+        
+        return self.plugins
+    
+    def _load_plugin_file(self, file_path: Path):
+        """Load a single plugin file."""
+        # Load the module
+        spec = importlib.util.spec_from_file_location(file_path.stem, file_path)
+        if not spec or not spec.loader:
+            return
+            
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[file_path.stem] = module
+        spec.loader.exec_module(module)
+        
+        # Find tool classes
+        for name, obj in inspect.getmembers(module):
+            if (inspect.isclass(obj) and 
+                issubclass(obj, BaseTool) and 
+                obj != BaseTool and
+                hasattr(obj, 'name')):
+                
+                # Load metadata if available
+                metadata = None
+                metadata_file = file_path.with_suffix('.json')
+                if metadata_file.exists():
+                    with open(metadata_file) as f:
+                        metadata = json.load(f)
+                
+                plugin = ToolPlugin(
+                    name=obj.name,
+                    tool_class=obj,
+                    source_path=file_path,
+                    metadata=metadata
+                )
+                self.plugins[obj.name] = plugin
+    
+    def _load_plugin_package(self, package_dir: Path):
+        """Load a plugin package."""
+        # Add parent to path temporarily
+        parent = str(package_dir.parent)
+        if parent not in sys.path:
+            sys.path.insert(0, parent)
+        
+        try:
+            # Import the package
+            module = importlib.import_module(package_dir.name)
+            
+            # Look for tools
+            if hasattr(module, 'TOOLS'):
+                # Package exports TOOLS list
+                for tool_class in module.TOOLS:
+                    if issubclass(tool_class, BaseTool):
+                        plugin = ToolPlugin(
+                            name=tool_class.name,
+                            tool_class=tool_class,
+                            source_path=package_dir
+                        )
+                        self.plugins[tool_class.name] = plugin
+            else:
+                # Search for tool classes
+                for name, obj in inspect.getmembers(module):
+                    if (inspect.isclass(obj) and 
+                        issubclass(obj, BaseTool) and 
+                        obj != BaseTool and
+                        hasattr(obj, 'name')):
+                        
+                        plugin = ToolPlugin(
+                            name=obj.name,
+                            tool_class=obj,
+                            source_path=package_dir
+                        )
+                        self.plugins[obj.name] = plugin
+        finally:
+            # Remove from path
+            if parent in sys.path:
+                sys.path.remove(parent)
+    
+    def get_tool_class(self, name: str) -> Optional[Type[BaseTool]]:
+        """Get a tool class by name."""
+        plugin = self.plugins.get(name)
+        return plugin.tool_class if plugin else None
+    
+    def list_plugins(self) -> List[str]:
+        """List all loaded plugin names."""
+        return list(self.plugins.keys())
+
+
+# Global plugin loader instance
+_plugin_loader = PluginLoader()
+
+
+def load_user_plugins() -> Dict[str, ToolPlugin]:
+    """Load all user plugins."""
+    return _plugin_loader.load_plugins()
+
+
+def get_plugin_tool(name: str) -> Optional[Type[BaseTool]]:
+    """Get a plugin tool class by name."""
+    return _plugin_loader.get_tool_class(name)
+
+
+def list_plugin_tools() -> List[str]:
+    """List all available plugin tools."""
+    return _plugin_loader.list_plugins()
+
+
+def create_plugin_template(output_dir: Path, tool_name: str):
+    """Create a template for a new plugin tool."""
+    output_dir.mkdir(parents=True, exist_ok=True)
+    
+    # Create tool file
+    tool_file = output_dir / f"{tool_name}_tool.py"
+    tool_content = f'''"""Custom {tool_name} tool plugin."""
+
+from hanzo_mcp.tools.common.base import BaseTool
+from typing import Dict, Any
+
+
+class {tool_name.title()}Tool(BaseTool):
+    """Custom {tool_name} tool implementation."""
+    
+    name = "{tool_name}"
+    description = "Custom {tool_name} tool"
+    
+    async def run(self, params: Dict[str, Any], ctx) -> Dict[str, Any]:
+        """Execute the {tool_name} tool."""
+        # Get parameters
+        action = params.get("action", "default")
+        
+        # Implement your tool logic here
+        if action == "default":
+            return {{
+                "status": "success",
+                "message": f"Running {tool_name} tool",
+                "data": {{
+                    "params": params
+                }}
+            }}
+        
+        # Add more actions as needed
+        elif action == "custom_action":
+            # Your custom logic here
+            pass
+        
+        return {{
+            "status": "error",
+            "message": f"Unknown action: {{action}}"
+        }}
+
+
+# Optional: Export tools explicitly
+TOOLS = [{tool_name.title()}Tool]
+'''
+    
+    with open(tool_file, 'w') as f:
+        f.write(tool_content)
+    
+    # Create metadata file
+    metadata_file = output_dir / f"{tool_name}_tool.json"
+    metadata_content = {
+        "name": tool_name,
+        "version": "1.0.0",
+        "author": "Your Name",
+        "description": f"Custom {tool_name} tool",
+        "modes": ["custom"],  # Modes this tool should be added to
+        "dependencies": [],
+        "config": {
+            # Tool-specific configuration
+        }
+    }
+    
+    with open(metadata_file, 'w') as f:
+        json.dump(metadata_content, f, indent=2)
+    
+    # Create README
+    readme_file = output_dir / "README.md"
+    readme_content = f"""# {tool_name.title()} Tool Plugin
+
+Custom tool plugin for Hanzo MCP.
+
+## Installation
+
+1. Place this directory in one of:
+   - `~/.hanzo/plugins/`
+   - `./.hanzo/plugins/` (project-specific)
+   - Any path in `HANZO_PLUGIN_PATH` environment variable
+
+2. The tool will be automatically loaded when Hanzo MCP starts.
+
+## Usage
+
+The tool will be available as `{tool_name}` in any mode that includes it.
+
+## Configuration
+
+Edit the `{tool_name}_tool.json` file to:
+- Add the tool to specific modes
+- Configure tool-specific settings
+- Specify dependencies
+
+## Development
+
+Modify `{tool_name}_tool.py` to implement your custom functionality.
+"""
+    
+    with open(readme_file, 'w') as f:
+        f.write(readme_content)
+    
+    print(f"Created plugin template in {output_dir}")
+    print(f"Files created:")
+    print(f"  - {tool_file}")
+    print(f"  - {metadata_file}")
+    print(f"  - {readme_file}")

hanzo_mcp/tools/common/stats.py

@@ -43,7 +43,7 @@ class StatsTool(BaseTool):
     @override
     def description(self) -> str:
         """Get the tool description."""
-        return """Show comprehensive system and Hanzo MCP statistics.
+        return """Show comprehensive system and Hanzo AI statistics.
 
 Displays:
 - System resources (CPU, memory, disk)
@@ -79,7 +79,7 @@ Example:
         warnings = []
         
         # Header
-        output.append("=== Hanzo MCP System Statistics ===")
+        output.append("=== Hanzo AI System Statistics ===")
         output.append(f"Time: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
         output.append("")
         
@@ -205,8 +205,8 @@ Example:
         
         output.append("")
         
-        # Hanzo MCP Specifics
-        output.append("=== Hanzo MCP ===")
+        # Hanzo AI Specifics
+        output.append("=== Hanzo AI ===")
         
         # Log directory size
         log_dir = Path.home() / ".hanzo" / "logs"

hanzo_mcp/tools/common/tool_list.py

@@ -57,13 +57,14 @@ class ToolListTool(BaseTool):
             ("tree", "Directory tree visualization (Unix-style)"),
             ("find", "Find text in files (rg/ag/ack/grep)"),
             ("symbols", "Code symbols search with tree-sitter"),
-            ("search", "Unified search (parallel grep/symbols/vector/git)"),
+            ("search", "Search (parallel grep/symbols/vector/git)"),
             ("git_search", "Search git history"),
             ("glob", "Find files by name pattern"),
             ("content_replace", "Replace content across files"),
         ],
         "shell": [
             ("run_command", "Execute shell commands (--background option)"),
+            ("streaming_command", "Run commands with disk-based output streaming"),
             ("processes", "List background processes"),
             ("pkill", "Kill background processes"),
             ("logs", "View process logs"),
@@ -78,6 +79,8 @@ class ToolListTool(BaseTool):
         "ai": [
             ("llm", "LLM interface (query/consensus/list/models/enable/disable)"),
             ("agent", "AI agents (run/start/call/stop/list with A2A support)"),
+            ("swarm", "Parallel agent execution across multiple files"),
+            ("hierarchical_swarm", "Hierarchical agent teams with Claude Code integration"),
             ("mcp", "MCP servers (list/add/remove/enable/disable/restart)"),
         ],
         "config": [

hanzo_mcp/tools/common/truncate.py

@@ -0,0 +1,101 @@
+"""Response truncation utilities for MCP tools.
+
+This module provides utilities to ensure MCP tool responses don't exceed token limits.
+"""
+
+import tiktoken
+
+
+def estimate_tokens(text: str, model: str = "gpt-4") -> int:
+    """Estimate the number of tokens in a text string.
+    
+    Args:
+        text: The text to estimate tokens for
+        model: The model to use for token estimation (default: gpt-4)
+        
+    Returns:
+        Estimated number of tokens
+    """
+    try:
+        # Try to get the encoding for the specific model
+        encoding = tiktoken.encoding_for_model(model)
+    except KeyError:
+        # Fall back to cl100k_base which is used by newer models
+        encoding = tiktoken.get_encoding("cl100k_base")
+    
+    return len(encoding.encode(text))
+
+
+def truncate_response(
+    response: str, 
+    max_tokens: int = 20000,
+    truncation_message: str = "\n\n[Response truncated due to length. Please use pagination, filtering, or limit parameters to see more.]"
+) -> str:
+    """Truncate a response to fit within token limits.
+    
+    Args:
+        response: The response text to truncate
+        max_tokens: Maximum number of tokens allowed (default: 20000)
+        truncation_message: Message to append when truncating
+        
+    Returns:
+        Truncated response if needed, original response otherwise
+    """
+    # Quick check - if response is short, no need to count tokens
+    if len(response) < max_tokens * 2:  # Rough estimate: 1 token ≈ 2-4 chars
+        return response
+    
+    # Estimate tokens
+    token_count = estimate_tokens(response)
+    
+    # If within limit, return as-is
+    if token_count <= max_tokens:
+        return response
+    
+    # Need to truncate
+    # Binary search to find the right truncation point
+    left, right = 0, len(response)
+    truncation_msg_tokens = estimate_tokens(truncation_message)
+    target_tokens = max_tokens - truncation_msg_tokens
+    
+    while left < right - 1:
+        mid = (left + right) // 2
+        mid_tokens = estimate_tokens(response[:mid])
+        
+        if mid_tokens <= target_tokens:
+            left = mid
+        else:
+            right = mid
+    
+    # Find a good break point (newline or space)
+    truncate_at = left
+    for i in range(min(100, left), -1, -1):
+        if response[left - i] in '\n ':
+            truncate_at = left - i
+            break
+    
+    return response[:truncate_at] + truncation_message
+
+
+def truncate_lines(
+    response: str,
+    max_lines: int = 1000,
+    truncation_message: str = "\n\n[Response truncated to {max_lines} lines. Please use pagination or filtering to see more.]"
+) -> str:
+    """Truncate a response by number of lines.
+    
+    Args:
+        response: The response text to truncate
+        max_lines: Maximum number of lines allowed (default: 1000)
+        truncation_message: Message template to append when truncating
+        
+    Returns:
+        Truncated response if needed, original response otherwise
+    """
+    lines = response.split('\n')
+    
+    if len(lines) <= max_lines:
+        return response
+    
+    truncated = '\n'.join(lines[:max_lines])
+    return truncated + truncation_message.format(max_lines=max_lines)

hanzo_mcp/tools/common/validation.py

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

hanzo_mcp/tools/config/__init__.py

@@ -1,10 +1,12 @@
-"""Configuration tools for Hanzo MCP."""
+"""Configuration tools for Hanzo AI."""
 
 from hanzo_mcp.tools.config.config_tool import ConfigTool
 from hanzo_mcp.tools.config.index_config import IndexConfig, IndexScope
+from hanzo_mcp.tools.config.mode_tool import mode_tool
 
 __all__ = [
     "ConfigTool",
     "IndexConfig", 
     "IndexScope",
+    "mode_tool",
 ]

hanzo_mcp/tools/config/config_tool.py

@@ -1,4 +1,4 @@
-"""Configuration tool for Hanzo MCP.
+"""Configuration tool for Hanzo AI.
 
 Git-style config tool for managing settings.
 """

hanzo_mcp/tools/config/mode_tool.py

@@ -0,0 +1,209 @@
+"""Tool for managing development modes with programmer personalities."""
+
+from typing import Optional, override
+
+from mcp.server.fastmcp import Context as MCPContext
+
+from hanzo_mcp.tools.common.base import BaseTool
+from hanzo_mcp.tools.common.mode import ModeRegistry, register_default_modes
+from mcp.server import FastMCP
+
+
+class ModeTool(BaseTool):
+    """Tool for managing development modes."""
+    
+    name = "mode"
+    
+    def __init__(self):
+        """Initialize the mode tool."""
+        super().__init__()
+        # Register default modes on initialization
+        register_default_modes()
+    
+    @property
+    @override
+    def description(self) -> str:
+        """Get the tool description."""
+        return """Manage development modes (programmer personalities). Actions: list (default), activate, show, current.
+
+Usage:
+mode
+mode --action list
+mode --action activate guido
+mode --action show linus
+mode --action current"""
+    
+    @override
+    async def run(
+        self,
+        ctx: MCPContext,
+        action: str = "list",
+        name: Optional[str] = None,
+    ) -> str:
+        """Manage development modes.
+        
+        Args:
+            ctx: MCP context
+            action: Action to perform (list, activate, show, current)
+            name: Mode name (for activate/show actions)
+            
+        Returns:
+            Action result
+        """
+        if action == "list":
+            modes = ModeRegistry.list()
+            if not modes:
+                return "No modes registered"
+            
+            output = ["Available development modes (100 programmer personalities):"]
+            active = ModeRegistry.get_active()
+            
+            # Group modes by category
+            categories = {
+                "Language Creators": ["guido", "matz", "brendan", "dennis", "bjarne", "james", "anders", "larry", "rasmus", "rich"],
+                "Systems & Infrastructure": ["linus", "rob", "ken", "bill", "richard", "brian", "donald", "graydon", "ryan", "mitchell"],
+                "Web & Frontend": ["tim", "douglas", "john", "evan", "jordan", "jeremy", "david", "taylor", "adrian", "matt"],
+                "Database & Data": ["michael_s", "michael_w", "salvatore", "dwight", "edgar", "jim_gray", "jeff_dean", "sanjay", "mike", "matei"],
+                "AI & Machine Learning": ["yann", "geoffrey", "yoshua", "andrew", "demis", "ilya", "andrej", "chris", "francois", "jeremy_howard"],
+                "Security & Cryptography": ["bruce", "phil", "whitfield", "ralph", "daniel_b", "moxie", "theo", "dan_kaminsky", "katie", "matt_blaze"],
+                "Gaming & Graphics": ["john_carmack", "sid", "shigeru", "gabe", "markus", "jonathan", "casey", "tim_sweeney", "hideo", "will"],
+                "Open Source Leaders": ["miguel", "nat", "patrick", "ian", "mark_shuttleworth", "lennart", "bram", "daniel_r", "judd", "fabrice"],
+                "Modern Innovators": ["vitalik", "satoshi", "chris_lattner", "joe", "jose", "sebastian", "palmer", "dylan", "guillermo", "tom"],
+                "Special Configurations": ["fullstack", "minimal", "data_scientist", "devops", "security", "academic", "startup", "enterprise", "creative", "hanzo"],
+            }
+            
+            for category, mode_names in categories.items():
+                output.append(f"\n{category}:")
+                for mode_name in mode_names:
+                    mode = next((m for m in modes if m.name == mode_name), None)
+                    if mode:
+                        marker = " (active)" if active and active.name == mode.name else ""
+                        output.append(f"  {mode.name}{marker}: {mode.programmer} - {mode.description}")
+            
+            output.append("\nUse 'mode --action activate <name>' to activate a mode")
+            
+            return "\n".join(output)
+        
+        elif action == "activate":
+            if not name:
+                return "Error: Mode name required for activate action"
+            
+            try:
+                ModeRegistry.set_active(name)
+                mode = ModeRegistry.get(name)
+                
+                output = [f"Activated mode: {mode.name}"]
+                output.append(f"Programmer: {mode.programmer}")
+                output.append(f"Description: {mode.description}")
+                if mode.philosophy:
+                    output.append(f"Philosophy: {mode.philosophy}")
+                output.append(f"\nEnabled tools ({len(mode.tools)}):")
+                
+                # Group tools by category
+                core_tools = []
+                package_tools = []
+                ai_tools = []
+                search_tools = []
+                other_tools = []
+                
+                for tool in sorted(mode.tools):
+                    if tool in ["read", "write", "edit", "multi_edit", "bash", "tree", "grep"]:
+                        core_tools.append(tool)
+                    elif tool in ["npx", "uvx", "pip", "cargo", "gem"]:
+                        package_tools.append(tool)
+                    elif tool in ["agent", "consensus", "critic", "think"]:
+                        ai_tools.append(tool)
+                    elif tool in ["search", "symbols", "git_search"]:
+                        search_tools.append(tool)
+                    else:
+                        other_tools.append(tool)
+                
+                if core_tools:
+                    output.append(f"  Core: {', '.join(core_tools)}")
+                if package_tools:
+                    output.append(f"  Package managers: {', '.join(package_tools)}")
+                if ai_tools:
+                    output.append(f"  AI tools: {', '.join(ai_tools)}")
+                if search_tools:
+                    output.append(f"  Search: {', '.join(search_tools)}")
+                if other_tools:
+                    output.append(f"  Specialized: {', '.join(other_tools)}")
+                
+                if mode.environment:
+                    output.append("\nEnvironment variables:")
+                    for key, value in mode.environment.items():
+                        output.append(f"  {key}={value}")
+                
+                output.append("\nNote: Restart MCP session for changes to take full effect")
+                
+                return "\n".join(output)
+                
+            except ValueError as e:
+                return str(e)
+        
+        elif action == "show":
+            if not name:
+                return "Error: Mode name required for show action"
+            
+            mode = ModeRegistry.get(name)
+            if not mode:
+                return f"Mode '{name}' not found"
+            
+            output = [f"Mode: {mode.name}"]
+            output.append(f"Programmer: {mode.programmer}")
+            output.append(f"Description: {mode.description}")
+            if mode.philosophy:
+                output.append(f"Philosophy: {mode.philosophy}")
+            output.append(f"\nTools ({len(mode.tools)}):")
+            
+            for tool in sorted(mode.tools):
+                output.append(f"  - {tool}")
+            
+            if mode.environment:
+                output.append("\nEnvironment:")
+                for key, value in mode.environment.items():
+                    output.append(f"  {key}={value}")
+            
+            return "\n".join(output)
+        
+        elif action == "current":
+            active = ModeRegistry.get_active()
+            if not active:
+                return "No mode currently active\nUse 'mode --action activate <name>' to activate one"
+            
+            output = [f"Current mode: {active.name}"]
+            output.append(f"Programmer: {active.programmer}")
+            output.append(f"Description: {active.description}")
+            if active.philosophy:
+                output.append(f"Philosophy: {active.philosophy}")
+            output.append(f"Enabled tools: {len(active.tools)}")
+            
+            return "\n".join(output)
+        
+        else:
+            return f"Unknown action: {action}. Use 'list', 'activate', 'show', or 'current'"
+
+    def register(self, server: FastMCP) -> None:
+        """Register the tool with the MCP server."""
+        tool_self = self
+        
+        @server.tool(name=self.name, description=self.description)
+        async def mode_handler(
+            ctx: MCPContext,
+            action: str = "list",
+            name: Optional[str] = None
+        ) -> str:
+            """Handle mode tool calls."""
+            return await tool_self.run(ctx, action=action, name=name)
+    
+    async def call(self, ctx: MCPContext, **params) -> str:
+        """Call the tool with arguments."""
+        return await self.run(
+            ctx,
+            action=params.get("action", "list"),
+            name=params.get("name")
+        )
+
+
+# Create tool instance
+mode_tool = ModeTool()

hanzo_mcp/tools/database/__init__.py

@@ -1,4 +1,4 @@
-"""Database tools for Hanzo MCP.
+"""Database tools for Hanzo AI.
 
 This package provides tools for working with embedded SQLite databases
 and graph databases in projects.