Skip to main content
Glama
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.