mcp-schema-enum-regression

name: "mcp-schema-enum-regression" description: "Keep generated MCP schemas strict-client compatible by avoiding nullable enum signatures." domain: "mcp-server" confidence: "high" source: "observed"

Context

Use this when an MCP client rejects tool schemas because enum arrays include invalid sentinel members (often surfaced as null or empty strings).

Patterns

• Test the published contract with ListToolsAsync() and recurse every schema node that contains an enum array.
• Treat nullable enum parameters in MCP tool signatures as the hazard point; strict clients do not tolerate the SDK's sentinel output for them.
• Keep the primary action parameter as a required enum when you want discoverable action lists.
• Emit other action-specific enum inputs as optional strings, then parse them in generated MCP code before routing.
• For [FromString] enum paths, keep the string transport shape and let the existing service-side parser do the enum conversion.

Examples

• src/ExcelMcp.Generators.Mcp/McpToolGenerator.cs: required action enum, optional enum-like inputs as strings, local parse for direct enum parameters.
• tests/ExcelMcp.McpServer.Tests/Integration/Tools/GeneratedToolSchemaEnumRegressionTests.cs: recursive schema regression plus focused optional-parameter check.

Anti-Patterns

• Do not patch one generated .g.cs output by hand.
• Do not leave nullable enums in published MCP signatures and hope clients normalize them.
• Do not fix only action; scan every enum-bearing property across the tool catalog.