hanzo-mcp 0.5.1__py3-none-any.whl → 0.6.1__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 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
+
+
+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 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., '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/npx_unified.py

@@ -0,0 +1,101 @@
+"""NPX 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 NpxTool(BaseBinaryTool):
+    """Tool for running npx commands."""
+    
+    name = "npx"
+    
+    @property
+    @override
+    def description(self) -> str:
+        """Get the tool description."""
+        return """Run npx packages. Actions: run (default), background.
+
+Usage:
+npx create-react-app my-app
+npx --action background http-server -p 8080
+npx prettier --write "**/*.js"
+npx --action background json-server db.json"""
+    
+    @override
+    def get_binary_name(self) -> str:
+        """Get the binary name."""
+        return "npx"
+    
+    @override
+    async def run(
+        self,
+        ctx: MCPContext,
+        package: str,
+        args: str = "",
+        action: str = "run",
+        cwd: Optional[str] = None,
+        yes: bool = True,
+    ) -> str:
+        """Run an npx command.
+        
+        Args:
+            ctx: MCP context
+            package: NPX package to run
+            args: Additional arguments
+            action: Action to perform (run, background)
+            cwd: Working directory
+            yes: Auto-confirm package installation
+            
+        Returns:
+            Command output or process info
+        """
+        # Prepare working directory
+        work_dir = Path(cwd).resolve() if cwd else Path.cwd()
+        
+        # Prepare flags
+        flags = []
+        if yes:
+            flags.append("-y")
+        
+        # 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 npx 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 npx
+            )
+
+    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
+npx_tool = NpxTool()

hanzo_mcp/tools/shell/open.py

@@ -0,0 +1,107 @@
+"""Open files or URLs in the default application."""
+
+import platform
+import subprocess
+import webbrowser
+from pathlib import Path
+from typing import override
+from urllib.parse import urlparse
+
+from mcp.server.fastmcp import Context as MCPContext
+
+from hanzo_mcp.tools.common.base import BaseTool
+from mcp.server import FastMCP
+
+
+class OpenTool(BaseTool):
+    """Tool for opening files or URLs in the default application."""
+
+    name = "open"
+    
+    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)
+
+    @property
+    @override
+    def description(self) -> str:
+        """Get the tool description."""
+        return """Open files or URLs. Platform-aware.
+
+Usage:
+open https://example.com
+open ./document.pdf
+open /path/to/image.png"""
+
+    @override
+    async def run(self, ctx: MCPContext, path: str) -> str:
+        """Open a file or URL in the default application.
+        
+        Args:
+            ctx: MCP context
+            path: File path or URL to open
+            
+        Returns:
+            Success message
+            
+        Raises:
+            RuntimeError: If opening fails
+        """
+        # Check if it's a URL
+        parsed = urlparse(path)
+        is_url = parsed.scheme in ('http', 'https', 'ftp', 'file')
+        
+        if is_url:
+            # Open URL in default browser
+            try:
+                webbrowser.open(path)
+                return f"Opened URL in browser: {path}"
+            except Exception as e:
+                raise RuntimeError(f"Failed to open URL: {e}")
+        
+        # It's a file path
+        file_path = Path(path).expanduser().resolve()
+        
+        if not file_path.exists():
+            raise RuntimeError(f"File not found: {file_path}")
+        
+        system = platform.system().lower()
+        
+        try:
+            if system == "darwin":  # macOS
+                subprocess.run(["open", str(file_path)], check=True)
+            elif system == "linux":
+                # Try xdg-open first (most common)
+                try:
+                    subprocess.run(["xdg-open", str(file_path)], check=True)
+                except (subprocess.CalledProcessError, FileNotFoundError):
+                    # Fallback to other common openers
+                    for opener in ["gnome-open", "kde-open", "exo-open"]:
+                        try:
+                            subprocess.run([opener, str(file_path)], check=True)
+                            break
+                        except (subprocess.CalledProcessError, FileNotFoundError):
+                            continue
+                    else:
+                        raise RuntimeError("No suitable file opener found on Linux")
+            elif system == "windows":
+                # Use os.startfile on Windows
+                import os
+                os.startfile(str(file_path))
+            else:
+                raise RuntimeError(f"Unsupported platform: {system}")
+                
+            return f"Opened file: {file_path}"
+            
+        except subprocess.CalledProcessError as e:
+            raise RuntimeError(f"Failed to open file: {e}")
+        except Exception as e:
+            raise RuntimeError(f"Error opening file: {e}")
+
+
+# Create tool instance
+open_tool = OpenTool()