mcp-codex-worker 1.0.4 → 1.0.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +109 -118
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,29 +1,26 @@
|
|
|
1
1
|
# mcp-codex-worker
|
|
2
2
|
|
|
3
|
-
A stdio MCP server that bridges MCP clients to the Codex app-server runtime. Provides **5 task tools** for
|
|
3
|
+
A stdio MCP server that bridges MCP clients to the Codex app-server runtime. Provides **5 task tools** for fully autonomous agent orchestration — spawn, wait, respond, message, cancel. All commands and file edits are auto-approved. Full observability via file-backed reporting and MCP resource subscriptions.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
### MCP server
|
|
8
|
-
|
|
9
|
-
```bash
|
|
10
|
-
npx -y mcp-codex-worker
|
|
11
|
-
```
|
|
5
|
+
Does not call OpenAI APIs directly — all work is delegated to `codex app-server` (see [codex-app-server protocol reference](https://github.com/openai/codex/blob/main/codex-rs/app-server/README.md)).
|
|
12
6
|
|
|
13
|
-
|
|
7
|
+
## Install
|
|
14
8
|
|
|
15
9
|
```bash
|
|
16
|
-
|
|
10
|
+
npx -y mcp-codex-worker@latest
|
|
17
11
|
```
|
|
18
12
|
|
|
19
|
-
Add to
|
|
13
|
+
Add to Claude Code:
|
|
20
14
|
|
|
21
15
|
```json
|
|
22
16
|
{
|
|
23
17
|
"mcpServers": {
|
|
24
18
|
"codex-worker": {
|
|
25
19
|
"command": "npx",
|
|
26
|
-
"args": ["-y", "mcp-codex-worker"]
|
|
20
|
+
"args": ["-y", "mcp-codex-worker@latest"],
|
|
21
|
+
"env": {
|
|
22
|
+
"CODEX_LB_API_KEY": "${CODEX_LB_API_KEY}"
|
|
23
|
+
}
|
|
27
24
|
}
|
|
28
25
|
}
|
|
29
26
|
}
|
|
@@ -31,172 +28,166 @@ Add to any MCP client config (Claude Desktop, VS Code, Cursor, etc.):
|
|
|
31
28
|
|
|
32
29
|
### Companion skill (optional)
|
|
33
30
|
|
|
34
|
-
The `run-codex-subagents` skill teaches AI agents how to orchestrate tasks through this server — wave execution, approval handling, parallel dispatch, and more.
|
|
35
|
-
|
|
36
31
|
```bash
|
|
37
32
|
npx -y skills add -y -g yigitkonur/skills-by-yigitkonur/skills/run-codex-subagents
|
|
38
33
|
```
|
|
39
34
|
|
|
40
|
-
Or install the full skills pack:
|
|
41
|
-
|
|
42
|
-
```bash
|
|
43
|
-
npx -y skills add -y -g yigitkonur/skills-by-yigitkonur
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
The skill is also bundled at `skills/run-codex-subagents/` in this repo for reference.
|
|
47
|
-
|
|
48
35
|
## Requirements
|
|
49
36
|
|
|
50
37
|
- Node 22+
|
|
51
|
-
- `codex` CLI installed
|
|
38
|
+
- `codex` CLI installed
|
|
39
|
+
- `CODEX_LB_API_KEY` or `OPENAI_API_KEY` in environment
|
|
52
40
|
|
|
53
|
-
##
|
|
54
|
-
|
|
55
|
-
The primary interface. Provider-agnostic — tasks route to Codex today, Copilot and Claude CLI in Phase 2.
|
|
41
|
+
## Tools
|
|
56
42
|
|
|
57
43
|
| Tool | Purpose |
|
|
58
44
|
|---|---|
|
|
59
|
-
| `spawn-task` | Create and start a
|
|
60
|
-
| `wait-task` | Block until
|
|
61
|
-
| `respond-task` | Answer
|
|
62
|
-
| `message-task` | Send
|
|
45
|
+
| `spawn-task` | Create and start a task. Returns `task_id`, `disk_paths`, and "what to do next" guidance. |
|
|
46
|
+
| `wait-task` | Block until completion/failure/input. Returns output, liveness signals, and next actions. |
|
|
47
|
+
| `respond-task` | Answer agent questions (`user_input` only — approvals are auto-handled). |
|
|
48
|
+
| `message-task` | Send follow-up instructions to a running task. |
|
|
63
49
|
| `cancel-task` | Cancel one or more tasks (single or batch). |
|
|
64
50
|
|
|
51
|
+
### Model selection
|
|
52
|
+
|
|
53
|
+
Only `gpt-5.4` — pass the `reasoning` parameter:
|
|
54
|
+
|
|
55
|
+
| Value | Use case |
|
|
56
|
+
|---|---|
|
|
57
|
+
| `gpt-5.4(medium)` | Default. Most coding, refactors, debugging. |
|
|
58
|
+
| `gpt-5.4(high)` | Multi-file reasoning, subtle bugs, design decisions. |
|
|
59
|
+
| `gpt-5.4(xhigh)` | Deep research, novel architecture. |
|
|
60
|
+
| `gpt-5.4(low)` | Trivial mechanical edits. |
|
|
61
|
+
|
|
65
62
|
### Typical workflow
|
|
66
63
|
|
|
67
64
|
```
|
|
68
|
-
spawn-task
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
65
|
+
spawn-task { prompt: "..." }
|
|
66
|
+
→ { task_id: "bold-eagle-456", status: "working", disk_paths: {...} }
|
|
67
|
+
---
|
|
68
|
+
**What to do next:**
|
|
69
|
+
- Call `wait-task` with task_id to block until done.
|
|
70
|
+
- If you have more tasks, launch them now — all run in parallel.
|
|
71
|
+
|
|
72
|
+
wait-task { task_id: "bold-eagle-456" }
|
|
73
|
+
→ { status: "completed", output: [...] }
|
|
74
|
+
---
|
|
75
|
+
**What to do next:**
|
|
76
|
+
- Read `task:///bold-eagle-456` for the full result.
|
|
72
77
|
```
|
|
73
78
|
|
|
74
|
-
|
|
79
|
+
No `respond-task` needed for command/file approvals — they're auto-approved instantly.
|
|
75
80
|
|
|
76
|
-
|
|
81
|
+
## Auto-Approval
|
|
77
82
|
|
|
78
|
-
|
|
79
|
-
|---|---|---|---|
|
|
80
|
-
| `prompt` | string | yes | What the task should do. Be specific — include file paths, function names. |
|
|
81
|
-
| `cwd` | string | no | Working directory. Agent sees files here. |
|
|
82
|
-
| `task_type` | enum | no | `coder` (default), `planner`, `tester`, `researcher`, `general` |
|
|
83
|
-
| `model` | string | no | Override provider default model. |
|
|
84
|
-
| `timeout_ms` | integer | no | Max execution time (1,000–3,600,000 ms). |
|
|
85
|
-
| `developer_instructions` | string | no | System-level constraints injected before the prompt. |
|
|
86
|
-
| `labels` | string[] | no | Arbitrary labels for filtering. |
|
|
87
|
-
| `depends_on` | string[] | no | Task IDs that must complete first. |
|
|
88
|
-
| `context_files` | array | no | Files to include: `[{ path, description? }]` |
|
|
83
|
+
The server auto-approves ALL Codex approval requests without waiting:
|
|
89
84
|
|
|
90
|
-
|
|
85
|
+
| Request | Response | Log |
|
|
86
|
+
|---|---|---|
|
|
87
|
+
| Command approval | `accept` | `[auto-approve] cmd: npm test` |
|
|
88
|
+
| File change | `accept` | `[auto-approve] file change` |
|
|
89
|
+
| MCP elicitation | `accept` | `[auto-approve] elicitation` |
|
|
90
|
+
| Permission request | `grant all for session` | `[auto-approve] permissions` |
|
|
91
91
|
|
|
92
|
-
|
|
92
|
+
Only `user_input` (agent asks a question) and `dynamic_tool` (external tool needs data) still pause the task.
|
|
93
93
|
|
|
94
|
-
|
|
94
|
+
Combined with `approval_policy = "never"` and `sandbox_mode = "danger-full-access"` from your `config.toml`, agents run fully autonomously.
|
|
95
95
|
|
|
96
|
-
|
|
97
|
-
|---|---|---|---|
|
|
98
|
-
| `task_id` | string | yes | — |
|
|
99
|
-
| `timeout_ms` | integer | no | 30,000 |
|
|
100
|
-
| `poll_interval_ms` | integer | no | 1,000 |
|
|
96
|
+
## Reporting & Observability
|
|
101
97
|
|
|
102
|
-
|
|
98
|
+
Every task persists to `~/.mcp-codex-worker/tasks/<task-id>/`:
|
|
103
99
|
|
|
104
|
-
|
|
100
|
+
| File | Content |
|
|
101
|
+
|---|---|
|
|
102
|
+
| `meta.json` | Task state snapshot (refreshes every 10s during activity) |
|
|
103
|
+
| `summary.log` | Formatted one-liners: `[HH:MM:SS] cmd: npm test (exit 0, 1.2s)` |
|
|
104
|
+
| `verbose.log` | Full execution trace, streaming command output |
|
|
105
|
+
| `events.jsonl` | Raw Codex notification stream — every event with timestamp |
|
|
105
106
|
|
|
106
|
-
|
|
107
|
+
### MCP Resources
|
|
107
108
|
|
|
108
|
-
|
|
|
109
|
-
|
|
110
|
-
| `
|
|
111
|
-
| `
|
|
112
|
-
| `
|
|
113
|
-
| `
|
|
114
|
-
| `
|
|
109
|
+
| URI | Content |
|
|
110
|
+
|---|---|
|
|
111
|
+
| `task:///all` | Scoreboard (auto-subscribed, push on change) |
|
|
112
|
+
| `task:///{id}` | Task detail with metadata |
|
|
113
|
+
| `task:///{id}/log` | Summary log |
|
|
114
|
+
| `task:///{id}/log.verbose` | Verbose log (reads from disk) |
|
|
115
|
+
| `task:///{id}/events` | Raw event trace (JSONL from disk) |
|
|
115
116
|
|
|
116
|
-
###
|
|
117
|
+
### Resource Subscriptions
|
|
117
118
|
|
|
118
|
-
|
|
119
|
+
```json
|
|
120
|
+
{ "resources": { "subscribe": true, "listChanged": true } }
|
|
121
|
+
```
|
|
119
122
|
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
| `message` | string | yes |
|
|
124
|
-
| `model` | string | no |
|
|
123
|
+
- `task:///all` auto-subscribed at startup
|
|
124
|
+
- `notifications/resources/updated` on status changes (immediate) and output (throttled 1s)
|
|
125
|
+
- `notifications/resources/list_changed` on task creation
|
|
125
126
|
|
|
126
|
-
|
|
127
|
+
## Codex App-Server Integration
|
|
127
128
|
|
|
128
|
-
|
|
129
|
+
This server acts as a client to the [Codex app-server](https://github.com/openai/codex/blob/main/codex-rs/app-server/README.md) protocol. Key integration points:
|
|
129
130
|
|
|
130
|
-
|
|
|
131
|
-
|
|
132
|
-
| `
|
|
131
|
+
| Feature | How we use it |
|
|
132
|
+
|---|---|
|
|
133
|
+
| `initialize` | `experimentalApi: true`, then `account/login/start` with API key |
|
|
134
|
+
| `thread/start` | Omit `approvalPolicy`/`sandbox` — config.toml takes effect |
|
|
135
|
+
| `turn/start` | Pass `effort` for reasoning level |
|
|
136
|
+
| Approval requests | Auto-respond via `respondToServerRequest()` |
|
|
137
|
+
| `turn/completed` | Captures turn status in summary log |
|
|
138
|
+
| `item/*` notifications | Event capture module processes 6 types into logs |
|
|
139
|
+
| `error` notification | Captures `codexErrorInfo` classification |
|
|
140
|
+
| stderr | Piped to verbose.log and events.jsonl for diagnostics |
|
|
141
|
+
| Process exit | Detects exit code/signal, classifies auth errors |
|
|
133
142
|
|
|
134
|
-
|
|
143
|
+
### Auth
|
|
135
144
|
|
|
136
|
-
|
|
145
|
+
On startup, sends `account/login/start` with `CODEX_LB_API_KEY` (or `OPENAI_API_KEY`) to switch from stale OAuth tokens to API key auth. This prevents the "refresh token already used" crash.
|
|
137
146
|
|
|
138
|
-
|
|
139
|
-
|---|---|
|
|
140
|
-
| `task:///all` | Scoreboard — all tasks with status badges and elapsed time |
|
|
141
|
-
| `task:///{id}` | Detail — metadata, provider session, timestamps, error |
|
|
142
|
-
| `task:///{id}/log` | Summary log — last 20 output lines |
|
|
143
|
-
| `task:///{id}/log.verbose` | Verbose log — full output history |
|
|
147
|
+
### Crash Recovery
|
|
144
148
|
|
|
145
|
-
|
|
149
|
+
On restart, loads all `meta.json` files from disk. Terminal tasks restore as-is. Non-terminal tasks (RUNNING, WAITING_ANSWER) are marked UNKNOWN since Codex sessions don't survive restarts.
|
|
146
150
|
|
|
147
|
-
|
|
151
|
+
## Wire States (SEP-1686)
|
|
148
152
|
|
|
149
153
|
| State | Meaning |
|
|
150
154
|
|---|---|
|
|
151
155
|
| `submitted` | Queued, not started |
|
|
152
|
-
| `working` | Agent
|
|
153
|
-
| `input_required` | Paused
|
|
156
|
+
| `working` | Agent executing |
|
|
157
|
+
| `input_required` | Paused — needs `user_input` or `dynamic_tool` response |
|
|
154
158
|
| `completed` | Done |
|
|
155
|
-
| `failed` | Error |
|
|
156
|
-
| `cancelled` | Interrupted |
|
|
159
|
+
| `failed` | Error (includes AUTH_TOKEN_EXPIRED, RATE_LIMITED classifications) |
|
|
160
|
+
| `cancelled` | Interrupted by user |
|
|
157
161
|
| `unknown` | Crash recovery fallback |
|
|
158
162
|
|
|
159
|
-
##
|
|
160
|
-
|
|
161
|
-
Spawn multiple tasks simultaneously. Each runs in an independent agent workspace.
|
|
162
|
-
|
|
163
|
-
```
|
|
164
|
-
spawn-task(prompt: "implement auth module", cwd: "/project") → task_a
|
|
165
|
-
spawn-task(prompt: "implement billing module", cwd: "/project") → task_b
|
|
166
|
-
spawn-task(prompt: "write e2e tests", cwd: "/project") → task_c
|
|
167
|
-
|
|
168
|
-
# Monitor via scoreboard
|
|
169
|
-
read resource: task:///all
|
|
170
|
-
→ tasks -- 3 total (1 done, 2 busy)
|
|
171
|
-
|
|
172
|
-
# Wait for each
|
|
173
|
-
wait-task(task_a) → completed
|
|
174
|
-
wait-task(task_b) → completed
|
|
175
|
-
wait-task(task_c) → completed
|
|
176
|
-
```
|
|
177
|
-
|
|
178
|
-
## Environment variables
|
|
163
|
+
## Environment Variables
|
|
179
164
|
|
|
180
165
|
| Variable | Description | Default |
|
|
181
166
|
|---|---|---|
|
|
167
|
+
| `CODEX_LB_API_KEY` | API key for codex-lb provider | — |
|
|
168
|
+
| `OPENAI_API_KEY` | Fallback API key | — |
|
|
182
169
|
| `CODEX_APP_SERVER_COMMAND` | Codex binary path | `codex` |
|
|
183
170
|
| `CODEX_APP_SERVER_ARGS` | App-server arguments | `app-server --listen stdio://` |
|
|
184
171
|
| `CODEX_HOME_DIRS` | Colon-separated profile roots for failover | `~/.codex` |
|
|
185
172
|
| `CODEX_ENABLE_FLEET` | Enable fleet mode (sub-agent instructions) | off |
|
|
186
173
|
|
|
187
|
-
##
|
|
174
|
+
## Development
|
|
188
175
|
|
|
189
176
|
```bash
|
|
190
177
|
npm install
|
|
191
|
-
npm run build
|
|
192
|
-
npm
|
|
193
|
-
npm run smoke #
|
|
178
|
+
npm run build # TypeScript compile
|
|
179
|
+
npm test # 158 unit tests
|
|
180
|
+
npm run smoke # live Codex test (needs CODEX_LB_API_KEY)
|
|
181
|
+
npm run serve # start locally
|
|
194
182
|
```
|
|
195
183
|
|
|
196
|
-
###
|
|
184
|
+
### Testing with mcpc
|
|
197
185
|
|
|
198
186
|
```bash
|
|
199
|
-
|
|
187
|
+
mcpc --config config.json cw connect @test
|
|
188
|
+
mcpc @test tools-list
|
|
189
|
+
mcpc @test resources-read "task:///all"
|
|
190
|
+
mcpc @test tools-call spawn-task '{"prompt":"echo hello","reasoning":"gpt-5.4(low)"}'
|
|
200
191
|
```
|
|
201
192
|
|
|
202
|
-
|
|
193
|
+
Use the local build (`node --import tsx src/index.ts`) for mcpc — `npx` has bridge startup timing issues.
|