feat: add SEP-2106 structuredContent wire-shape scenario (complements #295)

[olaservo]

Summary

Complements #295 by adding the second half of SEP-2106's wire-format changes that the keyword-preservation checks don't reach: the loosened outputSchema (non-object types at the root) and the widened structuredContent (any JSON value, not just records). These are exactly the shapes SEP-2106's motivation section is built around (the weather-forecast and get-count examples).

cc @pcarleton — heads-up that this picks up where #295 left off; happy to fold differently if you'd prefer the checks live inside JsonSchema2020_12Scenario.

What #295 covered vs. what this adds

SEP-2106 surface	Covered by #295?	Covered here?
inputSchema keeps type: \"object\" plus 2020-12 vocabulary survives tools/list	✅	—
outputSchema may be type: \"array\" at the root, advertised in tools/list	—	✅
outputSchema may be a primitive (type: \"number\") at the root	—	✅
tools/call returns an array directly in structuredContent (on the wire)	—	✅
tools/call returns a primitive directly in structuredContent (on the wire)	—	✅
Client MUST NOT auto-deref network $ref (SEP security section)	✅ (json-schema-ref-no-deref)	—

New scenario: sep-2106-structured-content

Six checks across two test tools:

check ID	what it asserts
sep-2106-array-output-tool-found	tool advertised
sep-2106-array-output-schema-preserved	outputSchema.type === 'array' survives tools/list (SDK didn't wrap it in {type:'object'})
sep-2106-array-structured-content	tools/call returns array directly in structuredContent
sep-2106-primitive-output-tool-found	tool advertised
sep-2106-primitive-output-schema-preserved	outputSchema.type === 'number' survives
sep-2106-primitive-structured-content	tools/call returns raw number in structuredContent

All emit FAILURE (capability-test framing, same as SEP-1613 / #295 — no new RFC 2119 sentences in the spec diff, so the keyword-mapping rule doesn't constrain severity). The scenario lives in pendingClientScenariosList only — the in-repo everything-server can't satisfy these checks until the SDK widens CallToolResultSchema.structuredContent to unknown. Once that lands, the pending entry comes out.

Why raw HTTP + a non-SDK reference server

Pre-SEP-2106, both sides of the SDK reject non-object structuredContent:

• The SDK Client response validator rejects the tools/list response (outputSchema.type !== 'object') and the tools/call response (structuredContent not a record). The scenario uses raw http.request to bypass that and inspect the actual wire bytes.
• The SDK Server validates outgoing tools/call results against the same CallToolResultSchema and returns JSON-RPC -32602 instead of letting array/primitive structuredContent through. That means the only way to demonstrate a fully-compliant server today is to skip the SDK entirely, which is what examples/servers/typescript/sep-2106-compliant-server.ts does (bare Express, ~170 lines).

The compliant server is the positive-test target. A vitest in negative.test.ts (port 3009) spawns it and asserts all six checks SUCCESS — without it, there's no way to prove the scenario isn't just emitting FAILURE everywhere.

Files

• src/scenarios/server/sep-2106-structured-content.ts — new scenario (raw HTTP, ~440 lines incl. helper)
• examples/servers/typescript/sep-2106-compliant-server.ts — non-SDK reference server (raw Express, ~170 lines)
• src/scenarios/server/negative.test.ts — positive vitest case against the compliant server
• src/scenarios/index.ts — register in pendingClientScenariosList + allClientScenariosList, comment mirrors SEP-1613 framing

Test plan

• npm run typecheck — clean
• npm run lint — clean
• npm test — 215/215 passing (was 207 pre-change; +1 positive case = 208? — actually pre-push hook reports 215 because the scenario emits checks that the existing soft suite counters also see; the only new vitest block is the compliant-server positive case)
• Reviewer to check whether the wire-shape concerns belong in their own scenario (this PR) or folded into JsonSchema2020_12Scenario alongside SEP-2106: traceability YAML + JSON Schema 2020-12 conformance checks #295's checks — I went with separate because the soft version gate (SKIPPED/FAILURE) doesn't quite fit here (the SDK can't return the new shape at any negotiated version), but happy to fold.
• Once the SDK ships SEP-2106's CallToolResultSchema widening: remove the pendingClientScenariosList entry; the in-repo everything-server can then be extended with these tools and the scenario goes green against it.

Notes for review

• Severity: SEP-2106's spec diff in docs/specification/draft/server/tools.mdx adds no new RFC 2119 sentences (descriptive-only loosening), so per AGENTS.md the keyword-mapping doesn't force a severity. I chose FAILURE to match SEP-2106: traceability YAML + JSON Schema 2020-12 conformance checks #295's choice for its capability checks; counter-argument: WARNING would be defensible if you consider these advisory until SDK support is widespread.
• sep-2106-broken-schema.ts negative-test server: not included — SEP-2106: traceability YAML + JSON Schema 2020-12 conformance checks #295 already ships sep-2106-stripped-schema.ts covering the same negative-test role for the keyword-preservation checks. Adding another wire-shape negative server felt like noise; the positive case + SEP-2106: traceability YAML + JSON Schema 2020-12 conformance checks #295's stripped server cover the failure modes adequately. Happy to add one if reviewers disagree.
• TextContent fallback SHOULD: deliberately not added — SEP-2106: traceability YAML + JSON Schema 2020-12 conformance checks #295 explicitly considered and dropped that yaml row (rationale: the SHOULD predates SEP-2106). If we want to test it under the existing tools.mdx SHOULD framing, that's a separate PR not tied to SEP-2106.

---

Note: implementation assisted by Claude Code 🦉 (full transcript available on request); design choices and the comparison to #295 are mine.

[pkg-pr-new]

Open in StackBlitz

npx https://pkg.pr.new/@modelcontextprotocol/conformance@308

commit: 7d4b97d