| 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.
