API Shakedown MCP server

API Shakedown

<!-- mcp-name: io.github.anzar-ahsan-commits/api-shakedown -->

Give it an OpenAPI spec. Get back a ready-to-run test harness: WireMock stubs, contract tests, robustness probes, and chaos scenarios, written by a team of LLM agents that review each other's work.

Runs locally on Ollama by default: no API key, no data leaves your machine. Cloud models (OpenAI, Anthropic) are bring-your-own-key. Available as a CLI, a Docker image, and an MCP server so an AI assistant can drive it.

Status: alpha (0.1.1). Works end to end on the example spec with a local 8B model.

A real run on the bundled example with qwen3:8b on a laptop, sped up: generation took about 9 minutes. Recording: docs/demo.cast.

Contents

• Why
• Quick start
• What you get
• How it works
• Install
• Usage
• Configuration
• MCP server
• Docker
• Architecture
• Limitations
• Roadmap

Why

Teams that consume an API need three things that are tedious to write by hand and go stale quickly:

limited, returns garbage, or goes down?

1. A realistic mock of the API to develop and test against.
2. Contract tests that tell you when the real API stops matching its spec.
3. Failure drills: what does your client do when the API is slow, flaky, rate

API Shakedown generates all three from the spec you already have, and keeps them honest: the LLMs never write code that runs. They propose data (response bodies, test cases, failure scenarios, test records), and code validates every item against the spec, feeds problems back to the model, and falls back to deterministic output when a model cannot get it right. Without any model at all (--offline), every part still works.

Quick start

Prerequisites: Python 3.11+, Docker (for WireMock), and Ollama with a model (ollama pull qwen3:8b) unless you use --offline or a cloud model.

pip install api-shakedown
shakedown doctor                                   # is the model ready?
shakedown run openapi.yaml --out my-harness        # minutes on a local model
cd my-harness
docker compose up -d                               # WireMock with your stubs on :8080
pip install -r requirements.txt
SHAKEDOWN_SELECT_STATUS=1 pytest tests/test_contract.py
python chaos/chaos.py on flaky-start               # now point your client at :8080
python chaos/chaos.py off

Try it on the bundled example: shakedown run examples/petstore.yaml --out petstore.

A real run on the example spec with qwen3:8b:

Petstore 1.0.0: 5 operations (ollama / qwen3:8b)
Generating test data...
Test data ready (3 Pet).
Generating stubs, contract tests, and chaos scenarios...
  stubs: done
  contracts: done
  chaos: done
  review contracts: approved
  review stubs: approved
  review chaos: approved

Shortened. The full README is on GitHub.