Audit protocol types

[MackinnonBuck]

Summary

Audits and standardizes MCP protocol types for consistency.

Fixes#519

Description

There are several inconsistencies across protocol types, including:

• init vs. set
• required vs. default property values
• Read-only vs. mutable collection properties
• enum vs. string
• JsonNode vs. JsonElement vs. IDictionary<string, JsonElement> vs. IDictionary<string, object>

This PR applies the following set of conventions to improve consistency:

Property Mutability

Guideline: Always use set - no init-only properties.

Rationale:

• If we're going to standardize on either set or init, it's easier to standardize on set because doing so is non-breaking
• Using init means that if we do want to mutate a property after initialization, we need to clone the its containing object, which can be error-prone and isn't great for perf
• It's not clear (to me at least) that we actually rely on the immutability of any properties in protocol types

Required Properties

Guideline: Use required when the spec indicates a property is required, unless a clear, safe default exists.

Rationale:

• Reduces initialization errors when mapping to/from protocol types
• Aligns better with the MCP schema

Safe defaults include:

• Empty collections
• The value returned by calling a type's parameterless constructor

Avoid defaults such as:

• The empty string ("") - this is rarely the expected value for a "required" property
• An enum value we arbitrary decide should be the default

Collections

Guideline: Prefer IList<T> / IDictionary<TKey, TValue> over IReadOnlyList<T> / IReadOnlyDictionary<TKey, TValue>.

Rationale:

• Reduces unnecessary cloning if mutation is needed
• It's not clear that we actually rely on collections in any protocol types being read-only

---

Open Questions

The following inconsistencies remain for further discussion:

enum vs. string: properties

The MCP schema defines some properties as unions of string values.

• enum offers strong typing
• string is more future-proof (e.g., if new values are added)

Existing examples of each:

• enum: ContextInclusion, Role
• string: ElicitResult.Action

JSON-like Structures:

The use of JsonNode, JsonElement, IDictionary<string, JsonElement>, and IDictionary<string, object> varies.

• These each have different pros and cons, and I'm not sure we necessarily want or need to standardize on a single one.
• We should define principles for when each is appropriate and align existing types accordingly.

---

Additional Notes

• None of these need to be hard and fast rules. If there's a compelling reason to deviate, it should be fine to do so.
• This PR also addresses a few smaller inconsistencies not listed above.

[eiriktsarpalis]

Guideline: Always use set - no init-only properties.

Rationale:

• If we're going to standardize on either set or init, it's easier to standardize on set because doing so is non-breaking
• Using init means that if we do want to mutate a property after initialization, we need to clone the its containing object, which can be error-prone and isn't great for perf
• It's not clear (to me at least) that we actually rely on the immutability of any properties in protocol types

For context, the presence of init properties is a holdover from when most of the models were record types, where the language supports persistable updates using with expressions. Since we decided to move away from records going from init to set sounds reasonable.

[halter73]

The use of JsonNode, JsonElement, IDictionary<string, JsonElement>, and IDictionary<string, object> varies.

• These each have different pros and cons, and I'm not sure we necessarily want or need to standardize on a single one.
• We should define principles for when each is appropriate and align existing types accordingly.

What are our principles around this? I know JsonNode is mutable and JsonElement is not, but why is JsonNode use for params and results and JsonElement or IDictionary<string, JsonElement> seemingly used everywhere else particularly considering these properties are settable? And what's up with IDictionary<string, object> just for experimental capabilities?

[MackinnonBuck]

What are our principles around this? I know JsonNode is mutable and JsonElement is not, but why is JsonNode use for params and results and JsonElement or IDictionary<string, JsonElement> seemingly used everywhere else particularly considering these properties are settable? And what's up with IDictionary<string, object> just for experimental capabilities?

Exactly what I'm wondering too 🙂 Maybe we could get an STJ expert to weigh in on this?

Edit: @eiriktsarpalis , do you have any thoughts about this?

[Copilot]

@MackinnonBuck I've opened a new pull request, #923, to work on those changes. Once the pull request is ready, I'll request review from you.

[eiriktsarpalis]

What are our principles around this? I know JsonNode is mutable and JsonElement is not, but why is JsonNode use for params and results and JsonElement or IDictionary<string, JsonElement> seemingly used everywhere else particularly considering these properties are settable? And what's up with IDictionary<string, object> just for experimental capabilities?

Exactly what I'm wondering too 🙂 Maybe we could get an STJ expert to weigh in on this?

Edit: @eiriktsarpalis , do you have any thoughts about this?

• JsonElement is a struct with default(JsonElement) representing an invalid value (similar to ImmutableArray<T>). This makes it awkward to use in properties that are optional, typically requiring JsonElement? which adds its own complexities into the mix. This is why I originally opted for JsonNode? to encode parameters, which is a class with null naturally mapping to JSON null.
• When such concerns aren't present JsonElement is the natural choice since it's more efficient (it's basically just a annotated buffer)..
• IDictionary<string, object> is used typically in hybrid situations where you want values to both be JsonElement or potentially other .NET values that we are able to serialize into JSON. This is how AIFunction has been designed to work.

[MackinnonBuck]

Thanks for the clarification, @eiriktsarpalis!

I'll leave the properties representing JSON objects as-is for this PR, then. Nothing jumps out at me as obviously using the wrong type.

[stephentoub]

This seems like a problem. We have code that checks whether Id has been set and if it hasn't it sets it to the next ID in the sequence. With this change, the developer needs to explicitly set the ID, and that code we have would appear to be dead? Making this required places a significant burden on a developer to track sent IDs and will make it likely I think that they end up sending duplicated IDs, violating the protocol.

[stephentoub]

cc: @MackinnonBuck, @halter73

[stephentoub]

Looking at the rest of the changes, I guess the intent is that it's ok to set it to default? That of course still begs the question then why it's required.