python-sdk/pkg/hanzo-tools

hanzo-tools

Core infrastructure and plugin framework for Hanzo AI's modular MCP tool system.

Install

pip install hanzo-tools          # Core only
pip install hanzo-tools[dev]     # filesystem, shell, editor, lsp, refactor, todo, reasoning, config
pip install hanzo-tools[ai]      # llm, agent, memory
pip install hanzo-tools[all]     # Everything

Individual tool packages can be installed separately:

pip install hanzo-tools-fs
pip install hanzo-tools-shell
pip install hanzo-tools-browser
pip install hanzo-tools-llm
pip install hanzo-tools-memory
pip install hanzo-tools-editor
pip install hanzo-tools-vector
# ... etc

Usage

Register all discovered tools

from hanzo_tools import discover_tools, register_all
from mcp.server import FastMCP

mcp = FastMCP("my-server")

# Auto-discover and register all installed tool packages
registered = register_all(mcp)

Register individual tool packages

from hanzo_tools.fs import register_tools as register_fs
from hanzo_tools.shell import register_tools as register_shell

register_fs(mcp, permission_manager)
register_shell(mcp)

Build a custom tool

from typing import Any
from mcp.server import FastMCP
from mcp.server.fastmcp import Context as MCPContext
from hanzo_tools.core import BaseTool, ToolRegistry, with_error_logging

class WeatherTool(BaseTool):
    @property
    def name(self) -> str:
        return "get_weather"

    @property
    def description(self) -> str:
        return "Get current weather for a location"

    @with_error_logging("get_weather")
    async def call(self, ctx: MCPContext, **params: Any) -> str:
        location = params["location"]
        return f"Weather in {location}: 72°F, sunny"

    def register(self, mcp_server: FastMCP) -> None:
        @mcp_server.tool()
        async def get_weather(location: str, ctx: MCPContext) -> str:
            """Get current weather for a location."""
            return await self.call(ctx, location=location)

# Register with the MCP server
ToolRegistry.register_tool(mcp, WeatherTool())

Filesystem tools with permissions

from hanzo_tools.core import FileSystemTool, PermissionManager

pm = PermissionManager(
    allowed_paths=["/home/user/projects"],
    deny_patterns=[".git", "node_modules", ".env"],
)

class ReadFileTool(FileSystemTool):
    def __init__(self):
        super().__init__(permission_manager=pm)

    @property
    def name(self) -> str:
        return "read_file"

    @property
    def description(self) -> str:
        return "Read a file"

    async def call(self, ctx, **params):
        path = params["path"]
        if not self.is_path_allowed(path):
            return "Access denied"
        return open(path).read()

    def register(self, mcp_server):
        @mcp_server.tool()
        async def read_file(path: str, ctx) -> str:
            """Read a file."""
            return await self.call(ctx, path=path)

Decorators

from hanzo_tools.core import auto_timeout, with_error_logging, handle_connection_errors

@auto_timeout("search", timeout=120)
@with_error_logging("search")
@handle_connection_errors
async def search_files(pattern: str, path: str) -> str:
    ...

Timeouts are configurable via environment variables:

HANZO_TIMEOUT_SEARCH=300   # Override search timeout to 5 minutes
HANZO_TIMEOUT_BROWSER=600  # Override browser timeout to 10 minutes

Tool enable/disable

from hanzo_tools.core import ToolRegistry

# Disable a tool at runtime
ToolRegistry.set_tool_enabled("browser", False)

# Check if a tool is enabled
if ToolRegistry.is_tool_enabled("browser"):
    ...

Tool states persist to ~/.hanzo/mcp/tool_states.json.

Architecture

hanzo-tools (core)
├── BaseTool          — Abstract base for all tools
├── FileSystemTool    — Base for filesystem tools with permissions
├── ToolRegistry      — Enable/disable and registration
├── ToolContext       — Execution context with logging/progress
├── PermissionManager — Path-based access control
├── MCPResourceDocument — Structured response formatting
├── auto_timeout      — Configurable async timeouts
├── with_error_logging — Error logging to ~/.hanzo/mcp/logs/
├── handle_connection_errors — Graceful disconnect handling
├── validate_path_parameter  — Path validation
├── discover_tools()  — Plugin discovery via entry points
└── register_all()    — Auto-register all discovered tools

hanzo-tools-fs        — File read/write/search/glob
hanzo-tools-shell     — Shell command execution
hanzo-tools-browser   — Browser automation (Playwright)
hanzo-tools-editor    — Code editing with AST awareness
hanzo-tools-lsp       — Language Server Protocol integration
hanzo-tools-refactor  — Refactoring operations
hanzo-tools-llm       — LLM inference tools
hanzo-tools-agent     — Agent orchestration
hanzo-tools-memory    — Persistent memory/context
hanzo-tools-vector    — Vector DB operations
hanzo-tools-database  — Database query tools
hanzo-tools-jupyter   — Jupyter notebook tools
hanzo-tools-todo      — Task/todo management
hanzo-tools-reasoning — Chain-of-thought reasoning
hanzo-tools-config    — Configuration management
hanzo-tools-mcp       — MCP protocol utilities
hanzo-tools-computer  — Computer use (screen/keyboard)

Tool packages register via importlib.metadata entry points (group="hanzo.tools"), enabling automatic discovery without explicit imports.

API

Core Classes

Class	Purpose
BaseTool	Abstract base — implement name, description, call(), register()
FileSystemTool	Extends BaseTool with permission_manager and validate_path()
ToolRegistry	Class-level enable/disable with JSON persistence
ToolContext	Wraps MCP context with info(), warning(), error(), progress()
PermissionManager	Allowed paths + deny patterns for filesystem access control
MCPResourceDocument	Response type with to_json_string(), to_readable_string(), to_dict()
ValidationResult	Boolean result with optional error message

Decorators

Decorator	Purpose
@auto_timeout(name, timeout=None)	Async timeout with env var override (HANZO_TIMEOUT_*)
@with_error_logging(name)	Log errors to ~/.hanzo/mcp/logs/ and return friendly messages
@handle_connection_errors	Catch disconnects gracefully
@retry(max_attempts, delay, backoff)	Exponential backoff retry

Top-level Functions

Function	Purpose
discover_tools()	Find all installed tool packages via entry points
register_all(mcp, pm, enabled)	Register all discovered tools with an MCP server

License

MIT