NV oOS Gateway

NV oOS MCP Gateway

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

NV oOS（Open Operator System） WordPress プラットフォーム向けの、フリート単位でスコープされた公開 Model Context Protocol エンドポイントです。API キーは 1 つで、紐付けられたすべてのサイトを利用できます。ツールは <site-slug>.<tool> の形式で名前空間が付与されます。

このゲートウェイは、ストリーミング可能な HTTP（MCP 2026-07-28）を使用する MCP 集約プロキシです。公開 API キーで呼び出し元を認証し、Fleet Operator トークンを使って、紐付けられた NV oOS サイトのネイティブな /wp-json/mcp-ai/v1/mcp エンドポイントに initialize / tools/list / tools/call を転送します。また、サイトごとにツール名にプレフィックスを付けて、フリート全体での名前の衝突を防ぎます。

デプロイ先は Cloudways Velocity（マネージド Node ホスティング）で、URL は https://mcp.nvoos.pro です。詳しくは docs/operations/deployment/mcp-gateway-velocity-setup.md を参照してください。

一方向ミラー： このアドオンが正本であり、sync-mcp-gateway.yml によって、スタンドアロンリポジトリ nvdigitalsolutions/nvoos-mcp-gateway（ブランチ main）に同期されます。このワークフローは、同期のたびにサブツリーを 1 つのコミットとしてスナップショットし、--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	yes	公開鍵 → サイトスラッグ：key=slug-a,slug-b;key2=slug-c（または JSON オブジェクト）
GATEWAY_PUBLIC_KEYS_PREVIOUS	no	ローテーション時の重複期間 — 前の鍵マップ（使用時に一度警告）
PUBLIC_SITE_SLUGS	no	公開 /health エンドポイントのプライバシーフィルター：認証なしで表示するスラッグをカンマ区切りで指定します（* または未設定の場合、設定済みのすべてのサイト）。/health/full では常にすべてのサイトが報告されます。
NVOOS_SITE_<SLUG>_URL	per site	上流の MCP エンドポイント。/wp-json/mcp-ai/v1/mcp を含む完全な URL
NVOOS_SITE_<SLUG>_TOKEN	per site	Fleet Operator トークン（op_xxxx.SECRET）。ログへの記録や返却は行われません
AUTH_MODE	no	strict（デフォルト）では、キーが設定されていない場合、起動時にフェイルクローズします
UPSTREAM_TIMEOUT_MS	no	サイトごとの tools/list と通知のタイムアウト（デフォルト 20000）
UPSTREAM_TOOL_TIMEOUT_MS	no	tools/call のみの制限時間 — 長時間実行するツールに余裕を持たせても、tools/list は遅くなりません（デフォルト：UPSTREAM_TIMEOUT_MS）
GATEWAY_OAUTH_ISSUER	no	OAuth 2.1 認可サーバーの発行者（例：Auth0 テナント）。設定すると、ゲートウェイは RFC 9728 保護リソースになります — 以下の OAuth セクションを参照してください
GATEWAY_OAUTH_JWKS_URI	no	JWKS のオーバーライド（デフォルトは発行者の /.well-known/jwks.json）
GATEWAY_OAUTH_RESOURCE	no	RFC 8707 リソース識別子／トークンのオーディエンス（デフォルト https://mcp.nvoos.pro）
TRUST_PROXY	Velocity では yes	1 — NGINX が X-Forwarded-For を設定します
ALLOWED_ORIGINS	no	ブラウザベースのクライアント向け CORS オリジンをカンマ区切りで指定します
MAX_JSON_BODY	no	リクエストボディの上限（デフォルト 1mb）
RATE_LIMIT_GLOBAL / _MCP / _HEALTH	no	グループごとの上限（デフォルトは 600/5min、120/min、60/min）
TOOL_QUOTAS	no	ツールごとの割り当て。簡潔な形式：<pattern>:<rate>/<window>:<burst> — 例：delete_post:5/1h:2,woo_*:60/1m:*。最も具体的なパターンが優先されます。（Proposal 094）
GATEWAY_POLICY	no	ポリシールールセット（JSON 文字列）— 以下のポリシーリファレンスを参照してください。（Proposal 094）
POLICY_FILE	no	代替手段：JSON ポリシーファイルへのパス（Git でバージョン管理されるポリシー。起動時に読み込まれます）。
SHADOW_POLICY	no	シャドウルールセット（JSON 文字列）— 評価・記録されますが、適用はされません。
GEO_MAP	no	公開鍵 ID を ISO 国コードに対応付ける JSON オブジェクト（信頼できるプロキシの背後にない場合に使用）。
GATEWAY_ADMIN_TOKEN	no	/admin/* の機能を有効にするオペレータートークン（未設定の場合は機能しません）。
AUDIT_SINK_URL / AUDIT_SINK_SECRET	no	ガバナンスイベント（deny、quota_exceeded、call_ok など）用の HMAC 署名付き Webhook。両方を設定する必要があります。
SITE_LIFECYCLE	no	サイトごとのカタログ状態：slug-a:draft,slug-b:published（デフォルト published）。

スラッグ → 環境変数のサフィックス対応：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

ポリシーと割り当て（Proposal 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、午前0時をまたぐ時間帯）、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 は、プレフィックス付きの名前を常に受け付けます。また、キーが 1 つのサイトだけにバインドされている場合は、プレフィックスなしの名前も受け付けます（パススルーモード）。
• 上流サービスで障害が発生した場合、呼び出し全体を失敗させるのではなく、リストに _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 になります。
• レート制限は公開鍵ごとに適用されます（1 つのキーによる過剰な使用で、別のキーの割り当てを使い切ることはありません）。上流のトークンはヘッダーのみで扱われ、レスポンス、ログ、エラーに含まれることはありません。
• 認証：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 は、Authorization ヘッダーが必須のストリーミング可能な HTTP リモートとして、公式 MCP レジストリ（registry.modelcontextprotocol.io）に io.github.nvdigitalsolutions/nvoos-mcp-gateway として登録されています。レジストリのメタデータは server.json にあり、mcp-publisher CLI で公開されています。コミュニティのディレクトリ（mcpservers.org、mcp.directory、PulseMCP、Glama） にはここを参照する項目が掲載されています。GET / ランディングページは ディレクトリのレビュー担当者向けのページです。

ライセンス

GPL-3.0-or-later — リポジトリの LICENSE をご覧ください。