Surrogate Protocol MCP Server

A Model Context Protocol (MCP) server for multi-agent coding orchestration. Enables Claude Code to spawn autonomous coding agents with isolated worktrees, file locks, and validation gates.

What's New in 3.0.0

🚀 Google-Level Agentic Platform Upgrade

Phase 1 - Spanner State Management:

• SQLite with WAL mode replaces YAML (99.9% faster lock acquisition: 10s → <1ms)
• ACID transactions eliminate race conditions
• Automatic migration from YAML with backup/rollback support

Phase 2 - CitC Workspace Isolation:

• Pre-provisioned workspace pools for instant allocation (<500ms)
• Atomic workspace provisioning via filesystem operations
• Graveyard-based async cleanup for non-blocking decommissioning

Phase 3 - Intelligence Layer:

• Blaze-lite dependency graph for selective test execution (50% reduction)
• Tricorder semantic review with 5 built-in rules (90% compliance)
• Automated architecture compliance checking

Hotfix:

• Fixed HAS_CHANGES gate failing on manually merged branches

Features

• Isolated Worktrees: Each agent gets its own git worktree for parallel work
• File Locking: Prevents conflicts when multiple agents work simultaneously
• Validation Gates: Automatic testing, type-checking, linting, and building
• Session Recovery: Reconcile and recover from crashes
• Observability: Detailed logs and reports for debugging

Installation

📦 npm: https://www.npmjs.com/package/surrogate-protocol-mcp

For Claude Code

claude mcp add surrogate-protocol-mcp --scope user -- npx surrogate-protocol-mcp@latest

For Codex

codex mcp add surrogate-protocol-mcp -- npx surrogate-protocol-mcp@latest

For Antigravity

Add to your Antigravity MCP settings:

{
  "mcp": {
    "servers": {
      "surrogate-protocol": {
        "command": "npx",
        "args": ["-y", "surrogate-protocol-mcp@latest"]
      }
    }
  }
}

From GitHub (Latest Dev Version)

Add to your .mcp.json:

{
  "mcpServers": {
    "surrogate-protocol": {
      "command": "npx",
      "args": [
        "-y",
        "-p",
        "github:NeMeJP/surrogate-protocol-mcp",
        "surrogate-mcp"
      ]
    }
  }
}

Local Development

git clone https://github.com/NeMeJP/surrogate-protocol-mcp.git
cd surrogate-protocol-mcp
npm install
npm run build
npm link

Then in .mcp.json:

{
  "mcpServers": {
    "surrogate-protocol": {
      "command": "node",
      "args": ["/path/to/surrogate-protocol-mcp/dist/mcp-server.js"]
    }
  }
}

Usage

Basic Workflow

1. Check Status: get_status() - Always call first
2. Spawn Agent: spawn_surrogate(id, role, task, files_to_lock)
3. Monitor: get_status() to check progress
4. Complete: Agent auto-submits when done (runs validation gates)

Available Tools

| Tool | Purpose | |------|---------| | get_status() | Get current state, active surrogates, locked files | | spawn_surrogate() | Create and start a new agent | | update_surrogate_status() | Update agent progress status | | submit_work() | Complete task (runs validation gates) | | fail_surrogate() | Mark agent as failed and release locks | | check_file_locks() | Check if files are locked before spawning | | reconcile_surrogates() | Recover from crashes and sync state | | get_surrogate_logs() | Get detailed logs for debugging | | get_surrogate_report() | Get completion report with git stats | | clean_zombies() | Clean up orphaned worktrees |

Example: Multi-Agent Task

// 1. Check current state
get_status()

// 2. Check file availability
check_file_locks(['src/auth.ts', 'src/api/login.ts'])

// 3. Spawn first agent
spawn_surrogate({
  id: 'auth-01',
  role: 'security-engineer',
  task: 'Implement JWT authentication',
  files_to_lock: ['src/auth.ts', 'src/middleware/verify.ts']
})

// 4. Spawn second agent (different files)
spawn_surrogate({
  id: 'api-01',
  role: 'backend-dev',
  task: 'Add API rate limiting',
  files_to_lock: ['src/api/middleware.ts']
})

// 5. Monitor progress
get_status()

// Agents work autonomously and submit when complete!

Validation Gates

When an agent calls submit_work(), these gates run automatically:

1. Rebase - Sync with main branch
2. Tests - Run test suite (project-aware: npm test, pytest, etc.)
3. Type Check - TypeScript or mypy validation
4. Lint - Code style checks (warnings only)
5. Build - Compilation check
6. Security - Dependency audit (warnings only)

If any critical gate fails, the submission is rejected and the agent must fix issues.

Requirements

• Node.js 18+
• Git
• Claude CLI for autonomous agents

Claude CLI Installation

The MCP automatically detects Claude CLI on startup. Just install Claude Code:

Windows:

# PowerShell
irm https://claude.ai/install.ps1 | iex

# Or WinGet
winget install Anthropic.ClaudeCode

macOS:

brew install --cask claude-code

Linux: Visit https://code.claude.com/docs/en/setup

The MCP will automatically:

• ✅ Search for claude in your PATH
• ✅ Check common installation locations (e.g., ~/.local/bin/claude.exe on Windows)
• ✅ Set CLAUDE_BINARY_PATH environment variable automatically
• ⚠️ Show helpful installation instructions if not found

Configuration

Optional environment variables:

# Claude CLI binary path (ONLY if auto-detection fails)
export CLAUDE_BINARY_PATH=/path/to/claude

# Auto-cleanup worktrees on completion
export SURROGATE_CLEANUP_ON_COMPLETE=true

Note: In version 2.1.0+, manual CLAUDE_BINARY_PATH configuration is usually not needed!

Project Structure

surrogate-protocol-mcp/
├── src/
│   ├── mcp-server.ts           # Main MCP server
│   ├── utils/
│   │   ├── state.ts            # State management
│   │   ├── worktree.ts         # Git worktree operations
│   │   ├── gates.ts            # Validation gates
│   │   ├── agent.ts            # Agent spawning
│   │   ├── logging.ts          # Structured logging
│   │   └── artifacts.ts        # Reports and markers
├── dist/                       # Compiled JavaScript
├── package.json
└── tsconfig.json

Troubleshooting

"Surrogate not found"

Run reconcile_surrogates() to sync state after crashes.

"File lock conflict"

Another agent owns those files. Wait for completion or choose different files.

"GATE_FAILED"

Fix the issues reported in the error message and call submit_work() again.

Zombie worktrees

Run clean_zombies() to remove orphaned worktrees.

Development

# Build
npm run build

# Watch mode
npm run dev

# Run tests
npm test

# Lint
npm run lint

License

MIT

Author

DETA Entertainment Studios