hanzo-mcp 0.5.0__py3-none-any.whl → 0.5.2__py3-none-any.whl

hanzo_mcp/tools/shell/npx.py

@@ -0,0 +1,194 @@
+"""Run Node.js packages with npx."""
+
+import subprocess
+import shutil
+from typing import Annotated, Optional, TypedDict, Unpack, final, override
+
+from 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
+
+
+Package = Annotated[
+    str,
+    Field(
+        description="Package name to run (e.g., 'eslint', 'prettier', 'create-react-app')",
+        min_length=1,
+    ),
+]
+
+Args = Annotated[
+    Optional[str],
+    Field(
+        description="Arguments to pass to the package",
+        default=None,
+    ),
+]
+
+Yes = Annotated[
+    bool,
+    Field(
+        description="Auto-confirm package installation",
+        default=True,
+    ),
+]
+
+Timeout = Annotated[
+    int,
+    Field(
+        description="Timeout in seconds (default 120)",
+        default=120,
+    ),
+]
+
+
+class NpxParams(TypedDict, total=False):
+    """Parameters for npx tool."""
+
+    package: str
+    args: Optional[str]
+    yes: bool
+    timeout: int
+
+
+@final
+class NpxTool(BaseTool):
+    """Tool for running Node.js packages with npx."""
+
+    def __init__(self, permission_manager: PermissionManager):
+        """Initialize the npx 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 "npx"
+
+    @property
+    @override
+    def description(self) -> str:
+        """Get the tool description."""
+        return """Run Node.js packages using npx (Node package runner).
+
+npx allows running Node.js packages without installing them globally.
+It automatically downloads and executes packages on demand.
+
+Common packages:
+- eslint: JavaScript linter
+- prettier: Code formatter
+- typescript: TypeScript compiler
+- create-react-app: Create React apps
+- create-next-app: Create Next.js apps
+- jest: Testing framework
+- webpack: Module bundler
+- vite: Build tool
+- vercel: Deploy to Vercel
+- netlify-cli: Deploy to Netlify
+
+Examples:
+- npx --package eslint --args "--init"
+- npx --package prettier --args "--write src/**/*.js"
+- npx --package "create-react-app" --args "my-app"
+- npx --package typescript --args "--init"
+- npx --package jest --args "--coverage"
+
+For long-running servers, use npx_background instead.
+"""
+
+    @override
+    async def call(
+        self,
+        ctx: MCPContext,
+        **params: Unpack[NpxParams],
+    ) -> str:
+        """Execute npx command.
+
+        Args:
+            ctx: MCP context
+            **params: Tool parameters
+
+        Returns:
+            Command output
+        """
+        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", "")
+        yes = params.get("yes", True)
+        timeout = params.get("timeout", 120)
+
+        # Check if npx is available
+        if not shutil.which("npx"):
+            return """Error: npx is not installed. Install Node.js and npm:
+
+On macOS:
+brew install node
+
+On Ubuntu/Debian:
+sudo apt update && sudo apt install nodejs npm
+
+Or download from: https://nodejs.org/"""
+
+        # Build command
+        cmd = ["npx"]
+        
+        if yes:
+            cmd.append("--yes")
+        
+        cmd.append(package)
+        
+        # Add package arguments
+        if args:
+            # Split args properly (basic parsing)
+            import shlex
+            cmd.extend(shlex.split(args))
+
+        await tool_ctx.info(f"Running: {' '.join(cmd)}")
+
+        try:
+            # Execute command
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                check=True
+            )
+
+            output = []
+            if result.stdout:
+                output.append(result.stdout)
+            if result.stderr:
+                output.append(f"\nSTDERR:\n{result.stderr}")
+
+            return "\n".join(output) if output else "Command completed successfully with no output."
+
+        except subprocess.TimeoutExpired:
+            return f"Error: Command timed out after {timeout} seconds. Use npx_background for long-running processes."
+        except subprocess.CalledProcessError as e:
+            error_msg = [f"Error: Command failed with exit code {e.returncode}"]
+            if e.stdout:
+                error_msg.append(f"\nSTDOUT:\n{e.stdout}")
+            if e.stderr:
+                error_msg.append(f"\nSTDERR:\n{e.stderr}")
+            return "\n".join(error_msg)
+        except Exception as e:
+            await tool_ctx.error(f"Unexpected error: {str(e)}")
+            return f"Error running npx: {str(e)}"
+
+    def register(self, mcp_server) -> None:
+        """Register this tool with the MCP server."""
+        pass

hanzo_mcp/tools/shell/npx_background.py

@@ -0,0 +1,254 @@
+"""Run Node.js packages in background with npx."""
+
+import subprocess
+import shutil
+import uuid
+from typing import Annotated, Optional, TypedDict, Unpack, final, override
+
+from 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., 'http-server', 'json-server', 'serve')",
+        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,
+    ),
+]
+
+Yes = Annotated[
+    bool,
+    Field(
+        description="Auto-confirm package installation",
+        default=True,
+    ),
+]
+
+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 NpxBackgroundParams(TypedDict, total=False):
+    """Parameters for npx background tool."""
+
+    package: str
+    args: Optional[str]
+    name: Optional[str]
+    yes: bool
+    log_output: bool
+    working_dir: Optional[str]
+
+
+@final
+class NpxBackgroundTool(BaseTool):
+    """Tool for running Node.js packages in background with npx."""
+
+    def __init__(self, permission_manager: PermissionManager):
+        """Initialize the npx 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 "npx_background"
+
+    @property
+    @override
+    def description(self) -> str:
+        """Get the tool description."""
+        return """Run Node.js packages in the background using npx.
+
+Perfect for running servers and long-running Node.js applications.
+The process continues running even after the command returns.
+
+Common server packages:
+- http-server: Simple HTTP server
+- json-server: REST API mock server
+- serve: Static file server
+- live-server: Dev server with reload
+- webpack-dev-server: Webpack dev server
+- nodemon: Auto-restart on changes
+- localtunnel: Expose local server
+- ngrok: Secure tunnels
+
+Examples:
+- npx_background --package http-server --args "-p 8080" --name web-server
+- npx_background --package json-server --args "db.json --port 3001" --name api
+- npx_background --package serve --args "-s build -p 5000" --name static
+- npx_background --package live-server --args "--port=8081" --name dev-server
+
+Use 'processes' to list running processes and 'pkill' to stop them.
+"""
+
+    @override
+    async def call(
+        self,
+        ctx: MCPContext,
+        **params: Unpack[NpxBackgroundParams],
+    ) -> str:
+        """Execute npx 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"npx-{package}")
+        yes = params.get("yes", True)
+        log_output = params.get("log_output", True)
+        working_dir = params.get("working_dir")
+
+        # Check if npx is available
+        if not shutil.which("npx"):
+            return """Error: npx is not installed. Install Node.js and npm:
+
+On macOS:
+brew install node
+
+On Ubuntu/Debian:
+sudo apt update && sudo apt install nodejs npm
+
+Or download from: https://nodejs.org/"""
+
+        # Build command
+        cmd = ["npx"]
+        
+        if yes:
+            cmd.append("--yes")
+        
+        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 npx 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 npx background process: {str(e)}"
+
+    def register(self, mcp_server) -> None:
+        """Register this tool with the MCP server."""
+        pass

hanzo_mcp/tools/shell/pkill.py

@@ -0,0 +1,262 @@
+"""Tool for terminating background processes."""
+
+import os
+import signal
+import psutil
+from datetime import datetime
+from typing import Annotated, Optional, TypedDict, Unpack, final, override
+
+from 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 RunBackgroundTool
+
+
+ProcessId = Annotated[
+    Optional[str],
+    Field(
+        description="Process ID from run_background (use 'processes' to list)",
+        default=None,
+    ),
+]
+
+Pid = Annotated[
+    Optional[int],
+    Field(
+        description="System process ID (PID)",
+        default=None,
+    ),
+]
+
+Name = Annotated[
+    Optional[str],
+    Field(
+        description="Kill all processes matching this name",
+        default=None,
+    ),
+]
+
+Force = Annotated[
+    bool,
+    Field(
+        description="Force kill (SIGKILL instead of SIGTERM)",
+        default=False,
+    ),
+]
+
+All = Annotated[
+    bool,
+    Field(
+        description="Kill all background processes",
+        default=False,
+    ),
+]
+
+
+class PkillParams(TypedDict, total=False):
+    """Parameters for killing processes."""
+
+    id: Optional[str]
+    pid: Optional[int]
+    name: Optional[str]
+    force: bool
+    all: bool
+
+
+@final
+class PkillTool(BaseTool):
+    """Tool for terminating processes."""
+
+    def __init__(self, permission_manager: PermissionManager):
+        """Initialize the pkill 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 "pkill"
+
+    @property
+    @override
+    def description(self) -> str:
+        """Get the tool description."""
+        return """Terminate running processes.
+
+Can kill processes by:
+- ID: Process ID from run_background (recommended)
+- PID: System process ID
+- Name: All processes matching name
+- All: Terminate all background processes
+
+Options:
+- force: Use SIGKILL instead of SIGTERM
+- all: Kill all background processes
+
+Examples:
+- pkill --id abc123            # Kill specific background process
+- pkill --name "npm"           # Kill all npm processes
+- pkill --pid 12345            # Kill by system PID
+- pkill --all                  # Kill all background processes
+- pkill --id abc123 --force    # Force kill
+"""
+
+    @override
+    async def call(
+        self,
+        ctx: MCPContext,
+        **params: Unpack[PkillParams],
+    ) -> str:
+        """Kill processes.
+
+        Args:
+            ctx: MCP context
+            **params: Tool parameters
+
+        Returns:
+            Result of kill operation
+        """
+        tool_ctx = create_tool_context(ctx)
+        await tool_ctx.set_tool_info(self.name)
+
+        # Extract parameters
+        process_id = params.get("id")
+        pid = params.get("pid")
+        name = params.get("name")
+        force = params.get("force", False)
+        kill_all = params.get("all", False)
+
+        # Validate that at least one target is specified
+        if not any([process_id, pid, name, kill_all]):
+            return "Error: Must specify --id, --pid, --name, or --all"
+
+        killed_count = 0
+        errors = []
+
+        try:
+            # Kill all background processes
+            if kill_all:
+                await tool_ctx.info("Killing all background processes")
+                processes = RunBackgroundTool.get_processes()
+                
+                for proc_id, process in list(processes.items()):
+                    if process.is_running:
+                        try:
+                            if force:
+                                process.kill()
+                            else:
+                                process.terminate()
+                            killed_count += 1
+                            await tool_ctx.info(f"Killed process {proc_id} ({process.name})")
+                        except Exception as e:
+                            errors.append(f"Failed to kill {proc_id}: {str(e)}")
+                
+                if killed_count == 0:
+                    return "No running background processes to kill."
+
+            # Kill by process ID
+            elif process_id:
+                await tool_ctx.info(f"Killing process with ID: {process_id}")
+                process = RunBackgroundTool.get_process(process_id)
+                
+                if not process:
+                    return f"Process with ID '{process_id}' not found."
+                
+                if not process.is_running:
+                    return f"Process '{process_id}' is not running (return code: {process.return_code})."
+                
+                try:
+                    if force:
+                        process.kill()
+                    else:
+                        process.terminate()
+                    killed_count += 1
+                    await tool_ctx.info(f"Successfully killed process {process_id}")
+                except Exception as e:
+                    return f"Failed to kill process: {str(e)}"
+
+            # Kill by PID
+            elif pid:
+                await tool_ctx.info(f"Killing process with PID: {pid}")
+                try:
+                    p = psutil.Process(pid)
+                    
+                    if force:
+                        p.kill()
+                    else:
+                        p.terminate()
+                    
+                    killed_count += 1
+                    await tool_ctx.info(f"Successfully killed PID {pid}")
+                    
+                    # Check if this was a background process and update it
+                    for proc_id, process in RunBackgroundTool.get_processes().items():
+                        if process.pid == pid:
+                            process.end_time = datetime.now()
+                            break
+                            
+                except psutil.NoSuchProcess:
+                    return f"Process with PID {pid} not found."
+                except psutil.AccessDenied:
+                    return f"Permission denied to kill PID {pid}."
+                except Exception as e:
+                    return f"Failed to kill PID {pid}: {str(e)}"
+
+            # Kill by name
+            elif name:
+                await tool_ctx.info(f"Killing all processes matching: {name}")
+                
+                # First check background processes
+                bg_processes = RunBackgroundTool.get_processes()
+                for proc_id, process in list(bg_processes.items()):
+                    if name.lower() in process.name.lower() and process.is_running:
+                        try:
+                            if force:
+                                process.kill()
+                            else:
+                                process.terminate()
+                            killed_count += 1
+                            await tool_ctx.info(f"Killed background process {proc_id} ({process.name})")
+                        except Exception as e:
+                            errors.append(f"Failed to kill {proc_id}: {str(e)}")
+                
+                # Also check system processes
+                for proc in psutil.process_iter(['pid', 'name']):
+                    try:
+                        if name.lower() in proc.info['name'].lower():
+                            if force:
+                                proc.kill()
+                            else:
+                                proc.terminate()
+                            killed_count += 1
+                            await tool_ctx.info(f"Killed {proc.info['name']} (PID: {proc.info['pid']})")
+                    except (psutil.NoSuchProcess, psutil.AccessDenied):
+                        continue
+                    except Exception as e:
+                        errors.append(f"Failed to kill PID {proc.info['pid']}: {str(e)}")
+
+            # Build result message
+            if killed_count > 0:
+                result = f"Successfully killed {killed_count} process(es)."
+            else:
+                result = "No processes were killed."
+            
+            if errors:
+                result += f"\n\nErrors:\n" + "\n".join(errors)
+            
+            return result
+
+        except Exception as e:
+            await tool_ctx.error(f"Failed to kill processes: {str(e)}")
+            return f"Error killing processes: {str(e)}"
+
+    def register(self, mcp_server) -> None:
+        """Register this tool with the MCP server."""
+        pass