mimikos-seed

name	mimikos-seed
description	Seed a running Mimikos mock server in stateful mode by reading an OpenAPI spec, constructing valid request bodies, and creating resources via MCP tools. Use when the user wants to populate mock data, seed a mock server, or set up test data for Mimikos.

Mimikos Seeding Skill

Seed a running Mimikos instance in stateful mode so that GET and LIST endpoints return realistic data. You will read the OpenAPI spec, construct valid request bodies, and create resources via MCP tool calls (or HTTP requests as a fallback).

When to Use

• User says "seed mimikos", "populate the mock", "create test data", or similar
• User has a running Mimikos instance in stateful mode and wants data in it
• User wants to test their application against a mock API that has resources

Prerequisites

Before seeding, you must ensure Mimikos is running in stateful mode.

Determine Transport

MCP tools (preferred): If the Mimikos MCP server is configured, use MCP tool calls for all operations. MCP tools return structured JSON — no curl parsing needed.

HTTP fallback: If MCP tools are not available (agent has no MCP connection to Mimikos), use curl commands against the running server. All MCP operations have curl equivalents documented in the fallback sections below.

1. Locate the OpenAPI Spec File

Ask the user for the spec file path if you don't already know it. Look for .yaml, .yml, or .json files in the project that look like OpenAPI specs (contain openapi: or "openapi" at the top level).

2. Check if Mimikos Is Already Running

Via MCP:

server_status()

This returns {"running": true, "mode": "stateful", "port": 8080, ...} or {"running": false}.

Fallback: Run pgrep -af mimikos to inspect running processes. The output shows the full command line, including mode, port, and spec file.

If running in stateful mode — use it. Proceed to the seeding workflow.

If running in deterministic mode — inform the user: "Mimikos is running in deterministic mode. Seeding requires stateful mode. Should I restart it in stateful mode?" Do NOT stop the server without explicit user permission.

If not running — start it:

Via MCP:

start_server(specPath: "<spec-file>", mode: "stateful")

Fallback:

mimikos start --mode stateful <spec-file>

Start in non-strict mode (the default) unless the user explicitly requests strict. Non-strict is the right default for seeding because strict mode returns 500 if any generated response fails schema validation, which can block seeding on specs with minor schema inconsistencies.

3. Confirm the Port

Via MCP: the start_server response or server_status response includes the port.

Fallback: default port is 8080. Check the startup banner or process arguments for a custom port.

How Stateful Create Works

You must understand this before sending requests:

• Create responses merge your request body onto generated defaults. When you create with {"name": "Buddy"}, the response WILL contain "name": "Buddy". Fields you send override generated values. Fields you don't send are filled from the schema.

• The merge pipeline has three layers (last wins):

  1. Faker base — generates all fields from the schema (provides unique IDs, defaults)
  2. Spec example overlay — if the spec has media-type examples, they replace faker values for more realistic defaults (ID fields are protected from example overwrite to keep IDs unique)
  3. Request body overlay — your values override everything

• IDs are always generated by the server. Do not send id, gid, or similar identifier fields in request bodies — the server generates unique IDs per create.

• Your request body matters for: setting specific field values, validation (must pass the request schema), and deterministic seeding (different bodies produce different generated responses for fields you don't set).

Seeding Workflow

Follow these steps in order:

Step 1: Confirm Seeding Scope

Ask the user: "Do you want me to seed all create endpoints, or specific ones?"

• If the user names specific resources or endpoints, seed only those.
• If the user says "all" or doesn't specify, seed every endpoint classified as create.

Step 2: Discover Endpoints

Via MCP:

list_endpoints()

Returns all classified endpoints with their behavior type and confidence. Identify endpoints with "behavior": "create".

For detailed info on a specific endpoint:

get_endpoint(method: "POST", path: "/pets")

This tells you whether the endpoint has a request schema, response schema, examples, wrapper keys, and whether it's degraded.

Fallback: Check the Mimikos startup output for the endpoint table and any warnings.

Step 3: Check for Warnings

Two signals matter:

Failed endpoints — these always return 500. Do not attempt to seed them.

Degraded schemas — these have schemas that failed to compile:

• In stateful mode, degraded create endpoints always return 500 (they need the response schema to generate the resource to store). Skip them.
• In strict mode (strict=true), degraded endpoints with request bodies also return 500. Skip any body-bearing method on a degraded endpoint in strict mode.

Via MCP: get_endpoint returns "degraded": true for degraded endpoints.

If there are no warnings, all endpoints are healthy.

Step 4: Read the OpenAPI Spec

Open and read the spec file. You need to identify:

1. Create endpoints — look for POST operations that return 201 or 200 with a response body. Cross-reference with the behaviors from list_endpoints.

2. Request body schemas — for each create endpoint, follow the path:

   paths.<path>.post.requestBody.content["application/json"].schema
   

   Follow any $ref to find the actual schema definition in components.schemas.

3. Response body schemas — to understand what Mimikos will return:

   paths.<path>.post.responses["201"].content["application/json"].schema
   

Step 5: Determine Seeding Order

Seed parent resources before child resources. Use path nesting as the heuristic:

/pets                              → seed first (no parent dependency)
/pets/{petId}/vaccinations         → seed second (needs a pet ID)
/organizations                     → seed first
/organizations/{orgId}/teams       → seed second (needs an org ID)
/organizations/{orgId}/teams/{id}  → seed third (needs org + team)

Rules:

• Shorter paths (fewer segments) go first
• If two paths have the same depth, order doesn't matter
• Parameterless collection paths (/pets) come before parameterized item paths

Step 6: Construct Request Bodies

For each create endpoint, build a valid JSON body from the request schema:

Required fields only. Include all fields marked required in the schema. Optional fields can be included for realism but aren't necessary.

Omit ID fields. Do not include id, gid, _id, or similar identifier fields in request bodies. Mimikos generates these in the response. Sending them can conflict with identity extraction.

Follow the schema types:

• string → use a realistic value based on the field name
• integer / number → use a plausible value within any minimum/maximum bounds
• boolean → use true or false
• enum → pick one of the values listed in the schema
• object → recurse into the sub-schema's properties
• array → provide 1-2 items matching the items schema

Use field names as semantic hints:

• name, firstName, lastName → realistic names
• email → realistic email format
• phone → realistic phone number
• url, website → realistic URL
• description, summary → short descriptive text
• price, amount, cost → realistic monetary values
• address, city, country → realistic location data
• createdAt, updatedAt → ISO 8601 timestamps

Step 7: Handle Common Patterns

Wrapper keys (e.g., Asana, Notion): Some APIs wrap request bodies in an envelope like {"data": {...}}. You will see this in the request schema — the top-level object has a single property (e.g., data) whose value is the actual resource schema. Match the spec:

// Flat request (Petstore, Stripe):
{
  "name": "Buddy",
  "tag": "dog"
}

// Wrapped request (Asana):
{
  "data": {
    "name": "My Project"
  }
}

Via MCP: get_endpoint returns "wrapper_key" if the endpoint uses a wrapper.

Nested resources: When creating a child resource (e.g., POST /pets/{petId}/vaccinations), use a real ID from a previously created parent resource in the URL path.

Multiple resource types: Seed each resource type independently. Resources are stored by type — creating a pet does not affect the projects store.

Step 8: Send Create Requests

Via MCP:

manage_state(action: "create", path: "/pets", body: {"name": "Buddy", "tag": "dog"})

Response:

{
  "status_code": 201,
  "body": {
    "id": 6635,
    "name": "Buddy",
    "tag": "dog",
    "status": {"type": "archived", "reason": "jDKAKpGL"},
    "metadata": {}
  }
}

Fallback:

curl -s -X POST http://localhost:<port><path> \
  -H "Content-Type: application/json" \
  -d '<json-body>'

After each successful create:

1. Check the response status code (expect 201 or 200)
2. Extract the resource ID from the response body — look for id, gid, or the field that matches the path parameter name on the corresponding GET endpoint
3. Store this ID — you will need it for child resources and verification

Wrapper key responses: If the API uses wrapper keys, the ID is inside the wrapper:

// Flat response: ID is at body.id
{
  "id": "abc123",
  "name": "Generated Name"
}

// Wrapped response: ID is at body.data.gid
{
  "data": {
    "gid": "abc123",
    "name": "Generated Name"
  }
}

Step 9: Optionally Update After Creation

If you need to change field values after creation, use the update action:

Via MCP:

manage_state(action: "update", path: "/pets/6635", body: {"name": "New Name"})

Fallback:

curl -s -X PATCH http://localhost:<port><path>/<id> \
  -H "Content-Type: application/json" \
  -d '{"name": "New Name"}'

The update handler shallow-merges your fields onto the stored resource. But in most cases, you should send the desired values directly in the create body (Step 8) — they will appear in the create response.

For wrapped APIs, wrap the update body too.

Step 10: Verify

After seeding all resource types, verify the state:

Via MCP:

manage_state(action: "list", path: "/pets")
manage_state(action: "get", path: "/pets/6635")

Fallback:

curl -s http://localhost:<port>/pets
curl -s http://localhost:<port>/pets/6635

Check:

1. List endpoints — confirm resources exist and count matches
2. Fetch endpoints — spot-check individual resources using stored IDs
3. Count — verify the number of resources matches what you created

Report the results to the user: which resources were created, their IDs, and any failures.

Error Reference

Status	Meaning	Action
201/200	Success	Extract ID, continue
400	Request validation failed	Fix the request body — check required fields, types, constraints. The response body lists which fields failed.
404	Path not found	Check the URL path matches the spec exactly
405	Method not allowed	Check the HTTP method — this path may not support POST
415	Wrong content type	Add -H "Content-Type: application/json" (curl only — MCP tools set this automatically)
422	Validation error	Similar to 400 — fix request body
500	Server error	Likely a degraded or failed endpoint. Check startup output. Do not retry — this endpoint cannot be seeded.

Important Constraints

• Content-Type header is required for HTTP. Always send Content-Type: application/json with POST/PUT/PATCH requests via curl. MCP's manage_state tool sets this automatically.

• Request body size limit is 10MB. This is unlikely to be hit during seeding.

• State is in-memory. Restarting Mimikos clears all seeded data. The state does not persist across restarts.

• Resources are scoped by path hierarchy and parent IDs. /projects/{id}/tasks and /tasks are separate namespaces. Within a namespace, resources are further isolated by parent path parameter values — POST /projects/1/tasks creates a task visible only under GET /projects/1/tasks, not under GET /projects/2/tasks. Use the correct endpoint and parent IDs for the scope you need.

• Do not use request_status when seeding. The status override header bypasses stateful mode entirely — no resource will be stored and the response comes from the deterministic generator instead.

• Default capacity is 10,000 resources. Configurable via --max-resources (CLI) or the start_server MCP tool. LRU eviction applies when capacity is reached.

• Reset state if needed. To clear all resources and start fresh: Via MCP: manage_state(action: "reset") Via curl: restart the server.