omp-mcp-fifine
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
omp-mcp-fifine
A local single-user OMP orchestration platform: MCP bridge → persistent supervisor → independent runners. Derived from omp-worker-mcp 0.2.0, source commit e41ab1a; the original MIT license and copyright are retained.
Installation: clone to first task
Clone the source and run it directly: no build step or npm install is needed. This project does not install OMP or include model credentials. A working setup has three parts: configured OMP, a running independent supervisor, and an MCP client.
1. Check prerequisites
Linux/WSL with
/procand Unix sockets. This project's supervisor does not currently support native Windows/macOS; this does not describe OMP's own platform support.Node >=22.13 with built-in
node:sqlite, plus Git. Locally verified runtime: Node 26.8.1.Installed OMP with an authenticated, usable model. Local discovery was verified against OMP 18.18.7.
A systemd user manager for managed background mode only; foreground mode is the alternative.
Run everything inside WSL when using WSL, not in Windows PowerShell:
git --version
node --version
node -e "require('node:sqlite'); console.log('SQLite OK')"2. Install and configure OMP
Skip installation if omp --version already works. Otherwise review the official OMP installation instructions and installer before running the official command:
curl -fsSL https://omp.sh/install | shFollow its PATH instructions or open a new terminal, then check:
command -v omp
omp --version
# Interactive provider login for OAuth; skip if API-key/custom-provider auth is already configured
omp login
omp models
omp config get modelRoles --json
omp config pathConfigure API keys/custom providers through OMP itself, not this repository or MCP JSON. Confirm that OMP lists a model you can actually use. The default task agent selects role task; a populated model catalog does not imply that role exists. If needed, merge this into config.yml under the directory returned by omp config path, preserving other settings:
modelRoles:
task: your-provider/your-model-idReplace the placeholder with an actual full model identifier from omp models. Alternatively pass an explicit model or an existing role on every run. Never pass both.
3. Clone and check the project
The example uses a user-owned directory and requires no root. OMP_MCP_DIR is only a convenience variable used in this guide.
export OMP_MCP_DIR="$HOME/omp-mcp-fifine"
git clone https://github.com/five-five0909/omp-mcp-fifine.git "$OMP_MCP_DIR"
# Check the OMP binary, role configuration and agent listing; no model request
# Run from the clone so project-level OMP settings are resolved there
(cd "$OMP_MCP_DIR" && node src/server.js --self-check)
# Offline fixture tests: no network, model credentials or model charges
npm --prefix "$OMP_MCP_DIR" run check--self-check does not query the model catalog or validate credentials against a provider. It may report ok:true without a task role; check the returned roles and use the explicit model/role approach above. Later, pass the intended project directory as cwd to MCP models/roles, because OMP settings can differ between workspaces.
For the existing installation on the maintainer's machine, set OMP_MCP_DIR=/opt/dev-space/omp-mcp-fifine instead of cloning into that nonempty directory. Other paths are supported. Ensure your user owns the installation directory; do not default to running model tasks as root.
4. Start the supervisor — choose one mode
Recommended: transient systemd user service, independent of the calling terminal:
# If the user manager is unavailable, use foreground mode instead
systemctl --user is-system-running
node "$OMP_MCP_DIR/src/service.js" start
node "$OMP_MCP_DIR/src/service.js" status
node "$OMP_MCP_DIR/src/supervisor.js" statusThe supervisor status command should return JSON with pid, max_concurrency and task counts. Startup is asynchronous: if it is not ready yet, inspect service state and logs:
node "$OMP_MCP_DIR/src/service.js" logsAlternative: foreground mode, without systemd. Keep this terminal/process running and open your MCP client in another terminal:
node "$OMP_MCP_DIR/src/supervisor.js" start
# Wait for: supervisor readyDo not run both modes for the same data directory. A kernel lock prevents duplicate supervisors. The managed service is transient, not boot-enabled; restart after reboot, WSL shutdown or user-manager exit. No linger setting is changed and survival after complete user logout is not guaranteed.
5. Connect your MCP client
Generate configuration using the actual absolute Node and server paths on your machine:
# CodeBuddy, Cursor and other mcpServers-JSON clients
node "$OMP_MCP_DIR/scripts/client-config.js" standard-json
# Claude Code: prints an installation command; review and execute that output yourself
node "$OMP_MCP_DIR/scripts/client-config.js" claude
# Codex: prints a TOML configuration snippet
node "$OMP_MCP_DIR/scripts/client-config.js" codex
# Other supported configuration renderers
node "$OMP_MCP_DIR/scripts/client-config.js" --helpThe generator only prints; it does not install anything. Merge the snippet into your client's existing MCP configuration without replacing unrelated entries, or review and execute the printed CLI command. Refresh MCP or start a new client session afterward.
The generated service key is
omp. If the old OMP bridge is already configured, rename the new entry/CLI server name toomp-fifineand select that new service.MCP launches
src/server.js, notsrc/supervisor.js. Start the independent supervisor in step 4; the MCP bridge does not auto-start it.Run both under the same Linux user, with consistent OMP configuration and
OMP_WORKER_HOME.Runtime data defaults to
~/.omp/omp-mcp-fifine, separate from source and upstream data. When overriding it, set the same absolute value in the MCP entry'senvand the supervisor environment.GUI clients may not inherit terminal PATH. If OMP is missing, use the absolute path from
command -v ompasOMP_BINconsistently on both sides.Set the client tool timeout longer than the requested
waitduration. A short wait timeout does not fail or cancel the worker.
6. Verify the first task
Ask the client to call supervisor_status, then models or roles with the intended project's absolute cwd on the new service. Call run with a real existing directory and discovered model:
{
"prompt": "Reply with exactly PONG and nothing else.",
"cwd": "/absolute/path/to/an/existing/project",
"model": "your-provider/your-model-id",
"access": "read",
"max_time_sec": 60,
"idempotency_key": "installation-smoke-1"
}Follow with wait using the returned ID:
{"job_id":"<job_id from run>","timeout_sec":90}Success means status: succeeded and PONG in the result, not merely accepted submission. This step calls a real model and may incur charges. Offline tests do not verify your credentials or network. Change the idempotency key when deliberately starting a fresh test; exact replay returns the original job.
Related MCP server: Astatide Conductor
Stop, update and troubleshoot
# Managed service
node "$OMP_MCP_DIR/src/service.js" stop
# Foreground mode ONLY: Ctrl+C, or from another terminal
node "$OMP_MCP_DIR/src/supervisor.js" stopFor managed mode, use service.js stop, not supervisor.js stop: the service has a restart-on-failure policy, and direct supervisor termination can trigger a restart.
Stopping the scheduler is not cancellation: authorized runners continue and pending/DAG successors resume after scheduler restart. To stop a task, call cancel and inspect its result.
Before updating, check your worktree and preferably wait for running tasks to finish. For managed-service mode:
git -C "$OMP_MCP_DIR" status --short
# Preserve any local changes first; do not force-reset them
node "$OMP_MCP_DIR/src/service.js" stop &&
git -C "$OMP_MCP_DIR" pull --ff-only &&
npm --prefix "$OMP_MCP_DIR" run check &&
node "$OMP_MCP_DIR/src/service.js" startThe && chain stops on a failed pull/test; diagnose that failure before restarting. Do not continue over a failed update. Refresh the client's MCP connection too. Re-export OMP_MCP_DIR in new terminals if it is not already set.
Symptom | What to check |
Cannot load | Actual Node selected by the client; regenerate config after upgrading |
OMP binary missing |
|
Unknown role | Configure a real task role, or pass an existing role/full model explicitly |
Supervisor unavailable | Start it independently; check same user, runtime directory and service logs |
Cannot connect to | Use foreground mode; not a model/MCP configuration failure |
Terminal works, client auth fails | Compare OMP configuration and credential-variable environments; never publish secrets in logs or Git |
| Inspect evidence before manual resolution; never blindly replay uncertain work |
Tools
models,roles,agents: native OMP configuration discovery; no supervisor required.run: validate and durably enqueue one task, returning model, job ID and wait guidance.submit: atomically submit up to 100 DAG nodes withkeyanddepends_on(local keys or existing job IDs).wait,status,list: collect or inspect actual execution state. Wait timeout never cancels execution.cancel: TERM, grace period, KILL if needed, then confirm exit; uncertain results stay cancelling/unknown.events: ordered replayable state events and cursor-based long wait. Caller persists cursor and deduplicates IDs.supervisor_status: scheduler health, concurrency and limitations.resolve: explicitly resolve an unknown job after human inspection, without rerunning it; requires confirmation and reason, rejects known live processes.cleanup: preview aged terminal-job log/session deletion; onlyconfirm:truedeletes. Database history/events remain.
{
"idempotency_key": "review-v1",
"jobs": [
{"key":"a", "prompt":"Inspect this repository", "cwd":"/absolute/repo", "model":"provider/model-id", "access":"read"},
{"key":"b", "depends_on":["a"], "prompt":"Read the agreed shared artifact and implement the change", "cwd":"/absolute/repo", "model":"provider/model-id", "artifacts":["result.txt"]}
]
}Replace model with an exact identifier from models. Model and role are mutually exclusive; agent chooses the prompt independently. Models are resolved before enqueue. Dependencies provide ordering, not automatic injection of upstream results: specify shared artifact paths when transferring information. Failed/cancelled/unknown prerequisites block downstream work. No automatic retries or unblocking; explicitly submit new work when appropriate.
Idempotency keys return original tasks on exact replay and reject changed input. Use the same key after uncertain submission outcomes.
Reliability and boundaries
SQLite WAL/FULL transactions store submission, launch claim and events. A runner requires a durable permit plus supervisor IPC before executing. Recovery checks PID start time and boot identity, authenticated completion records and retained-log hashes. An uncertain launch is never blindly replayed: unknown reserves concurrency/workspace locks until inspected. Manual resolution remains visibly distinguished from automated success.
Default concurrency is 2. Overlapping workspaces serialize if either job is a writer; readers may run concurrently. resources are exclusive logical labels, not OS quotas. Symlink access across workspaces, Git shared state, detached descendant processes and arbitrary access by trusted same-user code are not sandboxed.
auto_wake:false: no verified CodeBuddy automatic conversation-wakeup adapter is installed. A server notification does not automatically resume the host AI. Use wait or replay events after reconnect. The existing MCP connection has not been switched for this project; no live wakeup claim is made.
Workers use automatic tool approval and have the current user's privileges. access:read restricts OMP tools to read/grep/glob, not an OS sandbox. The optional realpath cwd allowlist is not filesystem isolation. Skills/rules are off by default. The Unix socket is private to its user; this is not a multi-user network service.
Credentials travel through filtered environment and IPC, not persisted launch specs/database; prompts, logs and OMP sessions may still contain sensitive data. Each stdout/stderr retains its first 8 MiB by default, drains excess output and reports dropped bytes. API results return at most a 16 KB tail of retained data. Relative required artifacts are checked for containment, file type, size (64 MiB each) and SHA-256; missing artifacts fail a task. Artifacts are not automatically copied.
Configuration: OMP_MAX_CONCURRENCY (2), OMP_LOG_LIMIT_BYTES (8388608), OMP_CANCEL_GRACE_MS (3000), plus upstream OMP_BIN, OMP_CONFIG, OMP_MODELS, OMP_WORKER_ALLOWED_ROOTS, OMP_WORKER_PASS_ENV, OMP_WORKER_IMPORT_SHELL_ENV. Supervisor environment controls execution; keep discovery and execution configuration consistent. OMP_WORKER_HOME must fit a Unix socket path (100-byte maximum including socket filename).
Verification
npm --prefix "$OMP_MCP_DIR" run check
# Optional transient systemd service test, fixture only
npm --prefix "$OMP_MCP_DIR" run check:service
# Opt-in real worker; incurs model usage, requires a running supervisor
# Replace task with a role that actually exists in your OMP configuration
OMP_WORKER_SMOKE_ROLE=task npm --prefix "$OMP_MCP_DIR" run check:workerOffline tests cover discovery, framing, idempotency, DAG cycles/blocking, concurrency/resource/workspace locks, cancellation, logs/artifacts, MCP disconnect survival, restart, six crash phases, PID mismatch and database failures. Systemd transient-service survival has been locally tested. Real-model end-to-end and automatic host wakeup are not claimed by offline tests; upstream client verification claims do not automatically apply to this fork.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted MCP memory and agent control plane for durable conversations, jobs, and operations.
- aXDeprecatedio.github.ax-platform
Agent-native collaboration network: orchestrate a team of long-running agents from any MCP client.
Private-by-default, local-first memory/context/task orchestrator for MCP apps and agents.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceMCP server orchestrating local multi-agent workflows with gated lifecycle, handoff events, and host-level continuation.-
- AlicenseNot gradedqualityFmaintenanceOrchestrates persistent task graphs and enforces approval policies for MCP-driven agent workflows, coordinating with Agents Gateway for execution.MIT
- AlicenseAqualityCmaintenanceEnables agents to submit and manage persistent, dependency-aware task graphs with immutable artifacts, resource reservations, durable event streaming, and retryable process execution over MCP.12MIT
- FlicenseNot gradedqualityDmaintenanceEnables local RAG orchestration with MCP, providing context retrieval, in-memory text ingestion, explicit tool invocation, and transport-neutral tool discovery.-