# omp-worker-mcp

English · [简体中文](README.zh-CN.md)

Stop burning your best-model quota on grunt work.

Let Claude Code, Codex, Grok Build, Kimi Code, or any other MCP client hand search, cleanup, batch work, and broad repository scans to the smaller models you already configured in OMP.

![OMP workers for every coding agent](assets/omp-worker-mcp-overview.png)

## Why I made this

I usually have several coding agents open at once: Codex in one window, Grok Build or Kimi Code in another, and OMP nearby. Some of the plans wired into OMP give me plenty of model time for the money. They are perfect for repository scans, first-pass reviews, and repetitive jobs that chew through tokens.

My plans for the tools I use every day are smaller. When quota gets tight, the last thing I want is another handoff document or a round of copying prompts between terminal windows. The agent I am already talking to should be able to send the job out and bring the result back.

So I built this MCP server. Your main agent keeps the context and makes the decisions. OMP handles the bounded background work. Claude Code, Codex, Grok Build, Kimi Code, OpenCode, Cursor, and other MCP clients can all share the same OMP roles and task agents.

## What your agent gets

Most jobs only need three tools:

- `models` finds a model by substring and returns ready-to-use `run` arguments. Optional.
- `run` starts an OMP worker and returns the resolved model plus a job ID and the next action.
- `wait` collects one or several results.

Your agent can start several independent jobs, keep working, then collect the results together. `status`, `list`, `cancel`, `agents`, and `roles` cover the rest.

Each worker has an `agent` and one model choice. The agent describes how to approach the task, such as `scout` or `reviewer`; the default `task` agent fits most work. The model comes from either a `role` — an entry of your OMP `modelRoles` map such as `task`, `slow`, or `designer` — or an explicit `model` id such as `provider/model-id`. If you pass neither, the worker keeps the agent's own default model when its agent declares one, and otherwise runs on the `task` role. Roles are names you can use directly, without discovering anything first; pass a role or a model, never both.

## Set it up

You need Node.js 22 or newer and an installed, authenticated [Oh My Pi](https://omp.sh).

```bash
git clone https://github.com/elijah7x/omp-worker-mcp.git
cd omp-worker-mcp
node src/server.js --self-check
npm run check
```

Then ask the project to print a config snippet for your client:

```bash
node scripts/client-config.js claude
node scripts/client-config.js codex
node scripts/client-config.js opencode
node scripts/client-config.js devin
node scripts/client-config.js standard-json
```

The script prints the config and leaves your files alone. [Client setup](docs/CLIENTS.md) covers the tested clients, their config locations, and the generic stdio form. Use `omp` as the MCP server name.

To test a real dispatch after connecting it:

```bash
npm run check:worker
```

## Give it useful work

OMP workers are most useful when a task has a clear boundary and can return a result instead of making the final decision. A few examples:

- Search a repository and explain how one subsystem works.
- Review a module for bugs or security issues.
- Run a test suite, investigate failures, and report the likely cause.
- Compare several files or draft a first-pass implementation.

Start independent jobs together. Keep the final edit, product judgment, and answer to the user in the parent agent.

Clients with skill or rules support can install [SKILL.md](SKILL.md). Other clients can work from the MCP tool descriptions.

A `run` call looks like this:

```json
{
  "prompt": "Review the authentication module for concrete security issues. Return findings with file paths and line numbers.",
  "cwd": "/path/to/project",
  "agent": "reviewer",
  "role": "slow"
}
```

To send a specific model instead of a role, pass `"model": "provider/model-id"` and omit `role`. The reply names the resolved model and the call to make next:

```json
{
  "job_id": "a1b2c3",
  "model": "your-provider/reasoning-model",
  "next_action": { "tool": "wait", "arguments": { "job_id": "a1b2c3" } }
}
```

The worker runs through OMP's non-interactive print mode. It does not take over an OMP TUI window you already have open.

`wait` blocks until the job finishes. A wait that exceeds its timeout returns with `timed_out: true` while the job keeps running — call `wait` again or check `status`; cancelling or abandoning a wait never cancels the job, which is what `cancel` is for.

## Use your own models and agents

The bridge does not keep a second model registry. Add or change models in OMP, where your provider setup and authentication already live.

For example, add roles to the block-form `modelRoles` map in `~/.omp/agent/config.yml`:

```yaml
modelRoles:
  task: your-provider/fast-model
  slow: your-provider/reasoning-model
  designer: your-provider/vision-model
```

Call `roles` with the target workspace's absolute `cwd`. OMP resolves its own YAML, project settings and `PI_CONFIG_FILES` overlays; a custom `OMP_CONFIG` is applied after them. The bridge's headless overlay is always last. Role mappings may refer to another role as `@name`; circular references are rejected.

To discover an unfamiliar model, call `models` with a substring and the same `cwd`; it returns exact identifiers and ready-to-use `run` arguments. Both discovery tools default to the server's working directory when `cwd` is omitted. There is no bridge catalog cache to become stale after configuration changes.

Custom OMP task agents work the same way. Add one to OMP's agent directory, restart the client, call `agents`, and use its name as `run.agent`.

## Connect another MCP client

The server uses local stdio MCP. In most clients, the command is:

```text
node /absolute/path/to/omp-worker-mcp/src/server.js
```

`node scripts/client-config.js standard-json` gives you a starting point. Clients with an official installer command — Claude Code, OpenCode, Command Code, Devin — get a ready-to-run command from the generator instead. If a client expects a different config shape, add a small renderer to `scripts/client-config.js`, a clean example under `examples/`, and a row to [Client setup](docs/CLIENTS.md). You do not need to touch the server.

## Access and privacy

This project assumes a trusted, single-user machine. OMP workers run unattended with the same file and command permissions as your local user.

Every `run` call must pass an existing absolute `cwd`, so a worker cannot drift into the MCP client's launch directory. Projects under your home folder, external volumes, and client worktrees all work without extra setup. Set `OMP_WORKER_ALLOWED_ROOTS` if you want to restrict jobs to specific roots; it is an optional allowlist, not a sandbox.

Private OMP skills and rules stay off unless a call enables them. The server passes a small set of environment variables to workers, and `roles`/`models` return the model information callers need to pick a worker.

Prompts and results remain under `~/.omp/omp-worker-mcp/jobs/`. They may contain source code. Use a container, OS sandbox, or restricted account if local-user access is too broad for your project. [Client setup](docs/CLIENTS.md) documents the environment and credential behavior.

## Development

```bash
npm run check
```

`npm run check` uses temporary homes and a deterministic OMP fixture; no installed OMP, credentials or network are required. It covers model ambiguity, private diagnostic suppression, generated configs, both MCP framing styles, and timeout-to-completion lifecycle. `npm run check:worker` is the opt-in real OMP dispatch.

The current release supports local stdio, detached jobs, role and agent discovery, explicit model selection with validation, cancellation, and saved results. Token streaming, remote transport, live TUI control, and automatic job cleanup are outside the current scope.

## 0.2.0 migration

- Replace `model: "@slow"` with `role: "slow"`. Pass `model` or `role`, never both.
- Bare model IDs must match exactly one catalog entry; `models({query})` returns usable full IDs. Unknown model and role targets fail before a job starts.
- `agent` selects the prompt independently, defaulting to `task`. To use a planning prompt with the planning model, pass both `agent: "plan"` and `role: "plan"`.
- Job responses expose the resolved model and the next `wait` call. A wait timeout leaves the worker running; only `cancel` stops it.
- Explicit `thinking` overrides a model/role `:level` suffix, then agent settings; otherwise it is off.
- Runtime requires OMP support for `omp models --json --no-extensions` and `omp config get modelRoles --json` (verified with 18.2.3). Default regression checks do not require OMP.

## License

MIT