# Claude Codex Orchestrator MCP

A local MCP server that wraps a Windows Claude -> Codex worker orchestration workflow.

The MCP server is intentionally thin. It exposes a stable tool surface and delegates execution to the existing PowerShell dispatcher scripts under `tools/`.

## What It Provides

- `create_task`: create one queued markdown task under `.orchestrator/tasks/`.
- `dispatch_task`: dispatch one task through `tools/invoke-orchestrated-task.ps1`.
- `read_status`: read compact `status.json` output and summarize the result.
- `run_task_loop`: run bounded retry/decision handling over queued tasks.
- `archive_artifacts`: archive historical artifacts, dry-run by default.

## Requirements

- Windows PowerShell 5.x or compatible `powershell.exe`.
- Node.js 20+.
- Codex CLI available on `PATH` for `app` and `code` lanes.
- Codex Desktop/app-server support for the `app` lane.

## Quick Start

```powershell
npm run mcp:orchestrator
```

The server speaks MCP over stdio. It is meant to be launched by an MCP client, not used as an interactive terminal program.

## MCP Client Config Example

Use absolute paths for your clone location and the workspace you want the orchestrator to manage:

```json
{
  "mcpServers": {
    "claude-codex-orchestrator": {
      "command": "C:/Program Files/nodejs/node.exe",
      "args": [
        "D:/path/to/claude-codex-orchestrator-mcp/tools/mcp-orchestrator-server.js"
      ],
      "env": {
        "ORCHESTRATOR_WORKSPACE_ROOT": "D:/path/to/your/workspace"
      }
    }
  }
}
```

## Safety Model

- The server validates file paths and keeps them inside the configured workspace.
- Set `ORCHESTRATOR_WORKSPACE_ROOT` when the MCP server is installed outside the workspace it should manage.
- Automation defaults to dry-run unless explicitly invoked with real automation flags in the underlying dispatcher path.
- Artifact archival defaults to dry-run; moves require `apply: true`.
- The MCP server does not edit Codex global config.
- Existing PowerShell scripts remain the source of truth for orchestration behavior.

## Repository Layout

```text
.
|-- AGENTS.md
|-- PROJECT-CONTEXT-MCP-SKILL.md
|-- package.json
|-- docs/
|   `-- ORCHESTRATOR-USAGE.md
|-- tools/
|   |-- mcp-orchestrator-server.js
|   |-- invoke-orchestrated-task.ps1
|   |-- invoke-codex-app-worker.ps1
|   |-- codex-app-worker.js
|   |-- invoke-codex-worker.ps1
|   |-- run-controlled-automation.ps1
|   |-- orchestrator-tasking.ps1
|   |-- invoke-orchestrator-task-loop.ps1
|   `-- archive-orchestrator-artifacts.ps1
`-- .claude/
    |-- commands/orchestrate.md
    `-- skills/claude-codex-orchestrator/SKILL.md
```

## Verification

Syntax-check the MCP server:

```powershell
node --check tools/mcp-orchestrator-server.js
```

Run non-Codex PowerShell checks:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File tools/test-orchestrator-tasking.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File tools/test-controlled-automation.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File tools/test-archive-orchestrator-artifacts.ps1
```

Full app/code worker tests require a working Codex CLI/app-server setup and may take longer.