@leo000001/codex-mcp 2.1.1 → 2.1.4
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 +61 -31
- package/dist/index.js +707 -36
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
[](https://github.com/xihuai18/codex-mcp/blob/master/LICENSE)
|
|
5
5
|
[](https://nodejs.org)
|
|
6
6
|
|
|
7
|
-
MCP server that wraps [OpenAI Codex](https://github.com/openai/codex)
|
|
7
|
+
MCP server that wraps [OpenAI Codex](https://github.com/openai/codex) — start coding agents, poll their progress, and manage permissions from any MCP client. Supports both `app-server` (full capability) and `exec` (fallback for codex variants without app-server) modes.
|
|
8
8
|
|
|
9
9
|
## Features
|
|
10
10
|
|
|
@@ -78,26 +78,32 @@ Or add to `~/.claude/settings.json`:
|
|
|
78
78
|
|
|
79
79
|
## Codex Executable Configuration
|
|
80
80
|
|
|
81
|
-
By default, codex-mcp auto-detects the Codex CLI by searching PATH for `codex`, then `codex-internal`. You can override this with environment variables
|
|
81
|
+
By default, codex-mcp auto-detects the Codex CLI by searching PATH for `codex`, then `codex-internal`. You can override this with environment variables.
|
|
82
82
|
|
|
83
|
-
|
|
84
|
-
| --- | --- | --- |
|
|
85
|
-
| `CODEX_MCP_DEFAULT_CODEX_COMMAND` | Bare command name (resolved from PATH) | `codex-internal` |
|
|
86
|
-
| `CODEX_MCP_DEFAULT_CODEX_PATH` | Absolute or relative filesystem path to the executable | `/usr/local/bin/codex-internal` |
|
|
83
|
+
Resolution priority:
|
|
87
84
|
|
|
88
|
-
-
|
|
89
|
-
-
|
|
85
|
+
- `CODEX_MCP_PATH`
|
|
86
|
+
- `CODEX_MCP_COMMAND`
|
|
87
|
+
- auto-detect from PATH: `codex`, then `codex-internal`
|
|
88
|
+
|
|
89
|
+
| Variable | Description | Example |
|
|
90
|
+
| ------------------- | ------------------------------------------------------ | ------------------------------- |
|
|
91
|
+
| `CODEX_MCP_COMMAND` | Bare command name (resolved from PATH) | `codex-internal` |
|
|
92
|
+
| `CODEX_MCP_PATH` | Absolute or relative filesystem path to the executable | `/usr/local/bin/codex-internal` |
|
|
93
|
+
|
|
94
|
+
- `CODEX_MCP_PATH` and `CODEX_MCP_COMMAND` are mutually exclusive.
|
|
95
|
+
- When none are set, codex-mcp tries `codex` then `codex-internal` on PATH automatically.
|
|
90
96
|
|
|
91
97
|
Examples:
|
|
92
98
|
|
|
93
99
|
```bash
|
|
94
100
|
# Use codex-internal instead of codex
|
|
95
|
-
|
|
101
|
+
CODEX_MCP_COMMAND=codex-internal npx -y @leo000001/codex-mcp
|
|
96
102
|
```
|
|
97
103
|
|
|
98
104
|
```bash
|
|
99
105
|
# Use an explicit path
|
|
100
|
-
|
|
106
|
+
CODEX_MCP_PATH=/opt/codex/bin/codex npx -y @leo000001/codex-mcp
|
|
101
107
|
```
|
|
102
108
|
|
|
103
109
|
MCP client config with env override:
|
|
@@ -109,7 +115,7 @@ MCP client config with env override:
|
|
|
109
115
|
"command": "npx",
|
|
110
116
|
"args": ["-y", "@leo000001/codex-mcp"],
|
|
111
117
|
"env": {
|
|
112
|
-
"
|
|
118
|
+
"CODEX_MCP_COMMAND": "codex-internal"
|
|
113
119
|
}
|
|
114
120
|
}
|
|
115
121
|
}
|
|
@@ -124,6 +130,27 @@ MCP client config with env override:
|
|
|
124
130
|
- `CODEX_MCP_STDIO_MODE=strict`: fail fast on blocking risks (e.g. TTY stdio), keep heuristic risks as warnings
|
|
125
131
|
- `CODEX_MCP_STDIO_MODE=off`: disable the preflight guard
|
|
126
132
|
|
|
133
|
+
## Exec Fallback Mode
|
|
134
|
+
|
|
135
|
+
When the codex binary does not support `app-server` (e.g. internal variants like `codex-internal`), codex-mcp automatically falls back to `codex exec --json` mode.
|
|
136
|
+
|
|
137
|
+
| Env Var | Default | Description |
|
|
138
|
+
| ------------------- | ----------- | -------------------------------------------------------------------------------------- |
|
|
139
|
+
| `CODEX_MCP_COMMAND` | `codex` | Command name used to select the Codex executable; lower priority than `CODEX_MCP_PATH` |
|
|
140
|
+
| `CODEX_MCP_MODE` | auto-detect | Force `app-server` or `exec` mode (skip detection) |
|
|
141
|
+
|
|
142
|
+
If you need an explicit path-based override, use `CODEX_MCP_PATH` from the executable configuration section above.
|
|
143
|
+
|
|
144
|
+
**Exec mode supports multi-turn context** via `codex exec resume`. First turn uses `codex exec`, subsequent turns use `codex exec resume <threadId>`.
|
|
145
|
+
|
|
146
|
+
**Exec mode limitations:**
|
|
147
|
+
|
|
148
|
+
- No approval/user-input interactions
|
|
149
|
+
- `threadFork`/`threadResume` throw `EXEC_NOT_SUPPORTED`
|
|
150
|
+
- `sandbox`/`profile`/`cwd`/`outputSchema` overrides only apply on the first turn (exec resume does not support these flags)
|
|
151
|
+
|
|
152
|
+
Check `codex-mcp:///server-info` `clientMode` field to detect which mode is active.
|
|
153
|
+
|
|
127
154
|
Examples:
|
|
128
155
|
|
|
129
156
|
```bash
|
|
@@ -222,13 +249,14 @@ Send a follow-up message to an existing session.
|
|
|
222
249
|
|
|
223
250
|
List, inspect, cancel, interrupt, fork sessions, or clean background terminals.
|
|
224
251
|
|
|
225
|
-
| Parameter | Type | Required
|
|
226
|
-
| ------------------ | ------- |
|
|
227
|
-
| `action` | string | Yes
|
|
228
|
-
| `sessionId` | string | For get/cancel/interrupt/fork/clean_background_terminals | Target session ID
|
|
229
|
-
| `includeSensitive` | boolean | No
|
|
252
|
+
| Parameter | Type | Required | Description |
|
|
253
|
+
| ------------------ | ------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
|
254
|
+
| `action` | string | Yes | `"list"`, `"get"`, `"cancel"`, `"interrupt"`, `"fork"`, or `"clean_background_terminals"` |
|
|
255
|
+
| `sessionId` | string | For get/cancel/interrupt/fork/clean_background_terminals | Target session ID |
|
|
256
|
+
| `includeSensitive` | boolean | No | Include `cwd`/`profile`/`config`/`threadId` in `get`. Default: `false` |
|
|
230
257
|
|
|
231
258
|
**Returns:**
|
|
259
|
+
|
|
232
260
|
- `action="list"` → `{ sessions: PublicSessionInfo[] }`
|
|
233
261
|
- `action="get"` → `PublicSessionInfo` (or `SensitiveSessionInfo` when `includeSensitive=true`)
|
|
234
262
|
- `action="cancel"|"interrupt"` → `{ success: true, message }`
|
|
@@ -248,21 +276,21 @@ List, inspect, cancel, interrupt, fork sessions, or clean background terminals.
|
|
|
248
276
|
|
|
249
277
|
Query a running session for events, respond to approval requests, or answer user input.
|
|
250
278
|
|
|
251
|
-
| Parameter
|
|
252
|
-
|
|
|
253
|
-
| `action`
|
|
254
|
-
| `sessionId`
|
|
255
|
-
| `cursor`
|
|
256
|
-
| `maxEvents`
|
|
257
|
-
| `responseMode`
|
|
258
|
-
| `pollOptions`
|
|
259
|
-
| `requestId`
|
|
260
|
-
| `decision`
|
|
279
|
+
| Parameter | Type | Required | Description |
|
|
280
|
+
| ---------------------- | -------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
281
|
+
| `action` | string | Yes | `"poll"`, `"respond_permission"`, or `"respond_user_input"` |
|
|
282
|
+
| `sessionId` | string | Yes | Target session ID |
|
|
283
|
+
| `cursor` | number | No | Event cursor for incremental polling (`action="poll"`). For `respond_*`, codex-mcp applies monotonic cursor progression: `max(cursor, sessionLastCursor)`. |
|
|
284
|
+
| `maxEvents` | number | No | Keep this small. `poll` default: `1` (minimum `1`; increase only for catch-up). `respond_*` default: `0` (recommended; compact ACK, no event replay). |
|
|
285
|
+
| `responseMode` | string | No | Response shaping mode: `minimal` (default), `delta_compact`, `full` |
|
|
286
|
+
| `pollOptions` | object | No | Optional controls: `includeEvents` (default `true`), `includeActions` (default `true`), `includeResult` (default `true`), `maxBytes` (default unlimited) |
|
|
287
|
+
| `requestId` | string | For respond_permission/user_input | Request ID from `actions[]` |
|
|
288
|
+
| `decision` | string | For respond_permission | For command approvals: `"accept"`, `"acceptForSession"`, `"acceptWithExecpolicyAmendment"`, `"decline"`, `"cancel"`; for file changes: `"accept"`, `"acceptForSession"`, `"decline"`, `"cancel"` |
|
|
261
289
|
| `execpolicy_amendment` | string[] | For acceptWithExecpolicyAmendment | Exec policy amendment list (required when `decision="acceptWithExecpolicyAmendment"`) |
|
|
262
|
-
| `denyMessage`
|
|
263
|
-
| `answers`
|
|
290
|
+
| `denyMessage` | string | No | Internal note on deny (not sent to app-server) |
|
|
291
|
+
| `answers` | object | For respond_user_input | For `respond_user_input`: `question-id -> { answers: string[] }` |
|
|
264
292
|
|
|
265
|
-
**Returns (poll and
|
|
293
|
+
**Returns (poll and respond\_\*):** `{ sessionId, status, pollInterval?, cursorResetTo?, events, nextCursor, actions?, result? }`
|
|
266
294
|
|
|
267
295
|
```json
|
|
268
296
|
{ "action": "poll", "sessionId": "sess_abc123", "cursor": 0 }
|
|
@@ -369,11 +397,12 @@ Three layers of protection:
|
|
|
369
397
|
> **Same-platform assumption**: codex-mcp assumes the MCP client and server run on the same machine. All communication uses stdio (local IPC), child processes share the local filesystem and `~/.codex/config.toml`, and `cwd` paths refer to the local filesystem.
|
|
370
398
|
|
|
371
399
|
```
|
|
372
|
-
MCP Client ←stdio→ codex-mcp server ←stdio→ codex app-server ←→ Codex Agent
|
|
400
|
+
MCP Client ←stdio→ codex-mcp server ←stdio→ codex app-server ←→ Codex Agent (app-server mode)
|
|
401
|
+
MCP Client ←stdio→ codex-mcp server ←stdio→ codex exec --json ←→ Codex Agent (exec fallback)
|
|
373
402
|
(same machine, stdio transport)
|
|
374
403
|
```
|
|
375
404
|
|
|
376
|
-
Each session spawns an independent
|
|
405
|
+
Each session spawns an independent child process. In app-server mode, it uses the JSON-RPC protocol over stdio. In exec fallback mode, it uses `codex exec --json` JSONL output with `codex exec resume` for multi-turn context.
|
|
377
406
|
|
|
378
407
|
## Development
|
|
379
408
|
|
|
@@ -389,6 +418,7 @@ npm run check:stdio:strict
|
|
|
389
418
|
```
|
|
390
419
|
|
|
391
420
|
End-to-end local test plan (after installing/configuring in an MCP client):
|
|
421
|
+
|
|
392
422
|
- Full guide (LLM operator handbook): `docs/E2E_LOCAL_TEST_PLAN.md`
|
|
393
423
|
- Quick English checklist: run `codex` → poll with `codex_check(action="poll")` → respond via `respond_permission`/`respond_user_input` if `actions[]` appears → continue polling until `status` is `idle`/`error`/`cancelled`.
|
|
394
424
|
|