Implement non-SEP changes from the 2025-11-25 → draft spec diff

[felixweinberger]

This is a tracking issue for the residual changes in the 2025-11-25 → draft spec diff that are not attributable to an individual SEP (type refinements and new normative guidance such as deterministic tools/list ordering, list-responses-when-capability-declared, empty-string cursor handling, resource path sanitization, completion value caps).

Reference: draft changelog · draft spec source

[mattzcarey]

Status — Residual 2025-11-25 → draft spec changes (non-SEP)

Track: C — independent, sweep at the end.
Source: §5 of the spec-page conformance map (mcp-spec-june-26.mattzcarey.workers.dev). 16 items, none wire-tier — all sdk type refinements or guidance/editorial. 309 hunks compared; 258 trace to release-1 SEPs.

Full list (mirror as a checklist in the issue body)

Type refinements (sdk)

• U-1 — New JSONValue / JSONObject / JSONArray types; ~15 retype sites (object → JSONObject). TS-only tightening. schema.ts:6-22 · 838d6f69 (fix: accept null tool call arguments #2139), 5c25208b (Add high-level MCP operation interceptor seam #2508)
• U-2 — Named JSON-RPC error interfaces (ParseError, InvalidRequestError, …). No new codes. schema.ts:290-368 · dc498fdf (fix(stdio): preserve multi-byte UTF-8 across chunk boundaries #2038)
• U-3 — 15 new *ResultResponse wrapper interfaces pairing each *Result with the JSON-RPC envelope. schema.ts:624,1071,1107,… · fad9db41 (fix(stdio): preserve multi-byte UTF-8 across chunk boundaries #2038)
• U-4 — MetaObject + RequestMetaObject aliases extracted (replace inline _meta types). Pure refactor. schema.ts:58 · 4c02c133 (fix(stdio): preserve multi-byte UTF-8 across chunk boundaries #2038)
• U-5 — @maxItems 100 JSDoc on CompleteResult.completion.values. schema.ts:2787 · 3b875c53 (Feature request: accept param spec as ZodType instead of ZodRawShape #588)
• U-16 — JSDoc added to Implementation.version. schema.ts:939-942 · e16fd354 (chore(deps): bump the npm_and_yarn group across 1 directory with 2 updates #1609)

New guidance (sdk-affecting MUSTs / SHOULDs)

• U-6 — Servers SHOULD return tools/list in deterministic order. tools.mdx:62-65 · 7390b6d6, 91e1f9e8 (docs: add @modelcontextprotocol/fastify to middleware listings #2516)
• U-7 — Capability declared ⇒ MUST respond to */list with current set (MAY be empty). 3 parallel insertions in tools.mdx:53-56, prompts.mdx:48, resources.mdx:59 · 30c5ced3 (fix: honor notifications/cancelled for request id 0 #2463)
• U-8 — Empty-string cursor is valid, MUST NOT be treated as end-of-results. pagination.mdx:93-95 · 5e463a21 ([DO NOT MERGE] RFC reference: request-first SDK architecture #1942)
• U-9 — Tool-name uniqueness is per-server; aggregating clients SHOULD prefix; SHOULD NOT rely on serverInfo.name. tools.mdx:315-324 · 828bd471 (fix(client): scope transport headers to MCP requests and handle redirects explicitly #2465), 4a04d4c3 (#2584)
• U-10 — Servers MUST sanitize file paths (directory-traversal). resources.mdx:406 · 828bd471 (fix(client): scope transport headers to MCP requests and handle redirects explicitly #2465)
• U-11 — Roots reframed as informational guidance, not access control; prompts reframed from "user-controlled" to "user-initiated" (server authors content). roots.mdx:10, index.mdx:67, prompts.mdx:16-17 · 65d7b670 (zod v4: toJSONSchema options are hardcoded — z.date() breaks tools/list; output schemas advertise required/closed shapes the raw structuredContent can't satisfy #2464)
• U-12 — Sampling spec normative rewrite: SamplingMessage MUST have role; SHOULD NOT retain messages between requests; client MUST respect maxTokens. sampling.mdx:521-524, 633 · d165cd68 (Allow OAuth client provider to implement token endpoint authentication methods #531)
• U-13 — Elicitation "sensitive information" narrowed to secrets/credentials. elicitation.mdx:35 · a5b18cdf (feat(client): validate discovery and endpoint URLs in the OAuth flow #2447)
• U-14 — DiscoverResult.instructions doc-comment expanded. schema.ts:606-613 · ff8bd88d (Implement SEP-2575: Make MCP Stateless #2184)
• U-15 — Stdio shutdown rewritten platform-neutral (close stdin → wait → force-kill; cite TerminateProcess; servers SHOULD exit promptly on stdin close). transports.mdx:86-100 · a7f693a6 (fix(client): align Streamable HTTP session-id lifecycle with the spec #2466)

Notes

• PRs chore(deps): bump pnpm/action-setup from 5.0.0 to 6.0.8 #2123 / fix: continue auth discovery after invalid JSON #2217 / zod listed in both dependencies and peerDependencies causes duplicate installs and TS type-incompatibility #2011 modified the draft mid-cycle but were overwritten by SEP-2575/2243 and do not appear in the final diff. No action.
• None of these are wire-tier. They're a low-risk sweep — ideal Track C late-window work or grouped into 2-3 PRs.

Suggested grouping into PRs

1. Types-only: U-1 + U-2 + U-3 + U-4 + U-5 + U-16 (mechanical schema changes)
2. List/pagination behavior: U-6 + U-7 + U-8
3. Tool aggregation + path safety: U-9 + U-10
4. Sampling/Roots/Prompts/Elicitation reframings: U-11 + U-12 + U-13 + U-14 (mostly JSDoc / docs)
5. Stdio shutdown: U-15 (transport behavior)

Coordination

• All independent. Can land in parallel with everything else.
• U-12 (sampling rewrite) touches the same surface as Implement SEP-2577: Deprecate Roots, Sampling, and Logging #2195 (SEP-2577 deprecation) — coordinate so they don't fight.