figwright: Skill for Claude Code

Absorbing a @modelcontextprotocol/server release into Figwright, end to end: audit → upgrade → prove the wire contract is unchanged.

Do not reason about this the way figma-typings-audit reasons about plugin typings. That package is types-only, so tsc is a real gate. This one is a runtime dependency: it serializes every tool result, generates the JSON Schema for all ~112 tools, and negotiates the protocol version. A release can leave every type identical and still change what clients see. pnpm typecheck will stay green through it.

Unlike every other dependency here, this one has a dedicated gate — use it. packages/mcp/test/e2e/mcp-wire.test.ts spawns the built dist over real stdio, speaks raw JSON-RPC at it, and asserts the advertised contract against what the specs declare. It runs in pnpm test. That gate answers did anything break; it does not answer what moved, which is what an audit is for — Stage 5 covers the difference.

Know the one thing that gate cannot see. Its schema check compares the SDK's output against test/tool-schema.ts's derivation, and both call the same z.toJSONSchema. That is independent of the SDK — it catches an SDK that stops asking Zod the same question — but not of Zod: when Zod changes what it answers, both sides move together and the equality still holds. An SDK bump that also moves the resolved zod version (its range is ^4.2.0, so it shares the repo's copy) can therefore reshape every client's schema with this gate green. packages/mcp/test/json-schema-generation.test.ts covers that half by pinning each construct's rendering by hand — if a bump moves the Zod version, read its diff too, and let probe.mjs name which tools changed.

Target version: whatever the user named, otherwise the latest @modelcontextprotocol/server on npm.

Stage 0 — Resolve versions

grep '@modelcontextprotocol' packages/mcp/package.json          # declared range
grep -m1 '@modelcontextprotocol/server@' pnpm-lock.yaml         # what is installed
npm view @modelcontextprotocol/server version dist-tags --json  # latest
gh api repos/modelcontextprotocol/typescript-sdk/releases --jq '.[0:15][] | "\(.tag_name)\t\(.published_at)"'

Figwright is on v2 — the package family (@modelcontextprotocol/server + its transitive /core, with /client, /node, /express, /hono, /fastify, /server-legacy, /codemod alongside). It depends on exactly one of them.

Two things the releases list will show that are not upgrades for us:

• Bare 1.30.0-style tags are the v1 legacy line (@modelcontextprotocol/sdk, source on the long-lived v1.x branch). Figwright left it; a v1 tag is not our concern.
• @modelcontextprotocol/{client,express,fastify,hono,node,server-legacy,codemod}@X tags ship on the same version number as server but are packages we do not install.

If installed and target are equal, say so and stop.