# 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](https://github.com/openai/codex) | `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](https://code.claude.com/docs/en/headless) | `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`](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

```bash
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`](https://www.npmjs.com/package/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

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

## Development

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