agent-services-mcp

agent-services-mcp

一个轻量级 MCP（模型上下文协议）服务，将三个现有服务作为可发现的工具公开，让 AI Agent 和兼容 MCP 的客户端通过一个连接即可找到并使用这些工具：

• provenance-receipts — 证明内容来源；返回 Ed25519 签名的凭证。
• quality-gate — 根据已发布的评分标准评估内容质量；返回 Ed25519 签名的评分凭证。
• agent-action-audit — 为 Agent 执行的操作签发防篡改审计凭证（用于 Agent 问责）；返回 Ed25519 签名的审计凭证。

这是一个轻量级封装。 每个工具都会向底层 Worker 转发 HTTP 调用，并原样返回其响应。它不会重新实现签名、评分或支付逻辑——这些逻辑由底层服务负责。工具描述也会如实说明每项服务能够证明什么。

快速入门 — 约 2 分钟完成首次（免费）调用

npm install && npm run build
node examples/free-call.mjs       # connects to the LIVE services and calls a free tool

examples/free-call.mjs 会使用 MCP 客户端调用此服务（指向线上部署），并调用 get_quality_rubric 和 verify_audit——两者免费，无需钱包。如需将服务接入 MCP 客户端（类似 Claude Desktop / Claude Code），请参阅下文的连接 MCP 客户端。

免费与付费一览： verify_provenance、verify_quality、verify_audit 和 get_quality_rubric 均为免费。certify_provenance、score_quality 和 audit_action 为付费工具（在 Base 上通过 x402 使用 USDC 进行小额支付）——两步支付流程和可运行示例请参阅调用付费工具。

封装的服务能够证明（以及不能证明）的内容

• 来源： 证明内容未被修改（SHA-256 哈希），且凭证由服务的密钥签发。generator_metadata 由调用方声明——它证明你声称了这一点，而不是证明某个特定模型确实运行过。这不是 AI 检测，也不保证内容真实。
• 质量： 根据已发布的评分标准（清晰度、完整性、内部一致性、明显错误的缺失情况）得出的可复现评分。它不代表绝对真相，不是外部标准，也不是事实核查。请通过 get_quality_rubric 工具查看评分标准。
• 审计： 证明操作记录真实有效（由服务的密钥签发），并且自签发后未被篡改（防篡改）。action、actor_metadata 和 context 均由调用方声明——它证明你声称了这条记录，而不是证明 Agent 的声明属实。这是一个问责／审计工具，不是测谎仪。

工具

工具	转发至	是否付费？	输入
certify_provenance	provenance-receipts POST /v1/certify	是（x402）	content（字符串），generator_metadata（对象，可选）
verify_provenance	provenance-receipts POST /v1/verify	否	content（字符串），receipt（对象）
score_quality	quality-gate POST /v1/score	是（x402）	content（字符串），rubric_version（字符串，可选），target_score（数字 0–100，可选）
verify_quality	quality-gate POST /v1/verify	否	content（字符串），receipt（对象）
get_quality_rubric	quality-gate GET /v1/rubric	否	无
audit_action	agent-action-audit POST /v1/audit	是（x402）	action（字符串），actor_metadata（对象），context（对象，可选）
verify_audit	agent-action-audit POST /v1/verify	否	action（字符串），actor_metadata（对象），context（对象，可选），receipt（对象）

完整描述和 Zod 输入/输出架构：src/tools.ts。 每个工具都会以文本形式返回服务的原始 JSON（rubric 则返回 Markdown）；verify_* 和 score_quality 工具还声明了 outputSchema，并返回可直接读取的已解析 structuredContent（例如 result.structuredContent.valid）。 非 2xx 响应（包括 402 Payment Required）会通过 isError: true 显示，并保留响应正文；对于 402，封装器会在前面添加简短且可执行的付款说明。三个付费工具还接受可选的 x_payment 输入（x402 X-PAYMENT 令牌），通过封装器完成付款——请参阅调用付费工具。

配置

三个服务 URL 均可通过环境变量配置（不含密钥，只有基础 URL）：

环境变量	线上（已部署）	本地开发回退值
PROVENANCE_URL	https://provenance-receipts.gpmiddleton71.workers.dev	http://localhost:8787
QUALITY_GATE_URL	https://quality-gate.gpmiddleton71.workers.dev	http://localhost:8788
AUDIT_URL	https://agent-action-audit.gpmiddleton71.workers.dev	http://localhost:8789

.env.example 和下方的客户端配置指向线上部署。如果未设置这些变量，服务会回退到 localhost，以供本地 wrangler dev 使用（Workers 默认使用 :8787，因此请将 quality-gate 运行在 :8788，并将 agent-action-audit 运行在 :8789，以避免冲突）。

使用线上服务时，付费工具（certify_provenance、score_quality、audit_action）需要 x402——此封装器会转发请求，但不持有钱包，因此如果没有 X-PAYMENT，这些工具会返回 402（付款要求），并通过 isError 显示。免费工具可正常使用。

调用付费工具（x402）

这三个付费工具需要支付 x402 小额款项（Base 主网上的 USDC）。包装器 不持有钱包——绝不会代你付款——因此付款分为两个步骤：

1. 不带 x_payment 调用工具。你会收到一个 402，其正文包含 x402 付款要求（网络、资产、金额、payTo）。包装器会在前面添加一行说明，解释接下来该怎么做。
2. 使用 x402 客户端和已注资的钱包，根据这些要求生成 x402 X-PAYMENT 令牌，然后**再次调用该工具，并在 x_payment 输入中传入该令牌。**包装器会将其作为 X-PAYMENT 标头转发；底层服务会验证并结算付款，然后返回已签名的收据。

要完成实际可用的付费调用，最简单的方法是：使用 x402 客户端直接向底层服务结算：

npm install x402-fetch
BUYER_PRIVATE_KEY=0x...  node examples/paid-call.mjs

examples/paid-call.mjs 使用 x402-fetch 和一个一次性 Base 主网钱包 （其中有少量真实 USDC），为 audit_action 付款并调用它。约有 0.01 USDC 从 买方转至服务的 payTo 地址，无需支付 Gas（由支付中介支付 Gas）。这是真实资金——请仅使用内有几美分的临时密钥。certify_provenance 和 score_quality 也适用同样的方式。

快速入门（本地）

# 1. Build the MCP server
npm install
npm run build            # -> dist/index.js

# 2. In separate terminals, run the three services (free; payments off)
#    (provenance-receipts) npm run dev                 # http://localhost:8787
#    (quality-gate)        npx wrangler dev --port 8788 # http://localhost:8788
#    (agent-action-audit)  npx wrangler dev --port 8789 # http://localhost:8789

# 3a. Smoke-test the free tool paths through an MCP stdio client
node scripts/test-client.mjs

# 3b. (optional, costs ~$0.012) prove the paid score_quality path end-to-end
node scripts/test-score.mjs

# 3c. Smoke-test the wrapper against the LIVE deployed services (free — the
#     paid tools return a forwarded 402; no payment, no scoring call)
node scripts/test-live.mjs

scripts/test-client.mjs 在本地测试免费工具；scripts/test-score.mjs 通过 score_quality 发起一次真实的 Anthropic 评分调用； scripts/test-live.mjs 将包装器指向已部署的 workers.dev URL，并断言免费工具可用，且付费工具会转发 x402 402。

连接 MCP 客户端（stdio）

此服务通过 stdio（stdin/stdout）使用 MCP。任何 MCP 客户端都会将其作为子进程启动。Claude Desktop / Claude Code 风格的 mcpServers 配置示例：

{
  "mcpServers": {
    "agent-services": {
      "command": "node",
      "args": ["C:\\Users\\Gareth\\agent-services-mcp\\dist\\index.js"],
      "env": {
        "PROVENANCE_URL": "https://provenance-receipts.gpmiddleton71.workers.dev",
        "QUALITY_GATE_URL": "https://quality-gate.gpmiddleton71.workers.dev",
        "AUDIT_URL": "https://agent-action-audit.gpmiddleton71.workers.dev"
      }
    }
  }
}

• 先运行 npm run build，确保 dist/index.js 存在。
• 客户端连接后会调用 tools/list（会看到上面的 7 个工具），并通过 tools/call 调用它们。
• 调用工具时，底层服务必须可通过配置的 URL 访问。
• 日志会输出到 stderr；stdout 专用于 MCP 协议。

通过 SDK 的 Client + StdioClientTransport 以编程方式连接 （command: "node"、args: ["dist/index.js"]）——参见 scripts/test-client.mjs。

x402 付款（仅转发，不在此处处理）

付费端点（/v1/certify、/v1/score、/v1/audit）由底层服务通过 x402 限制访问。此包装器只会 转发请求，不持有钱包。如果服务已启用付款，且未提供有效的 X-PAYMENT，则会返回 402 和付款 要求——包装器会将其作为 isError 返回，并完整保留要求正文。结算付款（签署 x402 授权）是客户端 针对底层服务的责任。x402 详情请参阅各服务的 README.md / docs/API.md。仅限 Base Sepolia 测试网——不支持主网。

独立验证收据

certify_provenance、score_quality 和 audit_action 返回的收据均由 Ed25519 签名，无需信任这些服务中的任何一个即可验证—— 重新计算内容／记录的哈希，并使用服务的公钥验证签名。每项服务都提供可运行的独立验证器和操作指南：参见 provenance-receipts/docs/VERIFYING.md、 quality-gate/docs/VERIFYING.md， 以及 agent-action-audit 的 docs/VERIFYING.md。

构建状态

• 步骤 1 — 框架骨架 + 工具定义（src/tools.ts）
• 步骤 2 — 工具处理程序（HTTP 转发）+ 本地冒烟测试
• 步骤 3 — README：项目介绍、工具，以及 MCP 客户端的连接方式
• 已上线 — 指向已部署的服务（*.gpmiddleton71.workers.dev） 并通过 scripts/test-live.mjs 完成端到端验证：免费工具可用；付费 工具会转发 x402 402。

所有 7 条工具路径均已针对线上部署完成验证（包括通过包装器端到端调用一次付费的 score_quality）；付费工具（certify_provenance、score_quality、audit_action）会转发 x402 402。

技术栈

• 官方 MCP SDK：@modelcontextprotocol/sdk v1.29.0（TypeScript），stdio 传输，使用 zod 定义输入架构。
• Node ESM + TypeScript（tsc → dist/）。

项目结构

agent-services-mcp/
├── src/
│   ├── index.ts     # MCP server: registers tools, forwards HTTP, stdio transport
│   └── tools.ts     # the 7 tool definitions (names, descriptions, Zod schemas)
├── scripts/
│   ├── test-client.mjs  # MCP stdio client — free tool smoke test (local)
│   ├── test-score.mjs   # MCP stdio client — one paid score_quality e2e check
│   └── test-live.mjs    # MCP stdio client — against the live deployed services
├── package.json
├── tsconfig.json
├── .gitignore
└── .env.example     # PROVENANCE_URL, QUALITY_GATE_URL, AUDIT_URL