| Name | hanzo-mcp JSON |
| Version |
0.8.5
JSON |
| download |
| home_page | None |
| Summary | The Zen of Hanzo MCP: One server to rule them all. The ultimate MCP that orchestrates all others. |
| upload_time | 2025-09-06 12:48:07 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | MIT |
| keywords |
mcp
claude
hanzo
code
agent
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Hanzo Model Context Protocol (MCP)
[](https://pypi.org/project/hanzo-mcp/)
[](https://pypi.org/project/hanzo-mcp/)
Model Context Protocol implementation for advanced tool use and context management.
## Installation
```bash
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
```python
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
```python
# 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
```python
# 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
```python
# 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
```python
# 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
```python
# 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
```python
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
```python
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
```python
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
```bash
# 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
```yaml
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
```bash
# Install to Claude Desktop
hanzo-mcp install-desktop
# Serve MCP
hanzo-mcp serve --port 3000
```
### Standalone Server
```bash
# 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
```bash
cd pkg/hanzo-mcp
uv sync --all-extras
```
### Testing
```bash
# Unit tests
pytest tests/ -v
# Integration tests
pytest tests/ -m integration
# With coverage
pytest tests/ --cov=hanzo_mcp
```
### Building
```bash
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
Raw data
{
"_id": null,
"home_page": null,
"name": "hanzo-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "mcp, claude, hanzo, code, agent",
"author": null,
"author_email": "Hanzo Industries Inc <dev@hanzo.ai>",
"download_url": "https://files.pythonhosted.org/packages/57/ad/f10bba54df4711f35eb8d1cb591f5d22b03a13c8d7db34f4377e0b84d286/hanzo_mcp-0.8.5.tar.gz",
"platform": null,
"description": "# Hanzo Model Context Protocol (MCP)\n\n[](https://pypi.org/project/hanzo-mcp/)\n[](https://pypi.org/project/hanzo-mcp/)\n\nModel Context Protocol implementation for advanced tool use and context management.\n\n## Installation\n\n```bash\npip install hanzo-mcp\n```\n\n## Features\n\n- **Tool Management**: Register and manage AI tools\n- **File Operations**: Read, write, edit files\n- **Code Intelligence**: AST analysis, symbol search\n- **Shell Execution**: Run commands safely\n- **Agent Delegation**: Recursive agent capabilities\n- **Memory Integration**: Persistent context storage\n- **Batch Operations**: Execute multiple tools efficiently\n\n## Quick Start\n\n### Basic Usage\n\n```python\nfrom hanzo_mcp import create_mcp_server\n\n# Create MCP server\nserver = create_mcp_server()\n\n# Register tools\nserver.register_filesystem_tools()\nserver.register_shell_tools()\nserver.register_agent_tools()\n\n# Start server\nawait server.start()\n```\n\n### Tool Categories\n\n#### Filesystem Tools\n\n```python\n# Read file\ncontent = await server.tools.read(file_path=\"/path/to/file.py\")\n\n# Write file\nawait server.tools.write(\n file_path=\"/path/to/new.py\",\n content=\"print('Hello')\"\n)\n\n# Edit file\nawait server.tools.edit(\n file_path=\"/path/to/file.py\",\n old_string=\"old code\",\n new_string=\"new code\"\n)\n\n# Multi-edit\nawait server.tools.multi_edit(\n file_path=\"/path/to/file.py\",\n edits=[\n {\"old_string\": \"foo\", \"new_string\": \"bar\"},\n {\"old_string\": \"baz\", \"new_string\": \"qux\"}\n ]\n)\n```\n\n#### Search Tools\n\n```python\n# Unified search (grep + AST + semantic)\nresults = await server.tools.search(\n pattern=\"function_name\",\n path=\"/project\"\n)\n\n# AST-aware search\nresults = await server.tools.grep_ast(\n pattern=\"class.*Service\",\n path=\"/src\"\n)\n\n# Symbol search\nsymbols = await server.tools.symbols(\n pattern=\"def test_\",\n path=\"/tests\"\n)\n```\n\n#### Shell Tools\n\n```python\n# Run command\nresult = await server.tools.bash(\n command=\"ls -la\",\n cwd=\"/project\"\n)\n\n# Run with auto-backgrounding\nresult = await server.tools.bash(\n command=\"python server.py\",\n timeout=120000 # Auto-backgrounds after 2 min\n)\n\n# Manage processes\nprocesses = await server.tools.process(action=\"list\")\nlogs = await server.tools.process(\n action=\"logs\",\n id=\"bash_abc123\"\n)\n```\n\n#### Agent Tools\n\n```python\n# Dispatch agent for complex tasks\nresult = await server.tools.dispatch_agent(\n prompt=\"Analyze the codebase architecture\",\n path=\"/project\"\n)\n\n# Network of agents\nresult = await server.tools.network(\n task=\"Implement user authentication\",\n agents=[\"architect\", \"developer\", \"tester\"]\n)\n\n# CLI tool integration\nresult = await server.tools.claude(\n args=[\"--analyze\", \"main.py\"]\n)\n```\n\n#### Batch Operations\n\n```python\n# Execute multiple tools in parallel\nresults = await server.tools.batch(\n description=\"Read multiple files\",\n invocations=[\n {\"tool_name\": \"read\", \"input\": {\"file_path\": \"file1.py\"}},\n {\"tool_name\": \"read\", \"input\": {\"file_path\": \"file2.py\"}},\n {\"tool_name\": \"grep\", \"input\": {\"pattern\": \"TODO\"}}\n ]\n)\n```\n\n## Advanced Features\n\n### Custom Tools\n\n```python\nfrom hanzo_mcp import Tool\n\nclass MyCustomTool(Tool):\n name = \"my_tool\"\n description = \"Custom tool\"\n \n async def call(self, ctx, **params):\n # Tool implementation\n return \"Result\"\n\n# Register custom tool\nserver.register_tool(MyCustomTool())\n```\n\n### Permission Management\n\n```python\nfrom hanzo_mcp import PermissionManager\n\n# Create permission manager\npm = PermissionManager()\n\n# Set permission mode\npm.set_mode(\"review\") # review, auto_approve, auto_deny\n\n# Check permission\nallowed = await pm.check_permission(\n tool=\"write\",\n params={\"file_path\": \"/etc/passwd\"}\n)\n```\n\n### Context Management\n\n```python\nfrom hanzo_mcp import ToolContext\n\n# Create context\nctx = ToolContext(\n cwd=\"/project\",\n env={\"API_KEY\": \"secret\"},\n timeout=30000\n)\n\n# Use with tools\nresult = await tool.call(ctx, **params)\n```\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# API keys for agent tools\nANTHROPIC_API_KEY=sk-ant-...\nOPENAI_API_KEY=sk-...\n\n# Tool settings\nMCP_PERMISSION_MODE=review\nMCP_MAX_FILE_SIZE=10485760\nMCP_TIMEOUT=120000\n\n# Search settings\nMCP_SEARCH_IGNORE=node_modules,*.pyc\nMCP_SEARCH_MAX_RESULTS=100\n```\n\n### Configuration File\n\n```yaml\ntools:\n filesystem:\n enabled: true\n max_file_size: 10MB\n allowed_paths:\n - /home/user/projects\n - /tmp\n \n shell:\n enabled: true\n timeout: 120000\n auto_background: true\n \n agent:\n enabled: true\n models:\n - claude-3-opus\n - gpt-4\n \n search:\n ignore_patterns:\n - node_modules\n - \"*.pyc\"\n - .git\n max_results: 100\n\npermissions:\n mode: review # review, auto_approve, auto_deny\n whitelist:\n - read\n - grep\n - search\n blacklist:\n - rm\n - sudo\n```\n\n## CLI Usage\n\n### Installation to Claude Desktop\n\n```bash\n# Install to Claude Desktop\nhanzo-mcp install-desktop\n\n# Serve MCP\nhanzo-mcp serve --port 3000\n```\n\n### Standalone Server\n\n```bash\n# Start MCP server\nhanzo-mcp serve\n\n# With custom config\nhanzo-mcp serve --config mcp-config.yaml\n\n# With specific tools\nhanzo-mcp serve --tools filesystem,shell,agent\n```\n\n## Development\n\n### Setup\n\n```bash\ncd pkg/hanzo-mcp\nuv sync --all-extras\n```\n\n### Testing\n\n```bash\n# Unit tests\npytest tests/ -v\n\n# Integration tests\npytest tests/ -m integration\n\n# With coverage\npytest tests/ --cov=hanzo_mcp\n```\n\n### Building\n\n```bash\nuv build\n```\n\n## Architecture\n\n### Tool Categories\n\n- **Filesystem**: File operations (read, write, edit)\n- **Search**: Code search (grep, AST, semantic)\n- **Shell**: Command execution and process management\n- **Agent**: AI agent delegation and orchestration\n- **Memory**: Context and knowledge persistence\n- **Config**: Configuration management\n- **LLM**: Direct LLM interactions\n\n### Security\n\n- Permission system for dangerous operations\n- Path validation and sandboxing\n- Command injection protection\n- Rate limiting on operations\n- Audit logging\n\n## License\n\nApache License 2.0\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "The Zen of Hanzo MCP: One server to rule them all. The ultimate MCP that orchestrates all others.",
"version": "0.8.5",
"project_urls": {
"Bug Tracker": "https://github.com/hanzoai/mcp/issues",
"Documentation": "https://mcp.hanzo.ai",
"Homepage": "https://github.com/hanzoai/mcp"
},
"split_keywords": [
"mcp",
" claude",
" hanzo",
" code",
" agent"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8b93a6f4a4a7b7e75fd480f39433abcd6c44067ab99decde883bae1ae1213d10",
"md5": "53f23653a05f98ead93bb9f83630cf70",
"sha256": "258451ca446756ab2df64724b2970866f83c88e4a171de83f2a24d0c1347a45f"
},
"downloads": -1,
"filename": "hanzo_mcp-0.8.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "53f23653a05f98ead93bb9f83630cf70",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 538082,
"upload_time": "2025-09-06T12:48:05",
"upload_time_iso_8601": "2025-09-06T12:48:05.317144Z",
"url": "https://files.pythonhosted.org/packages/8b/93/a6f4a4a7b7e75fd480f39433abcd6c44067ab99decde883bae1ae1213d10/hanzo_mcp-0.8.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "57adf10bba54df4711f35eb8d1cb591f5d22b03a13c8d7db34f4377e0b84d286",
"md5": "d14032bb9d7700b43db9978d50ed56c0",
"sha256": "235c3f72741841f0d0e896452a7e287fd0453c829190b824d261c35aaecfb81d"
},
"downloads": -1,
"filename": "hanzo_mcp-0.8.5.tar.gz",
"has_sig": false,
"md5_digest": "d14032bb9d7700b43db9978d50ed56c0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 483171,
"upload_time": "2025-09-06T12:48:07",
"upload_time_iso_8601": "2025-09-06T12:48:07.035200Z",
"url": "https://files.pythonhosted.org/packages/57/ad/f10bba54df4711f35eb8d1cb591f5d22b03a13c8d7db34f4377e0b84d286/hanzo_mcp-0.8.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-06 12:48:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hanzoai",
"github_project": "mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "hanzo-mcp"
}
