Example: stdio server gated by a committed surfacepin.lock.json

[yellowgram]

What

Add an example (not a runtime dependency of the published SDK) that shows the current server factory — createServer / McpServer.registerTool / serveStdio — with an external exact-hash lock of the tools list.

The gate is the MIT npm package surfacepin@^1.5.0 (pinStdio / verifyStdio, or the CLI surfacepin verify --stdio) against a file named surfacepin.lock.json. Pass/fail is digest equality. Field-diff labels (COMPATIBLE, BREAKING, HINT_FLIP) explain a mismatch; they are not the verdict. This is not a security or safety product, and it is not the internal behavior-surface pins in docs/behavior-surface-pins.md.

Why an example, not an SDK dependency

surfacepin shells out to a live stdio server and hashes tools/list. It should stay an optional devDependency of the example (npm install --save-dev surfacepin@^1.5.0). It depends on v1 @modelcontextprotocol/sdk, so it should not be a runtime dependency of the published v2 packages.

Suggested shape

• examples/surfacepin-lock/ next to the quickstarts (own package, excluded from the client/server story runner, typecheck-only in CI).
• Committed surfacepin.lock.json.
• README: lock live stdio, commit that filename, verify the same file in CI or pre-commit. Drift fails closed.
• Optional short generator note. No payment, hosted account, or upgrade step.

Draft implementation (fork only — not an upstream PR yet)

A discuss-first draft lives on the yellowgram fork:
yellowgram#1

Happy to retarget or drop it if an example like this does not belong upstream.