{
  "markdown": "# @jsonfabrica/mcp-server\n\n[![npm](https://img.shields.io/npm/v/@jsonfabrica/mcp-server)](https://www.npmjs.com/package/@jsonfabrica/mcp-server)\n[![license](https://img.shields.io/npm/l/@jsonfabrica/mcp-server)](./LICENSE)\n\nA local [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server\nthat lets an AI coding agent — Claude Desktop, Cursor, or anything else that\nspeaks MCP — generate realistic, schema-conformant JSON test data mid-session by\ncalling [JsonFabrica](https://jsonfabrica.com)'s REST API as MCP tools.\n\nIt runs over **stdio transport only**: your AI client launches it as a\nsubprocess, so there's no network service to host and no port to open. It never\ntalks to anything except the JsonFabrica gateway you configure.\n\n> New to JsonFabrica? It's an API-first service for generating synthetic JSON\n> test data from reusable templates — deterministic, seed-reproducible, with\n> referential integrity across related records. See\n> [jsonfabrica.com](https://jsonfabrica.com) and the\n> [API docs](https://jsonfabrica.com/docs).\n\n## Install / run\n\nAdd it to your MCP client's config so the client launches it via `npx`:\n\n```json\n{\n  \"mcpServers\": {\n    \"jsonfabrica\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jsonfabrica/mcp-server\"],\n      \"env\": {\n        \"JSONFABRICA_API_KEY\": \"sk_live_...\",\n        \"JSONFABRICA_API_URL\": \"https://api.jsonfabrica.com\"\n      }\n    }\n  }\n}\n```\n\n- **Claude Desktop** — add the block above to `claude_desktop_config.json`\n  (Settings → Developer → Edit Config), then restart.\n- **Cursor** — Settings → MCP → Add new MCP server, or add the block to\n  `~/.cursor/mcp.json`.\n\nGet an API key by signing up at [jsonfabrica.com](https://jsonfabrica.com) —\nSettings → API Keys.\n\nOr run it directly for local testing:\n\n```bash\nnpm install\nnpm run build\nJSONFABRICA_API_KEY=sk_live_... node dist/index.js\n```\n\n## What it looks like in a session\n\nOnce connected, an agent can do things like:\n\n> **You:** Generate 20 realistic customer records and 60 orders linked to them,\n> and drop them into `fixtures/seed.json`.\n>\n> **Agent:** *calls `jsonfabrica_create_template` for the customer and order\n> shapes, then `jsonfabrica_create_batch` with a `relations` map so each order\n> references a generated customer id, then writes the result to the file.*\n\nNo tab-switching to a dashboard, no hand-written fixtures.\n\n## Configuration\n\n| Env var | Required | Default | Notes |\n|---|---|---|---|\n| `JSONFABRICA_API_KEY` | Yes | — | If missing, the server still starts and answers tool discovery, but every tool call fails with \"check JSONFABRICA_API_KEY\". Never logged or echoed back in tool output. |\n| `JSONFABRICA_API_URL` | No | `https://api.jsonfabrica.com` | Base URL of the JsonFabrica gateway. Override this if you're self-hosting the gateway (e.g. `http://localhost:4000`). |\n\n## Tools\n\nEvery tool's description states, verbatim, which REST endpoint it calls. Tool\nnames are prefixed `jsonfabrica_` to avoid collisions with other MCP servers\nyour client may have loaded.\n\n### Health / Auth\n\n| Tool | Endpoint | Notes |\n|---|---|---|\n| `jsonfabrica_health` | `GET /health` | No auth. Connectivity check. |\n| `jsonfabrica_whoami` | `GET /v1/whoami` | Returns `{ tenantId, role }` for the configured key. |\n\n### Templates\n\n| Tool | Endpoint |\n|---|---|\n| `jsonfabrica_create_template` | `POST /v1/templates` |\n| `jsonfabrica_list_templates` | `GET /v1/templates` |\n| `jsonfabrica_get_template` | `GET /v1/templates/{templateId}` |\n| `jsonfabrica_update_template` | `PUT /v1/templates/{templateId}` |\n| `jsonfabrica_delete_template` | `DELETE /v1/templates/{templateId}` |\n| `jsonfabrica_generate_from_template` | `POST /v1/templates/{templateId}/generate` |\n| `jsonfabrica_generate_adhoc` | `POST /v1/templates/generate` (no persistence; same billing as persisted generation) |\n\nTemplate `body` strings use JsonFabrica's function-call placeholder syntax with\nangle brackets, e.g. `<getRandomFullName()>`, `<getRandomEmail()>`,\n`<createSeq('orderNo')>`. The full catalogue of built-in functions is documented\nat [jsonfabrica.com/docs/functions](https://jsonfabrica.com/docs/functions) —\nit's authoring reference, not something this server exposes as tools.\n\n### Sequences\n\n| Tool | Endpoint |\n|---|---|\n| `jsonfabrica_create_sequence` | `POST /v1/sequences` |\n| `jsonfabrica_list_sequences` | `GET /v1/sequences` |\n| `jsonfabrica_get_sequence` | `GET /v1/sequences/{name}` |\n| `jsonfabrica_update_sequence` | `PATCH /v1/sequences/{name}` |\n| `jsonfabrica_delete_sequence` | `DELETE /v1/sequences/{name}` |\n| `jsonfabrica_bump_sequence` | `POST /v1/sequences/{name}/bump` |\n\n### Batches\n\n| Tool | Endpoint |\n|---|---|\n| `jsonfabrica_create_batch` | `POST /v1/batches` (small batches run synchronously — 200 with `results`; larger batches are queued — 202, poll with `jsonfabrica_get_batch`) |\n| `jsonfabrica_get_batch` | `GET /v1/batches/{batchId}` |\n\n### Usage\n\n| Tool | Endpoint |\n|---|---|\n| `jsonfabrica_get_usage` | `GET /v1/usage` — returns `{ tenantId, usageTotal, asOf }` |\n\n### Admin — function weights\n\nRequires an API key with `role=admin`; the gateway returns 403 otherwise.\n\n| Tool | Endpoint |\n|---|---|\n| `jsonfabrica_list_function_weights` | `GET /v1/admin/function-weights` |\n| `jsonfabrica_update_function_weight` | `PATCH /v1/admin/function-weights/{functionName}` |\n\n### Explicitly out of scope\n\n- `POST /v1/signup` and `PATCH /v1/billing/tier` — unauthenticated\n  account-creation / billing-tier-change endpoints. Wrapping these would let a\n  model create real paid subscriptions or change billing tiers on the user's\n  behalf; excluded by design (generation API surface only).\n- `POST /v1/webhooks/stripe` — Stripe-only webhook ingestion, not a\n  developer-facing capability.\n\n## Error handling\n\nEvery tool catches errors internally and returns an MCP `isError: true` result\nwith a readable message — it never throws out of the handler or crashes the host\nprocess. Common cases:\n\n- **401** → \"Invalid or missing API key — check JSONFABRICA_API_KEY.\"\n- **403** (admin tools) → \"This API key does not have admin role.\"\n- **402** (blocked account) → the upstream `blockReason` is passed through.\n- Network failure (gateway unreachable) → a message naming the configured\n  `JSONFABRICA_API_URL`.\n- Anything else → `JsonFabrica API error [CODE] (HTTP status): message`.\n\n## Troubleshooting\n\n- **401 / \"Invalid or missing API key\"** → check `JSONFABRICA_API_KEY` is set\n  and valid.\n- **Connection refused / UPSTREAM_UNREACHABLE** → check `JSONFABRICA_API_URL` and\n  that the gateway is actually running and reachable from wherever this process\n  runs.\n- **403 on admin tools** → your API key's tenant doesn't have `role=admin`.\n\n## Development\n\n```bash\nnpm install\nnpm run build   # tsc -p tsconfig.json\nnpm test        # build + node --test dist/\nnpm start       # node dist/index.js (requires JSONFABRICA_API_KEY)\n```\n\nSource layout mirrors the OpenAPI spec's tags: one file per tag under\n`src/tools/`. `src/client.ts` is the only place that knows about `fetch`, the\nbase URL, and the `Authorization` header.\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n",
  "bytes": 7126,
  "sha": "8c19c1d864e03c34a0be66bb702694e5488700f15ebec1a41b7a2258a5891598",
  "repo_slug": "ms-methos/jsonfabrica-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ms_methos_jsonfabrica_mcp_serv_2b20b1d7/readme"
}