# Moa Orchestrator

> Local MCP server for cost-controlled Claude planning and isolated Codex implementation workers.

- **Type:** MCP server
- **Install:** `agentstack add mcp-wccjitou-lgtm-moa-orchestrator`
- **Verified:** Pending review
- **Seller:** [wccjitou-lgtm](https://agentstack.voostack.com/s/wccjitou-lgtm)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [wccjitou-lgtm](https://github.com/wccjitou-lgtm)
- **Source:** https://github.com/wccjitou-lgtm/moa-orchestrator

## Install

```sh
agentstack add mcp-wccjitou-lgtm-moa-orchestrator
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MoA Orchestrator

**MoA Orchestrator** is a local MCP server for agentic software engineering. It coordinates a cost-controlled Claude Planner and isolated Codex implementation workers, then returns reviewable patches instead of directly changing your main workspace.

[中文](docs/README.zh-CN.md) · [English](README.md) · [Français](docs/README.fr.md) · [Deutsch](docs/README.de.md)

[Quick Start](#quick-start) · [How It Works](#how-it-works) · [MCP Tools](#mcp-tools) · [Documentation](#documentation) · [Configuration](#configuration) · [Troubleshooting](#troubleshooting) · [Contributing](#contributing)

---

## Why MoA?

LLM agents are powerful, but coordinating them safely is hard. MoA turns multi-agent coding into a local, auditable workflow:

- **Claude plans only** through the Anthropic Messages API.
- **Codex implements only** inside isolated temporary git worktrees.
- **Patches are the boundary**: workers return unified diffs and patch references.
- **Humans stay in control**: only `moa.apply` with `confirm:true` can modify the main workspace.
- **Runs are observable**: task status, run manifests, worker logs, patches, and rollback records are stored under `.moa/`.

## Quick Start

### Requirements

- Node.js 20+
- Git
- Codex CLI on `PATH`
- Claude credentials when using `moa.plan` or `moa.run`
- Codex Desktop or another MCP client that can call stdio MCP servers

Check the local tools first:

```powershell
node --version
git --version
cmd /c codex --version
```

### Clone And Install

```powershell
git clone https://github.com/wccjitou-lgtm/moa-orchestrator.git
cd moa-orchestrator
cmd /c npm install
cmd /c npm test
```

### Configure Claude

MoA reads secrets only from environment variables. The default Claude key variable is `ANTHROPIC_API_KEY`.

```powershell
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "YOUR_ANTHROPIC_KEY", "User")
```

For Anthropic-compatible relays:

```powershell
[Environment]::SetEnvironmentVariable("MOA_CLAUDE_API_KEY_ENV", "ANTHROPIC_AUTH_TOKEN", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "YOUR_RELAY_TOKEN", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://your-relay.example", "User")
```

Restart Codex Desktop after setting user-level environment variables. Desktop apps usually do not inherit variables from an already-open terminal.

### Register With Codex Desktop

Use the absolute path to the cloned repository:

```powershell
cmd /c codex mcp add moa -- node "C:\path\to\moa-orchestrator\src\server.js"
```

Verify:

```powershell
cmd /c codex mcp get moa
cmd /c npm test -- test/server.test.js
```

Restart Codex Desktop, then call `moa.health`.

Expected `moa.health` shape:

```json
{
  "ok": true,
  "dependencies": {
    "node": { "ok": true },
    "git": { "ok": true },
    "codex": { "ok": true }
  },
  "config": {
    "claudeApiKeyPresent": true
  }
}
```

### Minimal Flow

1. Ask MoA to plan:

   ```json
   {
     "goal": "Add a small module, tests, and documentation",
     "scope": "project",
     "context": {
       "repoRoot": "C:\\path\\to\\repo",
       "contextFiles": ["src/index.js", "test/index.test.js"]
     }
   }
   ```

2. Run the saved plan without another Claude call:

   ```json
   {
     "planId": "plan-...",
     "autoApply": false
   }
   ```

3. Poll the run:

   ```json
   { "runId": "run-..." }
   ```

4. Preview, then apply only after review:

   ```json
   { "repoRoot": "C:\\path\\to\\repo", "runId": "run-...", "confirm": false }
   ```

   ```json
   { "repoRoot": "C:\\path\\to\\repo", "runId": "run-...", "confirm": true }
   ```

## Codex Desktop Deployment Checklist

Use this checklist when setting MoA up on a new machine:

1. `git clone` this repository and run `cmd /c npm install`.
2. Run `cmd /c npm test`; all tests should pass before registering the MCP server.
3. Run `cmd /c codex --version`; if this fails, install or repair the Codex CLI first.
4. Set `ANTHROPIC_API_KEY` or configure `MOA_CLAUDE_API_KEY_ENV` for your relay.
5. Restart Codex Desktop so it inherits the environment variables.
6. Register MoA with `cmd /c codex mcp add moa -- node "ABSOLUTE_PATH\src\server.js"`.
7. Run `cmd /c codex mcp get moa` and confirm it is enabled with stdio transport.
8. In Codex Desktop, call `moa.health`.
9. Only after health is green, try `moa.plan` with a small goal.

## How It Works

```text
User / Codex Desktop
        |
        | MCP tool call
        v
MCP Server: moa
        |
        +--> Claude Planner
        |      - project or node planning
        |      - bounded repository context
        |      - JSON output only
        |
        +--> Codex Workers
        |      - codex exec
        |      - isolated CODEX_HOME
        |      - temporary detached git worktree
        |      - unified diff output
        |
        +--> Patch Gate
               - preview
               - git apply --3way
               - rollbackRef
```

MoA deliberately separates responsibilities:

- **Planning**: Claude decomposes goals into nodes, dependencies, routes, interfaces, and acceptance checks.
- **Implementation**: Codex workers execute node contracts in isolated worktrees.
- **Archiving**: plans, tasks, logs, diffs, and run manifests are written to `.moa/`.
- **Application**: `moa.apply` is the only path that changes the main workspace.

## MCP Tools

| Tool | Purpose |
| --- | --- |
| `moa.health` | Check Node, Git, Codex CLI, and safe configuration summary. |
| `moa.plan` | Call Claude once for project or node planning and return JSON with usage. |
| `moa.implement` | Start one async Codex worker and return a `taskId` immediately. |
| `moa.run` | Start an async dependency-aware multi-node run. |
| `moa.taskStatus` | Poll an implement task or a whole run by `taskId` or `runId`. |
| `moa.apply` | Preview, apply, or roll back patches with explicit confirmation. |
| `moa.listRuns` | List recent run archives. |
| `moa.retryNode` | Retry one failed node from an archived run without replanning. |
| `moa.cleanup` | Remove orphaned MoA temp worktrees and message directories. |

## Documentation

- [Controller orchestration protocol](ORCHESTRATION.md)
- [Technical specification](SPEC.md)
- [Project introduction page](docs/project-introduction.html)
- [Execution trace introduction page](docs/project-introduction-trace.html)
- [Chinese README](docs/README.zh-CN.md)
- [French README](docs/README.fr.md)
- [German README](docs/README.de.md)

## Configuration

MoA can be configured with environment variables or a local `config.json`. Do not commit `config.json`.

| Variable | Default | Description |
| --- | --- | --- |
| `MOA_CLAUDE_API_KEY_ENV` | `ANTHROPIC_API_KEY` | Name of the environment variable that stores the Claude key. |
| `MOA_CLAUDE_BASE_URL` / `ANTHROPIC_BASE_URL` | `https://api.anthropic.com` | Anthropic or compatible API base URL. |
| `MOA_CLAUDE_MODEL` | `claude-opus-4-8` | Claude model name. |
| `MOA_CLAUDE_MAX_TOKENS` | `16384` | Maximum output tokens for planner calls. |
| `MOA_CODEX_COMMAND` | `codex` | Codex CLI command. |
| `MOA_CODEX_MODEL` | unset | Optional Codex model override. |
| `MOA_CODEX_ISO_HOME` | `.moa/codex-home` | Isolated Codex home used by workers. |
| `MOA_MAX_CLAUDE_CALLS_PER_RUN` | `2` | Claude call budget per run. |
| `MOA_MAX_CLAUDE_TOKENS_PER_RUN` | `200000` | Claude token budget per run. |
| `MOA_MAX_PARALLEL_WORKERS` | `2` | Maximum concurrent Codex workers. |
| `MOA_PLANNER_TIMEOUT_MS` | `600000` | Planner timeout. |
| `MOA_WORKER_TIMEOUT_MS` | `600000` | Worker timeout. |
| `MOA_MAX_INLINE_DIFF_BYTES` | `200000` | Inline diff response limit. |
| `MOA_MAX_PLAN_CONTEXT_BYTES` | `60000` | Planner repository context byte limit. |
| `MOA_RUNS_DIR` | `.moa/runs` | Run archive directory. |
| `MOA_TASKS_DIR` | `.moa/tasks` | Async task state directory. |

Example:

```json
{
  "claude": {
    "apiKeyEnv": "ANTHROPIC_API_KEY",
    "baseUrl": "https://api.anthropic.com",
    "model": "claude-opus-4-8",
    "maxTokens": 16384
  },
  "limits": {
    "maxClaudeCallsPerRun": 2,
    "maxParallelWorkers": 2,
    "workerTimeoutMs": 600000
  }
}
```

## Safety Model

- Claude is never invoked through the Claude CLI.
- Claude is never used inside implementation loops.
- Worker prompts are passed through stdin.
- Workers run in temporary detached git worktrees under `os.tmpdir()`.
- Workers use an isolated `CODEX_HOME`.
- Windows `.cmd` wrappers are spawned with `shell:true`; `git.exe` uses argument arrays.
- Main workspace writes require `moa.apply` and `confirm:true`.
- Rollback deletes only files added by the recorded apply operation and checks out only touched tracked files.

## Troubleshooting

### `moa.plan` reports missing Claude credentials

Set the environment variable named by `MOA_CLAUDE_API_KEY_ENV`. By default:

```powershell
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "", "User")
```

Make sure Codex Desktop was launched from an environment that contains that variable.

### Claude planning times out

Reduce `contextFiles`, lower `MOA_MAX_PLAN_CONTEXT_BYTES`, split the goal, or increase `MOA_PLANNER_TIMEOUT_MS`. Some MCP clients may still enforce their own shorter tool-call timeout.

### Codex worker fails because of global Codex state

MoA workers use an isolated `CODEX_HOME` and avoid copying global skills. Inspect the node log under `.moa/runs//`.

### A worker stays running too long

Check:

```json
{ "taskId": "implement-..." }
```

`moa.taskStatus` reports `elapsedMs`, `lastHeartbeat`, and `pid`. Hard timeouts mark the task failed and clean up the worktree.

### Patch conflicts during apply

Run preview first:

```json
{ "repoRoot": "C:\\path\\to\\repo", "runId": "run-...", "confirm": false }
```

If conflicts appear, inspect the patch archive and regenerate or resolve manually.

### Worktree leftovers

Use:

```json
{}
```

with `moa.cleanup`. It only scans MoA temp prefixes such as `moawt-*` and `moacodexmsg-*`.

## Development

Run all tests:

```powershell
cmd /c npm test
```

Run milestone subsets:

```powershell
cmd /c npm run test:m0
cmd /c npm run test:m1
cmd /c npm run test:m2
cmd /c npm run test:m3
cmd /c npm run test:m4
```

## Contributing

Contributions are welcome. Good first areas include:

- Planner prompt and repository context selection
- Worker lifecycle and cross-platform hardening
- Run archive visualization
- More MCP client examples
- Documentation and translated guides
- Test coverage for edge cases

Read [CONTRIBUTING.md](CONTRIBUTING.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), and [SECURITY.md](SECURITY.md) before opening a pull request.

## License

MIT. See [LICENSE](LICENSE).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [wccjitou-lgtm](https://github.com/wccjitou-lgtm)
- **Source:** [wccjitou-lgtm/moa-orchestrator](https://github.com/wccjitou-lgtm/moa-orchestrator)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-wccjitou-lgtm-moa-orchestrator
- Seller: https://agentstack.voostack.com/s/wccjitou-lgtm
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.