Implement SEP-2106: Tools inputSchema & outputSchema Conform to JSON Schema 2020-12

[felixweinberger]

This is a tracking issue for implementation of SEP-2106.

[mattzcarey]

Status — SEP-2106 (Tools inputSchema & outputSchema conform to JSON Schema 2020-12)

Track: C — independent, starts now.
Spec: seps/2106-json-schema-2020-12.md · merged

What's done — partial (cosmetic only)

• packages/core/src/types/spec.types.ts (main) carries doc-comments stating "Defaults to JSON Schema 2020-12 when no explicit $schema is provided" on Tool.inputSchema and Tool.outputSchema. But the type still says type: 'object' at the root for outputSchema and the validator has not been switched to 2020-12 semantics.
• No PRs yet referencing SEP-2106 directly.

Outstanding (acceptance criteria, summary)

• R-2106-1 (wire): Implementations MUST validate tool inputs/outputs against declared schemas including 2020-12 keywords (e.g. oneOf, anyOf, allOf, not, if/then/else, $ref, $defs, $anchor, prefixItems)
• R-2106-2 (sdk): Default dialect 2020-12 when $schema absent — needs the actual validator wired to 2020-12 (numeric exclusiveMinimum, prefixItems honored, etc.)
• R-2106-7 (sdk): outputSchema accepts any valid 2020-12 schema — drop the type: 'object' restriction at the root. Tool.outputSchema typings need to be unknown/JSONSchema.
• R-2106-8 (sdk): inputSchema keeps type: 'object' at root, but accepts arbitrary 2020-12 keywords alongside (oneOf/etc.)
• R-2106-5 (wire): Servers using array or primitive structuredContent MUST also emit a TextContent block with the serialized JSON (BC fallback)
• R-2106-6 (wire): structuredContent widened to any JSON value (object, array, string, number, boolean, null) — CallToolResult.structuredContent should be typed unknown, not {[k:string]:unknown}. (Today main still has structuredContent?: { [key: string]: unknown }.)
• R-2106-9 (sdk): SDK MUST NOT automatically dereference $ref to network URIs; only same-document JSON Pointers / $anchor resolved by default
• R-2106-10 (sdk): Opt-in external-$ref mode disabled by default; SHOULD enforce host allowlist (reject loopback/link-local/private), timeouts, size limits
• R-2106-11 (sdk): Unresolved external $ref → reject (not silently pass)
• R-2106-12 (guidance): Bound composition-keyword validation cost to prevent CPU DoS

Suggested validator choice

• The existing validator is Ajv (or similar). Ajv supports 2020-12 via Ajv2020. The migration:
  1. Switch default to Ajv2020
  2. Wire Tool.outputSchema widening + structuredContent: unknown
  3. Add the network $ref guard
  4. Add a depth / subschema-count limit

Coordination

• No cross-track dependencies. Can land independently.
• Watch interaction with Implement SEP-2200: Clarify tool result content visibility #2193 (SEP-2200): the widening of structuredContent to non-object JSON values is the same line of code in spec.types.ts. Land together to avoid churn.

[norika1207-lab]

This looks worth pinning down as a protocol-level regression rather than only an implementation bug.

For tools inputSchema and outputSchema JSON Schema 2020-12, the acceptance test I would want is a minimal client/server fixture that records the exact JSON-RPC or HTTP exchange, then asserts both the wire result and the local lifecycle state after the failure path. In MCP deployments, the dangerous failures are often not just wrong return values; they are pending requests, dropped notifications, mismatched session state, or errors that get translated into a generic response and become impossible to diagnose.

A useful fix boundary would preserve three signals: the protocol error sent to the peer, the local exception or cancellation reason available to application code, and a trace/log field that ties the two together. That makes the behavior debuggable for agent hosts without requiring every host to special-case this SDK detail.