validate

machinegrade validate

在使用 AI 生成的制品前，先根据契约验证它们：

• json_schema — 根据 JSON Schema 验证 artifact（收集所有错误）。
• openapi_response — 根据 OpenAPI 规范中指定 path + method + status 对应的响应架构验证响应正文。
• sql — 检查 SQL 字符串在指定方言中是否存在语法错误。

每项检查都会返回一个判定结果，而不是错误：{valid, errors, latency_ms}， 无论制品是否有效，HTTP 状态码均为 200。只有确实错误的请求 （无效密钥、不支持的类型、格式错误的正文、超出限制）才会返回带类型的 HTTP 错误。

服务运行于 https://api.machinegrade.dev — 提供免费层级、自助申请密钥， 30 秒即可试用（见下方第一个示例）。基于 Hono 构建；同一 代码库可在 Cloudflare Workers（生产环境）和纯 Node（本地 开发环境）上运行，并采用 MIT 许可证，方便你自行托管。

为什么

生成 JSON、API 响应或 SQL 的 Agent 需要在交付结果前，快速、低成本地进行 机器可检查的通过/失败验证 — 比完整的 LLM-as-judge 调用成本更低， 且结果确定。

在本地运行

npm install
npm run dev
# machinegrade validate listening on http://localhost:8787

3 个可运行示例

1. curl

# Get an API key (live service — works as-is)
curl -s -X POST https://api.machinegrade.dev/keys \
  -H 'content-type: application/json' \
  -d '{"email": "[email protected]"}'
# => {"key":"sk_..."}

# Validate a JSON artifact against a JSON Schema
curl -s -X POST https://api.machinegrade.dev/v1/validate \
  -H 'content-type: application/json' \
  -H 'X-Api-Key: sk_...' \
  -d '{
    "type": "json_schema",
    "artifact": {"name": "Ada", "age": 30},
    "contract": {
      "schema": {
        "type": "object",
        "required": ["name", "age"],
        "properties": {"name": {"type": "string"}, "age": {"type": "number"}}
      }
    }
  }'
# => {"valid":true,"errors":[],"latency_ms":1}

2. Python (requests)

import requests

base = "http://localhost:8787"

key = requests.post(f"{base}/keys", json={"email": "[email protected]"}).json()["key"]

resp = requests.post(
    f"{base}/v1/validate",
    headers={"X-Api-Key": key},
    json={
        "type": "sql",
        "artifact": "SELECT id, name FROM users WHERE id = 1",
        "contract": {"dialect": "mysql"},
    },
)
print(resp.status_code, resp.headers.get("X-Calls-Remaining"), resp.json())

3. MCP 配置片段

mcp/server.ts 公开了一个名为 validate 的工具，会转发请求到 POST /v1/validate。将兼容 MCP 的客户端指向它：

{
  "mcpServers": {
    "machinegrade-validate": {
      "command": "npx",
      "args": ["tsx", "mcp/server.ts"],
      "cwd": "/path/to/validate",
      "env": {
        "SANDBOX_URL": "http://localhost:8787",
        "SANDBOX_API_KEY": "sk_..."
      }
    }
  }
}

远程连接

生产服务还直接提供 MCP 端点 — 无需本地进程， 也无需安装 npm — 可通过可流式传输的 HTTP 访问：

POST https://api.machinegrade.dev/mcp

它与上文的 stdio 适配器提供的是同一个 validate 工具。 无需密钥即可使用 initialize 和 tools/list（可匿名发现）； tools/call 需要 X-Api-Key（通过 POST /keys 申请，与 REST API 相同 — 免费层级和限额共用）。

使用 Claude Code：

claude mcp add --transport http validate https://api.machinegrade.dev/mcp --header "X-Api-Key: sk_..."

通过 npm 提供的 stdio 适配器（@machinegrade/validate，见上文）仍可 用于本地/离线场景，或不支持 HTTP 传输的客户端。

Claude Desktop：一键安装

从 Releases 下载最新的 .mcpb 捆绑包， 然后双击。Claude Desktop 会在安装时询问 API 密钥，并将其存储在 操作系统密钥链（macOS Keychain、Windows Credential Manager）中，而非配置文件里 — 不会有任何内容写入 claude_desktop_config.json。

请先申请一个免费密钥（每月 500 次调用）：

curl -s -X POST https://api.machinegrade.dev/keys \
  -H 'content-type: application/json' \
  -d '{"email": "[email protected]"}'

该捆绑包是一个通过 stdio 调用托管 API 的轻量客户端：约 34 KB，不捆绑任何依赖项。如果你选择自行托管，可将扩展程序的 API base URL 设置为 你自己的部署地址，工具便会改为调用该地址。

API

完整契约请参阅 public/openapi.yaml，或在服务运行后查看 /v1/manifest，获取机器可读的 摘要（类型、限额、定价、错误代码）。 /llms.txt 是供 LLM Agent 查看的一份简短说明。

端点	输入	输出
POST /keys	{email}	{key}
POST /v1/validate	请求头 X-Api-Key，正文 {type, artifact, contract?}	判定结果，请求头 X-Calls-Remaining
GET /v1/manifest	—	功能清单
GET /stats	请求头 X-Admin-Token	漏斗数据：keys_issued、active_callers、repeat_callers_7d、limit_hits、paid_requests
POST /v1/paid-request	请求头 X-Api-Key	记录付费访问申请
GET /openapi.yaml、GET /llms.txt	—	静态文档
POST /mcp	MCP 可流式传输 HTTP，tools/call 需提供请求头 X-Api-Key	见上文“远程连接”

定价

• 免费层级： 每个密钥每月 500 次调用，速率限制为每分钟 60 次调用。
• 付费层级： 超出免费层级后，每次调用 EUR 0.002 — 即将开放。 可通过 POST /v1/paid-request 申请付费访问（需要 X-Api-Key）； 开放后你会收到通知。

错误

每个错误都是带类型的 JSON——{code, message, hint, docs_url}——而非 自由格式字符串：

代码	HTTP 状态码	触发时机
INVALID_KEY	401	缺少或未知的 X-Api-Key
LIMIT_EXCEEDED	402	超出免费套餐的月度限额（500 次调用）
UNSUPPORTED_TYPE	400	type 不是 json_schema、openapi_response 或 sql
MALFORMED_INPUT	400	请求体与文档中说明的结构不符
RATE_LIMITED	429	单个密钥每分钟调用次数超过 60 次

判定结果（{valid, errors, latency_ms}）不属于错误——产物无效是正常且预期的结果，返回的 HTTP 状态码为 200。

发送产物

artifact 必须是 JSON 值，而非 JSON 编码的字符串：

{"type": "json_schema", "artifact": {"name": "Ada"}, "contract": {"schema": {"type": "object"}}}   // correct
{"type": "json_schema", "artifact": "{\"name\": \"Ada\"}", "contract": {"schema": {"type": "object"}}}  // wrong

对于 type: "sql"，产物本身是一个字符串——即 SQL 语句。

由于 MCP 调用方经常会将值转为字符串（在工具架构声明 artifact 的类型之前，Claude Desktop 也曾如此处理），因此服务会以有限方式容忍错误的格式：如果 artifact 是字符串、类型为 json_schema 或 openapi_response，且契约的顶层架构声明的类型不包含 string，则会先对该字符串进行 JSON 解码，再进行验证，判定结果中会带有 "decoded_from_string": true。此字段为附加字段；{valid, errors, latency_ms} 保持不变。

服务有意不在其他情况下进行解码，因为字符串产物通常是合法的：

发送内容	契约架构	结果
"42"	{"type": "number"}	解码为 42，valid: true，decoded_from_string: true
"42"	{"type": "string"}	保持原样，valid: true
"{\"a\":1}"	{"type": "string"}	保持原样，valid: true
"{\"a\":1}"	{"required": ["a"]}	保持原样——没有顶层 type，意图未知

存储

src/storage.ts 定义了一个 Storage 接口及其两个实现：

• MemoryStorage——完整的内存实现，用于 npm run dev 和测试套件。
• D1Storage——真实的 Cloudflare D1 绑定，由 schema.sql（keys、 events 表）提供支持。用于生产环境；Workers 入口 src/index.ts 会在首次请求时根据 DB 绑定创建它。

使用以下命令将 schema.sql 应用到新的 D1 数据库：

wrangler d1 execute machinegrade-validate-db --file=schema.sql          # local
wrangler d1 execute machinegrade-validate-db --file=schema.sql --remote # production

测试

npm test          # vitest run, in-process via app.request(), MemoryStorage
npm run typecheck # tsc --noEmit

测试涵盖：密钥签发、每种验证器的成功与失败场景、带类型的 401/400/402/429 错误、计量限额（测试中两者均可注入，因此无需循环发送数百个真实请求），以及 /stats 漏斗计数。

部署

该服务运行在 Cloudflare Workers 上（Hono + D1 + Workers Static Assets）。要在全新的 Cloudflare 账户上自托管：

wrangler d1 create machinegrade-validate-db   # copy the returned database_id into wrangler.toml
wrangler d1 execute machinegrade-validate-db --file=schema.sql --remote
wrangler secret put ADMIN_TOKEN
wrangler deploy

然后通过 Cloudflare 控制面板或 wrangler 将自定义域名（例如 api.machinegrade.dev）绑定到 Worker。设置好仓库密钥 CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID，并取消注释 .github/workflows/ci.yml 中的 deploy 作业后，CI 即可在推送到 main 时进行部署。

关于 Workers 移植，有两点值得注意：

• GET /openapi.yaml 和 GET /llms.txt 由 ASSETS 绑定提供服务（wrangler.toml 中的 [assets]，指向 public/）——Cloudflare 会直接提供这些文件，不会调用 Worker。src/index.ts 中的路由是在本地 Node 开发和测试时使用的备用方案，因为此时没有 ASSETS 绑定。
• json_schema 和 openapi_response 验证器使用 @cfworker/json-schema，而非 ajv：ajv 通过 new Function(...) 编译架构，而 Workers 运行时不允许这样做；并且此处的架构会在每个请求中动态传入（由调用方提供），因此也无法在构建时预编译。

状态

目前仍处于早期阶段，确实如此：此服务已上线，免费层级的使用是真实的，我们正在评估它是否值得推出付费层级。你可以放心依赖以下几点：

• API 契约（/v1/validate 的请求/响应格式、类型化错误代码、判定语义）稳定可靠；只有通过带版本号的路径（/v2/...）才会引入破坏性变更，绝不会悄无声息地变更。
• 免费层级（每月 500 次调用）会保留。
• 如果我们决定停止此服务，公告发布后密钥仍可使用 90 天；而且验证器已在此代码库中开源，你可以自托管相同行为。

目前你能给我们的最宝贵帮助是反馈和集成案例：如果你需要超出免费层级的额度，请提交 issue，或使用 POST /v1/paid-request。