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
Metadata
Release files for hanzo-tools 0.3.10
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hanzo_tools-0.3.10.tar.gz | 31.6 kB | Without provenance | Details for hanzo_tools-0.3.10.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hanzo_tools-0.3.10-py3-none-any.whl | Python 3 | none | any | Details for hanzo_tools-0.3.10-py3-none-any.whl |
Total release size: 60.6 kB
Release files / hanzo_tools-0.3.10.tar.gz
| Download URL | hanzo_tools-0.3.10.tar.gz |
|---|---|
| Size | 31.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bc3577a61c03341da346b3c365271086f6bbec9c049af06fbb361c733fedb998
|
|
BLAKE2b-256 checksum How to use checksums |
86657f7ee924bdbe083be86373c46f1f88098a9818f29e9612267f3e3dcbbf56
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.9
|
Release files / hanzo_tools-0.3.10-py3-none-any.whl
| Download URL | hanzo_tools-0.3.10-py3-none-any.whl |
|---|---|
| Size | 29.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
77b526ea060b027831a87a868f171c0a076e008fc4781e34d46c484d09f9a122
|
|
BLAKE2b-256 checksum How to use checksums |
b7005f8918a7617671e82de16ed84e4c71e626c9079854a7c0779470d9e466e5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.9
|
Security for hanzo-tools 0.3.10
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.