NV oOS MCP Bridge

@nvdigitalsolutions/nvoos-mcp-bridge

为 NV oOS（开放式操作系统） WordPress 站点提供零依赖的 MCP stdio ↔ HTTP 中继。

每个 NV oOS 站点都会在 https://<site>/wp-json/mcp-ai/v1/mcp 提供 JSON-RPC 2.0 MCP 端点。大多数编辑器和 Agent（Zed、Claude Desktop、Cursor、Codex）都通过 stdio 启动 MCP 服务——此软件包负责桥接这两种传输方式。软件包提供两个可执行文件：

可执行文件	适用场景
nvoos-mcp	站点可通过 HTTPS 访问（常见情况）
nvoos-mcp-ssh	站点只能通过 SSH 访问（受限 VPS / Cloudways droplet）——自动为你建立 ssh -N -L 端口转发

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

---

快速开始（Zed）

zed: open settings → 添加到 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"
    }
  }
}

然后重新加载 Agent 面板（agent: restart language servers → 或重新打开 面板）。使用 Fleet Operator 管理界面（Settings → External Operators）创建一个限定范围的操作员令牌，并获取可直接粘贴的配置块。

仅支持 SSH 的站点

"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"
    }
  }
}

将 ssh 作为第一个参数传入，以通过 npx 选择 SSH 可执行文件 （npx 只会将主可执行文件作为裸软件包名称公开）。SSH 仅支持密钥认证：必须先确保 ssh <user>@<host> 可以非交互式运行。

其他客户端

环境变量相同，配置文件不同——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"
      }
    }
  }
}

在 Windows 主机上，某些客户端需要使用 cmd 包装器： "command": "cmd", "args": ["/c", "npx", "-y", "@nvdigitalsolutions/nvoos-mcp-bridge@latest"]。

---

配置

所有配置均使用环境变量——切勿将令牌放入 args （否则会显示在进程列表中）。

nvoos-mcp（HTTPS 中继）

变量	必需	默认值	用途
MCP_AI_BASE_URL	✅	—	MCP 端点的完整 URL，例如 https://example.com/wp-json/mcp-ai/v1/mcp
MCP_AI_TOKEN	⚠️	—	Bearer 凭据（cred_xxxxx.SECRET 或操作员令牌 op_xxxxx.SECRET）；未设置时不进行身份验证
MCP_AI_HOST_HEADER		—	覆盖 HTTP Host 标头（适用于代理/隧道后面会因 Host 而执行规范重定向的站点）
MCP_AI_HTTP_TIMEOUT		120000	请求超时时间，单位为毫秒
MCP_AI_ENV_FILE		~/.nvoos-bridge.env	用于存放机密信息的环境变量文件（见下文）

nvoos-mcp-ssh（SSH 版本）

增加了 MCP_AI_SSH_USER、MCP_AI_SSH_HOST（两者均为必需）、MCP_AI_SSH_PORT （默认值为 22）、MCP_AI_SSH_REMOTE_HOST（默认值为 localhost）、 MCP_AI_SSH_REMOTE_PORT（默认值为 80）、MCP_AI_LOCAL_PORT（默认值：可用端口）、 MCP_AI_SSH_CMD（默认值为 ssh）、MCP_AI_SSH_EXTRA_ARGS、 MCP_AI_SSH_BATCH_MODE、MCP_AI_SSH_READY_MS（默认值为 15000）。令牌、 Host 标头、超时和环境变量文件配置与 HTTPS 中继相同。

机密文件

避免在设置文件中存放令牌：

# ~/.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

进程环境中已有的值优先于文件中的值，因此仍可按项目覆盖配置。

---

行为约定

• 每行从 stdin 读取一个 JSON-RPC 2.0 对象，将其 POST 到端点 （Authorization: Bearer …），并将响应作为一行写入 stdout。
• 通知（没有 id）永远不会收到响应。
• 所有诊断信息都写入 stderr——stdout 仅传输 MCP 消息。
• stdin 到达 EOF 时，会等待正在处理的请求完成后再退出。
• 中继退出时会拆除 SSH 隧道——即使进程被强制终止也会如此 （正因如此，桥接程序会一直保持 ssh 的 stdin 打开）。

开发

bin/ 下的软件包文件是仓库中 bin/mcp-bridge.js、 bin/mcp-bridge-ssh.js 和 bin/utils/env-file.js 的逐字节副本—— 仓库的 bin/ 目录为权威版本。在那里修改，然后：

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

可选：通过 Docker 对运行中的 NV oOS 站点执行端到端测试（未设置环境变量时会跳过）：

MCP_AI_BASE_URL=http://localhost:8000/wp-json/mcp-ai/v1/mcp \
MCP_AI_TOKEN=cred_xxxxx.SECRET \
npm run test:e2e

生态系统发现

此软件包已列入 官方 MCP Registry （registry.modelcontextprotocol.io），注册名为 io.github.nvdigitalsolutions/nvoos-mcp-bridge（stdio / npm）。注册名称通过 package.json 中的 mcpName 字段声明（所有权验证标记）；注册表元数据位于 server.json 中，并通过 mcp-publisher CLI 发布。 社区目录（mcpservers.org、Glama、PulseMCP、mcp.directory、awesome-mcp-servers 列表）均收录了指向此软件包及其注册记录的条目。

许可证

GPL-3.0-or-later — 请参阅 LICENSE。