hanzo-mcp 0.8.3__py3-none-any.whl → 0.8.4__py3-none-any.whl

hanzo_mcp/tools/shell/zsh_tool.py

@@ -0,0 +1,266 @@
+"""Zsh shell tool for command execution with enhanced features."""
+
+import os
+import shutil
+import platform
+from typing import Optional, override
+from pathlib import Path
+
+from mcp.server import FastMCP
+from mcp.server.fastmcp import Context as MCPContext
+
+from hanzo_mcp.tools.shell.base_process import BaseScriptTool
+
+
+class ZshTool(BaseScriptTool):
+    """Tool for running commands in Zsh shell with enhanced features."""
+
+    name = "zsh"
+
+    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 zsh(
+            ctx: MCPContext,
+            command: str,
+            cwd: Optional[str] = None,
+            env: Optional[dict[str, str]] = None,
+            timeout: Optional[int] = None,
+        ) -> str:
+            return await tool_self.run(
+                ctx, command=command, cwd=cwd, env=env, timeout=timeout
+            )
+
+    async def call(self, ctx: MCPContext, **params) -> str:
+        """Call the tool with arguments."""
+        return await self.run(
+            ctx,
+            command=params["command"],
+            cwd=params.get("cwd"),
+            env=params.get("env"),
+            timeout=params.get("timeout"),
+        )
+
+    @property
+    @override
+    def description(self) -> str:
+        """Get the tool description."""
+        return """Run commands in Zsh shell with enhanced features like better globbing and completion.
+
+Zsh provides advanced features over bash:
+- Extended globbing patterns
+- Better tab completion
+- Array and associative array support
+- Powerful command line editing
+- Plugin ecosystem (oh-my-zsh, etc.)
+
+Commands that run for more than 2 minutes will automatically continue in the background.
+
+Usage:
+zsh "ls -la"
+zsh "echo $ZSH_VERSION"
+zsh "git status && git diff"
+zsh "npm run dev" --cwd ./frontend  # Auto-backgrounds if needed"""
+
+    @override
+    def get_interpreter(self) -> str:
+        """Get the zsh interpreter path."""
+        if platform.system() == "Windows":
+            # Try to find zsh on Windows (WSL, Git Bash, etc.)
+            zsh_paths = [
+                "C:\\Program Files\\Git\\usr\\bin\\zsh.exe",
+                "C:\\cygwin64\\bin\\zsh.exe",
+                "C:\\msys64\\usr\\bin\\zsh.exe",
+            ]
+            for path in zsh_paths:
+                if Path(path).exists():
+                    return path
+            # Fall back to bash if no zsh found
+            return "bash"
+        
+        # On Unix-like systems, check for zsh
+        zsh_path = shutil.which("zsh")
+        if zsh_path:
+            return zsh_path
+        
+        # Fall back to bash if zsh not found
+        return "bash"
+
+    @override
+    def get_script_flags(self) -> list[str]:
+        """Get interpreter flags."""
+        if platform.system() == "Windows" and self.get_interpreter().endswith(".exe"):
+            return ["-c"]
+        return ["-c"]
+
+    @override
+    def get_tool_name(self) -> str:
+        """Get the tool name."""
+        return "zsh"
+
+    @override
+    async def run(
+        self,
+        ctx: MCPContext,
+        command: str,
+        cwd: Optional[str] = None,
+        env: Optional[dict[str, str]] = None,
+        timeout: Optional[int] = None,
+    ) -> str:
+        """Run a zsh command with auto-backgrounding.
+
+        Args:
+            ctx: MCP context
+            command: Zsh command to execute
+            cwd: Working directory
+            env: Environment variables
+            timeout: Command timeout in seconds (ignored - auto-backgrounds after 2 minutes)
+
+        Returns:
+            Command output or background status
+        """
+        # Check if zsh is available
+        if not shutil.which("zsh") and platform.system() != "Windows":
+            return "Error: Zsh is not installed. Please install zsh first."
+        
+        # Prepare working directory
+        work_dir = Path(cwd).resolve() if cwd else Path.cwd()
+
+        # Use execute_sync which has auto-backgrounding
+        output = await self.execute_sync(
+            command, cwd=work_dir, env=env, timeout=timeout
+        )
+        return output if output else "Command completed successfully (no output)"
+
+
+class ShellTool(BaseScriptTool):
+    """Smart shell tool that uses the best available shell (zsh > bash)."""
+
+    name = "shell"
+
+    def __init__(self):
+        """Initialize and detect the best shell."""
+        super().__init__()
+        self._best_shell = self._detect_best_shell()
+
+    def _detect_best_shell(self) -> str:
+        """Detect the best available shell."""
+        # Check for zsh first
+        if shutil.which("zsh"):
+            # Also check if .zshrc exists
+            if (Path.home() / ".zshrc").exists():
+                return "zsh"
+        
+        # Check for user's preferred shell
+        user_shell = os.environ.get("SHELL", "")
+        if user_shell and Path(user_shell).exists():
+            return user_shell
+        
+        # Default to bash
+        return "bash"
+
+    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 shell(
+            ctx: MCPContext,
+            command: str,
+            cwd: Optional[str] = None,
+            env: Optional[dict[str, str]] = None,
+            timeout: Optional[int] = None,
+        ) -> str:
+            return await tool_self.run(
+                ctx, command=command, cwd=cwd, env=env, timeout=timeout
+            )
+
+    async def call(self, ctx: MCPContext, **params) -> str:
+        """Call the tool with arguments."""
+        return await self.run(
+            ctx,
+            command=params["command"],
+            cwd=params.get("cwd"),
+            env=params.get("env"),
+            timeout=params.get("timeout"),
+        )
+
+    @property
+    @override
+    def description(self) -> str:
+        """Get the tool description."""
+        return f"""Run shell commands using the best available shell (currently: {os.path.basename(self._best_shell)}).
+
+Automatically selects:
+- Zsh if available (with .zshrc)
+- User's preferred shell ($SHELL)
+- Bash as fallback
+
+Commands that run for more than 2 minutes will automatically continue in the background.
+
+Usage:
+shell "ls -la"
+shell "echo $SHELL"  # Shows which shell is being used
+shell "git status && git diff"
+shell "npm run dev" --cwd ./frontend  # Auto-backgrounds if needed"""
+
+    @override
+    def get_interpreter(self) -> str:
+        """Get the best shell interpreter."""
+        return self._best_shell
+
+    @override
+    def get_script_flags(self) -> list[str]:
+        """Get interpreter flags."""
+        if platform.system() == "Windows":
+            return ["/c"] if self._best_shell == "cmd.exe" else ["-c"]
+        return ["-c"]
+
+    @override
+    def get_tool_name(self) -> str:
+        """Get the tool name."""
+        return "shell"
+
+    @override
+    async def run(
+        self,
+        ctx: MCPContext,
+        command: str,
+        cwd: Optional[str] = None,
+        env: Optional[dict[str, str]] = None,
+        timeout: Optional[int] = None,
+    ) -> str:
+        """Run a shell command with auto-backgrounding.
+
+        Args:
+            ctx: MCP context
+            command: Shell command to execute
+            cwd: Working directory
+            env: Environment variables
+            timeout: Command timeout in seconds (ignored - auto-backgrounds after 2 minutes)
+
+        Returns:
+            Command output or background status
+        """
+        # Prepare working directory
+        work_dir = Path(cwd).resolve() if cwd else Path.cwd()
+
+        # Add shell info to output if verbose
+        shell_name = os.path.basename(self._best_shell)
+        
+        # Use execute_sync which has auto-backgrounding
+        output = await self.execute_sync(
+            command, cwd=work_dir, env=env, timeout=timeout
+        )
+        
+        if output:
+            return output
+        else:
+            return f"Command completed successfully in {shell_name} (no output)"
+
+
+# Create tool instances
+zsh_tool = ZshTool()
+shell_tool = ShellTool()  # Smart shell that prefers zsh

hanzo_mcp-0.8.4.dist-info/METADATA

@@ -0,0 +1,411 @@
+Metadata-Version: 2.4
+Name: hanzo-mcp
+Version: 0.8.4
+Summary: The Zen of Hanzo MCP: One server to rule them all. The ultimate MCP that orchestrates all others.
+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://mcp.hanzo.ai
+Keywords: mcp,claude,hanzo,code,agent
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.9.4
+Requires-Dist: fastmcp>=2.9.2
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: uvicorn>=0.34.0
+Requires-Dist: openai>=1.62.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: litellm>=1.73.2
+Requires-Dist: grep-ast>=0.8.1
+Requires-Dist: bashlex>=0.18
+Requires-Dist: libtmux>=0.39.0
+Requires-Dist: nbformat>=5.10.4
+Requires-Dist: psutil>=6.0.0
+Requires-Dist: pydantic>=2.9.2
+Requires-Dist: pydantic-settings>=2.7.0
+Requires-Dist: typing-extensions>=4.13.0
+Requires-Dist: watchdog>=6.0.0
+Requires-Dist: keyring>=24.0.0
+Requires-Dist: ffind>=1.3.0
+Provides-Extra: dev
+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>=3.0.0; extra == "dev"
+Requires-Dist: myst-parser>=4.0.0; extra == "dev"
+Requires-Dist: sphinx-copybutton>=0.5.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+Requires-Dist: types-aiofiles>=23.2.0; extra == "dev"
+Requires-Dist: types-psutil>=5.9.5; extra == "dev"
+Requires-Dist: types-setuptools>=69.5.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=8.0.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=3.0.0; extra == "docs"
+Requires-Dist: myst-parser>=4.0.0; extra == "docs"
+Requires-Dist: sphinx-copybutton>=0.5.0; extra == "docs"
+Provides-Extra: analytics
+Requires-Dist: posthog>=3.0.0; extra == "analytics"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-cov>=4.1.0; extra == "test"
+Requires-Dist: pytest-mock>=3.10.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.25.3; extra == "test"
+Requires-Dist: twisted; extra == "test"
+Provides-Extra: agents
+Requires-Dist: hanzo-agents>=0.1.0; extra == "agents"
+Provides-Extra: memory
+Requires-Dist: hanzo-memory>=1.0.0; extra == "memory"
+Provides-Extra: performance
+Requires-Dist: ujson>=5.7.0; extra == "performance"
+Requires-Dist: orjson>=3.9.0; extra == "performance"
+Provides-Extra: publish
+Requires-Dist: twine>=4.0.2; extra == "publish"
+Requires-Dist: build>=1.0.3; extra == "publish"
+
+# Hanzo Model Context Protocol (MCP)
+
+[![PyPI](https://img.shields.io/pypi/v/hanzo-mcp.svg)](https://pypi.org/project/hanzo-mcp/)
+[![Python Version](https://img.shields.io/pypi/pyversions/hanzo-mcp.svg)](https://pypi.org/project/hanzo-mcp/)
+
+Model Context Protocol implementation for advanced tool use and context management.
+
+## Installation
+
+```bash
+pip install hanzo-mcp
+```
+
+## Features
+
+- **Tool Management**: Register and manage AI tools
+- **File Operations**: Read, write, edit files
+- **Code Intelligence**: AST analysis, symbol search
+- **Shell Execution**: Run commands safely
+- **Agent Delegation**: Recursive agent capabilities
+- **Memory Integration**: Persistent context storage
+- **Batch Operations**: Execute multiple tools efficiently
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from hanzo_mcp import create_mcp_server
+
+# Create MCP server
+server = create_mcp_server()
+
+# Register tools
+server.register_filesystem_tools()
+server.register_shell_tools()
+server.register_agent_tools()
+
+# Start server
+await server.start()
+```
+
+### Tool Categories
+
+#### Filesystem Tools
+
+```python
+# Read file
+content = await server.tools.read(file_path="/path/to/file.py")
+
+# Write file
+await server.tools.write(
+    file_path="/path/to/new.py",
+    content="print('Hello')"
+)
+
+# Edit file
+await server.tools.edit(
+    file_path="/path/to/file.py",
+    old_string="old code",
+    new_string="new code"
+)
+
+# Multi-edit
+await server.tools.multi_edit(
+    file_path="/path/to/file.py",
+    edits=[
+        {"old_string": "foo", "new_string": "bar"},
+        {"old_string": "baz", "new_string": "qux"}
+    ]
+)
+```
+
+#### Search Tools
+
+```python
+# Unified search (grep + AST + semantic)
+results = await server.tools.search(
+    pattern="function_name",
+    path="/project"
+)
+
+# AST-aware search
+results = await server.tools.grep_ast(
+    pattern="class.*Service",
+    path="/src"
+)
+
+# Symbol search
+symbols = await server.tools.symbols(
+    pattern="def test_",
+    path="/tests"
+)
+```
+
+#### Shell Tools
+
+```python
+# Run command
+result = await server.tools.bash(
+    command="ls -la",
+    cwd="/project"
+)
+
+# Run with auto-backgrounding
+result = await server.tools.bash(
+    command="python server.py",
+    timeout=120000  # Auto-backgrounds after 2 min
+)
+
+# Manage processes
+processes = await server.tools.process(action="list")
+logs = await server.tools.process(
+    action="logs",
+    id="bash_abc123"
+)
+```
+
+#### Agent Tools
+
+```python
+# Dispatch agent for complex tasks
+result = await server.tools.dispatch_agent(
+    prompt="Analyze the codebase architecture",
+    path="/project"
+)
+
+# Network of agents
+result = await server.tools.network(
+    task="Implement user authentication",
+    agents=["architect", "developer", "tester"]
+)
+
+# CLI tool integration
+result = await server.tools.claude(
+    args=["--analyze", "main.py"]
+)
+```
+
+#### Batch Operations
+
+```python
+# Execute multiple tools in parallel
+results = await server.tools.batch(
+    description="Read multiple files",
+    invocations=[
+        {"tool_name": "read", "input": {"file_path": "file1.py"}},
+        {"tool_name": "read", "input": {"file_path": "file2.py"}},
+        {"tool_name": "grep", "input": {"pattern": "TODO"}}
+    ]
+)
+```
+
+## Advanced Features
+
+### Custom Tools
+
+```python
+from hanzo_mcp import Tool
+
+class MyCustomTool(Tool):
+    name = "my_tool"
+    description = "Custom tool"
+    
+    async def call(self, ctx, **params):
+        # Tool implementation
+        return "Result"
+
+# Register custom tool
+server.register_tool(MyCustomTool())
+```
+
+### Permission Management
+
+```python
+from hanzo_mcp import PermissionManager
+
+# Create permission manager
+pm = PermissionManager()
+
+# Set permission mode
+pm.set_mode("review")  # review, auto_approve, auto_deny
+
+# Check permission
+allowed = await pm.check_permission(
+    tool="write",
+    params={"file_path": "/etc/passwd"}
+)
+```
+
+### Context Management
+
+```python
+from hanzo_mcp import ToolContext
+
+# Create context
+ctx = ToolContext(
+    cwd="/project",
+    env={"API_KEY": "secret"},
+    timeout=30000
+)
+
+# Use with tools
+result = await tool.call(ctx, **params)
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# API keys for agent tools
+ANTHROPIC_API_KEY=sk-ant-...
+OPENAI_API_KEY=sk-...
+
+# Tool settings
+MCP_PERMISSION_MODE=review
+MCP_MAX_FILE_SIZE=10485760
+MCP_TIMEOUT=120000
+
+# Search settings
+MCP_SEARCH_IGNORE=node_modules,*.pyc
+MCP_SEARCH_MAX_RESULTS=100
+```
+
+### Configuration File
+
+```yaml
+tools:
+  filesystem:
+    enabled: true
+    max_file_size: 10MB
+    allowed_paths:
+      - /home/user/projects
+      - /tmp
+    
+  shell:
+    enabled: true
+    timeout: 120000
+    auto_background: true
+    
+  agent:
+    enabled: true
+    models:
+      - claude-3-opus
+      - gpt-4
+    
+  search:
+    ignore_patterns:
+      - node_modules
+      - "*.pyc"
+      - .git
+    max_results: 100
+
+permissions:
+  mode: review  # review, auto_approve, auto_deny
+  whitelist:
+    - read
+    - grep
+    - search
+  blacklist:
+    - rm
+    - sudo
+```
+
+## CLI Usage
+
+### Installation to Claude Desktop
+
+```bash
+# Install to Claude Desktop
+hanzo-mcp install-desktop
+
+# Serve MCP
+hanzo-mcp serve --port 3000
+```
+
+### Standalone Server
+
+```bash
+# Start MCP server
+hanzo-mcp serve
+
+# With custom config
+hanzo-mcp serve --config mcp-config.yaml
+
+# With specific tools
+hanzo-mcp serve --tools filesystem,shell,agent
+```
+
+## Development
+
+### Setup
+
+```bash
+cd pkg/hanzo-mcp
+uv sync --all-extras
+```
+
+### Testing
+
+```bash
+# Unit tests
+pytest tests/ -v
+
+# Integration tests
+pytest tests/ -m integration
+
+# With coverage
+pytest tests/ --cov=hanzo_mcp
+```
+
+### Building
+
+```bash
+uv build
+```
+
+## Architecture
+
+### Tool Categories
+
+- **Filesystem**: File operations (read, write, edit)
+- **Search**: Code search (grep, AST, semantic)
+- **Shell**: Command execution and process management
+- **Agent**: AI agent delegation and orchestration
+- **Memory**: Context and knowledge persistence
+- **Config**: Configuration management
+- **LLM**: Direct LLM interactions
+
+### Security
+
+- Permission system for dangerous operations
+- Path validation and sandboxing
+- Command injection protection
+- Rate limiting on operations
+- Audit logging
+
+## License
+
+Apache License 2.0