NV oOS Gateway

NV oOS MCP Gateway

==================

面向 NV oOS（Open Operator System） WordPress 平台的公开、面向整个站群的 Model Context Protocol 端点。一个 API 密钥即可访问所有已绑定站点，工具会以 <site-slug>.<tool> 的形式添加命名空间。

该网关是一个 MCP 聚合代理，使用可流式传输的 HTTP（MCP 2026-07-28）：它使用公开 API 密钥验证调用方，通过 Fleet Operator 令牌，将 initialize / tools/list / tools/call 转发到已绑定 NV oOS 站点的原生 /wp-json/mcp-ai/v1/mcp 端点，并为每个站点的工具名称添加前缀，避免站群中的名称冲突。

部署目标：Cloudways Velocity（托管式 Node 托管），地址为 https://mcp.nvoos.pro。详见 docs/operations/deployment/mcp-gateway-velocity-setup.md。

单向镜像：此插件是规范源，并通过 sync-mcp-gateway.yml 同步到独立仓库 nvdigitalsolutions/nvoos-mcp-gateway（分支 main）。每次同步都会将子树快照为一个提交，并在不使用 --force 的情况下推送——镜像仓库的 main 分支保持线性快进历史，因此托管平台（Cloudways Velocity）会在每次同步时自动部署。切勿直接向独立仓库提交内容——下一次同步会覆盖这些内容。

---

端点

路由	身份验证	用途
GET /mcp	公开	可流式传输的 HTTP 发现 JSON
POST /mcp	Bearer 密钥	JSON-RPC 2.0（initialize、ping、notifications、tools/list、tools/call、resources/、prompts/）
GET /health	公开	最简状态信息 + 按站点划分的健康状态注册表
GET /health/full	Bearer 密钥	完整视图（仅含主机的 URL、绑定信息）
GET /admin/policy	Operator 令牌	生效的策略 + 配额表（只读）
POST /admin/policy-sim	Operator 令牌	使用记录的调用回放候选策略
GET /admin/catalog	Operator 令牌	含各站点生命周期状态的站群目录
GET /	公开	面向目录审核人员的人工可读首页

配置（仅限环境变量）

变量	必需	用途
GATEWAY_PUBLIC_KEYS	是	公钥 → 站点 slug：key=slug-a,slug-b;key2=slug-c（或 JSON 对象）
GATEWAY_PUBLIC_KEYS_PREVIOUS	否	轮换重叠——旧密钥映射（使用时警告一次）
PUBLIC_SITE_SLUGS	否	公共 /health 端点的隐私筛选器：无需身份验证即可查看的 slug，以逗号分隔（* 或未设置 = 所有已配置站点）。/health/full 始终报告所有站点。
NVOOS_SITE_<SLUG>_URL	每个站点	上游 MCP 端点，完整 URL，包含 /wp-json/mcp-ai/v1/mcp
NVOOS_SITE_<SLUG>_TOKEN	每个站点	Fleet Operator 令牌（op_xxxx.SECRET）；绝不记录或返回
AUTH_MODE	否	strict（默认）在未设置密钥时于启动阶段拒绝启动
UPSTREAM_TIMEOUT_MS	否	每个站点的 tools/list 和通知超时（默认 20000）
UPSTREAM_TOOL_TIMEOUT_MS	否	仅用于 tools/call 的时限——为长时间运行的工具留出更多时间，而不拖慢 tools/list（默认值：UPSTREAM_TIMEOUT_MS）
GATEWAY_OAUTH_ISSUER	否	OAuth 2.1 授权服务器颁发者（例如 Auth0 租户）。设置后，网关将成为符合 RFC 9728 的受保护资源——参见下方 OAuth 部分
GATEWAY_OAUTH_JWKS_URI	否	JWKS 覆盖值（默认使用颁发者的 /.well-known/jwks.json）
GATEWAY_OAUTH_RESOURCE	否	RFC 8707 资源标识符 / 令牌受众（默认 https://mcp.nvoos.pro）
TRUST_PROXY	Velocity 上必需	1——NGINX 设置 X-Forwarded-For
ALLOWED_ORIGINS	否	面向浏览器的客户端使用的 CORS 来源，以逗号分隔
MAX_JSON_BODY	否	请求正文大小上限（默认 1mb）
RATE_LIMIT_GLOBAL / _MCP / _HEALTH	否	各组限额（默认分别为 600/5min、120/min、60/min）
TOOL_QUOTAS	否	每个工具的配额，简写格式：<pattern>:<rate>/<window>:<burst>——例如 delete_post:5/1h:2,woo_*:60/1m:*。优先采用最具体的 pattern。（提案 094）
GATEWAY_POLICY	否	策略规则集（JSON 字符串）——参见下方策略参考。（提案 094）
POLICY_FILE	否	替代方式：JSON 策略文件的路径（由 Git 版本控制的策略，在启动时读取）。
SHADOW_POLICY	否	影子规则集（JSON 字符串）——仅评估并记录，不会强制执行。
GEO_MAP	否	将公共密钥 ID 映射到 ISO 国家代码的 JSON 对象（未使用可信代理时使用）。
GATEWAY_ADMIN_TOKEN	否	启用 /admin/* 接口的操作员令牌（未设置时不起作用）。
AUDIT_SINK_URL / AUDIT_SINK_SECRET	否	用于治理事件的 HMAC 签名 Webhook（deny、quota_exceeded、call_ok 等）。必须同时设置。
SITE_LIFECYCLE	否	每个站点的目录状态：slug-a:draft,slug-b:published（默认 published）。

Slug → 环境变量后缀映射：site-a → NVOOS_SITE_SITE_A_*（大写， 连字符 → 下划线）。

示例

GATEWAY_PUBLIC_KEYS=demo-public-key-1234567890=demo-site
NVOOS_SITE_DEMO_SITE_URL=https://demo.example.com/wp-json/mcp-ai/v1/mcp
NVOOS_SITE_DEMO_SITE_TOKEN=op_xxxx.SECRET
AUTH_MODE=strict
TRUST_PROXY=1

策略与配额（提案 094）

每个工具的配额和声明式策略在各组限额之上生效。 站点仍是深层强制执行层（每个工具的 RPM、令牌预算、 迭代上限、能力边界、恶意使用时自动关闭）—— 网关增加了集群层，只能收紧限制，不能放宽。

配额

TOOL_QUOTAS=delete_post:5/1h:2,woo_*:60/1m:*,*:600/5m:*

超限时返回 HTTP 429 和 RFC 9558 标头 （RateLimit-Limit/Remaining/Reset、RateLimit-Policy），并附带 JSON-RPC 错误 -32099。计数桶按 (key × site × tool) 划分——一个过度活跃的密钥 无法耗尽其他密钥的配额。

策略语法

{
  "rules": [
    {
      "id": "no-night-deletes",
      "effect": "deny",
      "tool": { "match": "delete_*" },
      "time": { "window": { "tz": "Europe/London", "days": [1,2,3,4,5], "start": "09:00", "end": "17:00" } }
    }
  ]
}

首次匹配优先。效果：deny（403 + -32001）、require_approval （428 + -32002，附带经过脱敏的预览）。条件：tool.match（glob）、 site、key、time.window（IANA 时区、ISO 星期 1–7、跨午夜的时间窗口）、 geo.country（ISO alpha-2）。被拒绝的工具会从 tools/list 中完全筛除（不会进入模型上下文）。

检查

• 在 tools/call 中设置 dryRun: true，会评估策略和配额，但不会执行或消耗配额——结果包含 would_execute、policy 和 quota。
• POST /admin/policy-sim 会针对最近记录的 200 次调用（仅参数键）重放候选策略，并与当前策略进行比较。
• SHADOW_POLICY 会并行评估并记录日志，但绝不强制执行。

工具命名空间

• tools/list 会合并绑定到该密钥的所有站点，并为名称添加前缀：site-a.create_post、site-b.woo_get_products。
• tools/call 始终接受带前缀的名称；若该密钥仅绑定一个站点，也接受不带前缀的名称（直通模式）。
• 上游服务发生故障时，不会导致整个调用失败，而是将错误添加到 _meta.gateway.errors。
• v1 聚合限制：resources/* 和 prompts/* 使用第一个绑定的站点。

行为与安全

• 协议协商：initialize 会回显双方支持的最高协议版本（2026-07-28 → 2024-11-05）；若客户端未发送版本，则默认为 2024-11-05。若服务器硬编码的版本不受严格客户端（Zed、Claude Desktop）支持，客户端会以“Unsupported protocol version”中止。
• 无状态——v1 不支持会话和 SSE（2026 年 7 月的规范修订将无状态传输列为一等功能）。
• 默认拒绝：严格模式下未配置密钥时，启动会被拒绝；密钥未绑定任何已配置站点时返回 503；未知密钥返回带有 WWW-Authenticate 的 401。
• 速率限制按公钥分别计算（一个繁忙的密钥不会耗尽另一个密钥的额度）；上游令牌仅通过标头传递，绝不会出现在响应、日志或错误中。
• 身份验证：v1 使用静态 API 密钥；文档所述的升级路径为 OAuth 2.1（RFC 8414 + 动态客户端注册）。

Claude Code 插件

该附加组件附带一个 Claude Code 插件（.claude-plugin/plugin.json、commands/connect.md、skills/gateway/），会同步到镜像仓库，同时也作为市场来源：

/plugin marketplace add nvdigitalsolutions/nvoos-mcp-gateway

启用插件时，系统会提示输入网关 API 密钥（以敏感的 userConfig 选项安全存储），并将其填入 MCP 服务的 Authorization 标头。

OAuth 2.1 资源服务（可选）

设置 GATEWAY_OAUTH_ISSUER 后，网关会在静态密钥之外，同时充当 RFC 9728 受保护资源：

• GET /.well-known/oauth-protected-resource（以及路径中插入 /mcp 的变体）会提供受保护资源元数据文档（未配置 OAuth 时返回无操作的 404）。
• 401 响应会携带 WWW-Authenticate: Bearer resource_metadata="…", scope="…"，使 MCP 客户端可以针对已配置的授权服务器执行 OAuth 2.1 授权码 + PKCE 流程。
• JWT 持有者令牌会根据 AS JWKS 进行验证（缓存，失败时拒绝）：签名、iss、aud（RFC 8707 资源绑定）、exp/nbf 和作用域。
• 站点绑定基于作用域：每个 site:<slug> 作用域都会授权访问对应绑定的站点（只读的 site:read 作用域会予以公布，以供未来实施细粒度强制执行）。未授权访问任何已配置站点的令牌会收到 403 insufficient_scope。
• 上游代理逻辑不变：网关始终使用站点自己的 Fleet Operator 令牌进行交换——OAuth 令牌绝不会转发到上游（不存在混淆代理式直通）。

授权服务器：任何提供 RFC 8414 元数据和 JWKS 的 OAuth 2.1 AS（Auth0 是平台惯例）。动态客户端注册（RFC 7591）由 AS 负责，而非网关。

开发

npm install
npm test        # node:test suites — fake upstreams, no infrastructure
npm run dev     # node --watch src/index.js

针对 Docker Compose 开发站点的本地冒烟测试：

GATEWAY_PUBLIC_KEYS="dev-key-1234567890abcd=docker" \
NVOOS_SITE_DOCKER_URL="http://localhost:8000/wp-json/mcp-ai/v1/mcp" \
NVOOS_SITE_DOCKER_TOKEN="<assistant/operator token>" \
PORT=8899 npm start
# → curl http://127.0.0.1:8899/mcp

生态发现

公共端点 https://mcp.nvoos.pro/mcp 已列入官方 MCP 注册表（registry.modelcontextprotocol.io），名称为 io.github.nvdigitalsolutions/nvoos-mcp-gateway——一个需要 Authorization 标头的可流式 HTTP 远程服务。注册表元数据存放在 server.json 中，并通过 mcp-publisher CLI 发布。社区目录（mcpservers.org、mcp.directory、PulseMCP、Glama）收录的条目均指向此处；GET / 落地页是供目录审核者查看的页面。

许可证

GPL-3.0-or-later——详见仓库中的 LICENSE。