# mockd — Full LLM Context

> mockd is a multi-protocol API mock server written in Go. It supports HTTP/REST, WebSocket, GraphQL, gRPC, SOAP, MQTT, SSE, and OAuth from a single binary. It includes an 18-tool MCP server for AI agent integration, ~168 admin API endpoints, 35 faker types, 12 chaos fault types, 10 chaos profiles, stateful CRUD resources, and imports from 8 formats.

## Quick Start

```bash
# Install
brew install mockd
# or: go install github.com/getmockd/mockd/cmd/mockd@latest
# or: curl -fsSL https://get.mockd.io | sh

# Start server (admin on :4290, mock engine on :4280)
mockd serve

# Create a mock
curl -X POST http://localhost:4290/mocks -H 'Content-Type: application/json' -d '{
  "type": "http",
  "http": {
    "matcher": { "method": "GET", "path": "/api/users" },
    "response": { "status": 200, "body": "{\"users\": [{\"name\": \"{{faker.name}}\", \"email\": \"{{faker.email}}\"}]}" }
  }
}'

# Test it
curl http://localhost:4280/api/users
```

## Configuration Format (mockd.yaml)

```yaml
version: "1.0"
kind: MockCollection
metadata:
  name: my-api-mocks
mocks:
  - type: http
    http:
      matcher:
        method: GET
        path: /api/users/{id}
      response:
        status: 200
        headers:
          Content-Type: application/json
        body: |
          {
            "id": "{{request.pathParam.id}}",
            "name": "{{faker.name}}",
            "email": "{{faker.email}}",
            "seed": "{{faker.uuid}}"
          }
        seed: 42  # Optional: deterministic responses
serverConfig:
  chaos:
    enabled: true
    rules:
      - path: "/api/*"
        probability: 1.0
        faults:
          - type: circuit_breaker
            probability: 1.0
            config:
              tripAfter: 5
              openDuration: "10s"
              halfOpenErrorRate: 0.3
              successThreshold: 2
              statusCode: 503
```

## Stateful Tables & Extend (Digital Twins)

Define resource tables in config and bind mocks to them with `extend:` for automatic CRUD. This enables digital twins of real APIs (Stripe, Twilio, etc.).

### Tables Config

```yaml
version: "1.0"
kind: MockCollection
metadata:
  name: stripe-twin

tables:
  customers:
    id_strategy: prefix
    id_prefix: "cus_"
    seed_data:
      - name: "Alice Johnson"
        email: "alice@example.com"
        balance: 0
    response:
      envelope: data          # wrap list responses in {"data": [...]}
      total_field: total_count
      pagination: cursor
  charges:
    id_strategy: prefix
    id_prefix: "ch_"
    relationships:
      customer:
        table: customers
        field: customer

mocks:
  - type: http
    http:
      matcher: { method: GET, path: /v1/customers }
    extend:
      - table: customers
        action: list
  - type: http
    http:
      matcher: { method: POST, path: /v1/customers }
    extend:
      - table: customers
        action: create
  - type: http
    http:
      matcher: { method: GET, path: /v1/customers/{id} }
    extend:
      - table: customers
        action: get
  - type: http
    http:
      matcher: { method: POST, path: /v1/customers/{id} }
    extend:
      - table: customers
        action: update
  - type: http
    http:
      matcher: { method: DELETE, path: /v1/customers/{id} }
    extend:
      - table: customers
        action: delete
```

### Table Options

| Field | Description |
|-------|-------------|
| `id_strategy` | ID generation: `uuid` (default), `prefix`, `ulid`, `sequence`, `short` |
| `id_prefix` | Prefix for generated IDs when strategy is `prefix` (e.g., `cus_`) |
| `id_field` | Custom ID field name (default: `id`) |
| `max_items` | Maximum items the table can hold (0 = unlimited) |
| `seed_data` | Array of initial items to populate the table |
| `response` | Response transform config: `envelope`, `pagination`, `total_field`, `timestamp_fields` |
| `relationships` | Foreign key definitions for `?expand[]` support |
| `parent_field` | Foreign key field for nested/child resources |

### Extend Actions

| Action | Description |
|--------|-------------|
| `list` | List items with pagination, filtering, sorting |
| `get` | Get single item by path param ID |
| `create` | Create item from request body |
| `update` | Update item by path param ID |
| `delete` | Delete item by path param ID |
| `custom` | Execute a registered custom operation (requires `operation` field) |

### Imports

Import OpenAPI specs or other formats to auto-generate mocks:

```yaml
imports:
  - path: ./openapi.yaml
    format: openapi
```

### Custom Operations

Register multi-step business logic operations on tables:

```json
{
  "action": "register",
  "definition": {
    "name": "VerifyUser",
    "steps": [
      { "type": "validate", "field": "status", "operator": "eq", "value": "pending" },
      { "type": "update", "set": { "status": "verified", "verified_at": "{{now}}" } }
    ],
    "response": { "status": 200, "body": { "message": "User verified" } }
  }
}
```

## MCP Server Setup

mockd includes an 18-tool MCP server. Configure in your AI editor:

```json
{
  "mcpServers": {
    "mockd": {
      "command": "mockd",
      "args": ["mcp"]
    }
  }
}
```

Place this in:
- Claude Code: `~/.config/claude/settings.json` (mcpServers key)
- Cursor: `.cursor/mcp.json`
- GitHub Copilot: `.github/copilot-mcp.json`
- Windsurf: Windsurf Settings > MCP

### MCP Tools (18 total)

| Tool | Actions | Description |
|------|---------|-------------|
| manage_mock | list, get, create, update, delete, toggle | Mock CRUD for all 7 protocols |
| manage_context | get, switch | View/switch admin server context |
| manage_workspace | list, switch, create | List/switch/create workspaces with isolated mocks, state, and logs |
| import_mocks | — | Import from OpenAPI, Postman, HAR, WireMock, cURL, WSDL, Mockoon |
| export_mocks | — | Export as YAML or JSON |
| get_server_status | — | Health, ports, statistics |
| get_request_logs | — | Request/response logs with filtering |
| clear_request_logs | — | Clear all captured logs |
| get_chaos_config | — | Retrieve chaos configuration |
| set_chaos_config | — | Configure chaos (latency, errors, profiles, rules) |
| reset_chaos_stats | — | Reset chaos statistics |
| get_stateful_faults | — | Circuit breaker, retry-after, progressive degradation status |
| manage_circuit_breaker | trip, reset | Manual circuit breaker control |
| verify_mock | — | Assert invocation count |
| get_mock_invocations | — | List recorded invocations |
| reset_verification | — | Clear verification data |
| manage_state | overview, add_resource, list_items, get_item, create_item, reset, delete_resource | Stateful CRUD & digital twins |
| manage_custom_operation | list, get, register, delete, execute | Multi-step operations |

## Template Functions (35 Faker Types)

| Expression | Output |
|------------|--------|
| `{{faker.name}}` | Full name (e.g., "John Smith") |
| `{{faker.firstName}}` | First name |
| `{{faker.lastName}}` | Last name |
| `{{faker.email}}` | Email address |
| `{{faker.phone}}` | Phone number |
| `{{faker.company}}` | Company name |
| `{{faker.address}}` | Full address |
| `{{faker.url}}` | URL |
| `{{faker.ipv4}}` | IPv4 address |
| `{{faker.ipv6}}` | IPv6 address |
| `{{faker.macAddress}}` | MAC address |
| `{{faker.userAgent}}` | Browser user agent |
| `{{faker.creditCard}}` | Luhn-valid credit card number |
| `{{faker.creditCardExp}}` | Expiration date (MM/YY) |
| `{{faker.cvv}}` | 3-digit CVV |
| `{{faker.currencyCode}}` | ISO 4217 code |
| `{{faker.currency}}` | Currency name |
| `{{faker.iban}}` | IBAN number |
| `{{faker.price}}` | Price (N.NN) |
| `{{faker.productName}}` | Product name |
| `{{faker.color}}` | Color name |
| `{{faker.hexColor}}` | Hex color (#RRGGBB) |
| `{{faker.ssn}}` | SSN (###-##-####) |
| `{{faker.passport}}` | Passport number |
| `{{faker.jobTitle}}` | Job title |
| `{{faker.latitude}}` | Latitude (-90 to 90) |
| `{{faker.longitude}}` | Longitude (-180 to 180) |
| `{{faker.word}}` | Single word |
| `{{faker.sentence}}` | Full sentence |
| `{{faker.words}}` | 3-5 random words |
| `{{faker.words(n)}}` | N random words |
| `{{faker.slug}}` | URL-friendly slug |
| `{{faker.uuid}}` | UUID v4 |
| `{{faker.boolean}}` | true/false |
| `{{faker.mimeType}}` | MIME type |
| `{{faker.fileExtension}}` | File extension |

Additional template variables: `{{now}}`, `{{uuid}}`, `{{timestamp}}`, `{{random.int(min,max)}}`, `{{random.float}}`, `{{random.string(n)}}`, `{{sequence("name")}}`, `{{request.body.field}}`, `{{request.query.param}}`, `{{request.header.name}}`, `{{request.pathParam.name}}`

## Chaos Engineering

### 12 Fault Types
- `latency` — Random delay injection
- `error` — Error status code injection
- `timeout` — Connection timeout
- `corrupt_body` — Corrupts response body
- `empty_response` — Returns empty body
- `slow_body` — Drip-feed slow delivery
- `connection_reset` — Simulates TCP reset
- `partial_response` — Truncates response
- `circuit_breaker` — Stateful CLOSED/OPEN/HALF_OPEN state machine
- `retry_after` — 429/503 with Retry-After header and recovery
- `progressive_degradation` — Increasing latency over time
- `chunked_dribble` — Timed chunk delivery

### 10 Built-in Profiles
`slow-api`, `degraded`, `flaky`, `offline`, `timeout`, `rate-limited`, `mobile-3g`, `satellite`, `dns-flaky`, `overloaded`

```bash
mockd serve --chaos-profile flaky
# or via API:
curl -X POST http://localhost:4290/chaos/profiles/flaky/apply
```

## Import Formats (8)
- mockd (native YAML/JSON)
- OpenAPI 3.x / Swagger 2.0 (with schema-driven response generation)
- Postman Collection v2.x
- HAR (HTTP Archive)
- WireMock JSON mappings
- cURL commands
- WSDL 1.1 service definitions
- Mockoon environment JSON

```bash
mockd import openapi petstore.yaml
mockd import postman collection.json
mockd import mockoon environment.json
```

## CI/CD — Headless Engine Mode

```bash
# Auto-assign port, print URL for test framework
mockd engine --config mocks.yaml --port 0 --print-url
# Output: http://127.0.0.1:54321

# GitHub Action
- uses: getmockd/setup-mockd@v1
  with:
    version: latest
    config: mocks.yaml
```

## Key CLI Commands

```bash
mockd serve                    # Start admin + engine
mockd engine --config f.yaml   # Headless CI mode
mockd add                      # Create mock interactively
mockd list                     # List all mocks
mockd import openapi spec.yaml # Import from OpenAPI
mockd export --format yaml     # Export mocks
mockd chaos apply flaky        # Apply chaos profile
mockd verify check <id>        # Verify mock was called
mockd logs --requests          # View request logs
mockd mcp                      # Start MCP server (stdio)
```

## Key Admin API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | /health | Health check |
| GET | /status | Server stats |
| GET/POST | /mocks | List/create mocks |
| GET/PUT/DELETE | /mocks/{id} | Get/update/delete mock |
| POST | /mocks/{id}/toggle | Toggle mock |
| POST | /config | Import config |
| GET | /config | Export config |
| GET | /requests | List request logs |
| GET/PUT | /chaos | Get/set chaos config |
| GET | /chaos/faults | Stateful fault stats |
| POST | /chaos/circuit-breakers/{key}/trip | Trip circuit breaker |
| POST | /chaos/circuit-breakers/{key}/reset | Reset circuit breaker |
| GET | /chaos/profiles | List chaos profiles |
| POST | /chaos/profiles/{name}/apply | Apply profile |
| GET | /state/resources | List stateful resources |
| POST | /state/resources | Create resource |
| GET | /mocks/{id}/verify | Verification status |

## Ports
- Mock server: 4280 (default)
- Admin API: 4290 (default)
- Never use 8080/8081 (legacy, incorrect)

## Links
- Website: https://mockd.io
- GitHub: https://github.com/getmockd/mockd
- Docs: https://mockd.io/docs
- MCP Registry: io.mockd/mockd