mockzilla-mcp CLAUDE.md

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, peek_openapi, child tracking.
lib/discover.js discover_specs (filesystem scan + spec summaries).
lib/docs.js    mockzilla_docs_{topics,read,search}; raw GitHub source +
               MOCKZILLA_DOCS_DIR override for contributors editing docs.
lib/version.js Bridge version + npm registry update check (bridge_status).
lib/proxy.js   Hosted-plane forwarding (uses MOCKZILLA_TOKEN).
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.

Two planes

• Local plane. Tools that touch the user's machine. Defined in lib/tools.js, handlers live in lib/install.js or lib/local.js. Always available — no auth, no token.
• Hosted plane. Tools the Django server defines at app/mcp/tools.py. Proxied through when MOCKZILLA_TOKEN is set. When the bridge sees a tools/call for a name it doesn't recognise locally, it forwards to the hosted endpoint.

Tool names must not collide — local tools always win the dispatch, so a local tool with the same name as a hosted one would shadow it.

Adding a new local tool

There's a registry pattern — lib/tools.js is the single source of truth for what the agent sees. The actual handler lives in lib/local.js (or, if it's an install/cache concern, lib/install.js).

1. Write the handler

Add an async function to lib/local.js:

export async function describe_thing(args) {
  // Validate args. Throw if invalid; the bridge translates thrown
  // errors into MCP `isError: true` results so the agent surfaces
  // them to the user.
  if (typeof args.target !== "string") {
    throw new Error("`target` must be a string");
  }

  // Do the work. Plain return value becomes the result's JSON text
  // content. Keep it small and structured — the agent reads it.
  return { target: args.target, observed: someState() };
}