@alexgenovese/mcp-fleet-worker

Spawn headless OpenCode workers on cheap models — delegate expensive tool-using tasks to a fleet of parallel workers with isolated git worktrees. Optional Brick routing selects the optimal model per task automatically.

MCP Activation Keywords

Le seguenti keyword attivano questo MCP in Claude Code / OpenCode:

Aggiungi al tuo .claude/hooks/PreToolUse o usa direttamente i tool MCP via Claude Code.

Related MCP server: MCP Codex Worker

What Is This?

mcp-fleet-worker is an MCP server that lets you spawn headless OpenCode workers on any model configured in your opencode.json — from local Ollama models to cheap remote providers like GLM via z.ai.

Each worker runs in an isolated git worktree with its own CLAUDE_CONFIG_DIR, so multiple workers run side-by-side without conflicting. Workers are treated as disposable "grunt agents": a powerful orchestrator (Opus) fans out tasks, collects results, and lands the completed branches.

Why?

• Cost optimization: run cheap models (GLM-5.2, Haiku, Sonnet) for routine coding tasks, reserve Opus for orchestration

• Parallel execution: spawn N workers simultaneously, each in its own worktree

• Isolation: each worker gets a fresh git branch + scratch directory

• Fleet-ops ready: designed to pair with fleet-ops for test-gated landing

Technology Stack

Architecture

                    ┌─────────────────────────────────┐
                    │       Claude Code (Opus)         │
                    │    (orchestrator / caller)        │
                    └──────────┬──────────────────────┘
                               │ MCP (stdio)
                    ┌──────────▼──────────────────────┐
                    │     mcp-fleet-worker server      │
                    │                                   │
                    │  ┌─ fleet_worker_spawn            │
                    │  ├─ fleet_worker_collect          │
                    │  ├─ fleet_worker_status           │
                    │  ├─ fleet_worker_list_models      │
                    │  └─ fleet_worker_cancel           │
                    └──────────┬──────────────────────┘
                               │
                    ┌──────────▼──────────────────────┐
                    │      Git Worktree (.fleet-work/) │
                    │                                   │
                    │  worker-1/  ← branch `fleet/id1` │
                    │  worker-2/  ← branch `fleet/id2` │
                    │  ...                              │
                    └──────────┬──────────────────────┘
                               │
                    ┌──────────▼──────────────────────┐
                    │   ~/.fleet-worker/scratch/<id>/  │
                    │   (CLAUDE_CONFIG_DIR per worker) │
                    └─────────────────────────────────┘

Flow

1. Caller sends a prompt + optional model to fleet_worker_spawn

2. Server creates an isolated git worktree (.fleet-work/<id>/) with a dedicated branch (fleet/<id>)

3. Server spawns opencode run -m <model> --agent coder --auto --dir <worktree> --format json "<prompt>"

4. Caller polls fleet_worker_collect or waits for completion

5. Worker finishes → output is captured → fleet_worker_cancel cleans up worktree + scratch dir

Getting Started

Prerequisites

• Node.js >= 18

• npm or pnpm

• OpenCode installed (the opencode CLI in PATH)

• A git repository to use as the worker base directory

Installation

# Clone
git clone https://github.com/alexgenovese/mcp-fleet-worker.git
cd mcp-fleet-worker

# Install deps
npm install

# Build
npm run build

# Test
node dist/index.js

Configuration

Add to your opencode.json (or to your MCP hub config):

{
  "mcpServers": {
    "mcp-fleet-worker": {
      "command": "node",
      "args": ["/path/to/mcp-fleet-worker/dist/index.js"],
      "env": {
        "FLEET_WORKER_BASE_DIR": "/path/to/your/git/repo",
        "FLEET_WORKER_DEFAULT_MODEL": "regolo/glm5.2-beta",
        "FLEET_WORKER_BRICK_URL": "https://api.regolo.ai",
        "FLEET_WORKER_BRICK_API_KEY": "your-regolo-api-key",
        "OPENCODE_PATH": "opencode"
      }
    }
  }
}

Environment Variables:

Brick Smart Routing (Optional)

When FLEET_WORKER_BRICK_URL and FLEET_WORKER_BRICK_API_KEY are set, fleet_worker_spawn without an explicit model parameter will call Brick's /v1/routing/test endpoint to select the optimal model based on:

• Capability — 6 dimensions (coding, math_reasoning, creative_synthesis, instruction_following, planning_agentic, world_knowledge)

• Complexity — easy / medium / hard

• Cost — penalizes expensive models for simple tasks

How It Works

fleet_worker_spawn(prompt="fix typo in README.md")
  ↓
  Brick analyzes prompt → complexity: easy, capability: {instruction_following: 0.9}
  ↓
  Brick selects: ollama/qwen3:4b (cheapest capable model)
  ↓
  Worker spawns on ollama/qwen3:4b
  ↓
  fleet_worker_status shows: routed=true, costSavings=95%

When Routing Kicks In

Cost Savings Tracking

Every routed worker records its costSavings percentage (estimated vs. using the fallback model). This appears in:

• fleet_worker_spawn response (routing.costSavings)

• fleet_worker_status output (per-worker costSavings)

• fleet_worker_collect result (routing.costSavings)

See USE_CASES.md for detailed cost-saving scenarios for developers and CTOs.

Project Structure

mcp-fleet-worker/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── types.ts              # WorkerSpec, WorkerProcess, WorkerStatus
│   ├── lib/
│   │   ├── models.ts         # opencode.json parser (JSONC-aware)
│   │   ├── router.ts         # Brick routing client (Regolo API)
│   │   ├── worktree.ts       # Git worktree create/remove/cleanup
│   │   ├── config.ts         # Scratch directory (~/.fleet-worker/)
│   │   ├── id.ts             # Short UUID generator (8 chars)
│   │   └── worker-manager.ts # Spawn/track/kill opencode children
│   └── tools/
│       └── register.ts       # 5 MCP tool handlers
├── dist/                     # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Key Features

1. Multi-Model Support

Reads all providers and models from opencode.json — Ollama, GLM, custom OpenAI-compatible endpoints. Use fleet_worker_list_models to see what's available.

2. Git Worktree Isolation

Each worker runs in a dedicated git worktree (git worktree add -b fleet/<id>), so multiple workers can modify the same repo simultaneously without merge conflicts at runtime.

3. Background Execution

Workers spawn as child processes with captured stdout/stderr. Collect results async via fleet_worker_collect.

4. Cleanup

fleet_worker_cancel with cleanup: true removes:

• The worktree directory (.fleet-work/<id>/)

• The local git branch (fleet/<id>)

• The scratch config dir (~/.fleet-worker/scratch/<id>/)

5. JSONC Parsing

Reads opencode.json even with comments (// and /* */) — no need to strip them manually.

MCP Tools

fleet_worker_list_models

List all available models grouped by provider, with context window and cost info.

fleet_worker_spawn

Spawn a headless worker on any model.

fleet_worker_collect

Get a worker's result.

fleet_worker_status

List all workers with status, model, branch, elapsed time.

fleet_worker_cancel

Stop and clean up a worker.

Development Workflow

1. Install → npm install

2. Build → npm run build

3. Watch → npm run dev (tsc --watch)

4. Test locally → node dist/index.js (then connect with MCP inspector or Claude Desktop)

To test with the MCP inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Testing

# Type check
npx tsc --noEmit

# Build
npm run build

# Quick smoke test (list models)
node -e "
import('./dist/index.js').then(() => console.log('Server loads OK'))
"

License

MIT © Alex Geno