NV oOS MCP Bridge

@nvdigitalsolutions/nvoos-mcp-bridge

Zero-dependency MCP stdio ↔ HTTP relay for NV oOS (Open Operator System) WordPress sites.

Every NV oOS site exposes a JSON-RPC 2.0 MCP endpoint at https:// /wp-json/mcp-ai/v1/mcp. Most editors and agents (Zed, Claude Desktop, Cursor, Codex) spawn MCP servers over stdio — this package bridges the two transports. Two binaries ship:

npx -y @nvdigitalsolutions/nvoos-mcp-bridge@latest

Quick start (Zed)

zed: open settings → add to context_servers:

"nv-oos": {

"source": "custom", "command": { "path": "npx", "args": ["-y", "@nvdigitalsolutions/nvoos-mcp-bridge@latest"], "env": { "MCP_AI_BASE_URL": "https://your-site.com/wp-json/mcp-ai/v1/mcp", "MCP_AI_TOKEN": "cred_xxxxx.SECRET" } } }

Then reload the Agent Panel (agent: restart language servers → or reopen the panel). Use the Fleet Operator admin screen (Settings → External Operators) to mint a scoped operator token and get a ready-pasted block.

SSH-only sites

"nv-oos-ssh": {

"source": "custom", "command": { "path": "npx", "args": ["-y", "@nvdigitalsolutions/nvoos-mcp-bridge@latest", "ssh"], "env": { "MCP_AI_SSH_USER": "your-ssh-user", "MCP_AI_SSH_HOST": "203.0.113.10", "MCP_AI_SSH_PORT": "22", "MCP_AI_TOKEN": "op_xxxxx.SECRET" } } }

Pass ssh as the first argument to select the SSH binary via npx

(npx exposes only the primary bin as the bare package name). SSH auth is

key-only: ssh @ must work non-interactively first.

Other clients

Same env vars, different shells — Claude Desktop (claude_desktop_config.json → mcpServers), Cursor (.cursor/mcp.json), VS Code (.vscode/mcp.json):

{

"mcpServers": { "nv-oos": { "command": "npx", "args": ["-y", "@nvdigitalsolutions/nvoos-mcp-bridge@latest"], "env": { "MCP_AI_BASE_URL": "https://your-site.com/wp-json/mcp-ai/v1/mcp", "MCP_AI_TOKEN": "cred_xxxxx.SECRET" } } } }

On Windows hosts, some clients need the cmd wrapper: "command": "cmd", "args": ["/c", "npx", "-y", "@nvdigitalsolutions/nvoos-mcp-bridge@latest"].

Manager-session sites (NV Astro storefront)

Some NV surfaces split write auth: the storefront MCP (https://astro.nvoos.cloud/mcp) serves reads publicly, accepts NVOOS_MCP_TOKEN for design writes, and requires a manager session cookie for contract writes (cms_*, media_upload). Give the bridge login credentials and it obtains the session for you — no cookie copying, no re-login dance:

"nvoos-astro": {

"source": "custom", "command": { "path": "npx", "args": ["-y", "@nvdigitalsolutions/nvoos-mcp-bridge@latest"], "env": { "MCP_AI_BASE_URL": "https://astro.nvoos.cloud/mcp", "MCP_AI_TOKEN": " ", "MCP_AI_LOGIN_URL": "https://astro.nvoos.cloud/api/auth/login", "MCP_AI_LOGIN_EMAIL": "manager@your-domain.com", "MCP_AI_LOGIN_PASSWORD": " " } } }

At startup the bridge POSTs { "email": "…", "password": "…" } to MCP_AI_LOGIN_URL, attaches the returned session cookies to every upstream request, and re-establishes the session once when a request answers 401/403 or the cookies near expiry. The account needs the backend manage_astro capability. Keep the password out of shared settings files (editor secret store, or a dedicated manager account).

Configuration

All configuration is environment variables — never put tokens in args (they would show in process listings).

nvoos-mcp (HTTPS relay)

nvoos-mcp-ssh (SSH variant)

Adds MCP_AI_SSH_USER, MCP_AI_SSH_HOST (both required), MCP_AI_SSH_PORT (default 22), MCP_AI_SSH_REMOTE_HOST (default localhost), MCP_AI_SSH_REMOTE_PORT (default 80), MCP_AI_LOCAL_PORT (default: free port), MCP_AI_SSH_CMD (default ssh), MCP_AI_SSH_EXTRA_ARGS, MCP_AI_SSH_BATCH_MODE, MCP_AI_SSH_READY_MS (default 15000). Same token, Host-header, timeout, and env-file variables as the HTTPS relay.

Secret file

Keep tokens out of settings files:

# ~/.nvoos-bridge.env  (chmod 600)

MCP_AI_BASE_URL=https://your-site.com/wp-json/mcp-ai/v1/mcp MCP_AI_TOKEN=cred_xxxxx.SECRET

Values already present in the process environment win over the file, so per-project overrides still work.

Behavior contract

• Reads one JSON-RPC 2.0 object per stdin line, POSTs it to the endpoint (Authorization: Bearer …), writes the response as one stdout line.
• Notifications (no id) get no response, ever.
• Streamable HTTP: the relay advertises both media types (Accept: application/json, text/event-stream) and transparently unwraps SSE-framed responses (event: message + data: ) — SDK-v2 servers such as the NV Astro storefront answer in SSE whenever the client accepts it.
• Session bootstrap (opt-in): with MCP_AI_LOGIN_URL (or MCP_AI_COOKIE) configured, the bridge logs in at startup, attaches the session cookie to every request, and re-establishes the session once on an upstream 401/403 or near cookie expiry. Without session env vars the relay stays a fully transparent transport (HTTP statuses pass through untouched).
• All diagnostics go to stderr — stdout carries MCP messages only.
• On stdin EOF, in-flight requests drain before exit.
• The SSH tunnel is torn down when the relay exits — including on hard kill (the bridge holds ssh's stdin open for exactly this reason).

Development

The package files under bin/ are byte-identical copies of the repo's bin/mcp-bridge.js, bin/mcp-bridge-ssh.js, and bin/utils/env-file.js — the repo bin/ is canonical. Edit there, then:

npm run sync               # refresh the copies

npm run sync -- --check # drift gate (run in CI) npm test # node:test suite (in-process fake endpoint/ssh) npm run pack:dry-run # inspect the tarball before publishing

Optional Docker E2E against a live NV oOS site (skips when env is unset):

MCP_AI_BASE_URL=http://localhost:8000/wp-json/mcp-ai/v1/mcp \

MCP_AI_TOKEN=cred_xxxxx.SECRET \ npm run test:e2e

Ecosystem discovery

This package is listed in the official MCP Registry (registry.modelcontextprotocol.io) as io.github.nvdigitalsolutions/nvoos-mcp-bridge (stdio / npm). The registry name is declared via the mcpName field in package.json (ownership verification marker); the registry metadata itself lives in server.json and is published with the mcp-publisher CLI. Community directories (mcpservers.org, Glama, PulseMCP, mcp.directory, the awesome-mcp-servers list) carry entries that point back to this package and its registry record.

License

GPL-3.0-or-later — see LICENSE.