# Shimwire > Mock an OpenAPI/Swagger spec into a fake server, or run git-friendly TOML test collections against a real one โ€” one CLI, one shared engine, built on Bun. - **Type:** MCP server - **Install:** `agentstack add mcp-caspel26-shimwire` - **Verified:** Yes โ€” security-reviewed for prompt injection and unsafe behavior - **Seller:** [caspel26](https://agentstack.voostack.com/s/caspel26) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [caspel26](https://github.com/caspel26) - **Source:** https://github.com/caspel26/shimwire ## Install ```sh agentstack add mcp-caspel26-shimwire ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About **One tool for both sides of an API you don't fully control yet: mock the parts that aren't built, and test the parts that are.** [](https://github.com/caspel26/shimwire/actions/workflows/ci.yml) [](LICENSE) [](https://bun.sh) [](https://www.typescriptlang.org/) [](#contributing) `shimwire` reads an OpenAPI 3.x or Swagger 2.0 spec (older specs are converted automatically) and gives you two things from it, powered by one shared engine so they never drift apart: - ๐Ÿงช **Mock mode** โ€” a fake-but-schema-valid API server, so frontend work isn't blocked waiting on a backend. - ๐Ÿš€ **Client mode** โ€” a scriptable, git-friendly HTTP test runner. Collections are version-controlled TOML files you can diff and review in a PR, not JSON blobs locked in a proprietary cloud tool. --- ## Table of contents - [โœจ Features](#-features) - [๐Ÿค” Why](#-why) - [๐Ÿ“ฆ Installation](#-installation) - [๐Ÿš€ Quick start](#-quick-start) - [๐Ÿงฐ Commands](#-commands) - [โš™๏ธ Configuration](#๏ธ-configuration) - [๐Ÿ–ฅ๏ธ Testing a frontend against the mock server](#๏ธ-testing-a-frontend-against-the-mock-server) - [๐Ÿ“„ Collection format](#-collection-format) - [๐Ÿฉน Errors & debugging](#-errors--debugging) - [๐Ÿ—๏ธ Stack](#๏ธ-stack) - [๐Ÿค Contributing](#-contributing) - [๐Ÿ“œ License](#-license) ## โœจ Features - ๐Ÿ”€ **Spec-driven** โ€” mock server and test collections both come from the same OpenAPI/Swagger spec, so they can never disagree with each other. - ๐Ÿ“ **Git-native collections** โ€” plain TOML, reviewable in a normal PR diff, no proprietary cloud format. - ๐ŸŒ **CORS-ready mock server** โ€” on by default, so a browser frontend on another port just works. - ๐Ÿ“ก **Live request log** โ€” watch your frontend's traffic hit the mock in real time. - ๐ŸŽญ **Realistic fake data** โ€” schema-aware (respects `type`, `format`, `enum`, `min`/`max`), not just random junk. - ๐ŸŽฏ **Overrides** โ€” force a specific status, inject latency, or pin an exact response for edge-case testing. - ๐Ÿค– **Auto-scaffolding** โ€” `generate` builds a runnable collection from your spec, guessing request chaining and pre-filling auth. - ๐Ÿ–ฑ๏ธ **Interactive CLI** โ€” a guided menu (`shimwire cli`) for exploring a spec without memorizing flags. - ๐Ÿ“Š **HTML reports** โ€” readable request/response detail for `run`, not just terminal noise. - ๐Ÿฉบ **Clean errors** โ€” one readable line and exit code 1 on failure, not a raw stack trace. ## ๐Ÿค” Why Postman/Insomnia-style tools lock collections into proprietary formats that don't diff cleanly in git and don't run well in CI. Meanwhile, mocking a backend usually means hand-rolling fixtures that quietly drift from the real API contract. If you already have an OpenAPI (or Swagger 2.0) spec, both problems have the same fix: derive the mock _and_ the test collection from that one source of truth โ€” see [Features](#-features) above for what that gets you in practice. ## ๐Ÿ“ฆ Installation Requires [Bun](https://bun.sh) โ€” shimwire runs directly off its `#!/usr/bin/env bun` shebang, no separate build/Node install needed. ```bash npm install -g shimwire # or, without installing anything: bunx shimwire ``` Prefer building from source (or want to contribute)? ```bash git clone https://github.com/caspel26/shimwire cd shimwire bun install bun run src/cli.ts ``` Standalone binaries (no Bun install required to run) may come later. ## ๐Ÿš€ Quick start ```bash # scaffold a project cd my-project/ shimwire init # creates .shimwire/{collections,env,mock}/ # backend not ready yet? mock it from the OpenAPI/Swagger spec shimwire mock openapi.yaml --port 4000 # GET /users โ†’ 200 # POST /users โ†’ 201 # backend exists? auto-scaffold a runnable test collection from the same spec shimwire generate --from openapi.yaml --out users.toml # run it against a real backend shimwire run users.toml --env dev # โœ“ create_user POST /users 201 142ms # โœ“ get_user GET /users/42 200 38ms # wire into CI shimwire run smoke.toml --env staging --fail-on-error # get a readable HTML report instead of squinting at terminal lines shimwire run users.toml --env dev --report report.html ``` Prefer answering a few prompts instead of remembering flags? Try `shimwire cli` for a guided interactive menu. Full transcript (text version of the recording above) ```console $ shimwire init Created .shimwire/ in my-project .shimwire/collections/ .shimwire/env/ .shimwire/mock/ .shimwire/config.toml (commented-out defaults for generate/run/mock) .gitignore (created โ€” keeps .shimwire/env/*.toml out of git) $ shimwire mock ./openapi.yaml --port 4100 --no-watch & Loading spec from ./openapi.yaml... Mock server running on http://localhost:4100 GET /pets โ†’ 200 POST /pets โ†’ 201 GET /pets/{id} โ†’ 200 $ shimwire generate --from ./openapi.yaml --out .shimwire/collections/pets.toml Loading OpenAPI spec from ./openapi.yaml... Loaded "Petstore" โ€” 2 path(s) Generating collection... Writing .shimwire/collections/pets.toml... Wrote 3 request(s) to .shimwire/collections/pets.toml 1 item(s) flagged for manual review โ€” see file header. $ shimwire run .shimwire/collections/pets.toml --env dev โœ“ list_pets GET /pets 200 7ms โœ“ create_pet POST /pets 201 1ms โœ“ get_pet GET /pets/44bf8c98-8527-4f60-b5d0-3b68dca9685a 200 0ms $ shimwire run .shimwire/collections/pets.toml --env staging --fail-on-error โœ— list_pets Unable to connect. Is the computer able to access the url? โœ— create_pet Unable to connect. Is the computer able to access the url? โœ— get_pet Unknown or not-yet-run step "steps.create_pet" $ echo $? 1 ``` That last block is the whole point: the same collection that runs clean against `dev` catches a broken `staging` environment, and the nonzero exit code is exactly what `--fail-on-error` is for in a CI job. ## ๐Ÿงฐ Commands ### `shimwire init` Scaffolds `.shimwire/{collections,env,mock}/`, a starter `.shimwire/config.toml`, and a `.gitignore` entry protecting `.shimwire/env/*.toml` secrets. ### `shimwire cli` Launches an interactive menu โ€” pick "Mock", "Generate", "Workflow", "Run", or "Init" and answer a few validated prompts instead of remembering flags. Pre-fills answers from `.shimwire/config.toml` when present. Picking "Mock" starts the server in the background and returns to the menu, so you can immediately pick "Run" to test against it; after "Generate" it offers to run the collection it just wrote; "Workflow" lists every endpoint in a spec as a checkbox list to build a `.shimwire/workflows/.toml` without knowing ids up front. Useful when you're exploring a new spec rather than scripting something repeatable. ### `shimwire mock [spec]` Serves fake-but-schema-valid responses for every endpoint in a spec. | Flag | Default | Description | | ------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------- | | `[spec]` | โ€” | Path or URL to an OpenAPI 3.x / Swagger 2.0 spec. Falls back to `[mock].spec` in config. | | `-p, --port ` | `4000` | Port to listen on. | | `--overrides ` | `.shimwire/mock/overrides.toml` if present | Force specific status codes, bodies, or latency. | | `-l, --allow-local` | off | Allow fetching `spec` from localhost/private-network URLs (disables swagger-parser's SSRF guard). | | `-k, --insecure` | off | Skip TLS certificate verification while fetching `spec` (self-signed local certs). | | `--cors` / `--no-cors` | CORS on | Toggle permissive CORS headers. | | `--watch` / `--no-watch` | watch on | Toggle a live log line (time, method, path, status, duration) for every incoming request. | ### `shimwire generate` Auto-scaffolds a runnable collection from a spec, guessing request chaining and pre-filling auth. | Flag | Default | Description | | ----------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------- | | `-f, --from ` | โ€” | Path or URL to an OpenAPI 3.x / Swagger 2.0 spec. Falls back to `[generate].from` in config. | | `-o, --out ` | โ€” | Output path for the generated collection `.toml`. Falls back to `[generate].out`. | | `-s, --security ` | first auto-configurable scheme | When a spec offers multiple auth alternatives, pin one by name. | | `-l, --allow-local` | off | Same SSRF-guard override as `mock`. | | `-k, --insecure` | off | Same TLS bypass as `mock`. | If the spec has a login-shaped operation (by operationId/path, e.g. `POST /auth/login`) whose response has a token-shaped field, `generate` extracts it into `.shimwire/workflows/authentication_flow.toml` (see [Reusable workflows](#reusable-workflows)) instead of generating it as a top-level request, and every bearer-secured request gets `depends_on = ["login"]` with its token pointed at the login step's actual response field โ€” instead of the static `{{env.token}}` guess. Always flagged for review: the login step's body has faked credentials, since real ones can't be guessed. ### `shimwire workflow` Hand-pick specific endpoints from a spec and save them as a reusable `.shimwire/workflows/.toml` โ€” for building a workflow yourself rather than relying on `generate`'s login auto-detection above, e.g. a multi-step flow that isn't just a single login call. | Flag | Default | Description | | ----------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------- | | `-f, --from ` | โ€” | Path or URL to an OpenAPI 3.x / Swagger 2.0 spec. Falls back to `[generate].from` in config. | | `-n, --name ` | โ€” | Workflow file to write, under `.shimwire/workflows/`. | | `-e, --endpoints ` | โ€” | Comma-separated request ids to include. | | `-s, --security ` | first auto-configurable scheme | Same as `generate`. | | `-l, --allow-local` | off | Same SSRF-guard override as `mock`. | | `-k, --insecure` | off | Same TLS bypass as `mock`. | ```bash shimwire workflow --from openapi.yaml --name authentication_flow --endpoints login ``` Don't know the ids offhand? `shimwire cli` โ†’ "Workflow" lists every operation in the spec as a checkbox list (method, path, and the id it'll get) instead of requiring `--endpoints` up front. ### `shimwire run ` Runs a collection โ€” or a standalone workflow โ€” against a real backend. | Flag | Default | Description | | --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ | | `-e, --env ` | `dev` | Environment file under `.shimwire/env/.toml`. | | `--only ` | โ€” | Run a single request plus its dependencies. | | `--fail-on-error` | off | Exit non-zero if any request fails โ€” for CI. | | `-k, --insecure` | off | Skip TLS certificate verification. | | `-r, --report ` | โ€” | Write an HTML report (full request/response detail, sensitive headers redacted). Falls back to `[run].report` in config. | A workflow (`.shimwire/workflows/.toml`) can be run directly, the same as any collection โ€” no need to wrap it in one just to try it out: ```bash shimwire run .shimwire/workflows/authentication_flow.toml --env dev # or, resolved the same way collection names are: shimwire run authentication_flow.toml --env dev ``` `run` detects which shape a file is (a collection has `[meta]`, a workflow doesn't) and, for a bare workflow, resolves `{{env.base_url}}` from `--env` exactly like a hand-written collection would. ### `shimwire mcp` Starts an [MCP](https://modelcontextprotocol.io) server (stdio transport) exposing shimwire's spec/collection/workflow tools to an AI client โ€” Claude Desktop, Claude Code, or anything else that speaks MCP. Point a client's config at it: ```json { "mcpServers": { "shimwire": { "command": "bunx", "args": ["shimwire", "mcp"] } } } ``` The recording below isn't a shimwire subcommand โ€” it's [`assets/mcp-demo-client.ts`](assets/mcp-demo-client.ts), a small standalone script standing in for an AI agent, so you can see real tool calls and real responses instead of trusting a description: | Tool | Does | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `load_spec` | Parse a spec, list every operation's id/method/path โ€” see what's actually available before generating anything. | | `init_project` | Scaffold `.shimwire/`. | | `generate_collection` | Same as `shimwire generate` โ€” full collection from a spec, login auto-detected into a workflow. | | `create_workflow` | Same as `shimwire workflow` โ€” hand-picked endpoints saved as a named workflow. | | `list_collections` / `list_workflows` | See what's already in the project. | | `run_collection` | Run a collection or workflow, get structured pass/fail back per step โ€” so the result can be checked, not just assumed. | | `start_mock` | Start a mock server from a spec โ€ฆ ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source โ€” we do not rehost the code. - **Author:** [caspel26](https://github.com/caspel26) - **Source:** [caspel26/shimwire](https://github.com/caspel26/shimwire) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** โ€” Free ## Security capabilities Automated source analysis of v0.1.0 โ€” what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source โ€” more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** โ€” security scan: passed โ€” Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-caspel26-shimwire - Seller: https://agentstack.voostack.com/s/caspel26 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack โ€” the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.