apiryner

Official TypeScript SDK, CLI, and MCP server for Apiryner — a JSON layout-based random data generation API. Define a layout once, then pull realistic, reproducible mock data as JSON or CSV.

npm install apiryner

Zero runtime dependencies. Node.js 18+ (uses global fetch).

SDK

import { Apiryner } from "apiryner";

const api = new Apiryner({ apiKey: process.env.APIRYNER_KEY });

const users = await api.generate("user-profile", {
  count: 100,
  seed: 42,      // same seed → same data
  locale: "ko",
});

Layouts, snapshots, and bundles are managed with the same client — listLayouts, createLayout, getSnapshot, generateBundle, and friends. Extra entry points:

• apiryner/mock — offline mock generation from a schema, no API calls
• apiryner/webhook — webhook signature verification helpers
• apiryner/react, apiryner/vue — data-fetching adapters

CLI

npx apiryner login                                  # or: export APIRYNER_API_KEY=ak_...
npx apiryner generate user-profile -n 100 --seed 42 --format csv -o fixtures/users.csv
npx apiryner quick '{"id":"sequence","email":"email","age":"integer:18-65"}' -n 10 --locale ko
npx apiryner import openapi.yaml --type openapi --schema User   # JSON or YAML
npx apiryner codegen --lang typescript -o types/    # every layout on the account
npx apiryner serve --port 4000                      # local mock server from .apiryner.json
npx apiryner seed --layout users -n 500 --db postgres://localhost/dev

Run npx apiryner --help for the full command list.

Offline generation and locales

quick, serve, and fixture run without an account. --locale accepts en, ja, ko, zh, and random (a language per record); the mock server also reads ?locale= per request. Offline pools are smaller than the API's, so use the API when you need variety.

Seeding a database

seed prints PostgreSQL INSERT statements by default. Pass --db postgres://… to insert directly — that path needs pg installed alongside the CLI (npm install pg) and runs in one transaction, so a failure rolls the whole batch back. --dry-run prints the SQL instead of connecting, and --name overrides the table name when it differs from the layout slug.

Fixture manifests

fixture reads .apiryner.yml (or --config <file>) written in ordinary block YAML — nested mappings, sequences, flow collections, quoted strings, block scalars, and comments. Anchors, aliases, tags, and multi-document files are rejected rather than silently misread.

MCP server

apiryner mcp runs a Model Context Protocol server on stdio, so AI coding agents (Claude Code, Cursor, Claude Desktop, …) can generate mock data and read your layouts as tool calls instead of shelling out.

claude mcp add apiryner -- npx apiryner mcp

For clients configured through JSON (mcpServers):

{
  "mcpServers": {
    "apiryner": {
      "command": "npx",
      "args": ["apiryner", "mcp"],
      "env": { "APIRYNER_API_KEY": "ak_..." }
    }
  }
}

Tools

| Tool | Auth | Arguments | |------|------|-----------| | quick_generate | — | schema (required), count, seed | | infer_schema | — | input (required), type: json-sample (default) / json-schema / openapi / sql | | generate | required | slug (required), count, seed, locale, format: json / csv | | list_layouts | required | limit, offset |

quick_generate and infer_schema run entirely in the local process — no account, no network — so an agent can produce fixtures or turn an OpenAPI file into a layout schema before you have signed up. Pass the same seed to get identical records across calls.

// quick_generate
{
  "schema": { "id": "sequence", "name": { "type": "name" }, "age": "integer:18-65" },
  "count": 5,
  "seed": 42
}

generate and list_layouts call api.apiryner.com against your saved layouts. Have the agent run list_layouts first to discover slugs.

Authentication

Credentials are resolved once, lazily, on the first tool call that needs the API — in this order:

1. --key <key> passed after apiryner mcp, or $APIRYNER_API_KEY
2. the OAuth session from apiryner login (refreshed automatically when expired)
3. the API key stored by apiryner config set api-key <key>

Starting the server unauthenticated is fine: the account-backed tools return an isError result explaining what is missing, and they start working as soon as you log in — no restart needed. --base-url (or apiryner config set base-url <url>) points the server at a different API host.

Notes

• stdio transport only, tools capability only; protocol versions 2025-06-18, 2025-03-26, 2024-11-05.
• stdout carries nothing but JSON-RPC messages — the startup banner goes to stderr.
• The server is implemented in-package with no MCP SDK dependency, so it inherits the zero-dependency install.

Documentation

Full API reference and guides: https://apiryner.com/docs

License

MIT