Mockwave

Verify installation

mockwave version

Docker

docker run -p 8080:8080 -p 9090:9090 \
  -v $(pwd)/config.json:/config.json \
  ghcr.io/lfdubiela/mockwave:v0.1.0 \
  start -f /config.json

---

Compile your .proto to a descriptor

protoc --descriptor_set_out=service.pb --include_imports service.proto

DynamoDB Setup

Create two tables (substitute region/table names as needed):

aws dynamodb create-table --table-name mockwave-rules \
  --attribute-definitions AttributeName=id,AttributeType=S \
  --key-schema AttributeName=id,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST

aws dynamodb create-table --table-name mockwave-simulations \
  --attribute-definitions AttributeName=id,AttributeType=S \
  --key-schema AttributeName=id,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST

---

Setup

Ensure mockwave is on your $PATH (e.g. via brew install mockwave), then add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "mockwave-local": {
      "command": "mockwave",
      "args": ["mcp", "--admin-url", "http://localhost:9090"]
    }
  }
}

Multiple instances are supported — Claude Code namespaces the tools automatically:

{
  "mcpServers": {
    "mockwave-local": {
      "command": "mockwave",
      "args": ["mcp", "--admin-url", "http://localhost:9090"]
    },
    "mockwave-sandbox": {
      "command": "mockwave",
      "args": ["mcp", "--admin-url", "https://mockwave.sandbox.example.com"]
    }
  }
}

Security: The Mockwave admin API has no authentication. When pointing --admin-url at a remote instance, ensure the admin port is protected by a firewall or reverse proxy.

Docker

```bash

Building locally

docker build -t mockwave:local .
docker run -p 8080:8080 -p 9090:9090 \
  -v $(pwd)/config.json:/config.json \
  mockwave:local start -f /config.json

---

Building from Source

Requirements: Go 1.21+

```bash git clone https://github.com/lfdubiela/mockwave.git cd mockwave

Build binary

make build # outputs ./mockwave

Quick Start

Examples

```bash

Examples

Create a rule from a natural language description:

You: "Create a mock for GET /orders that returns 200 with an empty orders array"

Claude calls create_simulation → POST /api/simulations
Claude calls create_rule       → POST /api/rules
Claude: "Done. GET http://localhost:8080/orders now returns {"orders":[]}"

Generate mocks from an existing OpenAPI spec:

You: "Generate mocks from https://petstore3.swagger.io/api/v3/openapi.json"

Claude calls generate_from_openapi with the URL
Claude: "Created 18 rules and 18 simulations covering all Petstore endpoints.
         GET /pet/{petId} → 200 {"id":1,"name":"doggie","status":"available"}
         POST /pet        → 201 {"id":1,"name":"doggie"}
         DELETE /pet/{petId} → 200
         ..."

Inspect what's being hit and fix gaps:

You: "What requests are hitting mockwave but not matching any rule?"

Claude calls list_unmatched
Claude: "3 unmatched requests found:
         POST /api/v2/checkout  ← no rule
         GET  /api/v2/cart/99   ← no rule
         Want me to create mocks for these?"

Dynamic script mock via MCP:

You: "Create a mock for GET /users/:id that echoes the ID back in the response"

Claude calls create_simulation with script:
  const id = request.path.split('/').pop();
  return { body: { id: id, name: "User " + id } };
Claude calls create_rule → POST /api/rules
Claude: "Done. GET /users/42 now returns {"id":"42","name":"User 42"}"

Create a minimal config

cat > config.json <<'EOF' { "rules": [ { "id": "hello", "name": "Hello World", "match": { "method": "GET", "path": "/hello" }, "buckets": [{ "weight": 100, "action": "simulate", "simulation_id": "hello-sim" }] } ], "simulations": [ { "id": "hello-sim", "protocol": "http", "response": { "status": 200, "body": { "message": "Hello from Mockwave!" } } } ] } EOF

Validate a config file

mockwave validate config.json ```

---

Config File Format

The JSON config file has two top-level arrays: rules and simulations.

{
  "rules": [ ...Rule... ],
  "simulations": [ ...Simulation... ]
}

Run with a local config file

docker run -p 8080:8080 -p 9090:9090 \ -v $(pwd)/config.json:/config.json \ ghcr.io/lfdubiela/mockwave:v0.1.0 \ start -f /config.json

DynamoDB backend (IAM role or env vars)

docker run -p 8080:8080 -p 9090:9090 \ -e AWS_ACCESS_KEY_ID=... \ -e AWS_SECRET_ACCESS_KEY=... \ -e AWS_REGION=us-east-1 \ ghcr.io/lfdubiela/mockwave:v0.1.0 \ start --store dynamodb ```

CLI Reference

mockwave [command]

Commands:
  start     Start the mock server
  validate  Validate a config file without starting the server
  version   Print version
  mcp       Start MCP server for AI assistant integration (Claude Code, etc.)

Flags (start):
  -f, --config string            Path to JSON config file (required for --store=json)
      --port int                 Mock server port (default 8080)
      --admin-port int           Admin UI/API port (default 9090)
      --protocols string         Comma-separated: http,graphql,soap,grpc (default "http")
      --grpc-port int            gRPC server port (default 50051)
      --grpc-proto string        Path to compiled .pb descriptor for gRPC proto conversion

  # Store backend
      --store string             Storage backend: json|dynamodb|mongo|cosmos (default "json")

  # DynamoDB
      --dynamo-rules-table string  DynamoDB table for rules (default "mockwave-rules")
      --dynamo-sims-table string   DynamoDB table for simulations (default "mockwave-simulations")
      --dynamo-region string       AWS region (default "us-east-1")
      --dynamo-endpoint string     Custom endpoint, e.g. http://localhost:8000

  # MongoDB
      --mongo-uri string          MongoDB connection URI (default "mongodb://localhost:27017")
      --mongo-db string           MongoDB database name (default "mockwave")

  # Cosmos DB
      --cosmos-uri string         Cosmos DB connection string (MongoDB API)
      --cosmos-db string          Cosmos DB database name (default "mockwave")

Admin REST API

All endpoints are on the admin port (default :9090).

MCP (Claude Code integration)

With Mockwave running, add to ~/.claude/mcp.json (create if it doesn't exist):

{
  "mcpServers": {
    "mockwave-local": {
      "command": "mockwave",
      "args": ["mcp", "--admin-url", "http://localhost:9090"]
    }
  }
}

Then ask Claude Code to do the work:

"Generate mocks from https://petstore3.swagger.io/api/v3/openapi.json"
"Create a mock for POST /checkout that returns 201 with an order ID"
"What requests are hitting mockwave but not matching any rule?"

AI Integration (MCP)

mockwave mcp exposes a Model Context Protocol server that lets Claude Code (and other MCP-compatible AI assistants) create, inspect, and delete rules and simulations on any Mockwave instance — local or remote.