python-sdk/proto/zap

ZAP Protocol: MCP Superset for Agentic Operations

ZAP (Zero-latency Agent Protocol) extends MCP with capabilities for:

• Interactive Sessions: REPL/notebook execution across languages
• Streaming: Real-time output for long-running operations
• IDE Integration: Full editor control (VS Code, JetBrains, Neovim)
• Browser DevTools: Console, network, debugger control
• Extension Bridge: Browser/IDE extension communication

Protocol Versions

Version	MCP Compat	Features
1.0.0	2025-06-18	Full MCP + REPL + Browser + IDE

Wire Formats

• Primary: Cap'n Proto (binary, zero-copy)
• Fallback: JSON-RPC 2.0 (MCP compatible)

Message Types

Tool Execution (MCP Compatible)

{
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "read",
    "arguments": {"file_path": "/path/to/file"}
  }
}

REPL Session

{
  "id": "1",
  "method": "repl/eval",
  "params": {
    "session_id": "py_abc123",
    "language": "python",
    "code": "x = 1 + 1\nprint(x)",
    "stream_output": true
  }
}

Browser Console

{
  "id": "1",
  "method": "browser/console",
  "params": {
    "action": "evaluate",
    "code": "document.title"
  }
}

IDE Control

{
  "id": "1",
  "method": "ide/command",
  "params": {
    "action": "rename",
    "line": 10,
    "column": 5,
    "new_name": "betterName"
  }
}

Streaming

{
  "id": "1",
  "method": "stream/start",
  "params": {
    "type": "repl_output",
    "session_id": "py_abc123"
  }
}

Capabilities

REPL Languages

• Python (ipykernel)
• Node.js/TypeScript (tslab)
• Bash (bash_kernel)
• Ruby, Go, Rust, Julia (with kernels)

Browser Actions

• JavaScript evaluation
• Console message capture
• Network interception
• DOM manipulation
• Debugger control

IDE Actions

• File operations (open, save, close)
• Editor operations (select, insert, replace)
• Navigation (go to definition, find references)
• Refactoring (rename, format, extract)
• Terminal control
• Diagnostics and quick fixes

Extension Bridge

ZAP communicates with browser/IDE extensions via WebSocket:

Extension	Port	Protocol
Browser	9224	HTTP/WS
VS Code	9225	WebSocket
Cursor	9226	WebSocket
Windsurf	9227	WebSocket
Neovim	9228	WebSocket

Proto Files

• zap.proto - Main protocol definition
• Generated code available for:
  • Python: pip install hanzo-zap
  • TypeScript: npm install @hanzo/zap
  • Go: go get github.com/hanzoai/zap
  • Rust: cargo add hanzo-zap

Usage with hanzo-mcp

ZAP is fully integrated into hanzo-mcp tools:

# REPL evaluation
repl(action="eval", code="print('hello')", language="python")

# Browser console
browser(action="console")
browser(action="evaluate", code="document.title")

# IDE control
ide(action="open", path="/src/main.py")
ide(action="rename", new_name="newFunc", line=10, column=5)

Compared to MCP

Feature	MCP	ZAP
Tool calls	✓	✓
Resources	✓	✓
Prompts	✓	✓
Streaming	✗	✓
REPL sessions	✗	✓
IDE integration	✗	✓
Browser DevTools	✗	✓
Binary protocol	✗	✓ (Cap'n Proto)
Extension bridge	✗	✓

License

MIT - Hanzo Industries Inc