governed-mcp-gateway

Cubiczan Agent Platform

为真正投入使用的 Agent 提供身份、资金和证据。

三个 SKU，一个工作区。MCP 客户端在 tools/call 和 SSE 中保留 Bearer 主体。没有授权书，支出就无法结算；超过上限时，还需要人工第二把密钥。没有 Agent、CHP 锁和哈希文档，董事会声明就无法封存。

SKU	端口	源码	职责
Governed MCP Gateway	:7474	Cubiczan/governed-mcp-gateway	每次工具调用和每个 SSE 帧都包含主体。托管凭据轮换。工具允许列表。模式 Token 成本账本，以及按包 / 按需允许的 tools/list。
Agent Spend & Mandate Plane	:7475	此工作区	提议 → 授权 → 会签 → 结算。默认使用 Stripe；x402 是一种支付通道。
Auditable CFO Agent Mesh	:7476	此工作区	声明 → Agent → 锁 → 文档。ASC 842 / 606 / 718 引擎。HMAC 链式证据包。

共享基础组件（packages/shared）：CHP 门控、HMAC 账本、HTTP/SSE 辅助工具。运行时不依赖 npm。Stripe 和 x402 是支付通道——测试不会调用实际网络。

快速开始

npm install
npm test
npm run gateway   # :7474
npm run spend     # :7475
npm run cfo       # :7476

演示用 Bearer 密钥（也见 .env.example）：

角色	密钥
网关 Agent	mcp_agt_payops_demo
网关人工用户	mcp_human_controller_demo
网关研究 Agent（无 stripe.charge）	mcp_agt_research_demo
支出 Agent	spend_agt_payops_demo
支出人工用户	spend_human_controller_demo
CFO Agent	cfo_agt_lease_demo
CFO 人工用户	cfo_human_controller_demo

从本地运行的 API 重新生成 README 卡片：

npm run shots

---

1. Governed MCP Gateway

生产环境中的 MCP 会丢失身份信息。listTools 在请求线程上运行；tools/call 和 SSE 则在其他位置运行。此网关会将 Bearer 凭据解析为一个 Principal，在每次 JSON-RPC 调用中注入该主体，并在每个 SSE 帧中重复携带该主体。已命名的保险库输入会原地轮换——github_token 仍是 github_token。

curl -sS -H "Authorization: Bearer mcp_agt_payops_demo" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"echo.ping","arguments":{"hello":"world"}}}' \
  http://127.0.0.1:7474/mcp

方法	路径	说明
GET	/health /healthz	存活状态（{ ok, service, transport, mode }）。无需身份验证。
POST	/mcp	Streamable HTTP JSON-RPC initialize、tools/list（默认：会话包）、tools/call
GET	/mcp/sse?once=1	本地 SSE 通知，包含 _meta.cubiczan.principal（不是 Vercel 路径）
GET	/v1/context/tax	模式 Token 成本统计和会话报告
POST	/v1/context/need	将允许列表中的工具加入会话包
POST	/v1/credentials/:name/rotate	仅限人工用户的保险库轮换；旧哈希失效
POST	/v1/credentials/verify	根据当前哈希检查密钥

Glama 远程连接器

Glama 可以使用 Bearer 身份验证，对 https://$VERCEL_URL/mcp 上的无状态 Streamable HTTP 远程服务进行健康检查。这是托管的 HTTPS 接入路径。Stdio（npm run mcp / Dockerfile CMD）仍是 Glama Docker 构建路径。

Vercel 项目设置（导入此 GitHub 仓库；不要自行编造主机名）：

设置	值
Root Directory	.（仓库根目录 — vercel.json + api/）
Framework Preset	Other（vercel.json 设置 "framework": null）
Fluid Compute	On（"fluid": true）
Node.js	20 或更高版本
Install Command	npm ci && npm run build（vercel.json 已设置此项）
Build Command	npm run build（esbuild → dist/web.mjs；不要运行 tsc）
Output Directory	public（Other 预设所需的空静态目录；Fluid 仍会提供 /api）

npm run build 会运行 scripts/build-vercel.mjs（esbuild），并生成 dist/web.mjs。api/index.mjs 会导入该编译文件——它不会通过运行时 tsx 加载 TypeScript。演示允许列表和超大模式的种子数据会内联到该 bundle 中，因此 Fluid 不会打开 test/fixtures/（函数只包含 dist/**）。使用自定义 buildCommand 时，Other 预设仍要求有一个静态输出文件夹；该文件夹就是 public/（outputDirectory: "public"）。如果 Vercel 控制台中的 Build Command 仍设为 tsc，请清除该设置或将其设为 npm run build，以免再次出现 TS5097。只要 vercel.json 生效，就不需要在控制台中覆盖设置。

环境变量（Vercel Project → Settings → Environment Variables）。在公开 URL 上线前，请轮换演示值：

名称	本地演示值	用途
GATEWAY_AGENT_KEY	mcp_agt_payops_demo	Glama 连接器 Bearer（PayOps 允许列表）
GATEWAY_HUMAN_KEY	mcp_human_controller_demo	保管库 / 锁
GATEWAY_RESEARCH_KEY	mcp_agt_research_demo	研究允许列表（不含 stripe.charge）
SPEND_PLANE_URL	未设置	:7475 的可选钩子

部署后配置 Glama 连接器字段（将 $VERCEL_URL 替换为 Vercel 显示的部署主机名）：

• URL：https://$VERCEL_URL/mcp
• 传输方式：Streamable HTTP
• 身份验证：Bearer $GATEWAY_AGENT_KEY

本地冒烟测试（无需公开主机名）：

npm run mcp:http:smoke
# or:
npm run gateway
curl -sS http://127.0.0.1:7474/health
curl -sS -H "Authorization: Bearer mcp_agt_payops_demo" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  http://127.0.0.1:7474/mcp

initialize 不会生成 Mcp-Session-Id。如果需要会话包以外的内容，请在同一次 tools/list 调用中传入 params.pack / params.need。GET /mcp 返回 405（远程服务不支持粘性 SSE）。

---

2. Agent 支出与授权平面

Agent 提议，授权指令负责授权。金额超过自动上限时，需要人工联签。提议的 Agent 不能为自己的提议联签。结算通过支付通道进行：默认使用 Stripe meter event；如有需要，也可使用 x402 payment-required。此 MVP 不会进行链上调用。

curl -sS -H "Authorization: Bearer spend_agt_payops_demo" \
  -H "Content-Type: application/json" \
  -d '{"agent":"agt_payops","merchant":{"name":"Stripe","url":"https://stripe.com","country":"US"},"total":"12.00","rationale":"tool meter"}' \
  http://127.0.0.1:7475/v1/proposals

方法	路径	说明
POST	/v1/mandates	操作者创建剩余金额（分）额度
POST	/v1/proposals	Agent 提议；通道为 auto | approval | blocked
POST	/v1/countersign	人工使用第二把密钥联签；拒绝 Agent
POST	/v1/settle	{ "rail": "stripe" } 或 "x402"

3. 可审计的 CFO Agent 网格

董事会声明只有在具备一个 Agent、处于 LOCKED 的 CHP 状态，并且至少有一个源文档哈希后，才算完成。引擎负责计量（ASC 842 租赁滚存、ASC 606 受限 POC、ASC 718 SBC），不会裁定法律事实。Token 支出作为来源，附加到同一条 HMAC 链式账本上。

curl -sS -H "Authorization: Bearer cfo_agt_lease_demo" \
  -H "Content-Type: application/json" \
  -d '{"title":"AI spend is $12.00 this period","narrative":"Token ledger supports the board claim.","agentId":"agt_lease"}' \
  http://127.0.0.1:7476/v1/claims

方法	路径	说明
POST	/v1/claims	新建声明
POST	/v1/claims/:id/documents	附加具名来源；存储 SHA-256
POST	/v1/claims/:id/lock	人工锁定 → LOCKED
POST	/v1/engines/lease	ASC 842 分类与滚存
GET	/v1/evidence/:id	密封；没有文档或未锁定时返回 400

规范

OpenSpec 变更：ship-three-sku-platform、tools-list-token-tax、glama-streamable-http-remote、vercel-compiled-fluid-entry、vercel-public-output-directory。

许可证

MIT