/mcp-sdk-audit

name: mcp-sdk-audit
description: 'Upgrade @modelcontextprotocol/server (the MCP TypeScript SDK v2) and prove the wire contract survived. The SDK is a runtime dependency whose breakage lands on the wire, not in the type checker — so this sorts each release by which SDK source files it touched (Figwright uses only the server + stdio slice of a client/server/multi-runtime package family), then diffs what a real MCP client observes — negotiated protocol version, every tool JSON Schema, annotations, prompts — before and after the bump. Use whenever the user wants @modelcontextprotocol/server or the other @modelcontextprotocol/* packages updated or audited, asks what a new SDK version changes for the server or its clients, or lands on a Renovate bump PR for that package.'

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 every tool, 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.

Stage 1 — Read the release notes as an index, not as an answer

The GitHub Releases body is an auto-generated list of PR titles, written for SDK contributors: it says *what was changed*, never *who is affected*. "stdio buffer limit" reads like it belongs to whoever runs stdio; the useful question is which package and which directory it landed in.

So use the notes only to get the PR numbers, then ask each PR what it touched:

gh api repos/modelcontextprotocol/typescript-sdk/releases --jq '.[] | select(.tag_name=="@modelcontextprotocol/server@<target>") | .body'
# then, per PR number in that body:
gh pr view <n> --repo modelcontextprotocol/typescript-sdk --json title,files \
  --jq '"\(.title)\n  " + (.files | map(.path) | join("\n  "))'

⚠️ **Read the whole file list, never just the first entry.** v2 splits one concern across packages by design — a wire change routinely lands in `packages/core-internal/src/wire/`, `packages/server/src/server/`, and `packages/client/src/` at once. Judging a PR by its first file is how the hunk that mattered gets missed.

Stage 2 — Sort by file path

Figwright imports exactly two entry points (`packages/mcp/src/index.ts`, `src/prompts/*`, `test/tool-schema.ts`, `test/e2e/mcp-wire.test.ts`): `@modelcontextprotocol/server` and `@modelcontextprotocol/server/stdio`. That narrow slice is what makes this audit cheap — most of any given release is about parts of the family this server never loads.

| SDK path | Bearing on Figwright | | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | | `packages/server/src/server/mcp.ts`, `server.ts` | **Load-bearing.** `registerTool` / `registerPrompt` / result serialization | | `packages/server/src/server/serveStdio.ts`, `stdio.ts` | **Load-bearing.** The entry point and the only transport this server runs | | `packages/server/src/fromJsonSchema.ts`, `validators/` | **Load-bearing and invisible.** Turns each spec's