Jsonaut

Jsonaut

面向 AI Agent 客户构建的 JSON 修复与验证工具。发送可能格式错误的 JSON（LLM 工具调用输出、其他 Agent 的消息、不稳定的上游数据），即可获得已解析且符合 Schema 的 JSON。

• **免费层级：**确定性修复——尾随逗号、单引号、截断内容、Markdown 代码围栏、注释、Python 字面量——以及带类型强制转换的 JSON Schema 验证（字符串→数字、默认值、剥除幻觉字段）。按 IP 限流。
• **付费层级：**对确定性处理无法修复的输入进行 LLM 回退修复。每次调用 $0.01，仅在成功时收费，通过 x402（Base 上的 USDC）自动按次支付——无需账户，无需注册。

业务背景、市场研究和完整的 3 天计划见 IDEA.md 和 PLAN.md。

快速入门

npm install
npm test          # 27 tests: repair battery, schema coercion, HTTP API, MCP protocol
npm run dev       # http://localhost:8787 — demo page + API + MCP endpoint

试试看：

curl -s -X POST http://localhost:8787/v1/repair \
  -H "content-type: application/json" \
  -d "{\"input\": \"{'name': 'alice', 'count': '42',}\", \"schema\": {\"type\":\"object\",\"properties\":{\"count\":{\"type\":\"number\"}}}}"

{
  "valid": true,
  "repaired": { "name": "alice", "count": 42 },
  "method": "deterministic-repair",
  "changes": ["repaired JSON syntax (jsonrepair)", "$.count: coerced string \"42\" to number"]
}

API

路由	功能
POST /v1/repair	修复 + 可选的 Schema 验证/强制转换。请求体：{input, schema?, allow_llm_fallback?}
POST /v1/validate	仅验证，不修复。请求体：{input, schema}
POST /mcp	MCP 服务（Streamable HTTP，无状态）。工具：repair_json、validate_json
GET /	交互式演示页面
GET /llms.txt	面向 Agent 的能力 + 定价说明
GET /openapi.yaml	OpenAPI 3.1 规范

响应中的 method 值：direct（原本已有效）、deterministic-repair（免费修复）、llm-repair（付费修复）、failed。changes[] 会列出每一项修改，方便调用方审查对数据所做的处理。

在 Agent 中使用（MCP）

claude mcp add --transport http jsonaut https://YOUR-DEPLOYMENT/mcp

也可以在任何 MCP 客户端配置中使用：

{ "mcpServers": { "jsonaut": { "type": "http", "url": "https://YOUR-DEPLOYMENT/mcp" } } }

对于付费层级，客户端通过 x402 支付，并在重试时携带 X-PAYMENT 标头（支付凭证）。无需账户或 API 密钥——Agent 按次支付。

支付流程（x402）

1. Agent 使用 allow_llm_fallback: true 调用 /v1/repair；确定性修复失败。
2. 服务端返回 402，其中包含 x402 accepts 数组（Base 上的 USDC，金额为 PRICE_USD）。
3. Agent 付款后携带 X-PAYMENT 标头重试；服务端通过协调器验证支付，执行 LLM 修复，并且仅在修复成功时结算。

配置

环境变量	用途	必需场景
OPENROUTER_API_KEY	启用付费 LLM 回退层级（通过 OpenRouter；默认使用免费模型）	付费层级
OPENROUTER_MODEL	指定模型（默认 meta-llama/llama-3.3-70b-instruct:free）	—
X402_PAY_TO	接收 USDC 的 Base 钱包地址	x402 支付通道
X402_NETWORK	base 或 base-sepolia（默认 base）	x402 支付通道
FACILITATOR_URL	用于验证/结算的 x402 协调器	x402 支付通道
FREE_DAILY_LIMIT	每个 IP 每天的免费调用次数（默认 100）	—
PRICE_USD	付费层级价格（默认 0.01）	—
DEV_ALLOW_FREE_LLM	设为 true 后仅在本地开发时开放付费层级	—

本地开发所需的密钥放在 .dev.vars 文件（已加入 git 忽略）或 shell 环境变量中。

部署（Cloudflare Workers）

npx wrangler login
npx wrangler kv namespace create KV      # then paste the id into wrangler.toml
npx wrangler secret put OPENROUTER_API_KEY
npx wrangler deploy

同一代码库可在 Node 上用于本地开发（npm run dev），也可在生产环境部署到 Workers——没有 KV 绑定时，存储会回退到内存中。

项目结构

src/core/      pipeline.ts (repair engine) · coerce.ts (schema coercion) · llm.ts (paid tier)
src/http/      app.ts (routes) · payment.ts (x402 rail) · ratelimit.ts · demo.ts · billing.ts (parked, unused)
src/mcp/       server.ts (stateless Streamable HTTP MCP server)
src/worker.ts  Cloudflare Workers entry
src/dev.ts     Node dev entry
test/          full battery: broken-JSON cases, coercion, HTTP, MCP protocol

已知限制（MVP）

• Schema 强制转换不会解析 $ref 或 oneOf/anyOf 分支。
• x402 验证需要外部协调器（FACILITATOR_URL）；不内置链上验证。
• 高并发情况下，免费层级的限流是近似值（KV 读取-修改-写入）。