hanzo-tools-fs 0.3.0__tar.gz

hanzo_tools_fs-0.3.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: hanzo-tools-fs
+Version: 0.3.0
+Summary: Filesystem tools for Hanzo AI - read, write, edit, search, find
+Author-email: Hanzo Industries Inc <dev@hanzo.ai>
+License: MIT
+Project-URL: Homepage, https://github.com/hanzoai/python-sdk
+Keywords: hanzo,tools,filesystem,mcp,ai
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: aiofiles>=24.1.0
+Requires-Dist: grep-ast>=0.8.1
+Requires-Dist: ffind>=1.3.0
+Requires-Dist: watchdog>=6.0.0
+Requires-Dist: mcp>=1.25.0
+Requires-Dist: fastmcp>=2.14.1
+Requires-Dist: pydantic>=2.12.5
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: ruff>=0.14.0; extra == "dev"

hanzo_tools_fs-0.3.0/hanzo_tools/__init__.py

@@ -0,0 +1,3 @@
+"""Hanzo Tools namespace package."""
+
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

hanzo_tools_fs-0.3.0/hanzo_tools/fs/__init__.py

@@ -0,0 +1,136 @@
+"""Filesystem tools for Hanzo AI.
+
+Tools:
+- read: Read file contents
+- write: Write/create files
+- edit: Edit files with find/replace
+- multi_edit: Multiple edits in one operation
+- tree: Directory tree view
+- find: Find files by pattern
+- search: Search file contents
+- ast: AST-based code search
+- rules: Read project rules/config
+
+Install:
+    pip install hanzo-tools-fs
+
+Usage:
+    from hanzo_tools.fs import register_tools, TOOLS
+
+    # Register with MCP server
+    register_tools(mcp_server, permission_manager)
+
+    # Or access individual tools
+    from hanzo_tools.fs import ReadTool, WriteTool
+"""
+
+from hanzo_tools.fs.ast import ASTTool
+from hanzo_tools.fs.edit import EditTool
+from hanzo_tools.fs.find import FindTool
+from hanzo_tools.fs.read import ReadTool
+from hanzo_tools.fs.tree import TreeTool
+from hanzo_tools.fs.write import WriteTool
+from hanzo_tools.fs.search import SearchTool
+
+# Backwards compatibility aliases
+Edit = EditTool
+Read = ReadTool
+Write = WriteTool
+
+# Read-only tools (for agent sandboxing)
+READ_ONLY_TOOLS = [
+    ReadTool,
+    TreeTool,
+    FindTool,
+    SearchTool,
+    ASTTool,
+]
+
+# Export list for tool discovery
+TOOLS = [
+    ReadTool,
+    WriteTool,
+    EditTool,
+    TreeTool,
+    FindTool,
+    SearchTool,
+    ASTTool,
+]
+
+__all__ = [
+    # Tool classes
+    "ReadTool",
+    "WriteTool",
+    "EditTool",
+    "TreeTool",
+    "FindTool",
+    "SearchTool",
+    "ASTTool",
+    # Aliases
+    "Edit",
+    "Read",
+    "Write",
+    # Registration
+    "register_tools",
+    "get_read_only_filesystem_tools",
+    "TOOLS",
+    "READ_ONLY_TOOLS",
+]
+
+
+def get_read_only_filesystem_tools(permission_manager) -> list:
+    """Get read-only filesystem tools for sandboxed agents.
+
+    Returns tools that can only read files, not modify them:
+    - read: Read file contents
+    - tree: View directory structure
+    - find: Find files by pattern
+    - search: Search file contents
+    - ast: Code structure analysis
+
+    Args:
+        permission_manager: PermissionManager instance
+
+    Returns:
+        List of instantiated read-only tools
+    """
+    tools = []
+    for tool_class in READ_ONLY_TOOLS:
+        try:
+            tools.append(tool_class(permission_manager))
+        except TypeError:
+            tools.append(tool_class())
+    return tools
+
+
+def register_tools(mcp_server, permission_manager, enabled_tools: dict[str, bool] | None = None):
+    """Register all filesystem tools with the MCP server.
+
+    Args:
+        mcp_server: FastMCP server instance
+        permission_manager: PermissionManager for access control
+        enabled_tools: Dict of tool_name -> enabled state
+
+    Returns:
+        List of registered tool instances
+    """
+    from hanzo_tools.core import ToolRegistry
+
+    enabled = enabled_tools or {}
+    registered = []
+
+    for tool_class in TOOLS:
+        tool_name = tool_class.name if hasattr(tool_class, "name") else tool_class.__name__.lower()
+
+        if enabled.get(tool_name, True):  # Enabled by default
+            try:
+                tool = tool_class(permission_manager)
+                ToolRegistry.register_tool(mcp_server, tool)
+                registered.append(tool)
+            except TypeError:
+                # Tool doesn't need permission_manager
+                tool = tool_class()
+                ToolRegistry.register_tool(mcp_server, tool)
+                registered.append(tool)
+
+    return registered

hanzo_tools_fs-0.3.0/hanzo_tools/fs/ast.py

@@ -0,0 +1,291 @@
+"""AST-based code structure search using tree-sitter.
+
+This module provides the ASTTool for searching, indexing, and querying code symbols
+using tree-sitter AST parsing. It can find function definitions, class declarations,
+and other code structures with full context.
+"""
+
+import os
+from typing import Unpack, Annotated, TypedDict, final, override
+from pathlib import Path
+
+from pydantic import Field
+from mcp.server import FastMCP
+from mcp.server.fastmcp import Context as MCPContext
+
+from hanzo_tools.core import BaseTool
+
+# Lazy import for grep_ast
+_tree_context_cls = None
+
+
+def _get_tree_context():
+    """Lazy load TreeContext to avoid import-time overhead."""
+    global _tree_context_cls
+    if _tree_context_cls is None:
+        from grep_ast.grep_ast import TreeContext
+
+        _tree_context_cls = TreeContext
+    return _tree_context_cls
+
+
+# Type annotations for parameters
+Pattern = Annotated[
+    str,
+    Field(
+        description="The regex pattern to search for in source code files",
+        min_length=1,
+    ),
+]
+
+SearchPath = Annotated[
+    str,
+    Field(
+        description="The path to search in (file or directory)",
+        min_length=1,
+    ),
+]
+
+IgnoreCase = Annotated[
+    bool,
+    Field(
+        description="Whether to ignore case when matching",
+        default=False,
+    ),
+]
+
+LineNumber = Annotated[
+    bool,
+    Field(
+        description="Whether to display line numbers",
+        default=False,
+    ),
+]
+
+
+class ASTToolParams(TypedDict, total=False):
+    """Parameters for the ASTTool.
+
+    Attributes:
+        pattern: The regex pattern to search for in source code files
+        path: The path to search in (file or directory)
+        ignore_case: Whether to ignore case when matching
+        line_number: Whether to display line numbers
+    """
+
+    pattern: Pattern
+    path: SearchPath
+    ignore_case: IgnoreCase
+    line_number: LineNumber
+
+
+# Extensions supported by tree-sitter (common programming languages)
+SUPPORTED_EXTENSIONS = {
+    ".py",
+    ".pyw",  # Python
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",  # JavaScript
+    ".ts",
+    ".tsx",
+    ".mts",
+    ".cts",  # TypeScript
+    ".go",  # Go
+    ".rs",  # Rust
+    ".c",
+    ".h",  # C
+    ".cpp",
+    ".cc",
+    ".cxx",
+    ".hpp",
+    ".hh",
+    ".hxx",  # C++
+    ".java",  # Java
+    ".rb",  # Ruby
+    ".php",  # PHP
+    ".cs",  # C#
+    ".swift",  # Swift
+    ".kt",
+    ".kts",  # Kotlin
+    ".scala",  # Scala
+    ".lua",  # Lua
+    ".r",
+    ".R",  # R
+    ".jl",  # Julia
+    ".ex",
+    ".exs",  # Elixir
+    ".erl",
+    ".hrl",  # Erlang
+    ".ml",
+    ".mli",  # OCaml
+    ".hs",  # Haskell
+    ".elm",  # Elm
+    ".vue",  # Vue
+    ".svelte",  # Svelte
+}
+
+
+@final
+class ASTTool(BaseTool):
+    """Tool for searching and querying code structures using tree-sitter AST parsing."""
+
+    name = "ast"
+
+    @property
+    @override
+    def description(self) -> str:
+        """Get the tool description.
+
+        Returns:
+            Tool description
+        """
+        return """AST-based code structure search using tree-sitter. Find functions, classes, methods with full context.
+
+Usage:
+ast "function_name" ./src
+ast "class.*Service" ./src
+ast "def test_" ./tests
+
+Searches code structure intelligently, understanding syntax and providing semantic context."""
+
+    def _is_supported_file(self, path: str) -> bool:
+        """Check if file has a supported extension for tree-sitter parsing."""
+        return Path(path).suffix.lower() in SUPPORTED_EXTENSIONS
+
+    @override
+    async def call(
+        self,
+        ctx: MCPContext,
+        **params: Unpack[ASTToolParams],
+    ) -> str:
+        """Execute the tool with the given parameters.
+
+        Args:
+            ctx: MCP context
+            **params: Tool parameters
+
+        Returns:
+            Tool result
+        """
+        # Extract parameters
+        pattern: str = params["pattern"]
+        path: str = params["path"]
+        ignore_case = params.get("ignore_case", False)
+        line_number = params.get("line_number", False)
+
+        # Expand ~ in path
+        path = os.path.expanduser(path)
+
+        # Check if path exists
+        path_obj = Path(path)
+        if not path_obj.exists():
+            return f"Error: Path does not exist: {path}"
+
+        # Get the files to process
+        files_to_process = []
+
+        if path_obj.is_file():
+            if self._is_supported_file(str(path_obj)):
+                files_to_process.append(str(path_obj))
+            else:
+                return f"Error: File type not supported for AST parsing: {path_obj.suffix}"
+        elif path_obj.is_dir():
+            for root, _, files in os.walk(path_obj):
+                # Skip hidden directories and common non-code directories
+                root_path = Path(root)
+                if any(part.startswith(".") for part in root_path.parts):
+                    continue
+                if any(
+                    part in ("node_modules", "__pycache__", "venv", ".venv", "dist", "build")
+                    for part in root_path.parts
+                ):
+                    continue
+
+                for file in files:
+                    file_path = Path(root) / file
+                    if self._is_supported_file(str(file_path)):
+                        files_to_process.append(str(file_path))
+
+        if not files_to_process:
+            return f"No source code files found in {path}"
+
+        # Get TreeContext class
+        TreeContext = _get_tree_context()
+
+        # Process each file
+        results = []
+        errors = []
+
+        for file_path in files_to_process:
+            try:
+                # Read the file
+                with open(file_path, "r", encoding="utf-8") as f:
+                    code = f.read()
+
+                # Process the file with grep-ast
+                try:
+                    tc = TreeContext(
+                        file_path,
+                        code,
+                        color=False,
+                        verbose=False,
+                        line_number=line_number,
+                    )
+
+                    # Find matches
+                    loi = tc.grep(pattern, ignore_case)
+
+                    if loi:
+                        tc.add_lines_of_interest(loi)
+                        tc.add_context()
+                        output = tc.format()
+
+                        # Add the result to our list
+                        results.append(f"\n{file_path}:\n{output}\n")
+                except Exception as e:
+                    # Skip files that can't be parsed by tree-sitter
+                    errors.append(f"Could not parse {file_path}: {str(e)}")
+            except UnicodeDecodeError:
+                errors.append(f"Could not read {file_path} as text")
+            except Exception as e:
+                errors.append(f"Error processing {file_path}: {str(e)}")
+
+        if not results:
+            error_info = ""
+            if errors:
+                error_info = f"\n\nErrors encountered:\n" + "\n".join(errors[:5])
+                if len(errors) > 5:
+                    error_info += f"\n... and {len(errors) - 5} more errors"
+            return f"No matches found for '{pattern}' in {path}{error_info}"
+
+        summary = f"Found matches in {len(results)} file(s) (searched {len(files_to_process)} files)"
+        return summary + "\n" + "".join(results)
+
+    @override
+    def register(self, mcp_server: FastMCP) -> None:
+        """Register this 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 ast(
+            ctx: MCPContext,
+            pattern: Pattern,
+            path: SearchPath,
+            ignore_case: IgnoreCase = False,
+            line_number: LineNumber = False,
+        ) -> str:
+            return await tool_self.call(
+                ctx,
+                pattern=pattern,
+                path=path,
+                ignore_case=ignore_case,
+                line_number=line_number,
+            )

hanzo_tools_fs-0.3.0/hanzo_tools/fs/edit.py

@@ -0,0 +1,108 @@
+"""Edit tool - find and replace in files."""
+
+from typing import Optional, Annotated
+from pathlib import Path
+
+from pydantic import Field
+from mcp.server import FastMCP
+from mcp.server.fastmcp import Context as MCPContext
+
+from hanzo_tools.core import FileSystemTool, PermissionManager, auto_timeout
+
+
+class EditTool(FileSystemTool):
+    """Edit files with find and replace."""
+
+    name = "edit"
+
+    @property
+    def description(self) -> str:
+        return """Edit a file by replacing text.
+
+Args:
+    file_path: Absolute path to the file
+    old_string: Text to find (must be unique)
+    new_string: Text to replace with
+    expected_replacements: Expected number of replacements (default 1)
+
+Returns:
+    Success message with diff or error
+"""
+
+    def __init__(self, permission_manager: Optional[PermissionManager] = None):
+        super().__init__(permission_manager)
+
+    @auto_timeout("edit")
+    async def call(
+        self,
+        ctx: MCPContext,
+        file_path: str,
+        old_string: str,
+        new_string: str,
+        expected_replacements: int = 1,
+        **kwargs,
+    ) -> str:
+        """Edit file with find/replace."""
+        validation = self.validate_path(file_path)
+        if not validation:
+            return validation.error_message
+
+        if not self.is_path_allowed(file_path):
+            return f"Error: Access denied to path: {file_path}"
+
+        path = Path(file_path)
+
+        if not path.exists():
+            return f"Error: File does not exist: {file_path}"
+
+        if old_string == new_string:
+            return "Error: old_string and new_string are identical"
+
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                content = f.read()
+
+            # Count occurrences
+            count = content.count(old_string)
+
+            if count == 0:
+                return f"Error: old_string not found in file"
+
+            if count != expected_replacements:
+                return (
+                    f"Error: Found {count} occurrences of old_string, "
+                    f"expected {expected_replacements}. "
+                    f"Use expected_replacements={count} or make old_string more specific."
+                )
+
+            # Perform replacement
+            new_content = content.replace(old_string, new_string, expected_replacements)
+
+            with open(path, "w", encoding="utf-8") as f:
+                f.write(new_content)
+
+            return f"Successfully edited {file_path}\nReplaced {count} occurrence(s)"
+
+        except Exception as e:
+            return f"Error editing file: {e}"
+
+    def register(self, mcp_server: FastMCP) -> None:
+        """Register with MCP server."""
+        tool_instance = self
+
+        @mcp_server.tool()
+        async def edit(
+            file_path: Annotated[str, Field(description="Absolute path to the file")],
+            old_string: Annotated[str, Field(description="Text to find")],
+            new_string: Annotated[str, Field(description="Text to replace with")],
+            expected_replacements: Annotated[int, Field(description="Expected replacements")] = 1,
+            ctx: MCPContext = None,
+        ) -> str:
+            """Edit a file by replacing text."""
+            return await tool_instance.call(
+                ctx,
+                file_path=file_path,
+                old_string=old_string,
+                new_string=new_string,
+                expected_replacements=expected_replacements,
+            )

hanzo_tools_fs-0.3.0/hanzo_tools/fs/find.py

@@ -0,0 +1,112 @@
+"""Find tool - find files by pattern."""
+
+import fnmatch
+from typing import Optional, Annotated
+from pathlib import Path
+
+from pydantic import Field
+from mcp.server import FastMCP
+from mcp.server.fastmcp import Context as MCPContext
+
+from hanzo_tools.core import BaseTool, auto_timeout
+
+
+class FindTool(BaseTool):
+    """Find files by name pattern."""
+
+    name = "find"
+
+    @property
+    def description(self) -> str:
+        return """Find files and directories by name pattern.
+
+Args:
+    pattern: Glob pattern (e.g., "*.py", "test_*")
+    path: Directory to search in (default: current dir)
+    type: "file", "dir", or None for both
+    max_results: Maximum results to return (default 100)
+
+Returns:
+    List of matching paths
+"""
+
+    IGNORED_DIRS = {
+        ".git",
+        "__pycache__",
+        "node_modules",
+        ".venv",
+        "venv",
+        ".idea",
+        ".vscode",
+        ".mypy_cache",
+        ".pytest_cache",
+    }
+
+    @auto_timeout("find")
+    async def call(
+        self,
+        ctx: MCPContext,
+        pattern: str,
+        path: str = ".",
+        type: Optional[str] = None,
+        max_results: int = 100,
+        **kwargs,
+    ) -> str:
+        """Find files matching pattern."""
+        root = Path(path).resolve()
+
+        if not root.exists():
+            return f"Error: Path does not exist: {path}"
+
+        matches = []
+
+        def should_skip(p: Path) -> bool:
+            return any(part in self.IGNORED_DIRS for part in p.parts)
+
+        for item in root.rglob("*"):
+            if len(matches) >= max_results:
+                break
+
+            if should_skip(item):
+                continue
+
+            # Check type filter
+            if type == "file" and not item.is_file():
+                continue
+            if type == "dir" and not item.is_dir():
+                continue
+
+            # Check pattern match
+            if fnmatch.fnmatch(item.name, pattern):
+                try:
+                    rel_path = item.relative_to(root)
+                    suffix = "/" if item.is_dir() else ""
+                    matches.append(f"{rel_path}{suffix}")
+                except ValueError:
+                    matches.append(str(item))
+
+        if not matches:
+            return f"No matches found for pattern: {pattern}"
+
+        result = f"Found {len(matches)} matches:\n\n"
+        result += "\n".join(matches)
+
+        if len(matches) >= max_results:
+            result += f"\n\n[Truncated at {max_results} results]"
+
+        return result
+
+    def register(self, mcp_server: FastMCP) -> None:
+        """Register with MCP server."""
+        tool_instance = self
+
+        @mcp_server.tool()
+        async def find(
+            pattern: Annotated[str, Field(description="Glob pattern")],
+            path: Annotated[str, Field(description="Directory to search")] = ".",
+            type: Annotated[Optional[str], Field(description="file, dir, or None")] = None,
+            max_results: Annotated[int, Field(description="Max results")] = 100,
+            ctx: MCPContext = None,
+        ) -> str:
+            """Find files and directories by pattern."""
+            return await tool_instance.call(ctx, pattern=pattern, path=path, type=type, max_results=max_results)

hanzo_tools_fs-0.3.0/hanzo_tools/fs/read.py

@@ -0,0 +1,100 @@
+"""Read tool - read file contents."""
+
+from typing import Any, Optional, Annotated
+from pathlib import Path
+
+from pydantic import Field
+from mcp.server import FastMCP
+from mcp.server.fastmcp import Context as MCPContext
+
+from hanzo_tools.core import FileSystemTool, PermissionManager, auto_timeout
+
+
+class ReadTool(FileSystemTool):
+    """Read file contents with line numbers."""
+
+    name = "read"
+
+    @property
+    def description(self) -> str:
+        return """Read file contents with line numbers.
+
+Args:
+    file_path: Absolute path to the file
+    offset: Starting line (0-based, optional)
+    limit: Max lines to read (optional, default 2000)
+
+Returns:
+    File contents with line numbers
+"""
+
+    def __init__(self, permission_manager: Optional[PermissionManager] = None):
+        super().__init__(permission_manager)
+
+    @auto_timeout("read")
+    async def call(
+        self,
+        ctx: MCPContext,
+        file_path: str,
+        offset: int = 0,
+        limit: int = 2000,
+        **kwargs,
+    ) -> str:
+        """Read file contents."""
+        # Validate path
+        validation = self.validate_path(file_path)
+        if not validation:
+            return validation.error_message
+
+        if not self.is_path_allowed(file_path):
+            return f"Error: Access denied to path: {file_path}"
+
+        path = Path(file_path)
+
+        if not path.exists():
+            return f"Error: File does not exist: {file_path}"
+
+        if not path.is_file():
+            return f"Error: Not a file: {file_path}"
+
+        try:
+            with open(path, "r", encoding="utf-8", errors="replace") as f:
+                lines = f.readlines()
+
+            # Apply offset and limit
+            total_lines = len(lines)
+            selected = lines[offset : offset + limit]
+
+            # Format with line numbers
+            output_lines = []
+            for i, line in enumerate(selected, start=offset + 1):
+                line = line.rstrip("\n\r")
+                # Truncate long lines
+                if len(line) > 2000:
+                    line = line[:2000] + "..."
+                output_lines.append(f"{i:6}→{line}")
+
+            result = "\n".join(output_lines)
+
+            # Add info if truncated
+            if offset > 0 or offset + limit < total_lines:
+                result += f"\n\n[Showing lines {offset + 1}-{min(offset + limit, total_lines)} of {total_lines}]"
+
+            return result
+
+        except Exception as e:
+            return f"Error reading file: {e}"
+
+    def register(self, mcp_server: FastMCP) -> None:
+        """Register with MCP server."""
+        tool_instance = self
+
+        @mcp_server.tool()
+        async def read(
+            file_path: Annotated[str, Field(description="Absolute path to the file")],
+            offset: Annotated[int, Field(description="Starting line (0-based)")] = 0,
+            limit: Annotated[int, Field(description="Max lines to read")] = 2000,
+            ctx: MCPContext = None,
+        ) -> str:
+            """Read file contents with line numbers."""
+            return await tool_instance.call(ctx, file_path=file_path, offset=offset, limit=limit)

hanzo_tools_fs-0.3.0/hanzo_tools/fs/search.py

@@ -0,0 +1,195 @@
+"""Search tool - search file contents."""
+
+import re
+import asyncio
+from typing import Optional, Annotated
+from pathlib import Path
+
+import aiofiles
+from pydantic import Field
+from mcp.server import FastMCP
+from mcp.server.fastmcp import Context as MCPContext
+
+from hanzo_tools.core import BaseTool, auto_timeout
+
+
+class SearchTool(BaseTool):
+    """Search file contents using regex."""
+
+    name = "search"
+
+    @property
+    def description(self) -> str:
+        return """Search for patterns in file contents.
+
+Uses ripgrep (rg) if available, falls back to Python regex.
+
+Args:
+    pattern: Regex pattern to search for
+    path: Directory or file to search (default: current dir)
+    include: Glob pattern to filter files (e.g., "*.py")
+    context_lines: Lines of context around matches
+    max_results: Maximum results (default 50)
+
+Returns:
+    Matching lines with file paths and line numbers
+"""
+
+    @auto_timeout("search")
+    async def call(
+        self,
+        ctx: MCPContext,
+        pattern: str,
+        path: str = ".",
+        include: Optional[str] = None,
+        context_lines: int = 2,
+        max_results: int = 50,
+        **kwargs,
+    ) -> str:
+        """Search for pattern in files."""
+        root = Path(path).resolve()
+
+        if not root.exists():
+            return f"Error: Path does not exist: {path}"
+
+        # Try ripgrep first (much faster)
+        try:
+            result = await self._search_with_rg(pattern, root, include, context_lines, max_results)
+            if result is not None:
+                return result
+        except Exception:
+            pass
+
+        # Fallback to Python
+        return await self._search_with_python(pattern, root, include, context_lines, max_results)
+
+    async def _search_with_rg(
+        self,
+        pattern: str,
+        root: Path,
+        include: Optional[str],
+        context_lines: int,
+        max_results: int,
+    ) -> Optional[str]:
+        """Search using ripgrep (async)."""
+        cmd = [
+            "rg",
+            "--line-number",
+            "--color=never",
+            f"--max-count={max_results}",
+        ]
+
+        if context_lines > 0:
+            cmd.append(f"-C{context_lines}")
+
+        if include:
+            cmd.extend(["--glob", include])
+
+        cmd.extend([pattern, str(root)])
+
+        try:
+            process = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+
+            try:
+                stdout, stderr = await asyncio.wait_for(process.communicate(), timeout=30)
+            except asyncio.TimeoutError:
+                process.kill()
+                await process.wait()
+                return None
+
+            if process.returncode == 0:
+                return stdout.decode("utf-8", errors="replace") or "No matches found"
+            elif process.returncode == 1:
+                return "No matches found"
+            else:
+                return None  # Fall back to Python
+        except FileNotFoundError:
+            return None
+
+    async def _search_with_python(
+        self,
+        pattern: str,
+        root: Path,
+        include: Optional[str],
+        context_lines: int,
+        max_results: int,
+    ) -> str:
+        """Search using Python regex (async file I/O)."""
+        import fnmatch
+
+        try:
+            regex = re.compile(pattern)
+        except re.error as e:
+            return f"Invalid regex pattern: {e}"
+
+        matches = []
+
+        # Find files to search
+        if root.is_file():
+            files = [root]
+        else:
+            files = list(root.rglob("*"))
+
+        for file_path in files:
+            if not file_path.is_file():
+                continue
+
+            if include and not fnmatch.fnmatch(file_path.name, include):
+                continue
+
+            try:
+                async with aiofiles.open(file_path, "r", encoding="utf-8", errors="ignore") as f:
+                    content = await f.read()
+                    lines = content.splitlines()
+
+                for i, line in enumerate(lines, 1):
+                    if regex.search(line):
+                        rel_path = file_path.relative_to(root)
+                        matches.append(f"{rel_path}:{i}:{line.rstrip()}")
+
+                        if len(matches) >= max_results:
+                            break
+
+                if len(matches) >= max_results:
+                    break
+
+            except Exception:
+                continue
+
+        if not matches:
+            return "No matches found"
+
+        result = f"Found {len(matches)} matches:\n\n"
+        result += "\n".join(matches)
+
+        if len(matches) >= max_results:
+            result += f"\n\n[Truncated at {max_results} results]"
+
+        return result
+
+    def register(self, mcp_server: FastMCP) -> None:
+        """Register with MCP server."""
+        tool_instance = self
+
+        @mcp_server.tool()
+        async def search(
+            pattern: Annotated[str, Field(description="Regex pattern")],
+            path: Annotated[str, Field(description="Path to search")] = ".",
+            include: Annotated[Optional[str], Field(description="File pattern")] = None,
+            context_lines: Annotated[int, Field(description="Context lines")] = 2,
+            max_results: Annotated[int, Field(description="Max results")] = 50,
+            ctx: MCPContext = None,
+        ) -> str:
+            """Search for patterns in file contents."""
+            return await tool_instance.call(
+                ctx,
+                pattern=pattern,
+                path=path,
+                include=include,
+                context_lines=context_lines,
+                max_results=max_results,
+            )

hanzo_tools_fs-0.3.0/hanzo_tools/fs/tree.py

@@ -0,0 +1,118 @@
+"""Tree tool - directory tree view."""
+
+from typing import Annotated
+from pathlib import Path
+
+from pydantic import Field
+from mcp.server import FastMCP
+from mcp.server.fastmcp import Context as MCPContext
+
+from hanzo_tools.core import BaseTool, auto_timeout
+
+
+class TreeTool(BaseTool):
+    """Display directory tree structure."""
+
+    name = "tree"
+
+    @property
+    def description(self) -> str:
+        return """Display directory tree structure.
+
+Args:
+    path: Directory path to display
+    depth: Maximum depth to traverse (default 3)
+    include_filtered: Include normally filtered dirs like .git
+
+Returns:
+    Tree structure as text
+"""
+
+    # Directories to skip by default
+    FILTERED_DIRS = {
+        ".git",
+        "__pycache__",
+        "node_modules",
+        ".venv",
+        "venv",
+        ".idea",
+        ".vscode",
+        ".mypy_cache",
+        ".pytest_cache",
+        "dist",
+        "build",
+        "egg-info",
+        ".tox",
+        ".nox",
+    }
+
+    @auto_timeout("tree")
+    async def call(
+        self,
+        ctx: MCPContext,
+        path: str,
+        depth: int = 3,
+        include_filtered: bool = False,
+        **kwargs,
+    ) -> str:
+        """Generate directory tree."""
+        root = Path(path)
+
+        if not root.exists():
+            return f"Error: Path does not exist: {path}"
+
+        if not root.is_dir():
+            return f"Error: Not a directory: {path}"
+
+        lines = []
+        self._build_tree(root, lines, "", depth, include_filtered)
+
+        return "\n".join(lines)
+
+    def _build_tree(
+        self,
+        path: Path,
+        lines: list[str],
+        prefix: str,
+        depth: int,
+        include_filtered: bool,
+    ) -> None:
+        """Recursively build tree lines."""
+        if depth < 0:
+            return
+
+        try:
+            entries = sorted(path.iterdir(), key=lambda x: (not x.is_dir(), x.name.lower()))
+        except PermissionError:
+            lines.append(f"{prefix}[permission denied]")
+            return
+
+        # Filter entries
+        if not include_filtered:
+            entries = [e for e in entries if e.name not in self.FILTERED_DIRS]
+
+        for i, entry in enumerate(entries):
+            is_last = i == len(entries) - 1
+            connector = "└── " if is_last else "├── "
+
+            if entry.is_dir():
+                lines.append(f"{prefix}{connector}{entry.name}/")
+                if depth > 0:
+                    extension = "    " if is_last else "│   "
+                    self._build_tree(entry, lines, prefix + extension, depth - 1, include_filtered)
+            else:
+                lines.append(f"{prefix}{connector}{entry.name}")
+
+    def register(self, mcp_server: FastMCP) -> None:
+        """Register with MCP server."""
+        tool_instance = self
+
+        @mcp_server.tool()
+        async def tree(
+            path: Annotated[str, Field(description="Directory path")],
+            depth: Annotated[int, Field(description="Max depth")] = 3,
+            include_filtered: Annotated[bool, Field(description="Include filtered dirs")] = False,
+            ctx: MCPContext = None,
+        ) -> str:
+            """Display directory tree structure."""
+            return await tool_instance.call(ctx, path=path, depth=depth, include_filtered=include_filtered)

hanzo_tools_fs-0.3.0/hanzo_tools/fs/write.py

@@ -0,0 +1,75 @@
+"""Write tool - write/create files."""
+
+from typing import Optional, Annotated
+from pathlib import Path
+
+from pydantic import Field
+from mcp.server import FastMCP
+from mcp.server.fastmcp import Context as MCPContext
+
+from hanzo_tools.core import FileSystemTool, PermissionManager, auto_timeout
+
+
+class WriteTool(FileSystemTool):
+    """Write content to a file."""
+
+    name = "write"
+
+    @property
+    def description(self) -> str:
+        return """Write content to a file (creates or overwrites).
+
+Args:
+    file_path: Absolute path to the file
+    content: Content to write
+
+Returns:
+    Success message or error
+"""
+
+    def __init__(self, permission_manager: Optional[PermissionManager] = None):
+        super().__init__(permission_manager)
+
+    @auto_timeout("write")
+    async def call(
+        self,
+        ctx: MCPContext,
+        file_path: str,
+        content: str,
+        **kwargs,
+    ) -> str:
+        """Write content to file."""
+        validation = self.validate_path(file_path)
+        if not validation:
+            return validation.error_message
+
+        if not self.is_path_allowed(file_path):
+            return f"Error: Access denied to path: {file_path}"
+
+        path = Path(file_path)
+
+        try:
+            # Create parent directories if needed
+            path.parent.mkdir(parents=True, exist_ok=True)
+
+            # Write content
+            with open(path, "w", encoding="utf-8") as f:
+                f.write(content)
+
+            return f"Successfully wrote {len(content)} bytes to {file_path}"
+
+        except Exception as e:
+            return f"Error writing file: {e}"
+
+    def register(self, mcp_server: FastMCP) -> None:
+        """Register with MCP server."""
+        tool_instance = self
+
+        @mcp_server.tool()
+        async def write(
+            file_path: Annotated[str, Field(description="Absolute path to the file")],
+            content: Annotated[str, Field(description="Content to write")],
+            ctx: MCPContext = None,
+        ) -> str:
+            """Write content to a file."""
+            return await tool_instance.call(ctx, file_path=file_path, content=content)

hanzo_tools_fs-0.3.0/hanzo_tools_fs.egg-info/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: hanzo-tools-fs
+Version: 0.3.0
+Summary: Filesystem tools for Hanzo AI - read, write, edit, search, find
+Author-email: Hanzo Industries Inc <dev@hanzo.ai>
+License: MIT
+Project-URL: Homepage, https://github.com/hanzoai/python-sdk
+Keywords: hanzo,tools,filesystem,mcp,ai
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: aiofiles>=24.1.0
+Requires-Dist: grep-ast>=0.8.1
+Requires-Dist: ffind>=1.3.0
+Requires-Dist: watchdog>=6.0.0
+Requires-Dist: mcp>=1.25.0
+Requires-Dist: fastmcp>=2.14.1
+Requires-Dist: pydantic>=2.12.5
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: ruff>=0.14.0; extra == "dev"

hanzo_tools_fs-0.3.0/hanzo_tools_fs.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+pyproject.toml
+hanzo_tools/__init__.py
+hanzo_tools/fs/__init__.py
+hanzo_tools/fs/ast.py
+hanzo_tools/fs/edit.py
+hanzo_tools/fs/find.py
+hanzo_tools/fs/read.py
+hanzo_tools/fs/search.py
+hanzo_tools/fs/tree.py
+hanzo_tools/fs/write.py
+hanzo_tools_fs.egg-info/PKG-INFO
+hanzo_tools_fs.egg-info/SOURCES.txt
+hanzo_tools_fs.egg-info/dependency_links.txt
+hanzo_tools_fs.egg-info/entry_points.txt
+hanzo_tools_fs.egg-info/requires.txt
+hanzo_tools_fs.egg-info/top_level.txt

hanzo_tools_fs-0.3.0/hanzo_tools_fs.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hanzo_tools_fs-0.3.0/hanzo_tools_fs.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[hanzo.tools]
+fs = hanzo_tools.fs:TOOLS

hanzo_tools_fs-0.3.0/hanzo_tools_fs.egg-info/requires.txt

@@ -0,0 +1,11 @@
+aiofiles>=24.1.0
+grep-ast>=0.8.1
+ffind>=1.3.0
+watchdog>=6.0.0
+mcp>=1.25.0
+fastmcp>=2.14.1
+pydantic>=2.12.5
+
+[dev]
+pytest>=7.0.0
+ruff>=0.14.0

hanzo_tools_fs-0.3.0/hanzo_tools_fs.egg-info/top_level.txt

@@ -0,0 +1 @@
+hanzo_tools

hanzo_tools_fs-0.3.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hanzo-tools-fs"
+version = "0.3.0"
+description = "Filesystem tools for Hanzo AI - read, write, edit, search, find"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "Hanzo Industries Inc", email = "dev@hanzo.ai" }]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+keywords = ["hanzo", "tools", "filesystem", "mcp", "ai"]
+dependencies = [
+    "aiofiles>=24.1.0",
+    "grep-ast>=0.8.1",
+    "ffind>=1.3.0",
+    "watchdog>=6.0.0",
+    "mcp>=1.25.0",
+    "fastmcp>=2.14.1",
+    "pydantic>=2.12.5",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/hanzoai/python-sdk"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0.0", "ruff>=0.14.0"]
+
+[project.entry-points."hanzo.tools"]
+fs = "hanzo_tools.fs:TOOLS"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["hanzo_tools*"]
+
+[tool.setuptools.package-data]
+hanzo_tools = ["py.typed"]

hanzo_tools_fs-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+