python-sdk/docs/mcp/PARITY.md

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

   • Consolidate list_processes, get_process_output, kill_process
   • Match Python API: ps(), ps({ logs: "id" }), ps({ kill: "id" })

3. think and critic tools

   • Essential for AI reasoning patterns
   • Simple implementation, high value

Phase 2: TypeScript Feature Parity (Priority: P1)

1. Unified memory tool

   • Match Python's action-based API
   • Actions: recall, create, update, delete, facts, summarize

2. Enhanced browser tool

   • Add more Playwright actions
   • Match Python's 70+ action coverage

3. Agent tool

   • Unified interface for spawning external agents
   • 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

Recommended Actions

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.