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.

What your agent gets

Most jobs only need two tools:

• run starts an OMP worker and returns a job ID.
• 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 a role. The agent describes how to approach the task, such as scout or reviewer. The role chooses one of the model mappings in your OMP config, such as task, slow, or designer. If you omit both, the server uses task.

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 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"
}

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

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

Restart the MCP client and call roles. The new names are ready to use as run.role; the server needs no code change.

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. 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 hides model mappings and local agent paths by default.

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

The test suite covers config parsing, generated client configs, both supported MCP framing styles, job lifecycle, and a mocked OMP process. npm run check:worker adds a live OMP dispatch.

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

License

MIT