omp-worker-mcp

English · 简体中文

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.

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.

Related MCP server: agent-bridge

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.

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:

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 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:

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. Other clients can work from the MCP tool descriptions.

A run call looks like this:

{
  "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:

{
  "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:

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:

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. 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 documents the environment and credential behavior.

Development

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