jsonfabrica-mcp-server

Purpose

JsonFabrica MCP Server is a local MCP (Model Context Protocol) server used to let AI coding agents generate realistic JSON test data that conforms to a schema directly within a session. It wraps JsonFabrica's REST API as MCP tools for Claude Desktop, Cursor, or other MCP-capable clients to call.

Main capabilities

• Generate synthetic JSON test data by calling the JsonFabrica API through MCP tools.
• Support generating data from reusable templates, with deterministic results, reproducible seeds, and referential integrity maintained between related records.
• Can create a single document or generate related data in batches, for example first generating customer records, then generating order records that reference those customer ids.
• All tools catch errors internally and return MCP isError: true results and readable messages, without throwing outside the handler or crashing the host process.
• Tool names are uniformly prefixed with jsonfabrica_ to avoid conflicts with other MCP servers; each tool description states verbatim the REST endpoint it calls.

Usage

The server runs only over stdio transport: the AI client starts it as a child process, so there is no need to host a network service or open ports. It communicates only with the configured JsonFabrica gateway.

Add it to the MCP client configuration so the client starts it via npx .

• Claude Desktop: add the configuration block to claude_desktop_config.json(Settings → Developer → Edit Config), then restart.
• Cursor: Settings → MCP → Add new MCP server, or add the configuration block to ~/.cursor/mcp.json.

An API key can be obtained by registering at jsonfabrica.com: Settings → API Keys. It can also be run directly for local testing.

Typical usage in a session: the user asks to generate 20 realistic customer records and 60 related orders, and write them to fixtures/seed.json. The agent will call jsonfabrica_create_template to create the customer and order shapes, then call jsonfabrica_create_batch and provide a relations mapping so that each order references an already-generated customer id, and finally write the results to a file.

Template body strings use JsonFabrica's angle-bracket function-call placeholder syntax, for example <getRandomFullName()>、<getRandomEmail()>、<createSeq('orderNo')>. The complete catalog of built-in functions is at jsonfabrica.com/docs/functions; this is writing reference material, not a tool exposed by this server.

The two tools return the same structure:{ batchId, status, seed, results?, error? }, where status is queued | running | completed | failed. results appears when a batch completes, grouping generated documents by alias, with each value being an array of documents. A failed batch returns error: { code, message } instead of results. Batches with a total document count below 50 (the API default threshold) run synchronously; larger batches return 202 { batchId, status: "queued", seed }.

Suitable scenarios

Suitable for quickly generating test data in AI coding sessions, populating fixtures, constructing related datasets with referential relationships, and similar scenarios, without switching to a dashboard or hand-writing fixtures.

Limitations

The following endpoints are explicitly excluded from the design scope:

• POST /v1/signup and PATCH /v1/billing/tier: unauthenticated account creation or billing tier change endpoints. Wrapping these endpoints would let the model create real paid subscriptions or change billing tiers on behalf of the user, so they are excluded (generation API surface only).
• POST /v1/webhooks/stripe: Stripe-only webhook ingestion, not a developer-facing capability.

Common error cases: 401 means the API key is invalid or missing; 403 means the tenant that owns the API key is not allowed to perform that call; 402 (account blocked) passes through the upstream blockReason; network failure (gateway unreachable) gives a message containing the configured JSONFABRICA_API_URL message; otherwise returns JsonFabrica API error [CODE] (HTTP status): message.

Common troubleshooting

• 401 / "Invalid or missing API key": Check whether JSONFABRICA_API_KEY is set and valid.
• Connection refused / UPSTREAM_UNREACHABLE: Check JSONFABRICA_API_URL, and whether the gateway is running and reachable from where that process runs.
• 403 / FORBIDDEN: The tenant to which the API key belongs is not allowed to perform this call.

Source code and license

The source code layout corresponds to the tags of the OpenAPI specification:src/tools/ with one file per tag.src/client.ts is the only place that knows about fetch, the base URL, and the Authorization header. Licensed under MIT; see LICENSE for details.