mockzilla-mcp: Instructions file for Claude Code

mockzilla-mcp

Stdio MCP server bridging Claude Desktop / Cursor / etc. to mockzilla. Pure-JS, no build step, ESM, Node ≥ 18.

Layout

bin/cli.js     JSON-RPC entry: stdin loop, dispatch, signal handlers.
lib/tools.js   The local tool registry (descriptions + handler refs).
lib/install.js check_cli, install_cli, resolveMockzilla, cache helpers.
lib/local.js   serve_locally, stop_locally, info, lint, simplify, pack,
               generate, child tracking.
lib/discover.js discover_specs (filesystem scan + spec summaries).
lib/history.js  request_history (list) and diagnose_requests (analysis),
               both read from the running server's /.history API.
lib/replay.js   setup_replay (writes a replay block into config.yml) and
               list_replays, reading /.replay.
lib/github.js  publish_to_github and friends: push mocks to the user's own
               repo so the Mockzilla action deploys them. Drives their `gh`.
lib/docs.js    mockzilla_docs_{topics,read,search}, served from the packaged
               docs/ (MOCKZILLA_DOCS_DIR points at another build).
docs/          Built by `make build`, not in git. Ships in the npm tarball.
lib/version.js Bridge version + npm registry update check (bridge_status).
lib/auth.js    Hosted-plane login: OAuth in the browser, saved tokens, refresh.
lib/proxy.js   Hosted-plane forwarding with the saved login or MOCKZILLA_TOKEN.
lib/hosted.js  Hosted tool definitions packed at build, listed before login.
lib/util.js    Tiny shared helpers (shellEscape).

bin/cli.js is the only file the npm bin entry runs. It owns the JSON-RPC loop and delegates everything else.

Publishing to GitHub

lib/github.js is the only part of the bridge that writes outside this machine. It drives the user's own gh, pushes to a repository they name, and the deployed URL is public whatever the repo's visibility. So: visibility has no default, the repo is never invented, an existing services folder is merged into rather than replaced, and an existing workflow is never overwritten.