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

hanzo_mcp/tools/filesystem/unix_aliases.py

@@ -0,0 +1,99 @@
+"""Unix command aliases for common tools.
+
+Provides familiar Unix command names that map to MCP tools.
+"""
+
+from typing import Dict, Type
+from hanzo_mcp.tools.common.base import BaseTool
+
+
+def get_unix_aliases() -> Dict[str, str]:
+    """Get mapping of Unix commands to MCP tool names.
+    
+    Returns:
+        Dictionary mapping Unix command names to MCP tool names
+    """
+    return {
+        # File operations
+        "ls": "list_directory",
+        "cat": "read_file", 
+        "head": "read_file",  # With line limit
+        "tail": "read_file",  # With offset
+        "cp": "copy_path",
+        "mv": "move_path",
+        "rm": "delete_path",
+        "mkdir": "create_directory",
+        "touch": "write_file",  # Create empty file
+        
+        # Search operations
+        "grep": "find",  # Our unified find tool
+        "find": "glob",  # For finding files by name
+        "ffind": "find",  # Fast file content search
+        "rg": "find",  # Ripgrep alias
+        "ag": "find",  # Silver searcher alias
+        "ack": "find",  # Ack alias
+        
+        # Directory operations
+        "tree": "tree",  # Already named correctly
+        "pwd": "get_working_directory",
+        "cd": "change_directory",
+        
+        # Git operations (if git tools enabled)
+        "git": "git_command",
+        
+        # Process operations
+        "ps": "list_processes",
+        "kill": "kill_process",
+        
+        # Archive operations
+        "tar": "archive",
+        "unzip": "extract",
+        
+        # Network operations
+        "curl": "http_request",
+        "wget": "download_file",
+    }
+
+
+class UnixAliasRegistry:
+    """Registry for Unix command aliases."""
+    
+    def __init__(self):
+        self.aliases = get_unix_aliases()
+        
+    def register_aliases(self, mcp_server, tools: Dict[str, BaseTool]) -> None:
+        """Register Unix aliases for tools.
+        
+        Args:
+            mcp_server: The MCP server instance
+            tools: Dictionary of tool name to tool instance
+        """
+        for alias, tool_name in self.aliases.items():
+            if tool_name in tools:
+                tool = tools[tool_name]
+                # Register the tool under its alias name
+                self._register_alias(mcp_server, alias, tool)
+                
+    def _register_alias(self, mcp_server, alias: str, tool: BaseTool) -> None:
+        """Register a single alias for a tool.
+        
+        Args:
+            mcp_server: The MCP server instance
+            alias: The Unix command alias
+            tool: The tool instance
+        """
+        # Create a wrapper that preserves the original tool's functionality
+        # but registers under the alias name
+        original_name = tool.name
+        original_description = tool.description
+        
+        # Temporarily change the tool's name for registration
+        tool.name = alias
+        tool.description = f"{original_description}\n\n(Unix alias for {original_name})"
+        
+        # Register the tool
+        tool.register(mcp_server)
+        
+        # Restore original name
+        tool.name = original_name
+        tool.description = original_description

hanzo_mcp/tools/filesystem/watch.py

@@ -0,0 +1,174 @@
+"""Watch files for changes."""
+
+import asyncio
+import os
+from pathlib import Path
+from typing import override
+import time
+from datetime import datetime
+
+from mcp.server.fastmcp import Context as MCPContext
+
+from hanzo_mcp.tools.common.base import BaseTool
+from mcp.server import FastMCP
+
+
+class WatchTool(BaseTool):
+    """Tool for watching files for changes."""
+
+    name = "watch"
+    
+    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 """Watch files for changes. Reports modifications.
+
+Usage:
+watch ./src --pattern "*.py" --interval 2
+watch config.json
+watch . --recursive --exclude "__pycache__"
+"""
+
+    @override
+    async def run(
+        self, 
+        ctx: MCPContext, 
+        path: str,
+        pattern: str = "*",
+        interval: int = 1,
+        recursive: bool = True,
+        exclude: str = "",
+        duration: int = 30,
+    ) -> str:
+        """Watch files for changes.
+        
+        Args:
+            ctx: MCP context
+            path: Path to watch (file or directory)
+            pattern: Glob pattern for files to watch (default: "*")
+            interval: Check interval in seconds (default: 1)
+            recursive: Watch subdirectories (default: True)
+            exclude: Patterns to exclude (comma-separated)
+            duration: Max watch duration in seconds (default: 30)
+            
+        Returns:
+            Report of file changes
+        """
+        watch_path = Path(path).expanduser().resolve()
+        
+        if not watch_path.exists():
+            raise ValueError(f"Path does not exist: {watch_path}")
+        
+        # Parse exclude patterns
+        exclude_patterns = [p.strip() for p in exclude.split(",") if p.strip()]
+        
+        # Track file states
+        file_states = {}
+        changes = []
+        start_time = time.time()
+        
+        def should_exclude(file_path: Path) -> bool:
+            """Check if file should be excluded."""
+            for pattern in exclude_patterns:
+                if pattern in str(file_path):
+                    return True
+                if file_path.match(pattern):
+                    return True
+            return False
+        
+        def get_files() -> dict[Path, float]:
+            """Get all matching files with their modification times."""
+            files = {}
+            
+            if watch_path.is_file():
+                # Watching a single file
+                if not should_exclude(watch_path):
+                    try:
+                        files[watch_path] = watch_path.stat().st_mtime
+                    except:
+                        pass
+            else:
+                # Watching a directory
+                if recursive:
+                    paths = watch_path.rglob(pattern)
+                else:
+                    paths = watch_path.glob(pattern)
+                
+                for file_path in paths:
+                    if file_path.is_file() and not should_exclude(file_path):
+                        try:
+                            files[file_path] = file_path.stat().st_mtime
+                        except:
+                            pass
+            
+            return files
+        
+        # Initial scan
+        file_states = get_files()
+        initial_count = len(file_states)
+        
+        output = [f"Watching {watch_path} (pattern: {pattern})"]
+        output.append(f"Found {initial_count} files to monitor")
+        if exclude_patterns:
+            output.append(f"Excluding: {', '.join(exclude_patterns)}")
+        output.append(f"Monitoring for {duration} seconds...\n")
+        
+        # Monitor for changes
+        try:
+            while (time.time() - start_time) < duration:
+                await asyncio.sleep(interval)
+                
+                current_files = get_files()
+                
+                # Check for new files
+                for file_path, mtime in current_files.items():
+                    if file_path not in file_states:
+                        timestamp = datetime.now().strftime("%H:%M:%S")
+                        change = f"[{timestamp}] CREATED: {file_path.relative_to(watch_path.parent)}"
+                        changes.append(change)
+                        output.append(change)
+                
+                # Check for deleted files
+                for file_path in list(file_states.keys()):
+                    if file_path not in current_files:
+                        timestamp = datetime.now().strftime("%H:%M:%S")
+                        change = f"[{timestamp}] DELETED: {file_path.relative_to(watch_path.parent)}"
+                        changes.append(change)
+                        output.append(change)
+                        del file_states[file_path]
+                
+                # Check for modified files
+                for file_path, mtime in current_files.items():
+                    if file_path in file_states and mtime != file_states[file_path]:
+                        timestamp = datetime.now().strftime("%H:%M:%S")
+                        change = f"[{timestamp}] MODIFIED: {file_path.relative_to(watch_path.parent)}"
+                        changes.append(change)
+                        output.append(change)
+                        file_states[file_path] = mtime
+                
+                # Update file states for new files
+                for file_path, mtime in current_files.items():
+                    if file_path not in file_states:
+                        file_states[file_path] = mtime
+                
+        except asyncio.CancelledError:
+            output.append("\nWatch cancelled")
+        
+        # Summary
+        output.append(f"\nWatch completed after {int(time.time() - start_time)} seconds")
+        output.append(f"Total changes detected: {len(changes)}")
+        
+        return "\n".join(output)
+
+
+# Create tool instance
+watch_tool = WatchTool()

hanzo_mcp/tools/filesystem/write.py

@@ -6,9 +6,8 @@ This module provides the Write tool for creating or overwriting files.
 from pathlib import Path
 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.filesystem.base import FilesystemBaseTool
@@ -148,9 +147,8 @@ Usage:
 
         @mcp_server.tool(name=self.name, description=self.description)
         async def write(
-            ctx: MCPContext,
             file_path: FilePath,
             content: Content,
+            ctx: MCPContext
         ) -> str:
-            ctx = get_context()
             return await tool_self.call(ctx, file_path=file_path, content=content)

hanzo_mcp/tools/jupyter/__init__.py

@@ -4,17 +4,15 @@ This package provides tools for working with Jupyter notebooks (.ipynb files),
 including reading and editing notebook cells.
 """
 
-from fastmcp import FastMCP
+from mcp.server import FastMCP
 
 from hanzo_mcp.tools.common.base import BaseTool, ToolRegistry
 from hanzo_mcp.tools.common.permissions import PermissionManager
-from hanzo_mcp.tools.jupyter.notebook_edit import NoteBookEditTool
-from hanzo_mcp.tools.jupyter.notebook_read import NotebookReadTool
+from hanzo_mcp.tools.jupyter.jupyter import JupyterTool
 
 # Export all tool classes
 __all__ = [
-    "NotebookReadTool",
-    "NoteBookEditTool",
+    "JupyterTool",
     "get_jupyter_tools",
     "register_jupyter_tools",
 ]
@@ -31,9 +29,7 @@ def get_read_only_jupyter_tools(
     Returns:
         List of Jupyter notebook tool instances
     """
-    return [
-        NotebookReadTool(permission_manager),
-    ]
+    return []  # Unified tool handles both read and write
 
 
 def get_jupyter_tools(permission_manager: PermissionManager) -> list[BaseTool]:
@@ -46,8 +42,7 @@ def get_jupyter_tools(permission_manager: PermissionManager) -> list[BaseTool]:
         List of Jupyter notebook tool instances
     """
     return [
-        NotebookReadTool(permission_manager),
-        NoteBookEditTool(permission_manager),
+        JupyterTool(permission_manager),
     ]
 
 
@@ -68,8 +63,10 @@ def register_jupyter_tools(
     """
     # Define tool mapping
     tool_classes = {
-        "notebook_read": NotebookReadTool,
-        "notebook_edit": NoteBookEditTool,
+        "jupyter": JupyterTool,
+        # Legacy names for backward compatibility
+        "notebook_read": JupyterTool,
+        "notebook_edit": JupyterTool,
     }
     
     tools = []

hanzo_mcp/tools/jupyter/base.py

@@ -10,7 +10,7 @@ import re
 from pathlib import Path
 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 FileSystemTool
 from hanzo_mcp.tools.common.context import ToolContext, create_tool_context

hanzo_mcp/tools/jupyter/jupyter.py

@@ -0,0 +1,326 @@
+"""Unified Jupyter notebook tool."""
+
+from typing import Annotated, TypedDict, Unpack, final, override, Optional, List, Dict, Any
+import json
+import nbformat
+from pathlib import Path
+
+from mcp.server.fastmcp import Context as MCPContext
+from pydantic import Field
+
+from hanzo_mcp.tools.jupyter.base import JupyterBaseTool
+
+
+# Parameter types
+Action = Annotated[
+    str,
+    Field(
+        description="Action to perform: read (default), edit, create, delete, execute",
+        default="read",
+    ),
+]
+
+NotebookPath = Annotated[
+    str,
+    Field(
+        description="Path to the Jupyter notebook file (.ipynb)",
+    ),
+]
+
+CellId = Annotated[
+    Optional[str],
+    Field(
+        description="Cell ID for targeted operations",
+        default=None,
+    ),
+]
+
+CellIndex = Annotated[
+    Optional[int],
+    Field(
+        description="Cell index (0-based) for operations",
+        default=None,
+    ),
+]
+
+CellType = Annotated[
+    Optional[str],
+    Field(
+        description="Cell type: code or markdown",
+        default=None,
+    ),
+]
+
+Source = Annotated[
+    Optional[str],
+    Field(
+        description="New source content for cell",
+        default=None,
+    ),
+]
+
+EditMode = Annotated[
+    str,
+    Field(
+        description="Edit mode: replace (default), insert, delete",
+        default="replace",
+    ),
+]
+
+
+class NotebookParams(TypedDict, total=False):
+    """Parameters for notebook tool."""
+    action: str
+    notebook_path: str
+    cell_id: Optional[str]
+    cell_index: Optional[int]
+    cell_type: Optional[str]
+    source: Optional[str]
+    edit_mode: str
+
+
+@final
+class JupyterTool(JupyterBaseTool):
+    """Unified tool for Jupyter notebook operations."""
+
+    @property
+    @override
+    def name(self) -> str:
+        """Get the tool name."""
+        return "jupyter"
+
+    @property
+    @override
+    def description(self) -> str:
+        """Get the tool description."""
+        return """Jupyter notebooks. Actions: read (default), edit, create, delete, execute.
+
+Usage:
+jupyter "path/to/notebook.ipynb"
+jupyter "notebook.ipynb" --cell-index 2
+jupyter --action edit "notebook.ipynb" --cell-index 0 --source "print('Hello')"
+jupyter --action create "new.ipynb"
+"""
+
+    @override
+    async def call(
+        self,
+        ctx: MCPContext,
+        **params: Unpack[NotebookParams],
+    ) -> str:
+        """Execute notebook operation."""
+        tool_ctx = self.create_tool_context(ctx)
+
+        # Extract parameters
+        action = params.get("action", "read")
+        notebook_path = params.get("notebook_path")
+        
+        if not notebook_path:
+            return "Error: notebook_path is required"
+
+        # Validate path
+        path_validation = self.validate_path(notebook_path)
+        if path_validation.is_error:
+            await tool_ctx.error(path_validation.error_message)
+            return f"Error: {path_validation.error_message}"
+
+        # Check permissions
+        allowed, error_msg = await self.check_path_allowed(notebook_path, tool_ctx)
+        if not allowed:
+            return error_msg
+
+        # Route to appropriate handler
+        if action == "read":
+            return await self._handle_read(notebook_path, params, tool_ctx)
+        elif action == "edit":
+            return await self._handle_edit(notebook_path, params, tool_ctx)
+        elif action == "create":
+            return await self._handle_create(notebook_path, tool_ctx)
+        elif action == "delete":
+            return await self._handle_delete(notebook_path, params, tool_ctx)
+        elif action == "execute":
+            return await self._handle_execute(notebook_path, params, tool_ctx)
+        else:
+            return f"Error: Unknown action '{action}'. Valid actions: read, edit, create, delete, execute"
+
+    async def _handle_read(self, notebook_path: str, params: Dict[str, Any], tool_ctx) -> str:
+        """Read notebook or specific cell."""
+        exists, error_msg = await self.check_path_exists(notebook_path, tool_ctx)
+        if not exists:
+            return error_msg
+
+        try:
+            nb = self.read_notebook(notebook_path)
+            
+            # Check if specific cell requested
+            cell_id = params.get("cell_id")
+            cell_index = params.get("cell_index")
+            
+            if cell_id:
+                # Find cell by ID
+                for i, cell in enumerate(nb.cells):
+                    if cell.get("id") == cell_id:
+                        return self._format_cell(cell, i)
+                return f"Error: Cell with ID '{cell_id}' not found"
+            
+            elif cell_index is not None:
+                # Get cell by index
+                if 0 <= cell_index < len(nb.cells):
+                    return self._format_cell(nb.cells[cell_index], cell_index)
+                else:
+                    return f"Error: Cell index {cell_index} out of range (notebook has {len(nb.cells)} cells)"
+            
+            else:
+                # Return all cells
+                return self.format_notebook(nb)
+                
+        except Exception as e:
+            await tool_ctx.error(f"Failed to read notebook: {str(e)}")
+            return f"Error reading notebook: {str(e)}"
+
+    async def _handle_edit(self, notebook_path: str, params: Dict[str, Any], tool_ctx) -> str:
+        """Edit notebook cell."""
+        exists, error_msg = await self.check_path_exists(notebook_path, tool_ctx)
+        if not exists:
+            return error_msg
+
+        source = params.get("source")
+        if not source:
+            return "Error: source is required for edit action"
+
+        edit_mode = params.get("edit_mode", "replace")
+        cell_id = params.get("cell_id")
+        cell_index = params.get("cell_index")
+        cell_type = params.get("cell_type")
+
+        try:
+            nb = self.read_notebook(notebook_path)
+            
+            if edit_mode == "insert":
+                # Insert new cell
+                new_cell = nbformat.v4.new_code_cell(source) if cell_type != "markdown" else nbformat.v4.new_markdown_cell(source)
+                
+                if cell_index is not None:
+                    nb.cells.insert(cell_index, new_cell)
+                else:
+                    nb.cells.append(new_cell)
+                
+                self.write_notebook(nb, notebook_path)
+                return f"Successfully inserted new cell at index {cell_index if cell_index is not None else len(nb.cells)-1}"
+            
+            elif edit_mode == "delete":
+                # Delete cell
+                if cell_id:
+                    for i, cell in enumerate(nb.cells):
+                        if cell.get("id") == cell_id:
+                            nb.cells.pop(i)
+                            self.write_notebook(nb, notebook_path)
+                            return f"Successfully deleted cell with ID '{cell_id}'"
+                    return f"Error: Cell with ID '{cell_id}' not found"
+                
+                elif cell_index is not None:
+                    if 0 <= cell_index < len(nb.cells):
+                        nb.cells.pop(cell_index)
+                        self.write_notebook(nb, notebook_path)
+                        return f"Successfully deleted cell at index {cell_index}"
+                    else:
+                        return f"Error: Cell index {cell_index} out of range"
+                else:
+                    return "Error: cell_id or cell_index required for delete"
+            
+            else:  # replace
+                # Replace cell content
+                if cell_id:
+                    for cell in nb.cells:
+                        if cell.get("id") == cell_id:
+                            cell.source = source
+                            if cell_type:
+                                cell.cell_type = cell_type
+                            self.write_notebook(nb, notebook_path)
+                            return f"Successfully updated cell with ID '{cell_id}'"
+                    return f"Error: Cell with ID '{cell_id}' not found"
+                
+                elif cell_index is not None:
+                    if 0 <= cell_index < len(nb.cells):
+                        nb.cells[cell_index].source = source
+                        if cell_type:
+                            nb.cells[cell_index].cell_type = cell_type
+                        self.write_notebook(nb, notebook_path)
+                        return f"Successfully updated cell at index {cell_index}"
+                    else:
+                        return f"Error: Cell index {cell_index} out of range"
+                else:
+                    return "Error: cell_id or cell_index required for replace"
+                    
+        except Exception as e:
+            await tool_ctx.error(f"Failed to edit notebook: {str(e)}")
+            return f"Error editing notebook: {str(e)}"
+
+    async def _handle_create(self, notebook_path: str, tool_ctx) -> str:
+        """Create new notebook."""
+        # Check if already exists
+        path = Path(notebook_path)
+        if path.exists():
+            return f"Error: Notebook already exists at {notebook_path}"
+
+        try:
+            # Create new notebook
+            nb = nbformat.v4.new_notebook()
+            
+            # Ensure parent directory exists
+            path.parent.mkdir(parents=True, exist_ok=True)
+            
+            # Write notebook
+            self.write_notebook(nb, notebook_path)
+            return f"Successfully created notebook at {notebook_path}"
+            
+        except Exception as e:
+            await tool_ctx.error(f"Failed to create notebook: {str(e)}")
+            return f"Error creating notebook: {str(e)}"
+
+    async def _handle_delete(self, notebook_path: str, params: Dict[str, Any], tool_ctx) -> str:
+        """Delete notebook or cell."""
+        # If cell specified, delegate to edit with delete mode
+        if params.get("cell_id") or params.get("cell_index") is not None:
+            params["edit_mode"] = "delete"
+            return await self._handle_edit(notebook_path, params, tool_ctx)
+        
+        # Otherwise, delete entire notebook
+        exists, error_msg = await self.check_path_exists(notebook_path, tool_ctx)
+        if not exists:
+            return error_msg
+
+        try:
+            Path(notebook_path).unlink()
+            return f"Successfully deleted notebook {notebook_path}"
+        except Exception as e:
+            await tool_ctx.error(f"Failed to delete notebook: {str(e)}")
+            return f"Error deleting notebook: {str(e)}"
+
+    async def _handle_execute(self, notebook_path: str, params: Dict[str, Any], tool_ctx) -> str:
+        """Execute notebook cells (placeholder for future implementation)."""
+        return "Error: Cell execution not yet implemented. Use a Jupyter kernel or server for execution."
+
+    def _format_cell(self, cell: dict, index: int) -> str:
+        """Format a single cell for display."""
+        output = [f"Cell {index} ({cell.cell_type})"]
+        if cell.get("id"):
+            output.append(f"ID: {cell.id}")
+        output.append("-" * 40)
+        output.append(cell.source)
+        
+        if cell.cell_type == "code" and cell.get("outputs"):
+            output.append("\nOutputs:")
+            for out in cell.outputs:
+                if out.output_type == "stream":
+                    output.append(f"[{out.name}]: {out.text}")
+                elif out.output_type == "execute_result":
+                    output.append(f"[Out {out.execution_count}]: {out.data}")
+                elif out.output_type == "error":
+                    output.append(f"[Error]: {out.ename}: {out.evalue}")
+        
+        return "\n".join(output)
+
+    def register(self, mcp_server) -> None:
+        """Register this tool with the MCP server."""
+        pass