refactor: drop per-entry extension() builder helper

Keep only the whole-map extensions(Map) setter on both capability builders,
matching the existing experimental(Map) convention. The per-entry
extension(id, settings) helper was a novel API for a single field, duplicated
verbatim across both builders, with copy-on-write merge semantics no sibling
setter has. Callers pass Map.of(id, Map.of()) for "supported, no settings".

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Yugi-2

mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java

@@ -781,22 +781,6 @@ public Builder extensions(Map<String, Object> extensions) {
 				return this;
 			}
 
-			/**
-			 * Adds support for a single extension; {@code null} settings are sent as an
-			 * empty JSON object.
-			 * @param id the extension identifier
-			 * @param settings the per-extension settings, or {@code null}
-			 * @return this builder
-			 */
-			public Builder extension(String id, Map<String, Object> settings) {
-				Assert.hasText(id, "id must not be null or empty");
-				Map<String, Object> merged = (this.extensions != null) ? new HashMap<>(this.extensions)
-						: new HashMap<>();
-				merged.put(id, settings != null ? settings : Map.of());
-				this.extensions = merged;
-				return this;
-			}
-
 			public ClientCapabilities build() {
 				return new ClientCapabilities(experimental, roots, sampling, elicitation, extensions);
 			}
@@ -1024,22 +1008,6 @@ public Builder extensions(Map<String, Object> extensions) {
 				return this;
 			}
 
-			/**
-			 * Adds support for a single extension; {@code null} settings are sent as an
-			 * empty JSON object.
-			 * @param id the extension identifier
-			 * @param settings the per-extension settings, or {@code null}
-			 * @return this builder
-			 */
-			public Builder extension(String id, Map<String, Object> settings) {
-				Assert.hasText(id, "id must not be null or empty");
-				Map<String, Object> merged = (this.extensions != null) ? new HashMap<>(this.extensions)
-						: new HashMap<>();
-				merged.put(id, settings != null ? settings : Map.of());
-				this.extensions = merged;
-				return this;
-			}
-
 			public ServerCapabilities build() {
 				return new ServerCapabilities(completions, experimental, logging, prompts, resources, tools,
 						extensions);

mcp-test/src/test/java/io/modelcontextprotocol/spec/SchemaEvolutionTests.java

@@ -161,16 +161,15 @@ void serverCapabilitiesWithNullExtensionsOmitsFieldOnWire() throws IOException {
 
 	@Test
 	void serverCapabilitiesExtensionsRoundTrip() throws IOException {
-		McpSchema.ServerCapabilities caps = McpSchema.ServerCapabilities.builder()
-			.extension("com.example/ext-with-settings", Map.of("maxDepth", 3))
-			.extension("com.example/ext-without-settings", null)
-			.build();
+		Map<String, Object> extensions = Map.of("com.example/ext-with-settings", Map.of("maxDepth", 3),
+				"com.example/ext-without-settings", Map.of());
+		McpSchema.ServerCapabilities caps = McpSchema.ServerCapabilities.builder().extensions(extensions).build();
 
 		String json = mapper.writeValueAsString(caps);
 		assertThat(json).contains("\"com.example/ext-without-settings\":{}");
 
 		McpSchema.ServerCapabilities parsed = mapper.readValue(json, McpSchema.ServerCapabilities.class);
-		assertThat(parsed.extensions()).isEqualTo(caps.extensions());
+		assertThat(parsed.extensions()).isEqualTo(extensions);
 	}
 
 	// -----------------------------------------------------------------------
@@ -203,16 +202,15 @@ void clientCapabilitiesWithExtensionsUnknownFieldsIgnored() throws IOException {
 
 	@Test
 	void clientCapabilitiesExtensionsRoundTrip() throws IOException {
-		McpSchema.ClientCapabilities caps = McpSchema.ClientCapabilities.builder()
-			.extension("com.example/ext-with-settings", Map.of("maxDepth", 3))
-			.extension("com.example/ext-without-settings", null)
-			.build();
+		Map<String, Object> extensions = Map.of("com.example/ext-with-settings", Map.of("maxDepth", 3),
+				"com.example/ext-without-settings", Map.of());
+		McpSchema.ClientCapabilities caps = McpSchema.ClientCapabilities.builder().extensions(extensions).build();
 
 		String json = mapper.writeValueAsString(caps);
 		assertThat(json).contains("\"com.example/ext-without-settings\":{}");
 
 		McpSchema.ClientCapabilities parsed = mapper.readValue(json, McpSchema.ClientCapabilities.class);
-		assertThat(parsed.extensions()).isEqualTo(caps.extensions());
+		assertThat(parsed.extensions()).isEqualTo(extensions);
 	}
 
 	// -----------------------------------------------------------------------