hanzo-mcp 0.12.1

The Zen of Hanzo MCP: One server to rule them all. The ultimate MCP that orchestrates all others.

Hanzo Model Context Protocol (MCP)

Model Context Protocol implementation for advanced tool use and context management.

Installation

pip install hanzo-mcp

Features

• Tool Management: Register and manage AI tools
• File Operations: Read, write, edit files
• Code Intelligence: AST analysis, symbol search
• Shell Execution: Run commands safely
• Agent Delegation: Recursive agent capabilities
• Memory Integration: Persistent context storage
• Batch Operations: Execute multiple tools efficiently

Quick Start

Basic Usage

from hanzo_mcp import create_mcp_server

# Create MCP server
server = create_mcp_server()

# Register tools
server.register_filesystem_tools()
server.register_shell_tools()
server.register_agent_tools()

# Start server
await server.start()

Tool Categories

Filesystem Tools

# Read file
content = await server.tools.read(file_path="/path/to/file.py")

# Write file
await server.tools.write(
    file_path="/path/to/new.py",
    content="print('Hello')"
)

# Edit file
await server.tools.edit(
    file_path="/path/to/file.py",
    old_string="old code",
    new_string="new code"
)

# Multi-edit
await server.tools.multi_edit(
    file_path="/path/to/file.py",
    edits=[
        {"old_string": "foo", "new_string": "bar"},
        {"old_string": "baz", "new_string": "qux"}
    ]
)

Search Tools

# Unified search (grep + AST + semantic)
results = await server.tools.search(
    pattern="function_name",
    path="/project"
)

# AST-aware search
results = await server.tools.grep_ast(
    pattern="class.*Service",
    path="/src"
)

# Symbol search
symbols = await server.tools.symbols(
    pattern="def test_",
    path="/tests"
)

Shell Tools

# Run command
result = await server.tools.bash(
    command="ls -la",
    cwd="/project"
)

# Run with auto-backgrounding
result = await server.tools.bash(
    command="python server.py",
    timeout=120000  # Auto-backgrounds after 2 min
)

# Manage processes
processes = await server.tools.process(action="list")
logs = await server.tools.process(
    action="logs",
    id="bash_abc123"
)

Agent Tools

# Dispatch agent for complex tasks
result = await server.tools.dispatch_agent(
    prompt="Analyze the codebase architecture",
    path="/project"
)

# Network of agents
result = await server.tools.network(
    task="Implement user authentication",
    agents=["architect", "developer", "tester"]
)

# CLI tool integration
result = await server.tools.claude(
    args=["--analyze", "main.py"]
)

Batch Operations

# Execute multiple tools in parallel
results = await server.tools.batch(
    description="Read multiple files",
    invocations=[
        {"tool_name": "read", "input": {"file_path": "file1.py"}},
        {"tool_name": "read", "input": {"file_path": "file2.py"}},
        {"tool_name": "grep", "input": {"pattern": "TODO"}}
    ]
)

Advanced Features

Custom Tools

from hanzo_mcp import Tool

class MyCustomTool(Tool):
    name = "my_tool"
    description = "Custom tool"
    
    async def call(self, ctx, **params):
        # Tool implementation
        return "Result"

# Register custom tool
server.register_tool(MyCustomTool())

Permission Management

from hanzo_mcp import PermissionManager

# Create permission manager
pm = PermissionManager()

# Set permission mode
pm.set_mode("review")  # review, auto_approve, auto_deny

# Check permission
allowed = await pm.check_permission(
    tool="write",
    params={"file_path": "/etc/passwd"}
)

Context Management

from hanzo_mcp import ToolContext

# Create context
ctx = ToolContext(
    cwd="/project",
    env={"API_KEY": "secret"},
    timeout=30000
)

# Use with tools
result = await tool.call(ctx, **params)

Configuration

Environment Variables

# API keys for agent tools
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

# Tool settings
MCP_PERMISSION_MODE=review
MCP_MAX_FILE_SIZE=10485760
MCP_TIMEOUT=120000

# Search settings
MCP_SEARCH_IGNORE=node_modules,*.pyc
MCP_SEARCH_MAX_RESULTS=100

Configuration File

tools:
  filesystem:
    enabled: true
    max_file_size: 10MB
    allowed_paths:
      - /home/user/projects
      - /tmp
    
  shell:
    enabled: true
    timeout: 120000
    auto_background: true
    
  agent:
    enabled: true
    models:
      - claude-3-opus
      - gpt-4
    
  search:
    ignore_patterns:
      - node_modules
      - "*.pyc"
      - .git
    max_results: 100

permissions:
  mode: review  # review, auto_approve, auto_deny
  whitelist:
    - read
    - grep
    - search
  blacklist:
    - rm
    - sudo

CLI Usage

Installation to Claude Desktop

# Install to Claude Desktop
hanzo-mcp install-desktop

# Serve MCP
hanzo-mcp serve --port 3000

Standalone Server

# Start MCP server
hanzo-mcp serve

# With custom config
hanzo-mcp serve --config mcp-config.yaml

# With specific tools
hanzo-mcp serve --tools filesystem,shell,agent

Development

Setup

cd pkg/hanzo-mcp
uv sync --all-extras

Testing

# Unit tests
pytest tests/ -v

# Integration tests
pytest tests/ -m integration

# With coverage
pytest tests/ --cov=hanzo_mcp

Building

uv build

Architecture

Tool Categories

• Filesystem: File operations (read, write, edit)
• Search: Code search (grep, AST, semantic)
• Shell: Command execution and process management
• Agent: AI agent delegation and orchestration
• Memory: Context and knowledge persistence
• Config: Configuration management
• LLM: Direct LLM interactions

Security

• Permission system for dangerous operations
• Path validation and sandboxing
• Command injection protection
• Rate limiting on operations
• Audit logging

License

Apache License 2.0