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

hanzo_mcp/tools/filesystem/directory_tree.py

@@ -4,33 +4,75 @@ This module provides the DirectoryTreeTool for viewing file and directory struct
 """
 
 from pathlib import Path
-from typing import Any, final, override
+from typing import Annotated, Any, TypedDict, Unpack, final, override
 
-from mcp.server.fastmcp import Context as MCPContext
-from mcp.server.fastmcp import FastMCP
+from fastmcp import Context as MCPContext
+from fastmcp import FastMCP
+from fastmcp.server.dependencies import get_context
+from pydantic import Field
 
 from hanzo_mcp.tools.filesystem.base import FilesystemBaseTool
 
+DirectoryPath = Annotated[
+    str,
+    Field(
+        description="The path to the directory to view",
+        title="Path",
+    ),
+]
+
+Depth = Annotated[
+    int,
+    Field(
+        default=3,
+        description="The maximum depth to traverse (0 for unlimited)",
+        title="Depth",
+    ),
+]
+
+IncludeFiltered = Annotated[
+    bool,
+    Field(
+        default=False,
+        description="Include directories that are normally filtered",
+        title="Include Filtered",
+    ),
+]
+
+
+class DirectoryTreeToolParams(TypedDict):
+    """Parameters for the DirectoryTreeTool.
+
+    Attributes:
+        path: The path to the directory to view
+        depth: The maximum depth to traverse (0 for unlimited)
+        include_filtered: Include directories that are normally filtered
+    """
+
+    path: DirectoryPath
+    depth: Depth
+    include_filtered: IncludeFiltered
+
 
 @final
 class DirectoryTreeTool(FilesystemBaseTool):
     """Tool for viewing directory structure as a tree."""
-    
+
     @property
     @override
     def name(self) -> str:
         """Get the tool name.
-        
+
         Returns:
             Tool name
         """
         return "directory_tree"
-        
+
     @property
     @override
     def description(self) -> str:
         """Get the tool description.
-        
+
         Returns:
             Tool description
         """
@@ -41,75 +83,28 @@ Directories are marked with trailing slashes. The output is formatted as an
 indented list for readability. By default, common development directories like
 .git, node_modules, and venv are noted but not traversed unless explicitly
 requested. Only works within allowed directories."""
-        
-    @property
-    @override
-    def parameters(self) -> dict[str, Any]:
-        """Get the parameter specifications for the tool.
-        
-        Returns:
-            Parameter specifications
-        """
-        return {
-            "properties": {
-                "path": {
-                    "title": "Path",
-                    "type": "string",
-                    "description":"The path to the directory to view"
-                },
-                "depth": {
-                    "default": 3,
-                    "title": "Depth",
-                    "type": "integer",
-                    "description": "The maximum depth to traverse (0 for unlimited)"
-                },
-                "include_filtered": {
-                    "default": False,
-                    "title": "Include Filtered",
-                    "type": "boolean",
-                    "description": "Include directories that are normally filtered"
-                }
-            },
-            "required": ["path"],
-            "title": "directory_treeArguments",
-            "type": "object"
-        }
-        
-    @property
-    @override
-    def required(self) -> list[str]:
-        """Get the list of required parameter names.
-        
-        Returns:
-            List of required parameter names
-        """
-        return ["path"]
-        
+
     @override
-    async def call(self, ctx: MCPContext, **params: Any) -> str:
+    async def call(
+        self,
+        ctx: MCPContext,
+        **params: Unpack[DirectoryTreeToolParams],
+    ) -> 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)
-        
+
         # Extract parameters
-        path = params.get("path")
+        path: DirectoryPath = params["path"]
         depth = params.get("depth", 3)  # Default depth is 3
         include_filtered = params.get("include_filtered", False)  # Default to False
-        
-        if not path:
-            await tool_ctx.error("Parameter 'path' is required but was None")
-            return "Error: Parameter 'path' is required but was None"
-
-        if path.strip() == "":
-            await tool_ctx.error("Parameter 'path' cannot be empty")
-            return "Error: Parameter 'path' cannot be empty"
 
         # Validate path parameter
         path_validation = self.validate_path(path)
@@ -117,7 +112,9 @@ requested. Only works within allowed directories."""
             await tool_ctx.error(path_validation.error_message)
             return f"Error: {path_validation.error_message}"
 
-        await tool_ctx.info(f"Getting directory tree: {path} (depth: {depth}, include_filtered: {include_filtered})")
+        await tool_ctx.info(
+            f"Getting directory tree: {path} (depth: {depth}, include_filtered: {include_filtered})"
+        )
 
         # Check if path is allowed
         allowed, error_msg = await self.check_path_allowed(path, tool_ctx)
@@ -131,7 +128,7 @@ requested. Only works within allowed directories."""
             exists, error_msg = await self.check_path_exists(path, tool_ctx)
             if not exists:
                 return error_msg
-                
+
             # Check if path is a directory
             is_dir, error_msg = await self.check_is_directory(path, tool_ctx)
             if not is_dir:
@@ -139,35 +136,51 @@ requested. Only works within allowed directories."""
 
             # Define filtered directories
             FILTERED_DIRECTORIES = {
-                ".git", "node_modules", ".venv", "venv", 
-                "__pycache__", ".pytest_cache", ".idea", 
-                ".vs", ".vscode", "dist", "build", "target",
-                ".ruff_cache",".llm-context"
+                ".git",
+                "node_modules",
+                ".venv",
+                "venv",
+                "__pycache__",
+                ".pytest_cache",
+                ".idea",
+                ".vs",
+                ".vscode",
+                "dist",
+                "build",
+                "target",
+                ".ruff_cache",
+                ".llm-context",
             }
-            
+
             # Log filtering settings
-            await tool_ctx.info(f"Directory tree filtering: include_filtered={include_filtered}")
-            
+            await tool_ctx.info(
+                f"Directory tree filtering: include_filtered={include_filtered}"
+            )
+
             # Check if a directory should be filtered
             def should_filter(current_path: Path) -> bool:
                 # Don't filter if it's the explicitly requested path
                 if str(current_path.absolute()) == str(dir_path.absolute()):
                     # Don't filter explicitly requested paths
                     return False
-                    
+
                 # Filter based on directory name if filtering is enabled
-                return current_path.name in FILTERED_DIRECTORIES and not include_filtered
-            
+                return (
+                    current_path.name in FILTERED_DIRECTORIES and not include_filtered
+                )
+
             # Track stats for summary
             stats = {
                 "directories": 0,
                 "files": 0,
                 "skipped_depth": 0,
-                "skipped_filtered": 0
+                "skipped_filtered": 0,
             }
 
             # Build the tree recursively
-            async def build_tree(current_path: Path, current_depth: int = 0) -> list[dict[str, Any]]:
+            async def build_tree(
+                current_path: Path, current_depth: int = 0
+            ) -> list[dict[str, Any]]:
                 result: list[dict[str, Any]] = []
 
                 # Skip processing if path isn't allowed
@@ -176,8 +189,10 @@ requested. Only works within allowed directories."""
 
                 try:
                     # Sort entries: directories first, then files alphabetically
-                    entries = sorted(current_path.iterdir(), key=lambda x: (not x.is_dir(), x.name))
-                    
+                    entries = sorted(
+                        current_path.iterdir(), key=lambda x: (not x.is_dir(), x.name)
+                    )
+
                     for entry in entries:
                         # Skip entries that aren't allowed
                         if not self.is_path_allowed(str(entry)):
@@ -205,37 +220,38 @@ requested. Only works within allowed directories."""
                                 continue
 
                             # Process children recursively with depth increment
-                            entry_data["children"] = await build_tree(entry, current_depth + 1)
+                            entry_data["children"] = await build_tree(
+                                entry, current_depth + 1
+                            )
                             result.append(entry_data)
                         else:
                             # Files should be at the same level check as directories
                             if depth <= 0 or current_depth < depth:
                                 stats["files"] += 1
                                 # Add file entry
-                                result.append({
-                                    "name": entry.name,
-                                    "type": "file"
-                                })
-                            
+                                result.append({"name": entry.name, "type": "file"})
+
                 except Exception as e:
-                    await tool_ctx.warning(
-                        f"Error processing {current_path}: {str(e)}"
-                    )
+                    await tool_ctx.warning(f"Error processing {current_path}: {str(e)}")
 
                 return result
 
             # Format the tree as a simple indented structure
-            def format_tree(tree_data: list[dict[str, Any]], level: int = 0) -> list[str]:
+            def format_tree(
+                tree_data: list[dict[str, Any]], level: int = 0
+            ) -> list[str]:
                 lines = []
-                
+
                 for item in tree_data:
                     # Indentation based on level
                     indent = "  " * level
-                    
+
                     # Format based on type
                     if item["type"] == "directory":
                         if "skipped" in item:
-                            lines.append(f"{indent}{item['name']}/ [skipped - {item['skipped']}]")
+                            lines.append(
+                                f"{indent}{item['name']}/ [skipped - {item['skipped']}]"
+                            )
                         else:
                             lines.append(f"{indent}{item['name']}/")
                             # Add children with increased indentation if present
@@ -244,43 +260,51 @@ requested. Only works within allowed directories."""
                     else:
                         # File
                         lines.append(f"{indent}{item['name']}")
-                        
+
                 return lines
 
             # Build tree starting from the requested directory
             tree_data = await build_tree(dir_path)
-            
+
             # Format as simple text
             formatted_output = "\n".join(format_tree(tree_data))
-            
+
             # Add stats summary
             summary = (
                 f"\nDirectory Stats: {stats['directories']} directories, {stats['files']} files "
                 f"({stats['skipped_depth']} skipped due to depth limit, "
                 f"{stats['skipped_filtered']} filtered directories skipped)"
             )
-            
+
             await tool_ctx.info(
                 f"Generated directory tree for {path} (depth: {depth}, include_filtered: {include_filtered})"
             )
-            
+
             return formatted_output + summary
         except Exception as e:
             await tool_ctx.error(f"Error generating directory tree: {str(e)}")
             return f"Error generating directory tree: {str(e)}"
-            
+
     @override
     def register(self, mcp_server: FastMCP) -> None:
         """Register this directory tree 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.mcp_description)
-        async def directory_tree(ctx: MCPContext, path: str, depth: int = 3, include_filtered: bool = False) -> str:
-            return await tool_self.call(ctx, path=path, depth=depth, include_filtered=include_filtered)
+
+        @mcp_server.tool(name=self.name, description=self.description)
+        async def directory_tree(
+            ctx: MCPContext,
+            path: DirectoryPath,
+            depth: Depth,
+            include_filtered: IncludeFiltered,
+        ) -> str:
+            ctx = get_context()
+            return await tool_self.call(
+                ctx, path=path, depth=depth, include_filtered=include_filtered
+            )

hanzo_mcp/tools/filesystem/edit.py

@@ -0,0 +1,279 @@
+"""Edit tool implementation.
+
+This module provides the Edit tool for making precise text replacements in files.
+"""
+
+from difflib import unified_diff
+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 pydantic import Field
+
+from hanzo_mcp.tools.filesystem.base import FilesystemBaseTool
+
+FilePath = Annotated[
+    str,
+    Field(
+        description="The absolute path to the file to modify (must be absolute, not relative)",
+    ),
+]
+
+OldString = Annotated[
+    str,
+    Field(
+        description="The text to replace (must match the file contents exactly, including all whitespace and indentation)",
+    ),
+]
+
+NewString = Annotated[
+    str,
+    Field(
+        description="The edited text to replace the old_string",
+    ),
+]
+
+ExpectedReplacements = Annotated[
+    int,
+    Field(
+        default=1,
+        description="The expected number of replacements to perform. Defaults to 1 if not specified.",
+    ),
+]
+
+
+class EditToolParams(TypedDict):
+    """Parameters for the Edit tool.
+
+    Attributes:
+        file_path: The absolute path to the file to modify (must be absolute, not relative)
+        old_string: The text to replace (must match the file contents exactly, including all whitespace and indentation)
+        new_string: The edited text to replace the old_string
+        expected_replacements: The expected number of replacements to perform. Defaults to 1 if not specified.
+    """
+
+    file_path: FilePath
+    old_string: OldString
+    new_string: NewString
+    expected_replacements: ExpectedReplacements
+
+
+@final
+class Edit(FilesystemBaseTool):
+    """Tool for making precise text replacements in files."""
+
+    @property
+    @override
+    def name(self) -> str:
+        """Get the tool name.
+
+        Returns:
+            Tool name
+        """
+        return "edit"
+
+    @property
+    @override
+    def description(self) -> str:
+        """Get the tool description.
+
+        Returns:
+            Tool description
+        """
+        return """Performs exact string replacements in files with strict occurrence count validation.
+
+Usage:
+- When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: spaces + line number + tab. Everything after that tab is the actual file content to match. Never include any part of the line number prefix in the old_string or new_string.
+- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required."""
+
+    @override
+    async def call(
+        self,
+        ctx: MCPContext,
+        **params: Unpack[EditToolParams],
+    ) -> 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
+        file_path: FilePath = params["file_path"]
+        old_string: OldString = params["old_string"]
+        new_string: NewString = params["new_string"]
+        expected_replacements = params.get("expected_replacements", 1)
+
+        # Validate parameters
+        path_validation = self.validate_path(file_path)
+        if path_validation.is_error:
+            await tool_ctx.error(path_validation.error_message)
+            return f"Error: {path_validation.error_message}"
+
+        # Only validate old_string for non-empty if we're not creating a new file
+        # Empty old_string is valid when creating a new file
+        file_exists = Path(file_path).exists()
+        if file_exists and old_string.strip() == "":
+            await tool_ctx.error(
+                "Parameter 'old_string' cannot be empty for existing files"
+            )
+            return "Error: Parameter 'old_string' cannot be empty for existing files"
+
+        if (
+            expected_replacements is None
+            or not isinstance(expected_replacements, (int, float))
+            or expected_replacements < 0
+        ):
+            await tool_ctx.error(
+                "Parameter 'expected_replacements' must be a non-negative number"
+            )
+            return (
+                "Error: Parameter 'expected_replacements' must be a non-negative number"
+            )
+
+        await tool_ctx.info(f"Editing file: {file_path}")
+
+        # Check if file is allowed to be edited
+        allowed, error_msg = await self.check_path_allowed(file_path, tool_ctx)
+        if not allowed:
+            return error_msg
+
+        try:
+            file_path_obj = Path(file_path)
+
+            # If the file doesn't exist and old_string is empty, create a new file
+            if not file_path_obj.exists() and old_string == "":
+                # Check if parent directory is allowed
+                parent_dir = str(file_path_obj.parent)
+                if not self.is_path_allowed(parent_dir):
+                    await tool_ctx.error(f"Parent directory not allowed: {parent_dir}")
+                    return f"Error: Parent directory not allowed: {parent_dir}"
+
+                # Create parent directories if they don't exist
+                file_path_obj.parent.mkdir(parents=True, exist_ok=True)
+
+                # Create the new file with the new_string content
+                with open(file_path_obj, "w", encoding="utf-8") as f:
+                    f.write(new_string)
+
+                await tool_ctx.info(f"Successfully created file: {file_path}")
+                return (
+                    f"Successfully created file: {file_path} ({len(new_string)} bytes)"
+                )
+
+            # Check file exists for non-creation operations
+            exists, error_msg = await self.check_path_exists(file_path, tool_ctx)
+            if not exists:
+                return error_msg
+
+            # Check is a file
+            is_file, error_msg = await self.check_is_file(file_path, tool_ctx)
+            if not is_file:
+                return error_msg
+
+            # Read the file
+            try:
+                with open(file_path_obj, "r", encoding="utf-8") as f:
+                    original_content = f.read()
+
+                # Apply edit
+                if old_string in original_content:
+                    # Count occurrences of the old_string in the content
+                    occurrences = original_content.count(old_string)
+
+                    # Check if the number of occurrences matches expected_replacements
+                    if occurrences != expected_replacements:
+                        await tool_ctx.error(
+                            f"Found {occurrences} occurrences of the specified old_string, but expected {expected_replacements}"
+                        )
+                        return f"Error: Found {occurrences} occurrences of the specified old_string, but expected {expected_replacements}. Change your old_string to uniquely identify the target text, or set expected_replacements={occurrences} to replace all occurrences."
+
+                    # Replace all occurrences since the count matches expectations
+                    modified_content = original_content.replace(old_string, new_string)
+                else:
+                    # If we can't find the exact string, report an error
+                    await tool_ctx.error(
+                        "The specified old_string was not found in the file content"
+                    )
+                    return "Error: The specified old_string was not found in the file content. Please check that it matches exactly, including all whitespace and indentation."
+
+                # Generate diff
+                original_lines = original_content.splitlines(keepends=True)
+                modified_lines = modified_content.splitlines(keepends=True)
+
+                diff_lines = list(
+                    unified_diff(
+                        original_lines,
+                        modified_lines,
+                        fromfile=f"{file_path} (original)",
+                        tofile=f"{file_path} (modified)",
+                        n=3,
+                    )
+                )
+
+                diff_text = "".join(diff_lines)
+
+                # Determine the number of backticks needed
+                num_backticks = 3
+                while f"```{num_backticks}" in diff_text:
+                    num_backticks += 1
+
+                # Format diff with appropriate number of backticks
+                formatted_diff = (
+                    f"```{num_backticks}diff\n{diff_text}```{num_backticks}\n"
+                )
+
+                # Write the file if there are changes
+                if diff_text:
+                    with open(file_path_obj, "w", encoding="utf-8") as f:
+                        f.write(modified_content)
+
+                    await tool_ctx.info(
+                        f"Successfully edited file: {file_path} ({expected_replacements} replacements applied)"
+                    )
+                    return f"Successfully edited file: {file_path} ({expected_replacements} replacements applied)\n\n{formatted_diff}"
+                else:
+                    return f"No changes made to file: {file_path}"
+            except UnicodeDecodeError:
+                await tool_ctx.error(f"Cannot edit binary file: {file_path}")
+                return f"Error: Cannot edit binary file: {file_path}"
+        except Exception as e:
+            await tool_ctx.error(f"Error editing file: {str(e)}")
+            return f"Error editing file: {str(e)}"
+
+    @override
+    def register(self, mcp_server: FastMCP) -> None:
+        """Register this edit 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 edit(
+            ctx: MCPContext,
+            file_path: FilePath,
+            old_string: OldString,
+            new_string: NewString,
+            expected_replacements: ExpectedReplacements,
+        ) -> str:
+            ctx = get_context()
+            return await tool_self.call(
+                ctx,
+                file_path=file_path,
+                old_string=old_string,
+                new_string=new_string,
+                expected_replacements=expected_replacements,
+            )