Relax outputSchema to any JSON Schema 2020-12 document per SEP-2106

[jayaraman-venkatesan]

feat: relax outputSchema to any JSON Schema 2020-12 document per SEP-2106

Summary

Brings the C# SDK into compliance with SEP-2106 — Tools inputSchema & outputSchema Conform to JSON Schema 2020-12

Closes #1550

The SDK previously wrapped any non-object output schema in a {"type":"object","properties":{"result":<schema>},"required":["result"]} envelope at registration, and wrapped the corresponding return value in {"result": <value>} at every invocation. Both wrappings exist because the older MCP spec required outputSchema.type == "object". SEP-2106 lifts that restriction. This PR removes both ends of the wrapping plumbing, relaxes the validator, and lets natural JSON shapes flow through.

What changes on the wire

C# return type	Before	After
int Foo() => 72;	schema {"type":"object","properties":{"result":{"type":"integer"}},"required":["result"]}; structuredContent {"result":72}	schema {"type":"integer"}; structuredContent 72
string Foo() => "Paris";	{"result":"Paris"}	"Paris"
string[] Foo() => […];	{"result":[…]}	[…]
Person? Foo() => null;	{"result": null}	null
Person Foo() => new(...);	{"name":…,"age":…} (already an object — unchanged)	{"name":…,"age":…} (unchanged)

inputSchema is not changed — tool inputs are still required to have type: "object", which is consistent with SEP-2106 (it loosens outputSchema only).

Source-level changes

• src/ModelContextProtocol.Core/McpJsonUtilities.cs — added IsValidJsonSchemaDocument accepting JSON object or boolean. Kept IsValidMcpToolSchema unchanged for InputSchema (still strict).
• src/ModelContextProtocol.Core/Protocol/Tool.cs — OutputSchema setter switched to IsValidJsonSchemaDocument; XML doc rewritten to reference SEP-2106 and the new contract.
• src/ModelContextProtocol.Core/Server/AIFunctionMcpServerTool.cs — deleted the _structuredOutputRequiresWrapping field, the out bool parameter on CreateOutputSchema, the entire wrapping/normalization block in CreateOutputSchema, the wrapping block in CreateStructuredResponse, and constructor wiring around the flag.

Contract widening

The IsValidJsonSchemaDocument validator accepts a slightly broader set than just JSON objects. The full acceptance/rejection table:

OutputSchema value	Accepted?	Notes
{"type":"object","properties":…}	✅	Conventional schema
{"type":"array","items":…}	✅	Array schemas — primary SEP-2106 motivation
{"type":"string"}, {"type":"integer"}, etc.	✅	Primitives
{"type":["object","null"], …}	✅	Type-arrays for nullable schemas
{}	✅	"No constraints" object schema
{"oneOf":[…]}	✅	Compositions without explicit type
true	✅	JSON Schema 2020-12 §4.3 boolean schema — "matches anything"
false	✅	JSON Schema 2020-12 §4.3 boolean schema — "matches nothing"
null literal	❌	Throws ArgumentException
Bare numbers, strings, arrays	❌	Throws ArgumentException

Behavioural break call-out

Source-breaking for tools that returned non-object types and whose downstream consumers relied on the {"result": …} envelope. After this PR the same tool emits the raw value. Per SEP-2106 §"Backward Compatibility": servers that emit array/primitive structuredContent and want to stay interoperable with old clients SHOULD also emit a TextContent block with the serialized JSON.

The SDK doesn't auto-add such a block, that remains the tool author's choice.

End-to-end smoke test

Beyond unit tests, I built a small in-process client/server demo against this branch that prints both phases of MCP exchange (advertising and invocation) for tools whose return types span the interesting shapes — int, string, string[], nullable record, plain record. Side-by-side before/after tables of what came out are captured in post-2106.md of the demo repo.

• Demo source + captured run: https://github.com/jayaraman-venkatesan/sep-2106-demo
• Captured output (verbatim dotnet run): Post-2106.md

The demo wires up McpServer and McpClient over a System.IO.Pipelines pipe, registers tools via McpServerTool.Create(...) against this branch's <ProjectReference>, and prints outputSchema from tools/list followed by structuredContent from each tools/call. It confirms the wire shape end-to-end against a real client, not just unit-test mocks.

Did not implement

• inputSchema validation - explicitly unchanged per SEP-2106.
• JSON Schema 2020-12 keyword-level structural validation - IsValidJsonSchemaDocument is intentionally only a structural check (object or boolean). No $ref resolution, no oneOf/anyOf keyword validation.
• Auto-emitting a TextContent mirror of structured content for old-client interop - per SEP-2106 that's a server-author choice, not an SDK default.

Test plan

• dotnet test tests/ModelContextProtocol.Tests (net10.0) — 1904/0/5.
• TDD red→green confirmed for all flipped/new tests.
• End-to-end demo (jayaraman-venkatesan/sep-2106-demo) shows expected wire shapes.

[jayaraman-venkatesan]

@mikekistler

can you help review this PR

[mikekistler]

For backward compatibility reasons, I don't think we can completely eliminate the wrapping of non-object schemas, since this will still be needed for clients using 2025-11-25 or earlier protocol versions.

[jayaraman-venkatesan]

wrapping for non-object schemas is restored in c30725c, just at the wire emission boundary instead of inside CreateOutputSchema. The classification + transformation logic is the same as before SEP-2106; it moved from registration-time storage to per-request emission so a single registered Tool can serve both legacy and SEP-2106 clients off the same server

[mikekistler]

I think this method should be named IsValidToolOutputSchema, since it is designed specifically to validate tool output schemas and not any JSON Schema document.

I think we may also need to make this conditional on the protocol version.

[jayaraman-venkatesan]

Renamed the function.

About version control here, I did not make that change to keep tools contain schema per SEP-2106. But serving of schema on tools/call and tools/list make the decision of wrapping depending on negotiated protocol version

[mikekistler]

Thank you for this contribution!

This generally looks good but I think we may need to retain the behavior of prior protocol versions for backward compatibility.

[jayaraman-venkatesan]

I will make a change to consider negotiated protocol version

[jayaraman-venkatesan]

Thanks @mikekistler ! I tried to fix your comments on c30725c.

What clients now see

• Clients on protocol versions older than 2026-06-30 (2025-11-25 and earlier) see exactly the wire shape they saw before this PR: non-object output schemas wrapped in {"type":"object","properties":{"result":<schema>}}, type:["object","null"] normalized to "object", and the matching {"result": <value>} envelope on structuredContent.
• Clients on 2026-06-30 and later (DRAFT-2026-06-v1 and 2026-06-30) see the natural JSON Schema 2020-12 document per SEP-2106.

How

• Tool.OutputSchema storage stays natural — the spec-correct form is what kept in memory.
• The version-conditional reshaping happens at two wire emission sites:
  McpServerImpl's listToolsHandler (for tools/list) and
  AIFunctionMcpServerTool.CreateStructuredResponse (for tools/call).
• Both gate on a new sibling helperMcpSessionHandler.SupportsNaturalOutputSchemas(string?) — same pattern as
  the existing SupportsPrimingEvent.

Why
We could in principle store both schemas per Tool, but we don't need to. The wrapped form is fully derivable from the natural one. Given the natural schema, the envelope around it is deterministic — same construction every time. There's no information in the wrapped shape that the natural shape doesn't carry. So I considered storing both would be redundant.

Validator rename

• IsValidJsonSchemaDocument → IsValidToolOutputSchema per your inline. Exception message and XML doc updated to also mention JSON Schema 2020-12 boolean schemas (true/false per §4.3), which SEP-2106 accepts.

Verification

• End-to-end demo run against the released ModelContextProtocol 1.2.0 package and against this branch with the same unpinned client. Output is byte-identical, so older clients see exactly what they used to.

Please help review the changes