MCP SDK Audit

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.

The packages/client/** row is the subtle one: a limit added to the client's read path applies to Figwright's responses, since the client is what reads them. get_screenshot returns inline base64 and get_design_context returns large JSON, so client-side ceilings are a real exposure even though Figwright ships no client.

Stage 3 — Cross-check against the published dist

The PR list is a claim about the release; the tarball is the release. Confirm they agree — and catch anything that reached the build without a listed PR:

cd "$SCRATCH" && mkdir -p mcp-sdk-audit && cd mcp-sdk-audit
npm pack @modelcontextprotocol/server@<installed> @modelcontextprotocol/server@<target> \
         @modelcontextprotocol/core@<installed> @modelcontextprotocol/core@<target> \
         --pack-destination .
for p in server core; do for v in <installed> <target>; do
  mkdir -p "$p-$v" && tar -xzf "modelcontextprotocol-$p-$v.tgz" -C "$p-$v" --strip-components=1
done; done

# Partition each tree by CONTENT, not by filename. This one step produces both the
# coverage proof and the list of files that actually have to be read. Do it for core
# too — its chunks are content-hashed the same way.
for p in server core; do for v in <installed> <target>; do
  (cd "$p-$v/dist" && find . -type f ! -name '*.map' -exec shasum -a 256 {} \; \
     | sort -k2 > "../../hash-$p-$v.txt")
done; done
for p in server core; do
  echo "== $p =="
  comm -12 <(sort "hash-$p-<installed>.txt") <(sort "hash-$p-<target>.txt") | wc -l  # identical — the proof
  comm -3  <(sort "hash-$p-<installed>.txt") <(sort "hash-$p-<target>.txt") \
    | awk '{print $NF}' | sort -u                                                   # changed — the read list
done

🔴 Do not stop at diff -ru, and do not trust its file list — the gap it leaves is silent. v2 emits .mjs/.cjs siblings in a flat dist/ with content-hashed chunk names, so a chunk whose hash moved (mcp-DXXb3Vv3.mjs → mcp-Dw2OlZ1f.mjs) appears only as two Only in ... lines and its contents are never compared — while ReadBuffer, Protocol and registerTool all live in those chunks, not in stdio.mjs. The hash partition is what makes the read list complete: pair each changed chunk with its counterpart and diff it by name, explicitly.

diff -u server-<installed>/dist/<old-chunk>.mjs server-<target>/dist/<new-chunk>.mjs

The identical set is a real result, not bookkeeping: a release where ajvProvider-*, dialects-*, validators/ and types-*.d.mts all hash identically has not touched JSON Schema generation by a single byte. That is a static statement, so it is stronger than anything the probe can say.

⚠️ Two rename artifacts that read as false alarms:

• A long run of - lines in index.mjs can be a whole region relocated into another chunk — the 2.1.0 release moved bearerAuth and oauthMetadata into the mcp chunk, which looks exactly like deleting them until you find the matching + on the other side. Check before calling it a removal.
• .cjs and .d.cts entries are siblings of the .mjs / .d.mts you already read; read one of each pair, not both.

Within what is left, dist/**/*.d.mts hunks are the type-level surface (what tsc would catch); .mjs hunks with no .d.mts counterpart are the dangerous kind — behavior changed, signature didn't. Comparing the two versions' export { … } lists (names only, aliases stripped) settles whether the public surface lost anything, which the prose of a release note routinely omits.

Also diff package.json between the two versions: engines.node, dependencies (the pinned @modelcontextprotocol/core version and zod's supported range) all move without appearing in the source diff. v2 declares zod as a real dependency, not a peer — a range bump there can nest a second zod copy beside the repo's own.