Proposal: optional contract-stability metadata in server manifests (PIN-SPEC 3.2 surfaceHash) #1720

The registry tells a consumer what a server is, but nothing about whether its tool surface is stable across the versions it lists. Quickstart pinning is being fixed on the docs side (modelcontextprotocol#3431); the next gap after "install this exact version" is "and here is what that version serves".

Proposal: an optional, verifiable contract-stability field in the per-server manifest. Concretely, a surfaceHash - sha-256 over the canonical (sorted-keys, compact JSON per PIN-SPEC §3) array of per-tool canonical objects {name, description, inputSchema}, sorted by tool name. This is not a proposal-stage format: PIN-SPEC §3.2 specifies it (additive, optional), the reference implementation stamps it into every pin since 1.5.0, and 60+ public per-version snapshots exist as worked examples (archive), plus a slug-to-registry-id mapping for the servers we watch (registry-mapping.json).

What it would give the registry: publishers attest "version X serves this exact tool surface"; clients and CI verify a resolved server against the attestation before first run; population-level stability becomes computable. The field evidence says it matters: 25 of 28 watched npm-distributed servers changed at least one tool contract across version windows (our corpus), and a third-party sandbox log measuring 21,738 packages reports 6.5% shipping a version whose tools/list differed from the previous one (same spec thread).

Scope note: this is an offer of an interchange format, not a product pitch - the spec is free to reuse independent of the reference implementation. Happy to write it up as an RFC-style issue with exact canonicalization rules if there is interest.