hanzo-mcp 0.5.1__py3-none-any.whl → 0.6.1__py3-none-any.whl

hanzo_mcp/tools/shell/uvx_background.py

@@ -0,0 +1,249 @@
+"""Run Python packages in background with uvx."""
+
+import subprocess
+import shutil
+import uuid
+from typing import Annotated, Optional, TypedDict, Unpack, final, override
+
+from mcp.server.fastmcp import Context as MCPContext
+from pydantic import Field
+
+from hanzo_mcp.tools.common.base import BaseTool
+from hanzo_mcp.tools.common.context import create_tool_context
+from hanzo_mcp.tools.common.permissions import PermissionManager
+from hanzo_mcp.tools.shell.run_background import BackgroundProcess, RunBackgroundTool
+
+
+Package = Annotated[
+    str,
+    Field(
+        description="Package name to run (e.g., 'streamlit', 'jupyter-lab', 'mkdocs')",
+        min_length=1,
+    ),
+]
+
+Args = Annotated[
+    Optional[str],
+    Field(
+        description="Arguments to pass to the package",
+        default=None,
+    ),
+]
+
+Name = Annotated[
+    Optional[str],
+    Field(
+        description="Process name for identification",
+        default=None,
+    ),
+]
+
+PythonVersion = Annotated[
+    Optional[str],
+    Field(
+        description="Python version to use (e.g., '3.11', '3.12')",
+        default=None,
+    ),
+]
+
+LogOutput = Annotated[
+    bool,
+    Field(
+        description="Log output to file in ~/.hanzo/logs",
+        default=True,
+    ),
+]
+
+WorkingDir = Annotated[
+    Optional[str],
+    Field(
+        description="Working directory for the process",
+        default=None,
+    ),
+]
+
+
+class UvxBackgroundParams(TypedDict, total=False):
+    """Parameters for uvx background tool."""
+
+    package: str
+    args: Optional[str]
+    name: Optional[str]
+    python_version: Optional[str]
+    log_output: bool
+    working_dir: Optional[str]
+
+
+@final
+class UvxBackgroundTool(BaseTool):
+    """Tool for running Python packages in background with uvx."""
+
+    def __init__(self, permission_manager: PermissionManager):
+        """Initialize the uvx background tool.
+
+        Args:
+            permission_manager: Permission manager for access control
+        """
+        self.permission_manager = permission_manager
+
+    @property
+    @override
+    def name(self) -> str:
+        """Get the tool name."""
+        return "uvx_background"
+
+    @property
+    @override
+    def description(self) -> str:
+        """Get the tool description."""
+        return """Run Python packages in the background using uvx.
+
+Perfect for running servers and long-running Python applications.
+The process continues running even after the command returns.
+
+Common server packages:
+- streamlit: Data app framework
+- jupyter-lab: Jupyter Lab server
+- mkdocs: Documentation server
+- fastapi: FastAPI with uvicorn
+- flask: Flask development server
+- gradio: ML model demos
+- panel: Data app framework
+
+Examples:
+- uvx_background --package streamlit --args "run app.py --port 8501" --name streamlit-app
+- uvx_background --package jupyter-lab --args "--port 8888" --name jupyter
+- uvx_background --package mkdocs --args "serve --dev-addr 0.0.0.0:8000" --name docs
+- uvx_background --package gradio --args "app.py" --name ml-demo
+
+Use 'processes' to list running processes and 'pkill' to stop them.
+"""
+
+    @override
+    async def call(
+        self,
+        ctx: MCPContext,
+        **params: Unpack[UvxBackgroundParams],
+    ) -> str:
+        """Execute uvx command in background.
+
+        Args:
+            ctx: MCP context
+            **params: Tool parameters
+
+        Returns:
+            Process information
+        """
+        tool_ctx = create_tool_context(ctx)
+        await tool_ctx.set_tool_info(self.name)
+
+        # Extract parameters
+        package = params.get("package")
+        if not package:
+            return "Error: package is required"
+
+        args = params.get("args", "")
+        name = params.get("name", f"uvx-{package}")
+        python_version = params.get("python_version")
+        log_output = params.get("log_output", True)
+        working_dir = params.get("working_dir")
+
+        # Check if uvx is available
+        if not shutil.which("uvx"):
+            return """Error: uvx is not installed. Install it with:
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+Or on macOS:
+brew install uv"""
+
+        # Build command
+        cmd = ["uvx"]
+        
+        if python_version:
+            cmd.extend(["--python", python_version])
+        
+        cmd.append(package)
+        
+        # Add package arguments
+        if args:
+            # Split args properly (basic parsing)
+            import shlex
+            cmd.extend(shlex.split(args))
+
+        # Generate process ID
+        process_id = str(uuid.uuid4())[:8]
+        
+        # Prepare log file if needed
+        log_file = None
+        if log_output:
+            from pathlib import Path
+            log_dir = Path.home() / ".hanzo" / "logs"
+            log_dir.mkdir(parents=True, exist_ok=True)
+            log_file = log_dir / f"{name}_{process_id}.log"
+
+        await tool_ctx.info(f"Starting background process: {' '.join(cmd)}")
+
+        try:
+            # Start process
+            if log_output and log_file:
+                with open(log_file, "w") as f:
+                    process = subprocess.Popen(
+                        cmd,
+                        stdout=f,
+                        stderr=subprocess.STDOUT,
+                        cwd=working_dir,
+                        start_new_session=True
+                    )
+            else:
+                process = subprocess.Popen(
+                    cmd,
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    cwd=working_dir,
+                    start_new_session=True
+                )
+
+            # Create background process object
+            bg_process = BackgroundProcess(
+                process_id=process_id,
+                command=" ".join(cmd),
+                name=name,
+                process=process,
+                log_file=str(log_file) if log_file else None,
+                working_dir=working_dir
+            )
+
+            # Register with RunBackgroundTool
+            RunBackgroundTool._add_process(bg_process)
+
+            output = [
+                f"Started uvx background process:",
+                f"  ID: {process_id}",
+                f"  Name: {name}",
+                f"  Package: {package}",
+                f"  PID: {process.pid}",
+                f"  Command: {' '.join(cmd)}",
+            ]
+            
+            if working_dir:
+                output.append(f"  Working Dir: {working_dir}")
+            
+            if log_file:
+                output.append(f"  Log: {log_file}")
+            
+            output.extend([
+                "",
+                "Use 'processes' to list running processes.",
+                f"Use 'logs --process-id {process_id}' to view output.",
+                f"Use 'pkill --process-id {process_id}' to stop."
+            ])
+
+            return "\n".join(output)
+
+        except Exception as e:
+            await tool_ctx.error(f"Failed to start process: {str(e)}")
+            return f"Error starting uvx background process: {str(e)}"
+
+    def register(self, mcp_server) -> None:
+        """Register this tool with the MCP server."""
+        pass

hanzo_mcp/tools/shell/uvx_unified.py

@@ -0,0 +1,101 @@
+"""UVX tool for both sync and background execution."""
+
+from pathlib import Path
+from typing import Optional, override
+
+from mcp.server.fastmcp import Context as MCPContext
+
+from hanzo_mcp.tools.shell.base_process import BaseBinaryTool
+from mcp.server import FastMCP
+
+
+class UvxTool(BaseBinaryTool):
+    """Tool for running uvx commands."""
+    
+    name = "uvx"
+    
+    @property
+    @override
+    def description(self) -> str:
+        """Get the tool description."""
+        return """Run Python packages with uvx. Actions: run (default), background.
+
+Usage:
+uvx ruff check .
+uvx --action background mkdocs serve
+uvx black --check src/
+uvx --action background jupyter lab --port 8888"""
+    
+    @override
+    def get_binary_name(self) -> str:
+        """Get the binary name."""
+        return "uvx"
+    
+    @override
+    async def run(
+        self,
+        ctx: MCPContext,
+        package: str,
+        args: str = "",
+        action: str = "run",
+        cwd: Optional[str] = None,
+        python: Optional[str] = None,
+    ) -> str:
+        """Run a uvx command.
+        
+        Args:
+            ctx: MCP context
+            package: Python package to run
+            args: Additional arguments
+            action: Action to perform (run, background)
+            cwd: Working directory
+            python: Python version constraint
+            
+        Returns:
+            Command output or process info
+        """
+        # Prepare working directory
+        work_dir = Path(cwd).resolve() if cwd else Path.cwd()
+        
+        # Prepare flags
+        flags = []
+        if python:
+            flags.extend(["--python", python])
+        
+        # Build full command
+        full_args = args.split() if args else []
+        
+        if action == "background":
+            result = await self.execute_background(
+                package,
+                cwd=work_dir,
+                flags=flags,
+                args=full_args
+            )
+            return (
+                f"Started uvx process in background\n"
+                f"Process ID: {result['process_id']}\n"
+                f"PID: {result['pid']}\n"
+                f"Log file: {result['log_file']}"
+            )
+        else:
+            # Default to sync execution
+            return await self.execute_sync(
+                package,
+                cwd=work_dir,
+                flags=flags,
+                args=full_args,
+                timeout=300  # 5 minute timeout for uvx
+            )
+
+    def register(self, server: FastMCP) -> None:
+        """Register the tool with the MCP server."""
+        server.tool(name=self.name, description=self.description)(self.call)
+    
+    async def call(self, **kwargs) -> str:
+        """Call the tool with arguments."""
+        return await self.run(None, **kwargs)
+
+
+# Create tool instance
+uvx_tool = UvxTool()

hanzo_mcp/tools/todo/__init__.py

@@ -4,7 +4,7 @@ This package provides tools for managing todo lists across different Claude Desk
 using in-memory storage to maintain separate task lists for each conversation.
 """
 
-from fastmcp import FastMCP
+from mcp.server import FastMCP
 
 from hanzo_mcp.tools.common.base import BaseTool, ToolRegistry
 from hanzo_mcp.tools.todo.todo_read import TodoReadTool

hanzo_mcp/tools/todo/base.py

@@ -9,7 +9,7 @@ import time
 from abc import ABC
 from typing import Any, final
 
-from fastmcp import Context as MCPContext
+from mcp.server.fastmcp import Context as MCPContext
 
 from hanzo_mcp.tools.common.base import BaseTool
 from hanzo_mcp.tools.common.context import ToolContext, create_tool_context

hanzo_mcp/tools/todo/todo.py

@@ -0,0 +1,265 @@
+"""Unified todo tool."""
+
+from typing import Annotated, TypedDict, Unpack, final, override, Optional, List, Dict, Any
+import json
+import uuid
+from datetime import datetime
+from pathlib import Path
+
+from mcp.server.fastmcp import Context as MCPContext
+from pydantic import Field
+
+from hanzo_mcp.tools.todo.base import TodoBaseTool
+
+
+# Parameter types
+Action = Annotated[
+    str,
+    Field(
+        description="Action to perform: list (default), add, update, remove, clear",
+        default="list",
+    ),
+]
+
+Content = Annotated[
+    Optional[str],
+    Field(
+        description="Todo content for add/update",
+        default=None,
+    ),
+]
+
+TodoId = Annotated[
+    Optional[str],
+    Field(
+        description="Todo ID for update/remove",
+        default=None,
+    ),
+]
+
+Status = Annotated[
+    Optional[str],
+    Field(
+        description="Status: pending, in_progress, completed",
+        default="pending",
+    ),
+]
+
+Priority = Annotated[
+    Optional[str],
+    Field(
+        description="Priority: high, medium, low",
+        default="medium",
+    ),
+]
+
+Filter = Annotated[
+    Optional[str],
+    Field(
+        description="Filter todos by status for list action",
+        default=None,
+    ),
+]
+
+
+class TodoParams(TypedDict, total=False):
+    """Parameters for todo tool."""
+    action: str
+    content: Optional[str]
+    id: Optional[str]
+    status: Optional[str]
+    priority: Optional[str]
+    filter: Optional[str]
+
+
+@final
+class TodoTool(TodoBaseTool):
+    """Unified todo management tool."""
+
+    @property
+    @override
+    def name(self) -> str:
+        """Get the tool name."""
+        return "todo"
+
+    @property
+    @override
+    def description(self) -> str:
+        """Get the tool description."""
+        return """Manage todos. Actions: list (default), add, update, remove, clear.
+
+Usage:
+todo
+todo "Fix the bug in authentication"
+todo --action update --id abc123 --status completed
+todo --action remove --id abc123
+todo --filter in_progress
+"""
+
+    @override
+    async def call(
+        self,
+        ctx: MCPContext,
+        **params: Unpack[TodoParams],
+    ) -> str:
+        """Execute todo operation."""
+        tool_ctx = self.create_tool_context(ctx)
+
+        # Extract action
+        action = params.get("action", "list")
+        
+        # Route to appropriate handler
+        if action == "list":
+            return await self._handle_list(params.get("filter"), tool_ctx)
+        elif action == "add":
+            return await self._handle_add(params, tool_ctx)
+        elif action == "update":
+            return await self._handle_update(params, tool_ctx)
+        elif action == "remove":
+            return await self._handle_remove(params.get("id"), tool_ctx)
+        elif action == "clear":
+            return await self._handle_clear(params.get("filter"), tool_ctx)
+        else:
+            return f"Error: Unknown action '{action}'. Valid actions: list, add, update, remove, clear"
+
+    async def _handle_list(self, filter_status: Optional[str], tool_ctx) -> str:
+        """List todos."""
+        todos = self.read_todos()
+        
+        if not todos:
+            return "No todos found. Use 'todo \"Your task here\"' to add one."
+        
+        # Apply filter if specified
+        if filter_status:
+            todos = [t for t in todos if t.get("status") == filter_status]
+            if not todos:
+                return f"No todos with status '{filter_status}'"
+        
+        # Group by status
+        by_status = {}
+        for todo in todos:
+            status = todo.get("status", "pending")
+            if status not in by_status:
+                by_status[status] = []
+            by_status[status].append(todo)
+        
+        # Format output
+        output = ["=== Todo List ==="]
+        
+        # Show in order: in_progress, pending, completed
+        for status in ["in_progress", "pending", "completed"]:
+            if status in by_status:
+                output.append(f"\n{status.replace('_', ' ').title()}:")
+                for todo in by_status[status]:
+                    priority_icon = {"high": "🔴", "medium": "🟡", "low": "🟢"}.get(todo.get("priority", "medium"), "⚪")
+                    output.append(f"{priority_icon} [{todo['id'][:8]}] {todo['content']}")
+        
+        # Summary
+        output.append(f"\nTotal: {len(todos)} | In Progress: {len(by_status.get('in_progress', []))} | Pending: {len(by_status.get('pending', []))} | Completed: {len(by_status.get('completed', []))}")
+        
+        return "\n".join(output)
+
+    async def _handle_add(self, params: Dict[str, Any], tool_ctx) -> str:
+        """Add new todo."""
+        content = params.get("content")
+        if not content:
+            return "Error: content is required for add action"
+        
+        todos = self.read_todos()
+        
+        new_todo = {
+            "id": str(uuid.uuid4()),
+            "content": content,
+            "status": params.get("status", "pending"),
+            "priority": params.get("priority", "medium"),
+            "created_at": datetime.now().isoformat(),
+        }
+        
+        todos.append(new_todo)
+        self.write_todos(todos)
+        
+        await tool_ctx.info(f"Added todo: {content}")
+        return f"Added todo [{new_todo['id'][:8]}]: {content}"
+
+    async def _handle_update(self, params: Dict[str, Any], tool_ctx) -> str:
+        """Update existing todo."""
+        todo_id = params.get("id")
+        if not todo_id:
+            return "Error: id is required for update action"
+        
+        todos = self.read_todos()
+        
+        # Find todo (support partial ID match)
+        todo_found = None
+        for todo in todos:
+            if todo["id"].startswith(todo_id):
+                todo_found = todo
+                break
+        
+        if not todo_found:
+            return f"Error: Todo with ID '{todo_id}' not found"
+        
+        # Update fields
+        if params.get("content"):
+            todo_found["content"] = params["content"]
+        if params.get("status"):
+            todo_found["status"] = params["status"]
+        if params.get("priority"):
+            todo_found["priority"] = params["priority"]
+        
+        todo_found["updated_at"] = datetime.now().isoformat()
+        
+        self.write_todos(todos)
+        
+        await tool_ctx.info(f"Updated todo: {todo_found['content']}")
+        return f"Updated todo [{todo_found['id'][:8]}]: {todo_found['content']} (status: {todo_found['status']})"
+
+    async def _handle_remove(self, todo_id: Optional[str], tool_ctx) -> str:
+        """Remove todo."""
+        if not todo_id:
+            return "Error: id is required for remove action"
+        
+        todos = self.read_todos()
+        
+        # Find and remove (support partial ID match)
+        removed = None
+        for i, todo in enumerate(todos):
+            if todo["id"].startswith(todo_id):
+                removed = todos.pop(i)
+                break
+        
+        if not removed:
+            return f"Error: Todo with ID '{todo_id}' not found"
+        
+        self.write_todos(todos)
+        
+        await tool_ctx.info(f"Removed todo: {removed['content']}")
+        return f"Removed todo [{removed['id'][:8]}]: {removed['content']}"
+
+    async def _handle_clear(self, filter_status: Optional[str], tool_ctx) -> str:
+        """Clear todos."""
+        todos = self.read_todos()
+        
+        if filter_status:
+            # Clear only todos with specific status
+            original_count = len(todos)
+            todos = [t for t in todos if t.get("status") != filter_status]
+            removed_count = original_count - len(todos)
+            
+            if removed_count == 0:
+                return f"No todos with status '{filter_status}' to clear"
+            
+            self.write_todos(todos)
+            return f"Cleared {removed_count} todo(s) with status '{filter_status}'"
+        else:
+            # Clear all
+            if not todos:
+                return "No todos to clear"
+            
+            count = len(todos)
+            self.write_todos([])
+            return f"Cleared all {count} todo(s)"
+
+    def register(self, mcp_server) -> None:
+        """Register this tool with the MCP server."""
+        pass

hanzo_mcp/tools/todo/todo_read.py

@@ -6,9 +6,8 @@ This module provides the TodoRead tool for reading the current todo list for a s
 import json
 from typing import Annotated, TypedDict, Unpack, final, override
 
-from fastmcp import Context as MCPContext
-from fastmcp import FastMCP
-from fastmcp.server.dependencies import get_context
+from mcp.server.fastmcp import Context as MCPContext
+from mcp.server import FastMCP
 from pydantic import Field
 
 from hanzo_mcp.tools.todo.base import TodoBaseTool, TodoStorage
@@ -141,8 +140,7 @@ Usage:
 
         @mcp_server.tool(name=self.name, description=self.description)
         async def todo_read(
-            ctx: MCPContext,
             session_id: SessionId,
+            ctx: MCPContext
         ) -> str:
-            ctx = get_context()
             return await tool_self.call(ctx, session_id=session_id)

hanzo_mcp/tools/todo/todo_write.py

@@ -5,9 +5,8 @@ This module provides the TodoWrite tool for creating and managing a structured t
 
 from typing import Annotated, Literal, TypedDict, Unpack, final, override
 
-from fastmcp import Context as MCPContext
-from fastmcp import FastMCP
-from fastmcp.server.dependencies import get_context
+from mcp.server.fastmcp import Context as MCPContext
+from mcp.server import FastMCP
 from pydantic import Field
 
 from hanzo_mcp.tools.todo.base import TodoBaseTool, TodoStorage
@@ -370,9 +369,8 @@ When in doubt, use this tool. Being proactive with task management demonstrates
 
         @mcp_server.tool(name=self.name, description=self.description)
         async def todo_write(
-            ctx: MCPContext,
             session_id: SessionId,
             todos: Todos,
+            ctx: MCPContext
         ) -> str:
-            ctx = get_context()
             return await tool_self.call(ctx, session_id=session_id, todos=todos)