MCP 服务器

OMP Instances Control Plane

Local MCP control plane for managing multiple Oh My Pi processes via Unix sockets, enabling discovery, messaging, and lifecycle operations.

README

OMP Instances

Русская версия

Local MCP control plane for running Oh My Pi processes.

Use it when several OMP sessions are running and one session needs to discover, inspect, message, interrupt, rename, or stop another. Communication stays on the local machine through user-only Unix sockets.

No browser UI. No TCP server.

Install

curl -fsSL https://raw.githubusercontent.com/DKeken/omp-instances-control-plane/main/install.sh | sh

Restart running OMP processes after installation.

Installer is idempotent. Re-running same command updates installation and preserves unrelated MCP servers.

What installer changes

Installs repository into ~/.local/share/omp-instances-control-plane.
Installs locked Bun dependencies for MCP server.
Backs up existing omp-control.ts, omp-control.js, and mcp.json under ~/.omp/agent/backups.
Installs exactly one runtime extension symlink: ~/.omp/agent/extensions/omp-control.ts.
Merges only mcpServers["omp-instances"] into ~/.omp/agent/mcp.json.

Review before running a remote script:

curl -fsSL https://raw.githubusercontent.com/DKeken/omp-instances-control-plane/main/install.sh -o install.sh
cat install.sh
sh install.sh

Available tools

Tool	Purpose
`list`	List live OMP processes, aliases, PIDs, sessions, models, working directories, and idle/busy state.
`inspect`	Read current metadata for one process.
`send`	Send a message to one OMP process.
`ask`	Send a correlated request and wait for explicit `reply`.
`reply`	Complete a pending correlated request.
`broadcast`	Send one message to every reachable OMP process.
`rename`	Assign a readable alias to one process.
`doctor`	Diagnose permissions, stale sockets, duplicate aliases, and stale reply files.
`interrupt`	Abort current model/tool operation without exiting OMP.
`shutdown`	Gracefully stop one OMP process.

Targets accept exact alias, PID, instance ID, session ID, or unambiguous instance/session ID prefix.

How it works

flowchart LR
  A[OMP process A] -->|0600 record + Unix socket| R[(0700 local registry)]
  B[OMP process B] -->|0600 record + Unix socket| R
  M[MCP server] -->|discover and validate| R
  M -->|typed local request| A
  M -->|typed local request| B

Each OMP process loads omp-control.ts. Runtime extension:

creates random instance ID;
writes process metadata to local registry;
listens on private Unix socket;
refreshes state every five seconds;
removes record and socket during graceful shutdown.

MCP server treats registry files as discovery metadata, not authority. Before action it checks process liveness and contacts target socket.

Configuration

Variable	Default	Purpose
`OMP_INSTANCES_HOME`	`$XDG_DATA_HOME/omp-instances-control-plane` or `~/.local/share/omp-instances-control-plane`	Installed repository location.
`OMP_HOME`	`~/.omp/agent`	OMP agent configuration directory.
`OMP_MCP_CONFIG`	`$OMP_HOME/mcp.json`	MCP configuration file.
`OMP_INSTANCES_REF`	`main`	Repository branch installed by script.
`OMP_CONTROL_DIR`	`/tmp/omp-control-<uid>`	Shared runtime registry and socket directory. Must be same for every process.
`OMP_INSTANCE_NAME`	`<cwd-name>-<pid>`	Initial alias for one OMP process.

Portable custom installation example:

curl -fsSL https://raw.githubusercontent.com/DKeken/omp-instances-control-plane/main/install.sh | \
  OMP_INSTANCES_HOME="$HOME/tools/omp-instances" sh

OMP_INSTANCES_HOME is fail-closed because installer archives, swaps, and may remove this directory during rollback. It must be a dedicated path. Installer rejects filesystem root, HOME, OMP_HOME, their ancestors, paths inside OMP_HOME, symlink targets, and existing directories whose package.json#name is not omp-instances-control-plane. OMP_MCP_CONFIG cannot be inside installation root.

Updating

Run install command again. Installer prepares source, locked dependencies, and merged MCP configuration before changing active files. It then archives previous installation and activates repository, extension symlink, and MCP config as a rollback-backed transaction. Any activation error restores previous state.

Restart OMP processes so they load new runtime extension and MCP configuration.

Rollback and uninstall

Backups are stored in ~/.omp/agent/backups with one timestamp per installation.

To roll back an upgrade, stop OMP processes and restore matching repository and MCP backups:

rm -rf ~/.local/share/omp-instances-control-plane
tar -xzf ~/.omp/agent/backups/omp-instances-control-plane.<timestamp>.tar.gz \
  -C ~/.local/share
cp ~/.omp/agent/backups/mcp.json.<timestamp>.bak ~/.omp/agent/mcp.json

Installed extension symlink points to stable installation path, so restored repository supplies previous runtime automatically. Restart OMP processes after rollback.

If OMP_INSTANCES_HOME, OMP_HOME, or OMP_MCP_CONFIG was customized, use those paths instead.

For a first-install uninstall, stop OMP processes, remove ~/.omp/agent/extensions/omp-control.ts, delete only mcpServers["omp-instances"] from MCP config, then remove installation directory.

Security

Registry directories: 0700.
Records and sockets: 0600.
Backup directory and extension backup directories: 0700.
MCP config backups, installation archives, and copied extension backups: 0600.
Transport: local Unix sockets only.
Request and response frames are size-limited.
No generic shell execution, file API, HTTP endpoint, clipboard API, or raw PTY injection.
Same-user processes remain inside trust boundary. This project does not isolate mutually hostile processes running under same OS account.

See SECURITY.md for vulnerability reporting.

Troubleshooting

No instances appear

Restart OMP processes after installation. Confirm ~/.omp/agent/extensions/omp-control.ts points into installed repository and every process uses same OMP_CONTROL_DIR.