docs: require Server Card to be consistent with runtime behavior

[tadasant]

Closes #23.

What

Adds the missing normative requirement that a Server Card's declared values must not contradict the server's actual runtime behavior. The schema already encodes the omission half of the threat model (primitives are deliberately excluded because a static manifest drifts from runtime); this adds the complementary requirement for the fields the card does declare.

docs/discovery.md

• New "Consistency with Runtime Behavior" subsection under "MCP Server Cards":
  • A Server Card SHOULD accurately reflect the server's actual runtime behavior. The serverInfo (name, version) and supportedVersions returned by server/discover, plus the transport actually served at each remotes[] endpoint (and descriptive title/description/icons), SHOULD NOT contradict the equivalent values declared in the Server Card.
  • Clients MUST NOT treat Server Card contents as authoritative for security or access-control decisions, and SHOULD verify claims against the live connection — the same posture the spec takes toward primitives, generalized to the declared fields.
• New "Server Card Accuracy" subsection under "Security Considerations": frames an inaccurate (stale or crafted) card as a mild confusion/downgrade vector, so the consistency requirement is partly a security property, not just correctness. It is explanatory and points back to the single normative statement above rather than re-asserting the MUST NOT.

schema.ts

• Short pointer comment in the ServerCard JSDoc referencing the discovery-doc requirement, complementing the existing primitives-omission rationale. schema.json regenerated via npm run generate in the same commit (CI check enforces sync).

RFC 2119 keywords are used consistently with the rest of docs/discovery.md. The runtime reference is phrased around the draft spec's server/discover operation — the pre-initialize exchange that actually returns serverInfo/supportedVersions — rather than SEP-2127's DiscoverResultResponse, which has no term in this repo.

Security rationale

Because a Server Card is consumed before the client connects, an inaccurate card can steer a client toward a weaker configuration (downgrade) or a misidentified server (confusion) before it has observed the server's actual server/discover response. Treating the card as advisory rather than authoritative contains this risk.

Scope

Small and focused strictly on the card-vs-runtime consistency requirement. Distinct from #10 (the inverse — primitives the card omits) and #13/#9/#11/#12/#14/#21 (none touch card-vs-runtime consistency). No unrelated changes.

Verification

• npm run check passes — schema.json is in sync with schema.ts and tsc --noEmit is clean
• npm run validate passes — all 7 examples validate against the regenerated schema
• npm run format clean — no formatting changes left
• schema.json regenerated and committed alongside the schema.ts change (CI check enforces this)
• Fresh-eyes review by a separate agent — feedback addressed (full-term "Server Card" wording for consistency with the rest of the doc; de-duplicated the MUST NOT so the security section is explanatory and points to the single normative statement)
• Maintainer review (Sam) — substance approved; applied the requested brevity pass, tightening both new subsections with no change to any normative statement
• server/discover spec link verified to resolve to a real draft-spec page documenting serverInfo / supportedVersions
• CI green on the final commit (0d0389b) — build, Analyze (actions), and CodeQL all pass

This is a docs/comment-only change (no runtime code paths), so the verification is the build/schema toolchain rather than e2e tests. Local toolchain output:

✓ Generated schema.json
✓ schema.json is up to date    (npm run check)
All 7 example(s) passed.        (npm run validate)

Opened for human review — not merged, per repo policy.

[SamMorrowDrums]

I think this covers it well, in some ways it is wordier than I had anticipated - but other then possible brevity pass, I am happy.

[SamMorrowDrums]

Thanks I think this is solid.

[a-akimov]

Like the wording too. Thank you considering this and expanding the doc.