MCP-Swarm-Router

An MCP server that lets an LLM host (e.g. Claude Code) plan a large task, then delegate subtasks to local CLI agents based on their specialization — a "swarm router" for tools already installed on your machine.

Roster

id	specialization	CLI assumed	non-interactive invocation
codex	Image generation & heavy tools	OpenAI Codex CLI	codex exec --sandbox workspace-write "<prompt>"
agy	UI/UX design & creative	Google Antigravity CLI (agy, Gemini-based) — unverified, swap via env if wrong	agy -p "<prompt>" --dangerously-skip-permissions
claude-code	Hard coding & logic	Claude Code	claude -p "<prompt>" --output-format text --permission-mode acceptEdits

--sandbox workspace-write / acceptEdits / --dangerously-skip-permissions are there so each CLI can actually write files without blocking on an approval prompt — none of these processes have a TTY, so an unhandled prompt would hang until timeout_ms.

Edit src/registry.ts to add/remove agents or change how each one is invoked.

Tools

• get_agent_roster — returns the roster above as JSON (id, specialization, description, resolved CLI command). Call this first to decide which agent_name fits a subtask.
• delegate_task — spawns agent_name's CLI in workspace_path with prompt, waits for it to exit (or hit timeout_ms, default 15 min, max 1 hour), and returns { exitCode, signal, stdout, stderr, timedOut, durationMs }. Output per stream is capped at ~5MB (further output is dropped and truncated is set).

There's also a plan-and-delegate MCP prompt that spells out the intended workflow: call get_agent_roster → break the task into subtasks → confirm the plan for anything large → run delegate_task per subtask → summarize results.

Setup

npm install
npm run build

Each agent's CLI must be installed and reachable on PATH under the name in src/registry.ts (codex, agy, claude). If your local install differs, copy .env.example to .env (or set the vars in your shell / MCP client config) to point at the real binary:

MCP_SWARM_CODEX_CMD=
MCP_SWARM_AGY_CMD=
MCP_SWARM_CLAUDE_CMD=

Spawning goes through cross-spawn rather than a shell, so Windows .cmd/.bat shims (npm global installs) resolve correctly and the prompt text can't be interpreted as shell metacharacters.

Register with an MCP client

{
  "mcpServers": {
    "swarm-router": {
      "command": "node",
      "args": ["C:/KERJAAN/mcp-swarm-router/dist/index.js"]
    }
  }
}

Development

npm run dev    # run src/index.ts directly via tsx
npm run build  # compile to dist/
npm start      # run the compiled server