Hide experimental types from external source generators using internal property pattern

[MackinnonBuck]

Problem

Experimental properties on stable protocol types (e.g. Tool.Execution, ServerCapabilities.Tasks) cause two problems for consumers who don't use those APIs:

1. Binary compatibility. The STJ source generator emits code that directly references experimental types. If an experimental type is renamed, restructured, or removed in a future SDK version, previously compiled source-generated code breaks, even if the consumer never used the experimental API.
2. Unwanted diagnostics. The source generator's references to experimental types trigger MCPEXP001 at compile time, forcing consumers to suppress a diagnostic for an API they aren't using.

Approach

Alternative to #1260. Each experimental property is marked [JsonIgnore] and delegates to an internal property marked [JsonInclude][JsonPropertyName]:

[Experimental(Experimentals.Tasks_DiagnosticId, UrlFormat = Experimentals.Tasks_Url)]
[JsonIgnore]
public ToolExecution? Execution
{
    get => ExecutionCore;
    set => ExecutionCore = value;
}

[JsonInclude]
[JsonPropertyName("execution")]
internal ToolExecution? ExecutionCore { get; set; }

This resolves both issues. Because internal members are invisible across assembly boundaries, external source generators never emit code referencing experimental types, eliminating the binary compatibility concern. And because the public property is [JsonIgnore]d, the source generator uses object rather than the experimental type, avoiding the MCPEXP001 diagnostic entirely. The only code path that serializes these properties is the SDK's own McpJsonUtilities.DefaultOptions.

Consumer experience

• Not using experimental APIs: No diagnostics, no binary coupling to experimental types. Experimental properties are still serialized on the wire through the SDK's own resolver, so protocol compatibility is maintained.
• Using experimental APIs: Suppress MCPEXP001 as usual. Serialization through McpJsonUtilities.DefaultOptions handles everything.
• Custom JsonSerializerContext + experimental APIs: Configure TypeInfoResolverChain so the SDK's resolver takes precedence for SDK types. Only needed by consumers who both use experimental APIs and define a custom serialization context.
• Stabilization: Remove [Experimental]/[JsonIgnore], add [JsonPropertyName], convert to auto-property, delete the *Core property. No consumer changes required.

Changes

• Applied the internal property pattern to all 7 experimental properties across protocol types
• Added a compile-time regression test project (ExperimentalApiRegressionTest) that builds with [JsonSerializable] references to all affected types, verifying no MCPEXP001 diagnostics are emitted
• Added a scan-based test enforcing the internal property pattern across all experimental properties
• Added serialization round-trip tests verifying behavior with consumer-defined source-generated contexts

Fixes #1255

[jeffhandley]

Nit: Since we sometimes use a *Core suffix for protected or internal members, I suggest a suffix with stronger connotation about its purpose, such as Task_Experimental.

[MackinnonBuck]

Since we sometimes use a *Core suffix for protected or internal members

Just to clarify, this member is internal, so the name doesn't surface in public API. That said, I'm happy to consider other names if they better convey the purpose of the property.

[eiriktsarpalis]

How can we make sure this is being adequately advertised to users? The fact that we're silently dropping experimental properties only for externally defined source generators (but not externally defined reflection-based JSOs) seems to violate the principle of least astonishment, particularly in the face of us documenting that STJ has the same behavior regardless of what contract resolver is being used.

Given how STJ is being used typically in AOT apps, users could be seeing regressions trigger in unexpected manner, consider the following example:

JsonSerializerOptions options = new()
{
    TypeInfoResolverchain = { MyContext.Default, McpJsonUtilities.DefaultOptions.Resolver }
};

[JsonSerializable(typeof(MyCustomType)]
//[JsonSerializable(typeof(CallToolRequestParams)]
partial class MyContext : JsonSerializerContext;

Either uncommenting CallToolRequestParams or otherwise including it in the transitive type graph of MyContext will result in the experimental properties on CallToolRequestParams getting skipped silently. This seems like a very brittle arrangement to me.

[MackinnonBuck]

Yeah, that's the unfortunate footgun that this approach has. The brittle configuration is the main tradeoff this PR makes compared to #1260.

I would think that at a minimum, we'd need to document somewhere that anyone serializing MCP protocol types via JsonSerializerContext needs to configure their TypeInfoResolverChain with McpJsonUtilities.DefaultOptions.Resolver being the first entry.

We could also add some kind of McpJsonUtilities.CreateOptions(MyContext.Default) helper that sets up the TypeInfoResolverChain correctly, but customers still need to know to do that.

A more involved option could be to emit a compiler diagnostic if we detect that any protocol types are either directly or transitively included in a JsonSerializerContext. The warning would suggest adding an [McpJsonContext] attribute to MyContext, and another source generator would detect that attribute and add a correctly-configured McpOptions property to MyContext. I haven't explored this though, so the implementation might be prohibitively complex for the benefit it brings.