omp-worker-mcp 0.1.1 → 0.2.0
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 +344 -88
- package/README.zh-CN.md +342 -88
- package/bin/omp-worker-mcp.mjs +2 -10
- package/dist/index.js +2 -1
- package/dist/index.js.map +1 -1
- package/dist/runner.js +43 -13
- package/dist/runner.js.map +1 -1
- package/dist/security.js +66 -0
- package/dist/security.js.map +1 -0
- package/dist/version.js +19 -0
- package/dist/version.js.map +1 -0
- package/package.json +8 -3
- package/server.json +10 -14
package/README.md
CHANGED
|
@@ -2,99 +2,149 @@
|
|
|
2
2
|
|
|
3
3
|
# omp-worker-mcp
|
|
4
4
|
|
|
5
|
-
**
|
|
5
|
+
**Let your main AI agent plan and review — and hand the hands-on coding to local [Oh My Pi](https://github.com/can1357/oh-my-pi) workers.**
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
<a href="README.zh-CN.md">简体中文</a> •
|
|
10
|
-
<a href="docs/README.md">Documentation Hub</a>
|
|
11
|
-
</p>
|
|
7
|
+
An MCP server that turns ChatGPT, Codex, Claude Code, Cursor and other MCP clients into a *supervisor*,<br />
|
|
8
|
+
and Oh My Pi (OMP) on your own machine into its background *workforce*.
|
|
12
9
|
|
|
13
|
-
[](LICENSE)
|
|
14
10
|
[](https://www.npmjs.com/package/omp-worker-mcp)
|
|
15
|
-
[](package.json)
|
|
16
11
|
[](https://github.com/divenire990/omp-worker-mcp/actions/workflows/ci.yml)
|
|
17
|
-
[](package.json)
|
|
13
|
+
[](server.json)
|
|
14
|
+
[](LICENSE)
|
|
19
15
|
|
|
20
|
-
|
|
16
|
+
English · [简体中文](README.zh-CN.md) · [Documentation](docs/README.md)
|
|
21
17
|
|
|
22
|
-
<
|
|
18
|
+
<br />
|
|
23
19
|
|
|
24
|
-
<
|
|
25
|
-
<em>Asynchronous task execution, DAG dependency resolution, path ownership isolation, and structured result verification.</em>
|
|
26
|
-
</p>
|
|
20
|
+
<img src="assets/how-it-works.svg" alt="The supervisor agent delegates tasks to omp-worker-mcp, which runs OMP workers in the background and returns structured results for review" width="860" />
|
|
27
21
|
|
|
28
|
-
[Quick
|
|
22
|
+
[Quick start](#quick-start) · [Usage](#usage) · [Tools](#tools) · [Configuration](#configuration) · [Safety model](#safety-model) · [FAQ](#faq)
|
|
29
23
|
|
|
30
24
|
</div>
|
|
31
25
|
|
|
32
26
|
---
|
|
33
27
|
|
|
34
|
-
##
|
|
28
|
+
## What it does
|
|
35
29
|
|
|
36
|
-
|
|
37
|
-
- 🔀 **Topological DAG Orchestration**: Execute interdependent batch tasks with automatic dependency validation, concurrency pool limiting, and failure containment.
|
|
38
|
-
- 🛡️ **Workspace Path Isolation**: Enforce explicit write-path boundaries to prevent overlapping modifications between parallel tasks.
|
|
39
|
-
- 🔍 **Supervised Resumption & Envelopes**: Inspect interim execution logs in real time, extract structured result envelopes (`OMP_WORKER_RESULT`), and inject supervisory feedback via `omp_continue`.
|
|
40
|
-
- 💾 **Persistent State & Configurable Retention**: File-backed state persistence for job metadata and logs with optional TTL and storage capacity bounds.
|
|
30
|
+
Most coding agents do everything in one place: read the code, plan, edit, run tests, fix — all inside one conversation and one model's budget. `omp-worker-mcp` splits that work into two roles:
|
|
41
31
|
|
|
32
|
+
| Role | Who | Responsibility |
|
|
33
|
+
| :--- | :--- | :--- |
|
|
34
|
+
| **Supervisor** | The agent you talk to: ChatGPT, Codex, Claude Code, Cursor… | Understands the request, splits the work, writes acceptance criteria, reviews the results |
|
|
35
|
+
| **Worker** | The OMP CLI on your machine, using the model you picked in `omp setup` | Reads files, edits code, runs shell commands and tests, reports back |
|
|
42
36
|
|
|
43
|
-
|
|
37
|
+
`omp-worker-mcp` is the bridge between them. It gives the supervisor a small set of MCP tools, starts OMP in the background, keeps every job on disk, and returns a short structured report instead of a wall of logs.
|
|
44
38
|
|
|
45
|
-
|
|
39
|
+
**Highlights**
|
|
46
40
|
|
|
47
|
-
|
|
41
|
+
- **One task or a whole plan** — `omp_run_compact` delegates a single task; `omp_run_batch_compact` runs up to 50 tasks as a dependency graph (DAG), up to 10 at a time.
|
|
42
|
+
- **Declared write-scope validation** — parallel write tasks in a batch must declare the paths they own; overlapping declared scopes and dependency cycles are rejected before any worker starts (a scheduling check and prompt constraint, not an OS filesystem lock).
|
|
43
|
+
- **Results you can review** — every worker finishes with an `OMP_WORKER_RESULT` envelope: status, summary, changed files, verification evidence and remaining items.
|
|
44
|
+
- **Correct instead of restart** — `omp_continue` sends feedback to the *same* OMP session, so the worker keeps its context.
|
|
45
|
+
- **Persistent jobs** — job records, logs and results live on disk and can still be read after the MCP server restarts.
|
|
46
|
+
- **Works from ChatGPT on the web** — through OpenAI's Secure MCP Tunnel: no inbound port, plus an allowlist (`OMP_WORKER_ALLOWED_ROOTS`, available since `0.2.0`; npm `0.1.1` lacks this feature) for the directories jobs may run in.
|
|
48
47
|
|
|
49
|
-
|
|
50
|
-
|
|
48
|
+
## When to use it
|
|
49
|
+
|
|
50
|
+
**A good fit when**
|
|
51
51
|
|
|
52
|
-
|
|
52
|
+
- you want a strong model to make the decisions while a faster or cheaper model does the typing;
|
|
53
|
+
- the task is big enough to hand off: a feature, a bug fix with tests, a multi-module refactor, a long read-only investigation;
|
|
54
|
+
- you want several parts of a repo worked on in parallel without agents overwriting each other;
|
|
55
|
+
- you think with ChatGPT and want it to act on files on your own machine.
|
|
53
56
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
-
|
|
57
|
-
|
|
58
|
-
- **Linux** (`x86_64`, `aarch64`): Architectural design target; awaiting broader production verification.
|
|
59
|
-
- **Support Tiers**:
|
|
60
|
-
- **Author-Verified**: Codex (author's daily local workflow; not a cross-platform CI guarantee).
|
|
61
|
-
- **Documented / Reproducible**: Claude Code, WorkBuddy, Claude Desktop, Cursor, Cline, VS Code, Copilot CLI (*not CI integration-tested*).
|
|
62
|
-
- **Cloud / Remote Hosts**: Conditional (*requires complete runtime, OMP CLI in PATH, writable workspace, and process spawning permissions*).
|
|
57
|
+
**Probably not worth it when**
|
|
58
|
+
|
|
59
|
+
- the change is one line or the question is quick — the supervisor's own tools are faster;
|
|
60
|
+
- you need a real OS-level sandbox. This project controls *where* jobs start and *what* they are told to touch, not what OMP is technically able to do (see [Safety model](#safety-model)).
|
|
63
61
|
|
|
64
62
|
---
|
|
65
63
|
|
|
66
|
-
##
|
|
64
|
+
## Quick start
|
|
65
|
+
|
|
66
|
+
**You need:** Node.js ≥ 22 · [Oh My Pi](https://github.com/can1357/oh-my-pi) installed · an MCP client (Codex, Claude Code, Cursor, ChatGPT, …).
|
|
67
67
|
|
|
68
|
-
|
|
68
|
+
### 1. Install and set up OMP
|
|
69
69
|
|
|
70
|
-
|
|
70
|
+
Install OMP by following [its official instructions](https://github.com/can1357/oh-my-pi), then:
|
|
71
71
|
|
|
72
72
|
```bash
|
|
73
|
-
#
|
|
74
|
-
|
|
73
|
+
omp --version # confirm the CLI is on your PATH
|
|
74
|
+
omp setup # sign in and choose the default model
|
|
75
75
|
```
|
|
76
|
-
|
|
76
|
+
|
|
77
|
+
The default model you pick here is the model every worker will use. (Advanced: set `modelRoles.default: <provider>/<model>` in `~/.omp/agent/config.yml`.)
|
|
78
|
+
|
|
79
|
+
> If `omp` is not on your `PATH`, set `OMP_WORKER_OMP_COMMAND` to the full path of the executable in the MCP config below.
|
|
80
|
+
|
|
81
|
+
### 2. Register the MCP server in your client
|
|
82
|
+
|
|
83
|
+
There is nothing to install globally — the client runs the published package with `npx -y omp-worker-mcp`. Pick your client:
|
|
84
|
+
|
|
85
|
+
<details open>
|
|
86
|
+
<summary><b>Codex</b> — the author's daily setup</summary>
|
|
87
|
+
|
|
88
|
+
Edit `~/.codex/config.toml` (Windows: `C:\Users\<you>\.codex\config.toml`):
|
|
89
|
+
|
|
90
|
+
```toml
|
|
91
|
+
[mcp_servers.omp-worker]
|
|
92
|
+
command = "npx"
|
|
93
|
+
args = ["-y", "omp-worker-mcp"]
|
|
94
|
+
|
|
95
|
+
[mcp_servers.omp-worker.env]
|
|
96
|
+
OMP_WORKER_OMP_COMMAND = "omp"
|
|
97
|
+
|
|
98
|
+
# Optional (Codex Code Mode only): let Codex call omp-worker tools directly
|
|
99
|
+
# without code-mode wrapping. Per the current Codex config reference, merge into
|
|
100
|
+
# your existing [features.code_mode] table (do not create a duplicate table header)
|
|
101
|
+
# and append "mcp__omp_worker" while preserving any other list entries:
|
|
102
|
+
[features.code_mode]
|
|
103
|
+
direct_only_tool_namespaces = ["mcp__omp_worker"]
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
*(If `[features.code_mode]` already exists in your `config.toml`, merge into that table and append `"mcp__omp_worker"` to `direct_only_tool_namespaces` rather than duplicating the table or overwriting existing entries. Legacy Codex builds used a top-level `direct_only_tool_namespaces = ["mcp__omp_worker"]` key before any `[table]` header. Neither setting is required to register the MCP server; see [Codex direct namespace setup](docs/author-workflow.md#codex-direct-namespace-setup) and the [official Codex Config Reference](https://learn.chatgpt.com/docs/config-file/config-reference).)*
|
|
107
|
+
|
|
108
|
+
</details>
|
|
109
|
+
|
|
110
|
+
<details>
|
|
111
|
+
<summary><b>ChatGPT (web)</b> — via Secure MCP Tunnel</summary>
|
|
112
|
+
|
|
113
|
+
> **Version requirement (`>= 0.2.0`):** `OMP_WORKER_ALLOWED_ROOTS` is available since `omp-worker-mcp` `0.2.0` (historical npm `0.1.1` lacks this feature and does not enforce `OMP_WORKER_ALLOWED_ROOTS`). Confirm `npx -y omp-worker-mcp@latest --version` reports `0.2.0` or newer before exposing local execution remotely.
|
|
114
|
+
|
|
115
|
+
Run the server locally behind OpenAI's `tunnel-client`; your machine only makes outbound connections.
|
|
77
116
|
|
|
78
117
|
```bash
|
|
79
|
-
|
|
80
|
-
|
|
118
|
+
export OMP_WORKER_OMP_COMMAND=omp
|
|
119
|
+
export OMP_WORKER_ALLOWED_ROOTS='["/Users/you/Projects"]' # strongly recommended for remote access (available since 0.2.0; 0.1.1 lacks this feature)
|
|
120
|
+
export CONTROL_PLANE_API_KEY='<runtime-api-key>'
|
|
121
|
+
|
|
122
|
+
tunnel-client init \
|
|
123
|
+
--sample sample_mcp_stdio_local \
|
|
124
|
+
--profile omp-worker \
|
|
125
|
+
--tunnel-id <your-tunnel-id> \
|
|
126
|
+
--mcp-command "npx -y omp-worker-mcp"
|
|
127
|
+
|
|
128
|
+
tunnel-client doctor --profile omp-worker --explain
|
|
129
|
+
tunnel-client run --profile omp-worker
|
|
81
130
|
```
|
|
82
131
|
|
|
83
|
-
|
|
132
|
+
Windows PowerShell commands, `0.1.1` upgrade / local-build notes, managed runtime alternatives (`tunnel-client runtimes connect`), permission requirements and the full trust boundary: [ChatGPT Secure MCP Tunnel guide](docs/chatgpt-secure-tunnel.md).
|
|
133
|
+
</details>
|
|
134
|
+
|
|
135
|
+
<details>
|
|
136
|
+
<summary><b>Claude Code</b></summary>
|
|
84
137
|
|
|
85
138
|
```bash
|
|
86
|
-
|
|
87
|
-
cd omp-worker-mcp
|
|
88
|
-
npm ci
|
|
89
|
-
npm run build
|
|
90
|
-
npm test
|
|
139
|
+
claude mcp add omp-worker --scope user --env OMP_WORKER_OMP_COMMAND=omp -- npx -y omp-worker-mcp
|
|
91
140
|
```
|
|
92
141
|
|
|
93
|
-
|
|
142
|
+
Use `--scope project` to register it for the current project only. On Windows `cmd.exe`, if `npx` fails to resolve, use `cmd /c npx`.
|
|
94
143
|
|
|
95
|
-
|
|
144
|
+
</details>
|
|
96
145
|
|
|
97
|
-
|
|
146
|
+
<details>
|
|
147
|
+
<summary><b>Cursor · VS Code / Copilot · Windsurf · Continue · any JSON-config client</b></summary>
|
|
98
148
|
|
|
99
149
|
```json
|
|
100
150
|
{
|
|
@@ -110,65 +160,271 @@ Add `omp-worker-mcp` to your host harness's `mcpServers` configuration using sta
|
|
|
110
160
|
}
|
|
111
161
|
```
|
|
112
162
|
|
|
113
|
-
|
|
163
|
+
File locations and client-specific notes: [Client configurations](docs/client-configurations.md).
|
|
164
|
+
|
|
165
|
+
</details>
|
|
166
|
+
|
|
167
|
+
Restart the client after changing its config.
|
|
168
|
+
|
|
169
|
+
### 3. Tell your agent when to delegate
|
|
170
|
+
|
|
171
|
+
Registering the server makes the tools *available*; it does not make the agent *choose* them. Add a short policy to your project's instruction file — `AGENTS.md` (Codex), `CLAUDE.md` (Claude Code), `.cursorrules` / `.github/copilot-instructions.md` (others) — or to ChatGPT's project instructions:
|
|
172
|
+
|
|
173
|
+
```markdown
|
|
174
|
+
## Delegation policy (omp-worker-mcp)
|
|
175
|
+
- Quick questions, single-file edits, design discussion: do it yourself.
|
|
176
|
+
- Substantive single tasks (feature, bug fix, refactor, long investigation): inspect briefly,
|
|
177
|
+
then delegate with `omp_run_compact`, giving a clear `goal` and `acceptance` criteria.
|
|
178
|
+
- Multi-part work: use `omp_run_batch_compact`. Parallel write tasks need disjoint `ownership`;
|
|
179
|
+
tasks touching the same files must be ordered with `depends_on`.
|
|
180
|
+
- Review every result. If acceptance is not met, use `omp_continue` with specific feedback.
|
|
181
|
+
- Never delegate `git push`, publishing, deployments or secret changes — confirm those with the user.
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
A fuller template: [Author workflow → Policy template](docs/author-workflow.md#policy-template).
|
|
185
|
+
|
|
186
|
+
### 4. Run your first task
|
|
187
|
+
|
|
188
|
+
Start with something read-only:
|
|
189
|
+
|
|
190
|
+
```text
|
|
191
|
+
Use omp-worker-mcp to do a read-only inspection of this workspace: summarize the
|
|
192
|
+
project structure and dependencies. Do not modify any files.
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
**What you should see:** the agent calls `omp_run_compact`, OMP works in the background, and a short summary comes back with no files changed. If the job runs longer than the wait window (60 s by default), the call returns a `job_id` with status `running` and the agent keeps going with `omp_wait` — that is normal.
|
|
114
196
|
|
|
115
197
|
---
|
|
116
198
|
|
|
117
|
-
##
|
|
199
|
+
## Usage
|
|
118
200
|
|
|
119
|
-
|
|
201
|
+
Once the policy is in place you can just describe the outcome you want. The examples below show what the supervisor sends under the hood.
|
|
120
202
|
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
203
|
+
### A single task
|
|
204
|
+
|
|
205
|
+
> *"Add exponential backoff to the HTTP client in `src/net/`, cover it with unit tests, and make sure `npm test` passes."*
|
|
206
|
+
|
|
207
|
+
```jsonc
|
|
208
|
+
// omp_run_compact
|
|
209
|
+
{
|
|
210
|
+
"cwd": "/path/to/repo",
|
|
211
|
+
"goal": "Add exponential backoff (max 5 retries) to src/net/client.ts for 5xx and network errors.",
|
|
212
|
+
"acceptance": [
|
|
213
|
+
"Unit tests cover the retry and give-up paths",
|
|
214
|
+
"npm test passes"
|
|
215
|
+
],
|
|
216
|
+
"timeout_minutes": 30
|
|
217
|
+
}
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
What comes back is compact (abridged example):
|
|
221
|
+
|
|
222
|
+
```jsonc
|
|
223
|
+
{
|
|
224
|
+
"job_id": "job-…",
|
|
225
|
+
"status": "completed",
|
|
226
|
+
"attempt": 1,
|
|
227
|
+
"max_attempts": 3,
|
|
228
|
+
"session_id": "sess-…",
|
|
229
|
+
"summary": "Added retry with exponential backoff to the HTTP client.",
|
|
230
|
+
"artifacts": [
|
|
231
|
+
{ "path": "src/net/client.ts", "description": "retry loop + backoff helper" },
|
|
232
|
+
{ "path": "test/net/client.test.ts", "description": "retry / give-up tests" }
|
|
233
|
+
],
|
|
234
|
+
"verification": ["npm test: all tests passed"],
|
|
235
|
+
"remaining": [],
|
|
236
|
+
"details_path": "…/jobs/job-…/job.json"
|
|
237
|
+
}
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
### Several tasks as a DAG
|
|
129
241
|
|
|
130
|
-
|
|
242
|
+
> *"Add a `/health` endpoint to the API and a status badge to the UI in parallel, then add an integration test that covers both."*
|
|
131
243
|
|
|
132
|
-
|
|
244
|
+
```mermaid
|
|
245
|
+
graph LR
|
|
246
|
+
api["api · write src/api/"] --> tests["tests · write tests/"]
|
|
247
|
+
ui["ui · write src/ui/"] --> tests
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
```jsonc
|
|
251
|
+
// omp_run_batch_compact
|
|
252
|
+
{
|
|
253
|
+
"cwd": "/path/to/repo",
|
|
254
|
+
"max_parallel": 2,
|
|
255
|
+
"tasks": [
|
|
256
|
+
{ "id": "api", "goal": "Add GET /health returning build info.", "access": "write", "ownership": ["src/api/"] },
|
|
257
|
+
{ "id": "ui", "goal": "Show a status badge fed by /health.", "access": "write", "ownership": ["src/ui/"] },
|
|
258
|
+
{ "id": "tests", "goal": "Add an integration test for /health and the badge.",
|
|
259
|
+
"depends_on": ["api", "ui"], "access": "write", "ownership": ["tests/"],
|
|
260
|
+
"acceptance": ["npm test passes"] }
|
|
261
|
+
]
|
|
262
|
+
}
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
Rules worth knowing:
|
|
266
|
+
|
|
267
|
+
- `write` tasks must list the paths they own in `ownership` (relative to `cwd`); `read_only` tasks list none.
|
|
268
|
+
- Two tasks that may run at the same time cannot own overlapping paths — order them with `depends_on` instead.
|
|
269
|
+
- `max_parallel` is 1–10 (default 4); the whole group has a deadline (`group_timeout_minutes`, default 60).
|
|
270
|
+
- If the group is still running when the wait window ends, you get a `group_id`; continue with `omp_wait_group`.
|
|
271
|
+
|
|
272
|
+
### Supervising a job
|
|
273
|
+
|
|
274
|
+
| Situation | Tool |
|
|
133
275
|
| :--- | :--- |
|
|
134
|
-
|
|
|
135
|
-
|
|
|
136
|
-
|
|
|
276
|
+
| Still running | `omp_wait` / `omp_wait_group` |
|
|
277
|
+
| Need logs, attempts or the full final answer | `omp_result` |
|
|
278
|
+
| Result doesn't meet acceptance | `omp_continue` with concrete feedback (counts toward `max_attempts`, default 3) |
|
|
279
|
+
| Wrong direction, stop it | `omp_cancel` / `omp_cancel_group` |
|
|
280
|
+
|
|
281
|
+
---
|
|
282
|
+
|
|
283
|
+
## Tools
|
|
284
|
+
|
|
285
|
+
| Tool | Kind | What it does |
|
|
286
|
+
| :--- | :--- | :--- |
|
|
287
|
+
| `omp_run_compact` | **Recommended** | Start one task and wait up to `wait_seconds` (≤ 60) for a compact result |
|
|
288
|
+
| `omp_run_batch_compact` | **Recommended** | Validate and run a DAG of up to 50 tasks; wait up to `wait_seconds` (≤ 240) |
|
|
289
|
+
| `omp_delegate` | Low-level | Start one task and return a `job_id` immediately |
|
|
290
|
+
| `omp_wait` | Low-level | Wait for a job to finish |
|
|
291
|
+
| `omp_wait_group` | Low-level | Wait for a batch group to finish |
|
|
292
|
+
| `omp_result` | Inspect | Full status, attempts, `attempt-NN.stdout.jsonl` / `attempt-NN.stderr.log` paths, final response |
|
|
293
|
+
| `omp_continue` | Supervise | Send feedback to the same OMP session for another attempt |
|
|
294
|
+
| `omp_cancel` | Control | Stop a job and its process tree |
|
|
295
|
+
| `omp_cancel_group` | Control | Stop every pending and running task in a group |
|
|
137
296
|
|
|
138
|
-
|
|
297
|
+
Full parameters and limits: [Tool reference](docs/tool-reference.md).
|
|
139
298
|
|
|
140
299
|
---
|
|
141
300
|
|
|
142
|
-
##
|
|
301
|
+
## Configuration
|
|
143
302
|
|
|
144
|
-
|
|
145
|
-
2. **DAG Overlap Verification**: Parallel tasks within the same batch cannot declare overlapping write boundaries; tasks sharing paths must declare sequential `depends_on` dependencies.
|
|
146
|
-
3. **Structured Verification Contract**: Subagents deliver deliverables using the structured `OMP_WORKER_RESULT` envelope (status, summary, artifacts, verification checks, remaining items).
|
|
303
|
+
Everything is configured through environment variables, set in the client's MCP config (`env`) or in the shell that launches the server.
|
|
147
304
|
|
|
148
|
-
|
|
305
|
+
| Variable | Default | Purpose |
|
|
306
|
+
| :--- | :--- | :--- |
|
|
307
|
+
| `OMP_WORKER_OMP_COMMAND` | `omp` | OMP executable name or full path |
|
|
308
|
+
| `OMP_WORKER_ALLOWED_ROOTS` | *(unset = no restriction)* | JSON array of absolute directories that jobs must run inside. **Set this for any remote use.** *(Available since `0.2.0`; npm `0.1.1` lacks this feature.)* |
|
|
309
|
+
| `OMP_WORKER_STATE_DIR` | `~/.codex/state/omp-worker` | Where job state, prompts and logs are stored (the default path is used even if you don't use Codex) |
|
|
310
|
+
| `OMP_WORKER_RETENTION_TTL_SECONDS` | *(unset = keep forever)* | Delete finished records older than N seconds |
|
|
311
|
+
| `OMP_WORKER_RETENTION_MAX_BYTES` | *(unset = no limit)* | Delete the oldest finished records once the store exceeds N bytes |
|
|
312
|
+
|
|
313
|
+
All variables, the on-disk layout and restart behaviour: [Operations](docs/operations.md) · [`.env.example`](.env.example).
|
|
149
314
|
|
|
150
315
|
---
|
|
151
316
|
|
|
152
|
-
##
|
|
317
|
+
## Safety model
|
|
318
|
+
|
|
319
|
+
**What `omp-worker-mcp` enforces**
|
|
320
|
+
|
|
321
|
+
- With `OMP_WORKER_ALLOWED_ROOTS` set *(available since `0.2.0`; npm `0.1.1` lacks this feature)*, a job's `cwd` must resolve (via `realpath`) inside an approved root. Sibling-prefix tricks and symlink/junction escapes are rejected before OMP starts; a present-but-invalid value fails closed.
|
|
322
|
+
- In a batch, parallel `write` tasks must have disjoint `ownership`, and the graph must be acyclic — checked before any worker is spawned.
|
|
323
|
+
- Ownership and read-only intent are passed to each worker as explicit constraints.
|
|
324
|
+
|
|
325
|
+
**What it does not do**
|
|
153
326
|
|
|
154
|
-
|
|
327
|
+
- It is **not a sandbox**. OMP and anything it runs have the same permissions as the user account that started the server. Ownership is a scheduling check plus an instruction to the worker, not a filesystem lock.
|
|
328
|
+
- It does not decide what is safe to run. Keep `git push`, publishing, deployments and secret changes with you and the supervisor.
|
|
155
329
|
|
|
156
|
-
|
|
157
|
-
- [**Author Workflow & Architecture**](docs/author-workflow.md): Host-Worker supervision loop, execution strategies, and authoring guidelines.
|
|
158
|
-
- [**Client Configurations**](docs/client-configurations.md): Documented and reproducible configuration guidance for Codex, Claude Code, WorkBuddy, Cursor, VS Code, and more.
|
|
159
|
-
- [**Operations & State Lifecycle**](docs/operations.md): Environment variables, state directory layout, retention policies, and recovery.
|
|
160
|
-
- [**Tool Reference & Safety Contract**](docs/tool-reference.md): Full MCP tool specifications and safety boundaries.
|
|
161
|
-
- [**Benchmark Protocol**](benchmarks/README.md): Reproducible evaluation protocol comparing direct host execution against supervisor-worker delegation.
|
|
330
|
+
For remote access (e.g. ChatGPT via Secure MCP Tunnel), always set `OMP_WORKER_ALLOWED_ROOTS`, and consider a dedicated low-privilege account, a container or a VM. To report a vulnerability, see [SECURITY.md](SECURITY.md).
|
|
162
331
|
|
|
163
332
|
---
|
|
164
333
|
|
|
165
|
-
##
|
|
334
|
+
## Platform support
|
|
335
|
+
|
|
336
|
+
| Platform | Status |
|
|
337
|
+
| :--- | :--- |
|
|
338
|
+
| Windows | ✅ Verified end-to-end with the real OMP CLI and in CI (`windows-latest`) |
|
|
339
|
+
| macOS | 🟡 Full test suite runs in CI (`macos-latest`, with a fake OMP); not yet verified end-to-end with the real OMP CLI |
|
|
340
|
+
| Linux | 🟡 Full test suite runs in CI (`ubuntu-latest`, with a fake OMP); not yet verified end-to-end with the real OMP CLI |
|
|
341
|
+
|
|
342
|
+
| Client | Status |
|
|
343
|
+
| :--- | :--- |
|
|
344
|
+
| Codex | ✅ Used daily by the author |
|
|
345
|
+
| ChatGPT web (Secure MCP Tunnel) | 📄 Documented workflow — see the [guide](docs/chatgpt-secure-tunnel.md) |
|
|
346
|
+
| Claude Code, Cursor, VS Code / Copilot, Windsurf, Continue | 📄 Documented configurations, not integration-tested in CI |
|
|
347
|
+
| Cloud / remote agent hosts | ⚠️ Only if they provide Node.js ≥ 22, OMP on `PATH`, a writable workspace and process spawning |
|
|
348
|
+
|
|
349
|
+
Linux reports and client configs that you have verified are very welcome — see [Contributing](CONTRIBUTING.md).
|
|
350
|
+
|
|
351
|
+
---
|
|
352
|
+
|
|
353
|
+
## FAQ
|
|
354
|
+
|
|
355
|
+
<details>
|
|
356
|
+
<summary><b>The agent ignores the tools and does everything itself.</b></summary>
|
|
166
357
|
|
|
167
|
-
|
|
168
|
-
|
|
358
|
+
Tools being available doesn't mean they get chosen. Add the delegation policy from [step 3](#3-tell-your-agent-when-to-delegate), or name the server explicitly in your prompt ("use omp-worker-mcp to…"). On Codex with Code Mode enabled, you can also optionally configure `features.code_mode.direct_only_tool_namespaces`.
|
|
359
|
+
</details>
|
|
360
|
+
|
|
361
|
+
<details>
|
|
362
|
+
<summary><b>The job fails right away with "command not found" / <code>ENOENT</code>.</b></summary>
|
|
363
|
+
|
|
364
|
+
The MCP server can't find OMP. Set `OMP_WORKER_OMP_COMMAND` to the full path of the executable — GUI clients often start with a shorter `PATH` than your terminal.
|
|
365
|
+
</details>
|
|
366
|
+
|
|
367
|
+
<details>
|
|
368
|
+
<summary><b>I got a <code>job_id</code> with status <code>running</code> instead of a result.</b></summary>
|
|
369
|
+
|
|
370
|
+
Expected for longer tasks: the call only waits up to `wait_seconds`. The job keeps running in the background; call `omp_wait` (or `omp_wait_group`) to keep waiting.
|
|
371
|
+
</details>
|
|
372
|
+
|
|
373
|
+
<details>
|
|
374
|
+
<summary><b>Which model do the workers use?</b></summary>
|
|
375
|
+
|
|
376
|
+
OMP's default model — the one chosen in `omp setup` (or `modelRoles.default` in `~/.omp/agent/config.yml`). The supervisor's model is whatever your client uses. That's the point: they can be different.
|
|
377
|
+
</details>
|
|
378
|
+
|
|
379
|
+
<details>
|
|
380
|
+
<summary><b>"outside OMP_WORKER_ALLOWED_ROOTS" error.</b></summary>
|
|
381
|
+
|
|
382
|
+
The task's `cwd` is not inside any approved root. This is the allowlist working; add the directory to `OMP_WORKER_ALLOWED_ROOTS` if it should be allowed (note: `OMP_WORKER_ALLOWED_ROOTS` is available since `0.2.0`; npm `0.1.1` lacks this feature).
|
|
383
|
+
</details>
|
|
384
|
+
|
|
385
|
+
<details>
|
|
386
|
+
<summary><b>"Concurrent write ownership conflict" error.</b></summary>
|
|
387
|
+
|
|
388
|
+
Two tasks that could run at the same time own overlapping paths. Give them separate `ownership` scopes, or add `depends_on` so one runs after the other.
|
|
389
|
+
</details>
|
|
390
|
+
|
|
391
|
+
<details>
|
|
392
|
+
<summary><b>How is this different from the subagents built into my client?</b></summary>
|
|
393
|
+
|
|
394
|
+
The worker is a separate agent (OMP) with its own model and provider, runs in the background across conversation turns, keeps its state on disk, and can be driven by any MCP client — including ChatGPT on the web. Batches add dependency ordering and write-scope checks on top.
|
|
395
|
+
</details>
|
|
169
396
|
|
|
170
397
|
---
|
|
171
398
|
|
|
399
|
+
## Documentation
|
|
400
|
+
|
|
401
|
+
| Guide | Read it when you want to… |
|
|
402
|
+
| :--- | :--- |
|
|
403
|
+
| [Author workflow](docs/author-workflow.md) | Set up the delegation policy and understand the supervise → review → correct loop |
|
|
404
|
+
| [Client configurations](docs/client-configurations.md) | Configure Codex, Claude Code, Cursor, VS Code, Windsurf or Continue |
|
|
405
|
+
| [ChatGPT Secure MCP Tunnel](docs/chatgpt-secure-tunnel.md) | Drive local OMP from ChatGPT on the web |
|
|
406
|
+
| [Tool reference](docs/tool-reference.md) | See every tool, parameter and the result envelope |
|
|
407
|
+
| [Operations](docs/operations.md) | Tune environment variables, storage, retention and restarts |
|
|
408
|
+
| [Benchmark protocol](benchmarks/README.md) | Compare direct execution with supervisor–worker delegation |
|
|
409
|
+
| [Registry publishing](docs/registry-publishing.md) | Release to npm and the Official MCP Registry (maintainers) |
|
|
410
|
+
|
|
411
|
+
[COMPATIBILITY.md](COMPATIBILITY.md) defines the public contract and versioning policy; [CHANGELOG.md](CHANGELOG.md) lists releases.
|
|
412
|
+
|
|
413
|
+
## Contributing
|
|
414
|
+
|
|
415
|
+
Issues and pull requests are welcome — especially Linux verification and tested client configs. Start with [CONTRIBUTING.md](CONTRIBUTING.md). To build from source:
|
|
416
|
+
|
|
417
|
+
```bash
|
|
418
|
+
git clone https://github.com/divenire990/omp-worker-mcp.git
|
|
419
|
+
cd omp-worker-mcp
|
|
420
|
+
npm ci
|
|
421
|
+
npm test # builds, then runs the test suite against a fake OMP
|
|
422
|
+
```
|
|
423
|
+
|
|
424
|
+
## Acknowledgements
|
|
425
|
+
|
|
426
|
+
Built on the [Model Context Protocol TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) and designed around [Oh My Pi](https://github.com/can1357/oh-my-pi) (MIT). OMP is not bundled and must be installed separately. This project is independent and not affiliated with OMP, OpenAI or Anthropic.
|
|
427
|
+
|
|
172
428
|
## License
|
|
173
429
|
|
|
174
|
-
|
|
430
|
+
[MIT](LICENSE)
|