Auto-generate discriminated unions from OpenAPI discriminators

- Add discriminators to OpenAPI spec for transport and Argument types
- Enhance schema generation tool to auto-convert discriminators to allOf with if/then blocks
- Replace manual discriminated union patterns with auto-generated schema
- Ensures schema stays in sync with OpenAPI spec and produces cleaner validation errors

Author: BobDickinson

docs/reference/api/openapi.yaml

@@ -347,11 +347,16 @@ components:
           description: A hint to help clients determine the appropriate runtime for the package. This field should be provided when `runtimeArguments` are present.
           examples: [npx, uvx, docker, dnx]
         transport:
-          anyOf:
+          discriminator:
+            propertyName: type
+            mapping:
+              stdio: '#/components/schemas/StdioTransport'
+              streamable-http: '#/components/schemas/StreamableHttpTransport'
+              sse: '#/components/schemas/SseTransport'
+          oneOf:
             - $ref: '#/components/schemas/StdioTransport'
             - $ref: '#/components/schemas/StreamableHttpTransport'
             - $ref: '#/components/schemas/SseTransport'
-          description: Transport protocol configuration for the package
         runtimeArguments:
           type: array
           description: A list of arguments to be passed to the package's runtime command (such as docker or npx). The `runtimeHint` field should be provided when `runtimeArguments` are present.
@@ -478,7 +483,12 @@ components:
 
     Argument:
       description: "Warning: Arguments construct command-line parameters that may contain user-provided input. This creates potential command injection risks if clients execute commands in a shell environment. For example, a malicious argument value like ';rm -rf ~/Development' could execute dangerous commands. Clients should prefer non-shell execution methods (e.g., posix_spawn) when possible to eliminate injection risks entirely. Where not possible, clients should obtain consent from users or agents to run the resolved command before execution."
-      anyOf:
+      discriminator:
+        propertyName: type
+        mapping:
+          positional: '#/components/schemas/PositionalArgument'
+          named: '#/components/schemas/NamedArgument'
+      oneOf:
         - $ref: '#/components/schemas/PositionalArgument'
         - $ref: '#/components/schemas/NamedArgument'
 
@@ -624,7 +634,12 @@ components:
         remotes:
           type: array
           items:
-            anyOf:
+            discriminator:
+              propertyName: type
+              mapping:
+                streamable-http: '#/components/schemas/StreamableHttpTransport'
+                sse: '#/components/schemas/SseTransport'
+            oneOf:
               - $ref: '#/components/schemas/StreamableHttpTransport'
               - $ref: '#/components/schemas/SseTransport'
         _meta:

docs/reference/server-json/server.schema.json

@@ -1,19 +1,50 @@
 {
   "$comment": "This file is auto-generated from docs/reference/api/openapi.yaml. Do not edit manually. Run 'make generate-schema' to update.",
-  "$id": "https://static.modelcontextprotocol.io/schemas/2025-10-11/server.schema.json",
+  "$id": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
   "$ref": "#/definitions/ServerDetail",
   "$schema": "http://json-schema.org/draft-07/schema#",
   "definitions": {
     "Argument": {
-      "anyOf": [
+      "allOf": [
         {
-          "$ref": "#/definitions/PositionalArgument"
+          "if": {
+            "properties": {
+              "type": {
+                "const": "positional"
+              }
+            }
+          },
+          "then": {
+            "$ref": "#/definitions/PositionalArgument"
+          }
         },
         {
-          "$ref": "#/definitions/NamedArgument"
+          "if": {
+            "properties": {
+              "type": {
+                "const": "named"
+              }
+            }
+          },
+          "then": {
+            "$ref": "#/definitions/NamedArgument"
+          }
+        }
+      ],
+      "description": "Warning: Arguments construct command-line parameters that may contain user-provided input. This creates potential command injection risks if clients execute commands in a shell environment. For example, a malicious argument value like ';rm -rf ~/Development' could execute dangerous commands. Clients should prefer non-shell execution methods (e.g., posix_spawn) when possible to eliminate injection risks entirely. Where not possible, clients should obtain consent from users or agents to run the resolved command before execution.",
+      "properties": {
+        "type": {
+          "enum": [
+            "positional",
+            "named"
+          ],
+          "type": "string"
         }
+      },
+      "required": [
+        "type"
       ],
-      "description": "Warning: Arguments construct command-line parameters that may contain user-provided input. This creates potential command injection risks if clients execute commands in a shell environment. For example, a malicious argument value like ';rm -rf ~/Development' could execute dangerous commands. Clients should prefer non-shell execution methods (e.g., posix_spawn) when possible to eliminate injection risks entirely. Where not possible, clients should obtain consent from users or agents to run the resolved command before execution."
+      "type": "object"
     },
     "Icon": {
       "description": "An optionally-sized icon that can be displayed in a user interface.",
@@ -262,18 +293,58 @@
           "type": "string"
         },
         "transport": {
-          "anyOf": [
+          "allOf": [
             {
-              "$ref": "#/definitions/StdioTransport"
+              "if": {
+                "properties": {
+                  "type": {
+                    "const": "stdio"
+                  }
+                }
+              },
+              "then": {
+                "$ref": "#/definitions/StdioTransport"
+              }
             },
             {
-              "$ref": "#/definitions/StreamableHttpTransport"
+              "if": {
+                "properties": {
+                  "type": {
+                    "const": "streamable-http"
+                  }
+                }
+              },
+              "then": {
+                "$ref": "#/definitions/StreamableHttpTransport"
+              }
             },
             {
-              "$ref": "#/definitions/SseTransport"
+              "if": {
+                "properties": {
+                  "type": {
+                    "const": "sse"
+                  }
+                }
+              },
+              "then": {
+                "$ref": "#/definitions/SseTransport"
+              }
             }
           ],
-          "description": "Transport protocol configuration for the package"
+          "properties": {
+            "type": {
+              "enum": [
+                "stdio",
+                "streamable-http",
+                "sse"
+              ],
+              "type": "string"
+            }
+          },
+          "required": [
+            "type"
+          ],
+          "type": "object"
         },
         "version": {
           "description": "Package version. Must be a specific version. Version ranges are rejected (e.g., '^1.2.3', '~1.2.3', '\u003e=1.2.3', '1.x', '1.*').",
@@ -427,14 +498,45 @@
         },
         "remotes": {
           "items": {
-            "anyOf": [
+            "allOf": [
               {
-                "$ref": "#/definitions/StreamableHttpTransport"
+                "if": {
+                  "properties": {
+                    "type": {
+                      "const": "streamable-http"
+                    }
+                  }
+                },
+                "then": {
+                  "$ref": "#/definitions/StreamableHttpTransport"
+                }
               },
               {
-                "$ref": "#/definitions/SseTransport"
+                "if": {
+                  "properties": {
+                    "type": {
+                      "const": "sse"
+                    }
+                  }
+                },
+                "then": {
+                  "$ref": "#/definitions/SseTransport"
+                }
               }
-            ]
+            ],
+            "properties": {
+              "type": {
+                "enum": [
+                  "streamable-http",
+                  "sse"
+                ],
+                "type": "string"
+              }
+            },
+            "required": [
+              "type"
+            ],
+            "type": "object"
           },
           "type": "array"
         },

tools/extract-server-schema/main.go

@@ -33,16 +33,6 @@ func main() {
 		log.Fatalf("Failed to parse OpenAPI YAML: %v", err)
 	}
 
-	// Extract version from info section
-	info, ok := openapi["info"].(map[string]interface{})
-	if !ok {
-		log.Fatal("Missing 'info' in OpenAPI spec")
-	}
-	version, ok := info["version"].(string)
-	if !ok {
-		log.Fatal("Missing 'info.version' in OpenAPI spec")
-	}
-
 	// Extract components/schemas
 	components, ok := openapi["components"].(map[string]interface{})
 	if !ok {
@@ -88,18 +78,20 @@ func main() {
 		}
 	}
 
-	// Build the JSON Schema document with dynamic version from OpenAPI spec
-	schemaID := fmt.Sprintf("https://static.modelcontextprotocol.io/schemas/%s/server.schema.json", version)
+	// Build the JSON Schema document
 	jsonSchema := map[string]interface{}{
 		"$comment":    "This file is auto-generated from docs/reference/api/openapi.yaml. Do not edit manually. Run 'make generate-schema' to update.",
 		"$schema":     "http://json-schema.org/draft-07/schema#",
-		"$id":         schemaID,
+		"$id":         "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
 		"title":       "server.json defining a Model Context Protocol (MCP) server",
 		"$ref":        "#/definitions/ServerDetail",
 		"definitions": definitions,
 	}
 
-	// Replace all #/components/schemas/ references with #/definitions/
+	// Convert OpenAPI discriminators to JSON Schema if/then/else patterns first
+	jsonSchema = convertDiscriminators(jsonSchema).(map[string]interface{})
+
+	// Then replace all #/components/schemas/ references with #/definitions/
 	jsonSchema = replaceComponentRefs(jsonSchema).(map[string]interface{})
 
 	// Convert to JSON
@@ -191,3 +183,108 @@ func replaceComponentRefs(obj interface{}) interface{} {
 		return obj
 	}
 }
+
+// convertDiscriminators converts OpenAPI discriminators to JSON Schema if/then/else patterns
+func convertDiscriminators(obj interface{}) interface{} {
+	switch v := obj.(type) {
+	case map[string]interface{}:
+		// Check if this object has a discriminator with oneOf
+		if discriminator, hasDiscriminator := v["discriminator"].(map[string]interface{}); hasDiscriminator {
+			if oneOf, hasOneOf := v["oneOf"].([]interface{}); hasOneOf {
+				// Extract discriminator property name and mapping
+				propertyName, _ := discriminator["propertyName"].(string)
+				mapping, _ := discriminator["mapping"].(map[string]interface{})
+
+				if propertyName != "" && mapping != nil && len(oneOf) > 0 {
+					// Get description if present
+					description, _ := v["description"].(string)
+
+					// Build the allOf with if/then blocks for discriminated union
+					result := buildDiscriminatedUnion(propertyName, mapping, oneOf, description)
+
+					// Recursively convert discriminators in the result
+					return convertDiscriminators(result)
+				}
+			}
+		}
+
+		// Recursively convert discriminators in nested objects
+		result := make(map[string]interface{})
+		for key, value := range v {
+			result[key] = convertDiscriminators(value)
+		}
+		return result
+
+	case []interface{}:
+		result := make([]interface{}, len(v))
+		for i, item := range v {
+			result[i] = convertDiscriminators(item)
+		}
+		return result
+
+	default:
+		return obj
+	}
+}
+
+// buildDiscriminatedUnion builds an allOf structure with separate if/then blocks for each discriminator value
+func buildDiscriminatedUnion(propertyName string, mapping map[string]interface{}, oneOf []interface{}, description string) map[string]interface{} {
+	// Build a sorted list of mapping entries by extracting from oneOf order
+	mappingList := make([]struct{ key, ref string }, 0, len(oneOf))
+	for _, item := range oneOf {
+		if refMap, ok := item.(map[string]interface{}); ok {
+			if ref, ok := refMap["$ref"].(string); ok {
+				// Find the key in mapping that matches this ref
+				for key, value := range mapping {
+					if refValue, ok := value.(string); ok && refValue == ref {
+						mappingList = append(mappingList, struct{ key, ref string }{key, ref})
+						break
+					}
+				}
+			}
+		}
+	}
+
+	// Extract enum values in the same order
+	enumValues := make([]interface{}, 0, len(mappingList))
+	for _, item := range mappingList {
+		enumValues = append(enumValues, item.key)
+	}
+
+	// Build allOf array with separate if/then for each type
+	allOfItems := make([]interface{}, 0, len(mappingList))
+	for _, item := range mappingList {
+		allOfItems = append(allOfItems, map[string]interface{}{
+			"if": map[string]interface{}{
+				"properties": map[string]interface{}{
+					propertyName: map[string]interface{}{
+						"const": item.key,
+					},
+				},
+			},
+			"then": map[string]interface{}{
+				"$ref": item.ref,
+			},
+		})
+	}
+
+	// Build result as regular map (will be alphabetically sorted by Go's json.Marshal)
+	result := map[string]interface{}{
+		"type": "object",
+		"properties": map[string]interface{}{
+			propertyName: map[string]interface{}{
+				"type": "string",
+				"enum": enumValues,
+			},
+		},
+		"required": []interface{}{propertyName},
+		"allOf":    allOfItems,
+	}
+
+	// Add description if present
+	if description != "" {
+		result["description"] = description
+	}
+
+	return result
+}