Skip to content

MCP Implementation Parity Analysis

This document analyzes the parity status between Hanzo's three MCP implementations and provides a roadmap for convergence.

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                        VS Code Extension                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                    Backend Selection                       │   │
│  │  auto → python (if uvx) → typescript (fallback)          │   │
│  └──────────────────────────────────────────────────────────┘   │
└───────────┬──────────────────┬────────────────────┬─────────────┘
            │                  │                    │
            ▼                  ▼                    ▼
┌───────────────────┐ ┌────────────────┐ ┌──────────────────────┐
│  Python MCP       │ │ TypeScript MCP │ │   Rust MCP Client    │
│  (hanzo-mcp)      │ │ (@hanzo/mcp)   │ │   (hanzo-node)       │
│                   │ │                │ │                      │
│  30+ native tools │ │ 15+ tools      │ │  MCP proxy/client    │
│  Full features    │ │ Essential set  │ │  Connects to others  │
└───────────────────┘ └────────────────┘ └──────────────────────┘

Implementation Comparison

Python MCP (hanzo-mcp) - Reference Implementation

Status: Complete (30+ tools)

Category Tools Status
File System read, write, edit, tree, find, search, ast ✅ Complete
Shell cmd, zsh, bash, ps, npx, uvx, open ✅ Complete
Browser 70+ Playwright actions ✅ Complete
Memory unified memory (recall, create, update, delete, facts) ✅ Complete
Reasoning think, critic ✅ Complete
LSP definition, references, rename, hover ✅ Complete
Refactor rename, extract, inline, move ✅ Complete
Agent agent runner (claude, gemini, codex, etc.), iching, review ✅ Complete
LLM llm, consensus ✅ Complete
Todo unified todo management ✅ Complete
Config config, mode ✅ Complete
Database SQL query/search/stats, graph operations ✅ Complete
Vector index, vector_index, vector_search ✅ Complete
Jupyter notebook read/edit ✅ Complete
Editor neovim integration ✅ Complete

Key Features: - ✅ Auto-backgrounding (30s default, configurable via HANZO_AUTO_BACKGROUND_TIMEOUT) - ✅ DAG execution with parallel support - ✅ Process management (ps tool) - ✅ Entry-point based tool discovery - ✅ Unified action patterns (memory, agent tools) - ✅ 701 programmer personas

TypeScript MCP (@hanzo/mcp) - Essential Subset

Status: Partial (~15 tools)

Category Tools Status
File System read_file, write_file, list_files, get_file_info, directory_tree ✅ Complete
Shell bash, run_command, run_background, list_processes, get_process_output, kill_process ✅ Complete
Search grep, search ✅ Complete
Edit edit tools ✅ Complete
Browser HanzoDesktopTool, PlaywrightControlTool ⚠️ Basic
Memory separate memory tools ⚠️ Not unified
Reasoning - ❌ Missing
UI unified-ui, ui-registry, github-ui ✅ Complete
AutoGUI automation tools ✅ Complete
Orchestration agent tools ⚠️ Basic

Features Comparison: | Feature | Python | TypeScript | Gap | |---------|--------|------------|-----| | Auto-backgrounding | ✅ 30s | ✅ withAutoTimeout | Parity | | DAG execution | ✅ cmd tool | ❌ | Missing | | Process management | ✅ Unified ps | ⚠️ Separate tools | Different API | | Unified memory | ✅ Single tool | ❌ | Missing | | Think/Critic | ✅ | ❌ | Missing | | Personas | ✅ 701 | ❌ | Missing |

Rust MCP (hanzo-node/hanzo-mcp) - MCP Client/Proxy

Status: Different Architecture

The Rust implementation is an MCP client, not a tool provider. It:

  1. Connects to external MCP servers (via stdio, SSE, HTTP)
  2. Lists tools from connected servers
  3. Proxies tool calls to those servers

Supported Transports: - ✅ Stdio (spawns MCP server as subprocess) - ✅ SSE (Server-Sent Events) - ✅ HTTP (Streamable HTTP)

Use Case: - Embedded in hanzo-node (blockchain/AI node) - Orchestrates multiple MCP servers - Enables decentralized tool execution

Parity Roadmap

Phase 1: TypeScript Essential Parity (Priority: P0)

Add missing essential tools to TypeScript MCP:

  1. cmd tool with DAG support 

    cmd({ commands: ["npm install", "npm build"], parallel: true })
cmd({ commands: [
  { id: "install", run: "npm install" },
  { id: "build", run: "npm build", after: ["install"] }
]})

  2. Unified ps tool

  3. Consolidate list_processes, get_process_output, kill_process

  4. Match Python API: ps(), ps({ logs: "id" }), ps({ kill: "id" })

  5. think and critic tools

  6. Essential for AI reasoning patterns
  7. Simple implementation, high value

Phase 2: TypeScript Feature Parity (Priority: P1)

  1. Unified memory tool
  2. Match Python's action-based API

  3. Actions: recall, create, update, delete, facts, summarize

  4. Enhanced browser tool

  5. Add more Playwright actions

  6. Match Python's 70+ action coverage

  7. Agent tool

  8. Unified interface for spawning external agents
  9. Support for Claude, Gemini, Codex, etc.

Phase 3: Rust Tool Implementation (Priority: P2)

Consider adding native Rust tools for performance-critical operations:

  1. File I/O - High-performance read/write/search
  2. Process management - Native subprocess handling
  3. AST parsing - Tree-sitter based code analysis

This would allow hanzo-node to run standalone without Python dependency.

Extension Backend Selection Logic

The VS Code extension (~/work/hanzo/extension) uses this selection:

async selectBackend(backend: string): Promise<string> {
  if (backend !== 'auto') return backend;

  // Auto-detect: prefer Python if uvx available
  try {
    execSync('uvx --version', { stdio: 'ignore' });
    return 'python';  // Full 30+ tools
  } catch {
    return 'typescript';  // Essential ~15 tools
  }
}

Backend Capabilities:

Backend Tools Use Case
python 30+ Full development (recommended)
typescript ~15 Web-first, no Python needed
rust (proxy) High-performance, embedded
local-node varies Decentralized compute

Tool Name Mapping

For swappable backends, tool names should be consistent:

Python TypeScript Rust Action
read read_file - Align to read
write write_file - Align to write
cmd bash - Add cmd to TS
ps list_processes - Add unified ps
tree directory_tree - Align to tree
search grep - Keep both as aliases

Immediate (This Sprint)

  1. ✅ Extension supports multiple backends (done)
  2. ✅ Python MCP is reference (done)
  3. ⬜ Document tool name differences
  4. ⬜ Create TypeScript cmd tool issue

Short Term (Next 2 Sprints)

  1. ⬜ Add cmd with DAG to TypeScript
  2. ⬜ Add think/critic to TypeScript
  3. ⬜ Unify ps in TypeScript
  4. ⬜ Align tool names (read vs read_file)

Medium Term

  1. ⬜ Unified memory in TypeScript
  2. ⬜ Enhanced browser tool
  3. ⬜ Consider Rust native tools

Testing Parity

To ensure backends are swappable, run same tests against all:

# Python
uvx hanzo-mcp --test

# TypeScript
npx @hanzo/mcp --test

# Via extension (auto-detect)
code --command "hanzo.mcp.test"

Conclusion

The current architecture is sound: - Python: Reference implementation with full features - TypeScript: Essential subset for browser/VS Code - Rust: Client/proxy for orchestration

The priority is bringing TypeScript to essential parity (cmd, ps, think, critic), not full parity. Users needing all features should use Python backend.