hanzo-mcp 0.9.0__py3-none-any.whl → 0.9.1__py3-none-any.whl

hanzo_mcp/tools/filesystem/tree.py

@@ -0,0 +1,273 @@
+"""Tree tool implementation.
+
+Unix-style tree command for directory visualization.
+"""
+
+from typing import List, Unpack, Optional, Annotated, TypedDict, final, override
+from pathlib import Path
+
+from pydantic import Field
+from mcp.server.fastmcp import Context as MCPContext
+
+from hanzo_mcp.tools.common.auto_timeout import auto_timeout
+
+from hanzo_mcp.tools.filesystem.base import FilesystemBaseTool
+
+# Parameter types
+TreePath = Annotated[
+    str,
+    Field(
+        description="Directory path to display",
+        default=".",
+    ),
+]
+
+Depth = Annotated[
+    Optional[int],
+    Field(
+        description="Maximum depth to display",
+        default=None,
+    ),
+]
+
+ShowHidden = Annotated[
+    bool,
+    Field(
+        description="Show hidden files (starting with .)",
+        default=False,
+    ),
+]
+
+DirsOnly = Annotated[
+    bool,
+    Field(
+        description="Show only directories",
+        default=False,
+    ),
+]
+
+ShowSize = Annotated[
+    bool,
+    Field(
+        description="Show file sizes",
+        default=False,
+    ),
+]
+
+Pattern = Annotated[
+    Optional[str],
+    Field(
+        description="Only show files matching pattern",
+        default=None,
+    ),
+]
+
+
+class TreeParams(TypedDict, total=False):
+    """Parameters for tree tool."""
+
+    path: str
+    depth: Optional[int]
+    show_hidden: bool
+    dirs_only: bool
+    show_size: bool
+    pattern: Optional[str]
+
+
+@final
+class TreeTool(FilesystemBaseTool):
+    """Unix-style tree command for directory visualization."""
+
+    @property
+    @override
+    def name(self) -> str:
+        """Get the tool name."""
+        return "tree"
+
+    @property
+    @override
+    def description(self) -> str:
+        """Get the tool description."""
+        return """Directory tree visualization.
+
+Usage:
+tree
+tree ./src --depth 2
+tree --dirs-only
+tree --pattern "*.py" --show-size"""
+
+    @override
+    @auto_timeout("tree")
+
+
+    async def call(
+        self,
+        ctx: MCPContext,
+        **params: Unpack[TreeParams],
+    ) -> str:
+        """Execute tree command."""
+        tool_ctx = self.create_tool_context(ctx)
+
+        # Extract parameters
+        path = params.get("path", ".")
+        max_depth = params.get("depth")
+        show_hidden = params.get("show_hidden", False)
+        dirs_only = params.get("dirs_only", False)
+        show_size = params.get("show_size", False)
+        pattern = params.get("pattern")
+
+        # Validate path
+        path_validation = self.validate_path(path)
+        if path_validation.is_error:
+            return f"Error: {path_validation.error_message}"
+
+        # Check permissions
+        allowed, error_msg = await self.check_path_allowed(path, tool_ctx)
+        if not allowed:
+            return error_msg
+
+        # Check existence
+        exists, error_msg = await self.check_path_exists(path, tool_ctx)
+        if not exists:
+            return error_msg
+
+        path_obj = Path(path)
+        if not path_obj.is_dir():
+            return f"Error: {path} is not a directory"
+
+        # Build tree
+        output = [str(path_obj)]
+        stats = {"dirs": 0, "files": 0}
+
+        self._build_tree(
+            path_obj,
+            output,
+            stats,
+            prefix="",
+            is_last=True,
+            current_depth=0,
+            max_depth=max_depth,
+            show_hidden=show_hidden,
+            dirs_only=dirs_only,
+            show_size=show_size,
+            pattern=pattern,
+        )
+
+        # Add summary
+        output.append("")
+        if dirs_only:
+            output.append(f"{stats['dirs']} directories")
+        else:
+            output.append(f"{stats['dirs']} directories, {stats['files']} files")
+
+        return "\n".join(output)
+
+    def _build_tree(
+        self,
+        path: Path,
+        output: List[str],
+        stats: dict,
+        prefix: str,
+        is_last: bool,
+        current_depth: int,
+        max_depth: Optional[int],
+        show_hidden: bool,
+        dirs_only: bool,
+        show_size: bool,
+        pattern: Optional[str],
+    ) -> None:
+        """Recursively build tree structure."""
+        # Check depth limit
+        if max_depth is not None and current_depth >= max_depth:
+            return
+
+        try:
+            # Get entries
+            entries = list(path.iterdir())
+
+            # Filter hidden files
+            if not show_hidden:
+                entries = [e for e in entries if not e.name.startswith(".")]
+
+            # Filter by pattern
+            if pattern:
+                import fnmatch
+
+                entries = [e for e in entries if fnmatch.fnmatch(e.name, pattern) or e.is_dir()]
+
+            # Filter dirs only
+            if dirs_only:
+                entries = [e for e in entries if e.is_dir()]
+
+            # Sort entries (dirs first, then alphabetically)
+            entries.sort(key=lambda e: (not e.is_dir(), e.name.lower()))
+
+            # Process each entry
+            for i, entry in enumerate(entries):
+                is_last_entry = i == len(entries) - 1
+
+                # Skip if not allowed
+                if not self.is_path_allowed(str(entry)):
+                    continue
+
+                # Build the tree branch
+                if prefix:
+                    if is_last_entry:
+                        branch = prefix + "└── "
+                        extension = prefix + "    "
+                    else:
+                        branch = prefix + "├── "
+                        extension = prefix + "│   "
+                else:
+                    branch = ""
+                    extension = ""
+
+                # Build entry line
+                line = branch + entry.name
+
+                # Add size if requested
+                if show_size and entry.is_file():
+                    try:
+                        size = entry.stat().st_size
+                        line += f" ({self._format_size(size)})"
+                    except Exception:
+                        pass
+
+                output.append(line)
+
+                # Update stats
+                if entry.is_dir():
+                    stats["dirs"] += 1
+                    # Recurse into directory
+                    self._build_tree(
+                        entry,
+                        output,
+                        stats,
+                        prefix=extension,
+                        is_last=is_last_entry,
+                        current_depth=current_depth + 1,
+                        max_depth=max_depth,
+                        show_hidden=show_hidden,
+                        dirs_only=dirs_only,
+                        show_size=show_size,
+                        pattern=pattern,
+                    )
+                else:
+                    stats["files"] += 1
+
+        except PermissionError:
+            output.append(prefix + "[Permission Denied]")
+        except Exception as e:
+            output.append(prefix + f"[Error: {str(e)}]")
+
+    def _format_size(self, size: int) -> str:
+        """Format file size in human-readable format."""
+        for unit in ["B", "KB", "MB", "GB", "TB"]:
+            if size < 1024.0:
+                return f"{size:.1f}{unit}"
+            size /= 1024.0
+        return f"{size:.1f}PB"
+
+    def register(self, mcp_server) -> None:
+        """Register this tool with the MCP server."""
+        pass

hanzo_mcp/tools/filesystem/watch.py

@@ -7,6 +7,8 @@ from pathlib import Path
 from datetime import datetime
 
 from mcp.server import FastMCP
+
+from hanzo_mcp.tools.common.auto_timeout import auto_timeout
 from mcp.server.fastmcp import Context as MCPContext
 
 from hanzo_mcp.tools.common.base import BaseTool
@@ -41,11 +43,14 @@ class WatchTool(BaseTool):
                 duration=duration,
             )
 
+    @auto_timeout("watch")
+
+
     async def call(self, ctx: MCPContext, **params) -> str:
         """Call the tool with arguments."""
         return await self.run(
             ctx,
-            path=self.expand_path(params["path"]),
+            path=params["path"],
             pattern=params.get("pattern", "*"),
             interval=params.get("interval", 1),
             recursive=params.get("recursive", True),

hanzo_mcp/tools/filesystem/write.py

@@ -8,6 +8,8 @@ from pathlib import Path
 
 from pydantic import Field
 from mcp.server import FastMCP
+
+from hanzo_mcp.tools.common.auto_timeout import auto_timeout
 from mcp.server.fastmcp import Context as MCPContext
 
 from hanzo_mcp.tools.filesystem.base import FilesystemBaseTool
@@ -72,6 +74,9 @@ Usage:
 - NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User."""
 
     @override
+    @auto_timeout("write")
+
+
     async def call(
         self,
         ctx: MCPContext,
@@ -99,17 +104,18 @@ Usage:
             await tool_ctx.error(path_validation.error_message)
             return f"Error: {path_validation.error_message}"
 
-        # Expand path first (handles ~, $HOME, etc.)
-        expanded_path = self.expand_path(file_path)
-        await tool_ctx.info(f"Writing file: {expanded_path}")
+        await tool_ctx.info(f"Writing file: {file_path}")
 
-        # Check if file is allowed to be written (using expanded path)
-        allowed, error_msg = await self.check_path_allowed(expanded_path, tool_ctx)
+        # Check if file is allowed to be written
+        allowed, error_msg = await self.check_path_allowed(file_path, tool_ctx)
         if not allowed:
             return error_msg
 
+        # Additional check already verified by is_path_allowed above
+        await tool_ctx.info(f"Writing file: {file_path}")
+
         try:
-            path_obj = Path(expanded_path)
+            path_obj = Path(file_path)
 
             # Check if parent directory is allowed
             parent_dir = str(path_obj.parent)

hanzo_mcp/tools/jupyter/jupyter.py

@@ -16,6 +16,8 @@ import nbformat
 from pydantic import Field
 from mcp.server.fastmcp import Context as MCPContext
 
+from hanzo_mcp.tools.common.auto_timeout import auto_timeout
+
 from hanzo_mcp.tools.jupyter.base import JupyterBaseTool
 
 # Parameter types
@@ -111,6 +113,9 @@ jupyter --action create "new.ipynb"
 """
 
     @override
+    @auto_timeout("jupyter")
+
+
     async def call(
         self,
         ctx: MCPContext,
@@ -311,8 +316,31 @@ jupyter --action create "new.ipynb"
             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."
+        """Execute notebook cells using nbclient."""
+        try:
+            import nbclient
+            from nbclient import NotebookClient
+
+            nb = nbformat.read(notebook_path, as_version=4)
+
+            # Create a notebook client with default kernel
+            client = NotebookClient(
+                nb,
+                timeout=params.get('timeout', 600),
+                kernel_name=params.get('kernel_name', 'python3')
+            )
+
+            # Execute the notebook
+            await client.async_execute()
+
+            # Save the executed notebook
+            nbformat.write(nb, notebook_path)
+
+            return f"Successfully executed all cells in {notebook_path}"
+        except ImportError:
+            return "Error: nbclient not installed. Install with: pip install nbclient"
+        except Exception as e:
+            return f"Error executing notebook: {str(e)}"
 
     def _format_cell(self, cell: dict, index: int) -> str:
         """Format a single cell for display."""

hanzo_mcp/tools/jupyter/notebook_edit.py

@@ -0,0 +1,298 @@
+"""Edit notebook tool implementation.
+
+This module provides the NoteBookEditTool for editing Jupyter notebook files.
+"""
+
+import json
+from typing import Any, Unpack, Literal, Annotated, TypedDict, final, override
+from pathlib import Path
+
+from pydantic import Field
+from mcp.server import FastMCP
+
+from hanzo_mcp.tools.common.auto_timeout import auto_timeout
+from mcp.server.fastmcp import Context as MCPContext
+
+from hanzo_mcp.tools.jupyter.base import JupyterBaseTool
+
+NotebookPath = Annotated[
+    str,
+    Field(
+        description="The absolute path to the Jupyter notebook file to edit (must be absolute, not relative)",
+    ),
+]
+
+CellNumber = Annotated[
+    int,
+    Field(
+        description="The index of the cell to edit (0-based)",
+        ge=0,
+    ),
+]
+
+NewSource = Annotated[
+    str,
+    Field(
+        description="The new source for the cell",
+        default="",
+    ),
+]
+
+CellType = Annotated[
+    Literal["code", "markdown"],
+    Field(
+        description="The of the cell (code or markdown). If not specified, it defaults to the current cell type. If using edit_mode=insert, this is required.",
+        default="code",
+    ),
+]
+
+EditMode = Annotated[
+    Literal["replace", "insert", "delete"],
+    Field(
+        description="The of edit to make (replace, insert, delete). Defaults to replace.",
+        default="replace",
+    ),
+]
+
+
+class NotebookEditToolParams(TypedDict):
+    """Parameters for the NotebookEditTool.
+
+    Attributes:
+        notebook_path: The absolute path to the Jupyter notebook file to edit (must be absolute, not relative)
+        cell_number: The index of the cell to edit (0-based)
+        new_source: The new source for the cell
+        cell_type: The of the cell (code or markdown). If not specified, it defaults to the current cell type. If using edit_mode=insert, this is required.
+        edit_mode: The of edit to make (replace, insert, delete). Defaults to replace.
+    """
+
+    notebook_path: NotebookPath
+    cell_number: CellNumber
+    new_source: NewSource
+    cell_type: CellType
+    edit_mode: EditMode
+
+
+@final
+class NoteBookEditTool(JupyterBaseTool):
+    """Tool for editing Jupyter notebook files."""
+
+    @property
+    @override
+    def name(self) -> str:
+        """Get the tool name.
+
+        Returns:
+            Tool name
+        """
+        return "notebook_edit"
+
+    @property
+    @override
+    def description(self) -> str:
+        """Get the tool description.
+
+        Returns:
+            Tool description
+        """
+        return "Completely replaces the contents of a specific cell in a Jupyter notebook (.ipynb file) with new source. Jupyter notebooks are interactive documents that combine code, text, and visualizations, commonly used for data analysis and scientific computing. The notebook_path parameter must be an absolute path, not a relative path. The cell_number is 0-indexed. Use edit_mode=insert to add a new cell at the index specified by cell_number. Use edit_mode=delete to delete the cell at the index specified by cell_number."
+
+    @override
+    @auto_timeout("notebook_edit")
+
+
+    async def call(
+        self,
+        ctx: MCPContext,
+        **params: Unpack[NotebookEditToolParams],
+    ) -> str:
+        """Execute the tool with the given parameters.
+
+        Args:
+            ctx: MCP context
+            **params: Tool parameters
+
+        Returns:
+            Tool result
+        """
+        tool_ctx = self.create_tool_context(ctx)
+        self.set_tool_context_info(tool_ctx)
+
+        # Extract parameters
+        notebook_path = params.get("notebook_path")
+        cell_number = params.get("cell_number")
+        new_source = params.get("new_source")
+        cell_type = params.get("cell_type")
+        edit_mode = params.get("edit_mode", "replace")
+
+        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}"
+
+        # Validate edit_mode
+        if edit_mode not in ["replace", "insert", "delete"]:
+            await tool_ctx.error("Edit mode must be replace, insert, or delete")
+            return "Error: Edit mode must be replace, insert, or delete"
+
+        # In insert mode, cell_type is required
+        if edit_mode == "insert" and cell_type is None:
+            await tool_ctx.error("Cell type is required when using insert mode")
+            return "Error: Cell type is required when using insert mode"
+
+        # Don't validate new_source for delete mode
+        if edit_mode != "delete" and not new_source:
+            await tool_ctx.error("New source is required for replace or insert operations")
+            return "Error: New source is required for replace or insert operations"
+
+        await tool_ctx.info(f"Editing notebook: {notebook_path} (cell: {cell_number}, mode: {edit_mode})")
+
+        # Check if path is allowed
+        if not self.is_path_allowed(notebook_path):
+            await tool_ctx.error(f"Access denied - path outside allowed directories: {notebook_path}")
+            return f"Error: Access denied - path outside allowed directories: {notebook_path}"
+
+        try:
+            file_path = Path(notebook_path)
+
+            if not file_path.exists():
+                await tool_ctx.error(f"File does not exist: {notebook_path}")
+                return f"Error: File does not exist: {notebook_path}"
+
+            if not file_path.is_file():
+                await tool_ctx.error(f"Path is not a file: {notebook_path}")
+                return f"Error: Path is not a file: {notebook_path}"
+
+            # Check file extension
+            if file_path.suffix.lower() != ".ipynb":
+                await tool_ctx.error(f"File is not a Jupyter notebook: {notebook_path}")
+                return f"Error: File is not a Jupyter notebook: {notebook_path}"
+
+            # Read and parse the notebook
+            try:
+                with open(file_path, "r", encoding="utf-8") as f:
+                    content = f.read()
+                    notebook = json.loads(content)
+            except json.JSONDecodeError:
+                await tool_ctx.error(f"Invalid notebook format: {notebook_path}")
+                return f"Error: Invalid notebook format: {notebook_path}"
+            except UnicodeDecodeError:
+                await tool_ctx.error(f"Cannot read notebook file: {notebook_path}")
+                return f"Error: Cannot read notebook file: {notebook_path}"
+
+            # Check cell_number is valid
+            cells = notebook.get("cells", [])
+
+            if edit_mode == "insert":
+                if cell_number > len(cells):
+                    await tool_ctx.error(f"Cell number {cell_number} is out of bounds for insert (max: {len(cells)})")
+                    return f"Error: Cell number {cell_number} is out of bounds for insert (max: {len(cells)})"
+            else:  # replace or delete
+                if cell_number >= len(cells):
+                    await tool_ctx.error(f"Cell number {cell_number} is out of bounds (max: {len(cells) - 1})")
+                    return f"Error: Cell number {cell_number} is out of bounds (max: {len(cells) - 1})"
+
+            # Get notebook language (needed for context but not directly used in this block)
+            _ = notebook.get("metadata", {}).get("language_info", {}).get("name", "python")
+
+            # Perform the requested operation
+            if edit_mode == "replace":
+                # Get the target cell
+                target_cell = cells[cell_number]
+
+                # Store previous contents for reporting
+                old_type = target_cell.get("cell_type", "code")
+                old_source = target_cell.get("source", "")
+
+                # Fix for old_source which might be a list of strings
+                if isinstance(old_source, list):
+                    old_source = "".join([str(item) for item in old_source])
+
+                # Update source
+                target_cell["source"] = new_source
+
+                # Update type if specified
+                if cell_type is not None:
+                    target_cell["cell_type"] = cell_type
+
+                # If changing to markdown, remove code-specific fields
+                if cell_type == "markdown":
+                    if "outputs" in target_cell:
+                        del target_cell["outputs"]
+                    if "execution_count" in target_cell:
+                        del target_cell["execution_count"]
+
+                # If code cell, reset execution
+                if target_cell["cell_type"] == "code":
+                    target_cell["outputs"] = []
+                    target_cell["execution_count"] = None
+
+                change_description = f"Replaced cell {cell_number}"
+                if cell_type is not None and cell_type != old_type:
+                    change_description += f" (changed type from {old_type} to {cell_type})"
+
+            elif edit_mode == "insert":
+                # Create new cell
+                new_cell: dict[str, Any] = {
+                    "cell_type": cell_type,
+                    "source": new_source,
+                    "metadata": {},
+                }
+
+                # Add code-specific fields
+                if cell_type == "code":
+                    new_cell["outputs"] = []
+                    new_cell["execution_count"] = None
+
+                # Insert the cell
+                cells.insert(cell_number, new_cell)
+                change_description = f"Inserted new {cell_type} cell at position {cell_number}"
+
+            else:  # delete
+                # Store deleted cell info for reporting
+                deleted_cell = cells[cell_number]
+                deleted_type = deleted_cell.get("cell_type", "code")
+
+                # Remove the cell
+                del cells[cell_number]
+                change_description = f"Deleted {deleted_type} cell at position {cell_number}"
+
+            # Write the updated notebook back to file
+            with open(file_path, "w", encoding="utf-8") as f:
+                json.dump(notebook, f, indent=1)
+
+            await tool_ctx.info(f"Successfully edited notebook: {notebook_path} - {change_description}")
+            return f"Successfully edited notebook: {notebook_path} - {change_description}"
+        except Exception as e:
+            await tool_ctx.error(f"Error editing notebook: {str(e)}")
+            return f"Error editing notebook: {str(e)}"
+
+    @override
+    def register(self, mcp_server: FastMCP) -> None:
+        """Register this edit notebook tool with the MCP server.
+
+        Creates a wrapper function with explicitly defined parameters that match
+        the tool's parameter schema and registers it with the MCP server.
+
+        Args:
+            mcp_server: The FastMCP server instance
+        """
+        tool_self = self  # Create a reference to self for use in the closure
+
+        @mcp_server.tool(name=self.name, description=self.description)
+        async def notebook_edit(
+            notebook_path: NotebookPath,
+            cell_number: CellNumber,
+            new_source: NewSource,
+            cell_type: CellType,
+            edit_mode: EditMode,
+            ctx: MCPContext,
+        ) -> str:
+            return await tool_self.call(
+                ctx,
+                notebook_path=notebook_path,
+                cell_number=cell_number,
+                new_source=new_source,
+                cell_type=cell_type,
+                edit_mode=edit_mode,
+            )