JsonFabrica

@jsonfabrica/mcp-server

一个本地 Model Context Protocol（MCP）服务， 可让 AI 编码 Agent（Claude Desktop、Cursor 或任何支持 MCP 的客户端）在会话中调用 JsonFabrica 的 REST API，将其作为 MCP 工具来生成符合架构的逼真 JSON 测试数据。

它仅通过 stdio 传输运行：AI 客户端会将其作为子进程启动，因此无需托管网络服务，也无需开放端口。它只会与您配置的 JsonFabrica 网关通信。

初次接触 JsonFabrica？它是一项 API 优先的服务，可通过可复用模板生成合成 JSON 测试数据，支持确定性生成、种子复现，以及相关记录间的引用完整性。请参阅 jsonfabrica.com 和 API 文档。

安装 / 运行

将其添加到 MCP 客户端的配置中，以便客户端通过 npx 启动：

{
  "mcpServers": {
    "jsonfabrica": {
      "command": "npx",
      "args": ["-y", "@jsonfabrica/mcp-server"],
      "env": {
        "JSONFABRICA_API_KEY": "sk_live_...",
        "JSONFABRICA_API_URL": "https://api.jsonfabrica.com"
      }
    }
  }
}

• Claude Desktop — 将上面的代码块添加到 claude_desktop_config.json （Settings → Developer → Edit Config），然后重启。
• Cursor — 前往 Settings → MCP → Add new MCP server，或将代码块添加到 ~/.cursor/mcp.json。

在 jsonfabrica.com 注册以获取 API 密钥 — Settings → API Keys。

也可以直接运行以进行本地测试：

npm install
npm run build
JSONFABRICA_API_KEY=sk_live_... node dist/index.js

会话中的使用示例

连接后，Agent 可以执行以下操作：

**你：**生成 20 条逼真的客户记录和 60 条与这些客户关联的订单， 并将其写入 fixtures/seed.json。

Agent： 调用 jsonfabrica_create_template 定义客户和订单的数据结构， 然后调用 jsonfabrica_create_batch 并传入 relations 映射，让每个订单都引用 生成的客户 ID，最后将结果写入文件。

无需切换到控制面板，也无需手动编写测试数据。

配置

环境变量	必需	默认值	说明
JSONFABRICA_API_KEY	是	—	如果缺少此变量，服务仍会启动并响应工具发现请求，但每次工具调用都会失败并提示 "check JSONFABRICA_API_KEY"。绝不会记录或在工具输出中回显该密钥。
JSONFABRICA_API_URL	否	https://api.jsonfabrica.com	JsonFabrica 网关的基础 URL。如果您在自托管网关，可覆盖此值（例如 http://localhost:4000）。

工具

每个工具的说明都会原样注明其调用的 REST 端点。工具名称均以 jsonfabrica_ 为前缀， 以避免与客户端可能已加载的其他 MCP 服务发生冲突。

健康检查 / 身份验证

工具	端点	说明
jsonfabrica_health	GET /health	无需身份验证。检查连接状态。
jsonfabrica_whoami	GET /v1/whoami	返回配置密钥对应的 { tenantId, role }。

模板

工具	端点
jsonfabrica_create_template	POST /v1/templates
jsonfabrica_list_templates	GET /v1/templates
jsonfabrica_get_template	GET /v1/templates/{templateId}
jsonfabrica_update_template	PUT /v1/templates/{templateId}
jsonfabrica_delete_template	DELETE /v1/templates/{templateId}
jsonfabrica_generate_from_template	POST /v1/templates/{templateId}/generate
jsonfabrica_generate_adhoc	POST /v1/templates/generate（不持久化；计费方式与持久化生成相同）

模板 body 字符串使用 JsonFabrica 的函数调用占位符语法，尖括号内为函数调用， 例如 <getRandomFullName()>、<getRandomEmail()>、 <createSeq('orderNo')>。内置函数的完整目录见 jsonfabrica.com/docs/functions — 该文档是编写参考，并非此服务以工具形式提供的内容。

序列

工具	端点
jsonfabrica_create_sequence	POST /v1/sequences
jsonfabrica_list_sequences	GET /v1/sequences
jsonfabrica_get_sequence	GET /v1/sequences/{name}
jsonfabrica_update_sequence	PATCH /v1/sequences/{name}
jsonfabrica_delete_sequence	DELETE /v1/sequences/{name}
jsonfabrica_bump_sequence	POST /v1/sequences/{name}/bump

批次

工具	端点
jsonfabrica_create_batch	POST /v1/batches（小批次会同步运行——返回 200 和 results；较大的批次会进入队列——返回 202，使用 jsonfabrica_get_batch 轮询）
jsonfabrica_get_batch	GET /v1/batches/{batchId}

两个工具返回相同的结构：{ batchId, status, seed, results?, error? }， 其中 status 的值为 queued | running | completed | failed。批次状态为 completed 后会包含 results，并按别名对生成的文档分组——每个值都是文档数组：

{
  "batchId": "4f1c…",
  "status": "completed",
  "seed": 42,
  "results": {
    "customer": [{ "id": "c-1", "name": "Ada Lovelace" }],
    "order": [{ "id": "o-1", "customerId": "c-1" }, { "id": "o-2", "customerId": "c-1" }]
  }
}

失败的批次会包含 error: { code, message }，而不是 results。总文档数少于 50 的批次（API 的默认阈值）会同步运行； 较大的批次会返回 202 { batchId, status: "queued", seed }。

用法

工具	端点
jsonfabrica_get_usage	GET /v1/usage — 返回 { tenantId, usageTotal, asOf }

明确不在范围内

• POST /v1/signup 和 PATCH /v1/billing/tier ——无需身份验证的账户创建／账单套餐变更端点。封装这些端点会允许模型代表用户创建真实的付费订阅或更改账单套餐；因此根据设计将其排除在外（仅包含生成 API 接口）。
• POST /v1/webhooks/stripe ——仅供 Stripe 使用的 Webhook 接收接口，不是面向开发者的功能。

错误处理

每个工具都会在内部捕获错误，并返回包含易读消息的 MCP isError: true 结果——不会将错误抛出处理程序，也不会导致宿主进程崩溃。常见情况：

• 401 → “API 密钥无效或缺失——请检查 JSONFABRICA_API_KEY。”
• 403 → API 密钥所属的租户无权执行此调用。
• 402（账户受限）→ 原样传递上游的 blockReason。
• 网络故障（网关不可达）→ 返回一条指出已配置的 JSONFABRICA_API_URL 的消息。
• 其他情况 → JsonFabrica API error [CODE] (HTTP status): message。

故障排除

• 401 / “Invalid or missing API key” → 检查是否已设置 JSONFABRICA_API_KEY，且其值有效。
• 连接被拒绝 / UPSTREAM_UNREACHABLE → 检查 JSONFABRICA_API_URL，并确认网关正在运行，且从此进程运行的位置可以访问。
• 403 / FORBIDDEN → 你的 API 密钥所属租户无权执行此调用。

开发

npm install
npm run build   # tsc -p tsconfig.json
npm test        # build + node --test dist/
npm start       # node dist/index.js (requires JSONFABRICA_API_KEY)

源代码布局与 OpenAPI 规范中的标签相对应：src/tools/ 下每个标签对应一个文件。只有 src/client.ts 会处理 fetch、基础 URL 和 Authorization 标头。

许可证

MIT——参见 LICENSE。