agent-ruler-openmcp

name	agent-ruler-openmcp
description	Guidance for installing, upgrading, verifying, and using the npm package @agent-ruler/openmcp and its openmcp CLI. Use when a user asks how to install OpenMCP from npm, start or diagnose the Gateway, use OpenMCP CLI commands, configure skills through SKILL_PATH, troubleshoot global installs, or publish/test the CLI package.

Agent Ruler OpenMCP

Use this skill to help users install and operate the @agent-ruler/openmcp npm package. Prefer npm commands and the openmcp binary in all user-facing examples.

Package Facts

• npm package: @agent-ruler/openmcp
• CLI binary: openmcp
• Minimum Node.js: >=18
• Default Gateway WebSocket: ws://localhost:8282
• Default Gateway logs directory: %USERPROFILE%\.openmcp\logs\gateway on Windows, ~/.openmcp/logs/gateway on Unix-like systems

Install Or Upgrade

For normal users, recommend a global npm install:

npm install -g @agent-ruler/openmcp
openmcp --version
openmcp --help

To upgrade an existing global install:

npm install -g @agent-ruler/openmcp@latest
openmcp --version

If a specific release is needed:

npm install -g @agent-ruler/openmcp@0.1.4

Avoid telling users to run yarn openmcp ...; global npm users should run openmcp ... directly.

First Run Workflow

Start Gateway before running commands that call service controllers:

openmcp gateway start
openmcp gateway status

If startup fails or status is not running, ask for these diagnostics:

openmcp gateway logs -n 200
openmcp gateway logs-dir
openmcp gateway run -p 8282

Use gateway run when the user needs foreground stderr/stdout. Use gateway logs for background failures; it should include both gateway.log and gateway-startup.log.

If the Gateway uses a non-default port, pass -g to commands that talk to it:

openmcp mcp server list -g ws://127.0.0.1:9000

Common Commands

Show help and versions:

openmcp --help
openmcp gateway --help
openmcp mcp --help
openmcp debug --help

Manage Gateway:

openmcp gateway start
openmcp gateway status
openmcp gateway logs -n 200
openmcp gateway stop

Add and connect an MCP server from a file:

openmcp mcp server add --file ./mcp-server.json
openmcp mcp server list
openmcp mcp session connect --id <serverId>
openmcp mcp session current

Call debug commands after a session is connected:

openmcp debug tool list
openmcp debug tool call --name echo --args "{\"message\":\"hi\"}"
openmcp debug mcp ping

Start Web UI:

openmcp start

or manage Web UI separately:

openmcp webui start
openmcp webui status
openmcp webui stop

Skills In OpenMCP

OpenMCP reads local skills from the SKILL_PATH setting. SKILL_PATH may point to a single skill directory containing SKILL.md or to a parent directory containing multiple skill subdirectories.

Typical parent directory layout:

skills/
  my-skill/
    SKILL.md
  another-skill/
    SKILL.md

After configuring SKILL_PATH and starting Gateway:

openmcp skills list
openmcp skills load --skill-name my-skill
openmcp skills read-file --skill-name my-skill --file-path SKILL.md

When troubleshooting openmcp skills ..., first verify Gateway is running because the skills commands call the Gateway-backed service.

Troubleshooting

If openmcp is not recognized:

npm install -g @agent-ruler/openmcp
npm root -g
npm config get prefix

Tell the user to ensure the global npm executable directory is on PATH. On Windows this is often %APPDATA%\npm; on Unix-like systems it is usually <npm-prefix>/bin.

If gateway start says it may have failed:

1. Run openmcp gateway logs -n 200.
2. Run openmcp gateway run -p 8282 to see foreground errors.
3. Check the installed version with openmcp --version.
4. Ask the user to paste the full output, including Node.js version and stack traces.

If a published package starts locally from source but fails after global install, suspect missing runtime dependencies or vendored build files. Verify by installing the packed artifact into a clean temporary project and importing vendored modules before publishing.

Release Verification

Before publishing, prefer:

cd cli
npm pack

Install the generated .tgz in a clean temporary project and verify:

npm install <path-to-agent-ruler-openmcp.tgz>
npx openmcp --version
npx openmcp gateway --help

For a deeper check, run the published smoke test after the version has been published:

cd cli
npm run test:published