Opscotch Workspace

@opscotch/oms-workspace is an npm package that lets MCP clients connect to the Opscotch Workspace MCP server.

Requirements

• Node.js 18 or later
• Docker with Docker Compose V2
• Legal acceptance - Accept the Opscotch legal terms and use the resulting token as OPSCOTCH_LEGAL_ACCEPTED

Docker may be the standard host Docker daemon or a rootless per-user Docker daemon. Installation records the Docker endpoint that passed its checks, and runtime Compose commands use that endpoint even when an MCP client starts with a different environment.

The workspace ships with built-in default backend image refs for the local-development and public guidance MCP services. You can override those refs through the generated .env file or process environment, but you do not need to set them for normal use.

Quick Start

1. Install

This creates configuration in ~/.oms-workspace/ and pulls Docker images. Required environment variables:

OPSCOTCH_LEGAL_ACCEPTED=<token> \
OPSCOTCH_WORKSPACE_PATH=<path> \
pnpx @opscotch/oms-workspace install

If you use npm rather than pnpm, use npx -y @opscotch/oms-workspace install. The installer detects the runner that invoked it and prints matching MCP client configuration.

Where:

• OPSCOTCH_LEGAL_ACCEPTED - Token from accepting Opscotch legal terms
• OPSCOTCH_WORKSPACE_PATH - Root path accessible to the workspace (e.g., /home/user/dev/opscotch)

By default, install and runtime metadata are written under ~/.oms-workspace/. Set OMS_WORKSPACE_HOME only if you need a different per-user location.

2. Configure Your MCP Client

Use the configuration printed by the installer. For example, an install run with pnpx prints:

{
  "mcpServers": {
    "oms-workspace": {
      "command": "pnpx",
      "args": ["@opscotch/oms-workspace", "run"]
    }
  }
}

3. Use

Start your MCP client. The workspace will start automatically when you use tools prefixed with olds_ or og_.

Available Tools

• olds_... - Local development tools
• og_... - Public guidance tools

Workspace Paths

The local-development MCP backend runs inside Docker. OPSCOTCH_WORKSPACE_PATH is mounted read-only at /workspace, so file paths passed to olds_ tools should normally use the container-visible path, not the host path.

For example, if you install with:

OPSCOTCH_WORKSPACE_PATH=/home/jeremy/dev/opscotch

then this host checkout:

/home/jeremy/dev/opscotch/community/opscotch-community

is visible to MCP tools as:

/workspace/community/opscotch-community

Use that /workspace/... form for resource unit test roots and test file paths, such as:

/workspace/community/opscotch-community/unit-tests/apps/example/example.test.ts

Commands

oms-workspace install   # Create config and pull Docker images
oms-workspace update    # Refresh Docker images for the pinned Opscotch version
oms-workspace update 3.1.8 # Update the pinned Opscotch version and refresh images
oms-workspace run       # Start MCP stdio wrapper (called by MCP client)
oms-workspace stop      # Stop runtime and Docker containers
oms-workspace doctor    # Check system requirements
oms-workspace logs      # Show Docker backend logs

Configuration Files

Located in ~/.oms-workspace/:

~/.oms-workspace/runtime.json        # Connection metadata
~/.oms-workspace/runtime.pid         # Runtime process ID
~/.oms-workspace/runtime.log         # Runtime diagnostics
~/.oms-workspace/docker-compose.yml  # Docker Compose config
~/.oms-workspace/.env                # Environment variables

Docker Runtime

Default Docker

If your user can already run Docker, no extra configuration is needed:

docker ps
docker compose version
oms-workspace doctor

The package defaults to the docker CLI and will use Docker's default context unless DOCKER_HOST or DOCKER_CONTEXT is set.

Rootless Docker

For users that should not access the host rootful Docker socket, configure rootless Docker for that user instead of adding the user to the docker group.

Root-level prerequisites:

sudo apt install uidmap dbus-user-session docker-ce-rootless-extras
sudo loginctl enable-linger <user>

Ensure /etc/subuid and /etc/subgid contain ranges for the user. Then, as that user:

dockerd-rootless-setuptool.sh install
systemctl --user enable --now docker
export DOCKER_HOST=unix:///run/user/$(id -u)/docker.sock
oms-workspace doctor

If dockerd-rootless-setuptool.sh install reports systemd not detected or systemctl --user fails with Failed to connect to bus, start the daemon manually with the environment printed by the installer:

export XDG_RUNTIME_DIR=$HOME/.docker/run
export PATH=/usr/bin:$PATH
mkdir -p "$XDG_RUNTIME_DIR"
PATH=/usr/bin:/sbin:/usr/sbin:$PATH dockerd-rootless.sh > "$HOME/.docker/dockerd-rootless.log" 2>&1 &
export DOCKER_HOST=unix://$HOME/.docker/run/docker.sock
until docker ps >/dev/null 2>&1; do sleep 1; done
docker ps
oms-workspace doctor

For a persistent rootless Docker service, the user needs a working systemd user manager. On systemd hosts, root can enable linger with sudo loginctl enable-linger <user> and the user should start a fresh login session before running systemctl --user enable --now docker.

For a rootless setup, keep OMS_WORKSPACE_HOME per-user, normally ~/.oms-workspace, and use an OPSCOTCH_WORKSPACE_PATH the user can access. Avoid sharing Docker sockets, Compose project state, or ~/.oms-workspace between users.

Install with the same Docker environment that passed doctor. The installer persists the selected Docker endpoint in ~/.oms-workspace/.env, so the MCP client does not need to inherit it later:

export XDG_RUNTIME_DIR=$HOME/.docker/run
export DOCKER_HOST=unix://$HOME/.docker/run/docker.sock
export OMS_WORKSPACE_HOME=$HOME/.oms-workspace
export OPSCOTCH_VERSION=3.1.7
export OPSCOTCH_WORKSPACE_PATH=$HOME/workspace
export OPSCOTCH_LEGAL_ACCEPTED=<token>
oms-workspace install

OPSCOTCH_VERSION selects the backend image line. The installer writes the matching LOCAL_DEVELOPMENT_SERVER and PUBLIC_GUIDANCE_MCP image refs into ~/.oms-workspace/.env.

Persist XDG_RUNTIME_DIR and DOCKER_HOST in the user's shell profile for Docker CLI use. The generated MCP runtime uses the endpoint captured during installation.

Container CLI Override

Set OMS_WORKSPACE_CONTAINER_CLI to use a Docker-compatible CLI name other than docker:

OMS_WORKSPACE_CONTAINER_CLI=docker oms-workspace doctor

The default is docker.

Troubleshooting

Check system requirements

oms-workspace doctor

doctor reports the container CLI, DOCKER_HOST, DOCKER_CONTEXT, XDG_RUNTIME_DIR, Docker context, Docker Compose version, daemon reachability, and whether Docker reports rootless mode.

View backend logs

oms-workspace logs
oms-workspace logs --follow local-development-server

Path mapping errors

If olds_diagnose_resource_unit_test_path reports that a host path is outside /workspace, translate it through the Docker mount. A host path under OPSCOTCH_WORKSPACE_PATH should become the same relative path under /workspace.

Stop everything

oms-workspace stop

License

This package is free to use, but use is conditioned on agreement to the Opscotch legal terms:

• https://www.opscotch.co/legal

The packaged license notice is included in LICENSE.txt.

Versions

0.1.11

• Uses built-in backend image defaults for workspace runtime configuration, with .env and process overrides remaining optional.
• Lets doctor report the effective workspace versions and the running Docker images.
• Adds background image refresh scheduling so the runtime can stay current without delaying startup.
• Supports oms-workspace update [version] to repin the workspace backend images.

0.1.10

• Persists the Docker endpoint verified during install, so rootless Docker MCP runtimes do not inherit stale client sockets.
• Uses the installed Docker endpoint for runtime Compose lifecycle commands.
• Generates MCP client configuration using the installer runner, including pnpx for pnpm and npx -y as the npm default.

0.1.9

• Detects the effective Docker context host when DOCKER_HOST is unset
• Restarts stale runtimes when the resolved Docker endpoint changes

0.1.8

• Detects stale runtime Docker environment metadata and restarts the runtime when the current shell has changed
• Records the runtime Docker environment signature in runtime metadata for safer reconnects

0.1.7

• Adds runtime idle-shutdown diagnostics for reconnect churn
• Bumps the package version for the next publish

0.1.6

• Upgrades to opscotch 3.1.6
• Removes legacy licensing requirements

0.1.1

• Initial npm release
• CLI tool: opscotch-workspace
• Commands: install, run, stop, doctor, proxy, runtime
• Docker Compose backed MCP stdio proxy
• Connects to local development and public guidance MCP backends