opencode-army-mcp
by emilsenkel
README.md
# opencode-army-mcp
An MCP server that lets an orchestrator bot run a free-model OpenCode worker
army. It can inspect the fleet, start and queue tasks, plan waves, tune
policy, open PRs, and restart itself.
Safety invariants are hardcoded in `src/invariants.js` and checked at boot:
- **A1** — only free model ids (`opencode-go/*-free`, OpenRouter `:free`, a
narrow Zen-free allowlist). Paid models are refused; an empty free pool
queues work rather than falling back to a paid model.
- **A2** — no merge to main, no push to protected branches, no deploys.
Pushing an `oc/*` branch and opening a PR is allowed.
- **A3** — workers write only under a configured worktree root. Named
production trees may be registered as read-only git *sources*, never as a
working directory.
- **A4** — no tool returns a secret. Sensitive paths are unreadable; log
output is redacted.
- **A5** — the only LaunchAgent it may restart is its own (configured label).
The *rules* are not configurable at runtime. The *paths and hosts* they apply
to (worktree root, protected trees, listen address, token file, order-book
directory) come from environment variables. There is no baked-in private
layout.
A product-specific booking front door that lived beside this server in the
original tree is **not** included here.
## Stack
Node.js 20+, `@modelcontextprotocol/sdk`, `zod`. Tests use `node --test`.
## Setup
```bash
npm install
cp .env.example .env # optional; most values have local defaults
# write a bearer token (mode 600) to ~/.config/opencode-army-mcp/token
# or let the server generate one on first boot
npm test # unit tests; Mac-only integration tests are skipped
# ARMY_LIVE_TESTS=1 npm test # also run tests that need this machine's layout
node src/index.js # loopback, dispatch unarmed unless COS_MCP_DISPATCH=1
```
## Config
The default worktree root is `~/oc-worktrees` (override with `ARMY_WORKTREE_ROOT`).
See `.env.example`. Important variables: `ARMY_WORKTREE_ROOT`,
`ARMY_PROTECTED_PATHS`, `COS_MCP_TOKEN_PATH`, `COS_MCP_DISPATCH`,
`ARMY_LAUNCHD_LABEL`. Optional order-book tools talk to `ARMY_HQ_DIR` if you
have that CLI; they are skipped if it is absent.
## Licence
MIT, Copyright (c) 2026 Emil Senkel.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data