feat(mcp): Refactor MCP server API to use Specification pattern #2508

tzolov · 2025-03-18T11:22:59Z

Rename Registration classes to Specification (SyncToolRegistration → SyncToolSpecification)
Update transport classes to use Provider suffix (WebFluxSseServerTransport → WebFluxSseServerTransportProvider)
Add exchange parameter to handler methods for better context passing
Introduce McpBackwardCompatibility class to maintain backward compatibility
Update MCP Server documentation to reflect new API patterns
Add tests for backward compatibility

The changes align with the MCP specification evolution while maintaining backward compatibility through deprecated APIs.

tzolov · 2025-03-18T11:25:58Z

Depends on modelcontextprotocol/java-sdk#31

chemicL

Thanks for all the hard work in adapting the changes :) I left a few cosmetic remarks, but overall it will be awesome!

chemicL · 2025-03-18T15:06:16Z

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/mcp/mcp-server-boot-starter-docs.adoc

@@ -98,11 +98,11 @@ All properties are prefixed with `spring.ai.mcp.server`:
 * **Synchronous Server** - The default server type implemented using `McpSyncServer`. 
 It is designed for straightforward request-response patterns in your applications. 
 To enable this server type, set `spring.ai.mcp.server.type=SYNC` in your configuration. 
-When activated, it automatically handles the configuration of synchronous tool registrations.
+When activated, it automatically handles the configuration of synchronous tool specificaitons.


typo: specificaitons -> specifications

chemicL · 2025-03-18T15:06:32Z

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/mcp/mcp-server-boot-starter-docs.adoc


 * **Asynchronous Server** - The asynchronous server implementation uses `McpAsyncServer` and is optimized for non-blocking operations. 
 To enable this server type, configure your application with `spring.ai.mcp.server.type=ASYNC`. 
-This server type automatically sets up asynchronous tool registrations with built-in Project Reactor support.
+This server type automatically sets up asynchronous tool specificaitons with built-in Project Reactor support.


specificaitons -> specifications

chemicL · 2025-03-18T15:07:16Z

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/mcp/mcp-server-boot-starter-docs.adoc

@@ -115,14 +115,14 @@ The MCP Server supports three transport mechanisms, each with its dedicated star
 == Features and Capabilities

 The MCP Server Boot Starter allows servers to expose tools, resources, and prompts to clients.
-It automatically converts custom capability handlers registered as Spring beans to sync/async registrations based on server type:
+It automatically converts custom capability handlers registered as Spring beans to sync/async specificaitons based on server type:


another typo.. and more in this file

chemicL · 2025-03-18T15:09:39Z

mcp/common/src/main/java/org/springframework/ai/mcp/McpToolUtils.java

 	public static List<McpServerFeatures.SyncToolRegistration> toSyncToolRegistration(
 			List<ToolCallback> toolCallbacks) {
 		return toolCallbacks.stream().map(McpToolUtils::toSyncToolRegistration).toList();
 	}

+	/**
+	 * Converts a list of Spring AI tool callbacks to MCP synchronous tool specificaiton.


Another typo for specification - perhaps worth running a spell checker on all the changes in this PR.

chemicL · 2025-03-18T15:10:07Z

mcp/common/src/main/java/org/springframework/ai/mcp/McpToolUtils.java

+	 * Converts a list of Spring AI tool callbacks to MCP synchronous tool specificaiton.
+	 * <p>
+	 * This method processes multiple tool callbacks in bulk, converting each one to its
+	 * corresponding MCP tool registration while maintaining synchronous execution


registration -> specification

chemicL · 2025-03-18T15:24:30Z

.../src/main/java/org/springframework/ai/autoconfigure/mcp/server/McpBackwardCompatibility.java

+			return List.of();
+		}
+
+		return rootsChangeConsumers.stream().map(c -> new BiConsumer<McpSyncServerExchange, List<McpSchema.Root>>() {


Is there any reason for not using a lambda expression here?

I can do it but it requires explicit casting that I don't like. Anyway this is a deprecated throw away

chemicL · 2025-03-18T15:26:40Z

...rc/main/java/org/springframework/ai/autoconfigure/mcp/server/McpServerAutoConfiguration.java

@@ -94,17 +97,18 @@
 * </ul>
 * <p>
 * WebMvc transport support is provided separately by
- * {@link McpWebMvcServerAutoConfiguration}.
+ * {@link McpWebFluxServerAutoConfiguration}.


This was correct before if MVC is meant as the line above indicates

chemicL · 2025-03-18T15:27:38Z

...rc/main/java/org/springframework/ai/autoconfigure/mcp/server/McpServerAutoConfiguration.java

-			McpServerProperties serverProperties) {
-		List<ToolCallback> tools = toolCalls.stream().flatMap(List::stream).toList();
+	public List<McpServerFeatures.SyncToolSpecification> syncTools(ObjectProvider<List<ToolCallback>> toolCalls,
+			List<ToolCallback> toolCallbacks2, McpServerProperties serverProperties) {


toolCallbacks2 -> toolCallbacks ?

chemicL · 2025-03-18T15:28:42Z

...rc/main/java/org/springframework/ai/autoconfigure/mcp/server/McpServerAutoConfiguration.java

-			McpServerProperties serverProperties) {
-		var tools = toolCalls.stream().flatMap(List::stream).toList();
+	public List<McpServerFeatures.AsyncToolSpecification> asyncTools(ObjectProvider<List<ToolCallback>> toolCalls,
+			List<ToolCallback> toolCallbacks2, McpServerProperties serverProperties) {


does the toolCallbacks name need to change to one suffixed by 2?

chemicL · 2025-03-18T15:30:02Z

...n/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports


+org.springframework.ai.autoconfigure.mcp.server.McpServerAutoConfiguration2


This requires cleanup I suppose

ah, this is a blunder. renamed the classes but forgot to fix the configuration.

tzolov · 2025-03-19T08:49:49Z

Thanks for the review @chemicL . Last commit should address the review comments

chemicL · 2025-03-19T10:00:09Z

.../src/main/java/org/springframework/ai/autoconfigure/mcp/server/McpBackwardCompatibility.java

-			}
-		}).collect(Collectors.toList());
+		return rootsChangeConsumers.stream()
+			.map(c -> (BiConsumer<McpSyncServerExchange, List<McpSchema.Root>>) ((exchange, roots) -> c.accept(roots)))


Would this work?

.map(c -> (McpSyncServerExchange exchange, List<McpSchema.Root> roots) -> c.accept(roots))

I'm afraid not. Tried it before but it couldn't infer the types (or something like this).
This code will be removed after spring-ai M7 milestone release, so it is not that important.

seungy0 · 2025-03-24T04:10:43Z

.../src/main/java/org/springframework/ai/autoconfigure/mcp/server/McpBackwardCompatibility.java

+	}
+
+	@Bean
+	public List<McpServerFeatures.SyncToolSpecification> syncToolsRegistrationToSpecificaiton(


Suggested change

public List<McpServerFeatures.SyncToolSpecification> syncToolsRegistrationToSpecificaiton(

public List<McpServerFeatures.SyncToolSpecification> syncToolsRegistrationToSpecification(

Several method names contain a typo: "Specificaiton" instead of "Specification".

- Rename Registration classes to Specification (SyncToolRegistration → SyncToolSpecification) - Update transport classes to use Provider suffix (WebFluxSseServerTransport → WebFluxSseServerTransportProvider) - Add exchange parameter to handler methods for better context passing - Introduce McpBackwardCompatibility class to maintain backward compatibility - Update MCP Server documentation to reflect new API patterns - Add tests for backward compatibility The changes align with the MCP specification evolution while maintaining backward compatibility through deprecated APIs. Signed-off-by: Christian Tzolov <[email protected]>

Signed-off-by: Christian Tzolov <[email protected]>

…configuration Extracts the MCP tool callback functionality from McpClientAutoConfiguration into a new dedicated McpToolCallbackAutoConfiguration that is disabled by default. - Created new McpToolCallbackAutoConfiguration class that handles tool callback registration - Made tool callbacks opt-in by requiring explicit configuration with spring.ai.mcp.client.toolcallback.enabled=true - Removed deprecated tool callback methods from McpClientAutoConfiguration - Updated ClientMcpTransport references to McpClientTransport to align with MCP library changes - Added tests for the new auto-configuration and its conditions Signed-off-by: Christian Tzolov <[email protected]>

Signed-off-by: Christian Tzolov <[email protected]>

- Change separator in McpToolUtils.prefixedToolName from hyphen to underscore - Add conversion of any remaining hyphens to underscores in formatted tool names - Update affected tests to reflect the new naming convention - Add comprehensive tests for McpToolUtils.prefixedToolName method - Add integration test for payment transaction tools with Vertex AI Gemini Signed-off-by: Christian Tzolov <[email protected]>

markpollack · 2025-03-25T18:26:49Z

squashed and merged in fc955c7

tzolov added the MCP label Mar 18, 2025

tzolov added this to the 1.0.0-M7 milestone Mar 18, 2025

tzolov mentioned this pull request Mar 18, 2025

refactor: update MCP API usage to 0.8.0 and spring-ai 0.7.0 spring-projects/spring-ai-examples#15

Closed

chemicL requested changes Mar 18, 2025

View reviewed changes

chemicL reviewed Mar 19, 2025

View reviewed changes

tzolov force-pushed the mcp-0.8.0-migration branch 2 times, most recently from 46acf04 to fd1ae33 Compare March 22, 2025 08:43

tzolov marked this pull request as ready for review March 22, 2025 08:45

seungy0 suggested changes Mar 24, 2025

View reviewed changes

tzolov force-pushed the mcp-0.8.0-migration branch from 5a001b8 to 5320640 Compare March 24, 2025 15:29

markpollack self-assigned this Mar 24, 2025

tzolov added 6 commits March 25, 2025 11:00

Address review comments

b4b3b06

Signed-off-by: Christian Tzolov <[email protected]>

add mcp 0.8.0 breaking change note

953d4df

Signed-off-by: Christian Tzolov <[email protected]>

Update mcp version to 0.8.0

d7fc911

Signed-off-by: Christian Tzolov <[email protected]>

rebase to main

55a11f6

Signed-off-by: Christian Tzolov <[email protected]>

tzolov force-pushed the mcp-0.8.0-migration branch from 5320640 to 55a11f6 Compare March 25, 2025 10:04

markpollack closed this Mar 25, 2025


		org.springframework.ai.autoconfigure.mcp.server.McpServerAutoConfiguration2

	public List<McpServerFeatures.SyncToolSpecification> syncToolsRegistrationToSpecificaiton(
	public List<McpServerFeatures.SyncToolSpecification> syncToolsRegistrationToSpecification(

feat(mcp): Refactor MCP server API to use Specification pattern #2508

feat(mcp): Refactor MCP server API to use Specification pattern #2508

Uh oh!

Conversation

tzolov commented Mar 18, 2025

Uh oh!

tzolov commented Mar 18, 2025

Uh oh!

chemicL left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tzolov commented Mar 19, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

markpollack commented Mar 25, 2025

Uh oh!

Uh oh!