PromptMessage Roles do not serialize with lowercase enum values

[baronfel]

Describe the bug
When attempting to return a GetPromptResult from a GetPromptHandler, the Role field on the PromptMessage type serializes with an uppercase enum value, while tools like Claude and the MCP Inspector expect a lowercase value only.

To Reproduce
Steps to reproduce the behavior:

1. Use the following sample program:

using ModelContextProtocol;
using Microsoft.Extensions.Hosting;
using ModelContextProtocol.Protocol.Types;

var builder = Host.CreateApplicationBuilder(args);
builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithListPromptsHandler((ctx, ctok) => Task.FromResult(new ListPromptsResult()
    {
        Prompts = [new() { Name = "prompt1", Description = "Prompt 1" }]
    })
    )
    .WithGetPromptHandler((req, ctok) =>
    {
        if (req.Params!.Name == "prompt1")
        {
            return Task.FromResult(new GetPromptResult() { Messages = [new PromptMessage() { Content = new Content() { Text = "do the thing!", Type = "text" }, Role = Role.User }] });
        }
        throw new Exception("Prompt not found");
    });
await builder.Build().RunAsync();

2. build the app with dotnet build
3. Run the MCP Inspector: npx @modelcontextprotocol/inspector .\bin\Debug\net9.0\yourapp
4. list prompts
   
5. select the prompt1 prompt
6. See the following error:
   

[
    {
        "received": "User",
        "code": "invalid_enum_value",
        "options": [
            "user",
            "assistant"
        ],
        "path": [
            "messages",
            0,
            "role"
        ],
        "message": "Invalid enum value. Expected 'user' | 'assistant', received 'User'"
    }
]

Expected behavior
The prompt1 prompt should have been invoked in the MCP inspector.

Logs
See above

Additional context
Pretty sure this is a classic .NET-style enum serialization problem - we need to use lowecase enum serialization. I think we can do that with a naming policy on the Role type specifically?

[stephentoub]

cc: @eiriktsarpalis

[timheuer]

We had fixed this but looks like a refactor moved some options and didn’t carry the JsonNamingPolicy over on the refactor

csharp-sdk/src/ModelContextProtocol/Utils/Json/McpJsonUtilities.cs

Line 58 in d18da9a

Converters = { new JsonStringEnumConverter() },

Original: PederHP/mcpdotnet#64

[stephentoub]

@eiriktsarpalis, this was removed in e7fa619#diff-15cc87fa1e38fe82528133b832930e15e33197ec0fc5cd72ea88e93698a30122. Was that on purpose?

[zaevi]

JsonStringEnumConverter is not supported in native AOT, so yes I think the removal is purposed.

[baronfel]

I did a bit of hacking around and the following patch works for me for both framework-dependent and AOT modes using the sample MCP server in the issue description:

diff --git a/src/ModelContextProtocol/Protocol/Types/Role.cs b/src/ModelContextProtocol/Protocol/Types/Role.cs
index a8266a0..7413339 100644
--- a/src/ModelContextProtocol/Protocol/Types/Role.cs
+++ b/src/ModelContextProtocol/Protocol/Types/Role.cs
@@ -6,6 +6,7 @@ namespace ModelContextProtocol.Protocol.Types;
 /// Represents the type of role in the conversation.
 /// <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/2024-11-05/schema.json">See the schema for details</see>
 /// </summary>
+[JsonConverter(typeof(RoleConverter))]
 public enum Role
 {
     /// <summary>
@@ -19,4 +20,18 @@ public enum Role
     /// </summary>
     [JsonPropertyName("assistant")]
     Assistant
+}
+
+/// <summary>
+/// Converts a <see cref="Role"/> to or from a string. Required because the spec requires lowercase strings.
+/// </summary>
+public class RoleConverter : JsonStringEnumConverter<Role>
+{
+    /// <summary>
+    /// Constructor. Creates the <see cref="RoleConverter"/> with the
+    /// default naming policy and disallows integer values.
+    /// </summary>
+    public RoleConverter() : base(namingPolicy: System.Text.Json.JsonNamingPolicy.SnakeCaseLower, allowIntegerValues: false)
+    {
+    }
 }
\ No newline at end of file
diff --git a/src/ModelContextProtocol/Utils/Json/McpJsonUtilities.cs b/src/ModelContextProtocol/Utils/Json/McpJsonUtilities.cs
index 7a868a6..b1d8608 100644
--- a/src/ModelContextProtocol/Utils/Json/McpJsonUtilities.cs
+++ b/src/ModelContextProtocol/Utils/Json/McpJsonUtilities.cs
@@ -55,7 +55,7 @@ public static partial class McpJsonUtilities
             options = new(JsonSerializerDefaults.Web)
             {
                 TypeInfoResolver = new DefaultJsonTypeInfoResolver(),
-                Converters = { new JsonStringEnumConverter() },
+                Converters = { new JsonStringEnumConverter(namingPolicy: JsonNamingPolicy.SnakeCaseLower) },
                 DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
                 NumberHandling = JsonNumberHandling.AllowReadingFromString,
                 Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping,
@@ -122,6 +122,8 @@ public static partial class McpJsonUtilities
     [JsonSerializable(typeof(ListRootsResult))]
     [JsonSerializable(typeof(InitializeResult))]
     [JsonSerializable(typeof(CallToolResponse))]
+    [JsonSerializable(typeof(ListPromptsResult))]
+    [JsonSerializable(typeof(GetPromptResult))]
     internal sealed partial class JsonContext : JsonSerializerContext;
 
     private static JsonElement ParseJsonElement(ReadOnlySpan<byte> utf8Json)

I think the two meaningful parts are:

• making sure the prompt-related types are rooted on the JsonContext for AOT scenarios
• making sure the naming policy is applied

However, despite the fact that I made a converter specifically for the Role type to capture the fact that this enum particularly, not all enums, needed lower-casing, when I ran this without the change to set the namingPolicy directly on the JsonStringEnumConverter registered in McpJsonUtilities, my customization wasn't applied. I would hope that there's a way to define the required settings on- or adjacent-to the type itself without needing to repeat?