refactor: deprecate tool spec's arguments-only handler in favor of CallToolRequest by tzolov · Pull Request #375 · modelcontextprotocol/java-sdk

tzolov · 2025-07-05T13:26:48Z

Refactor tool specifications to use builder pattern and deprecate arguments-only handlers in favor of CallToolRequest

Deprecate handlers that take only Map<String, Object> arguments
Introduce new handlers that receive the full CallToolRequest object
Maintain backward compatibility with deprecated call handlers
Enhance API to provide access to complete tool request context beyond just arguments
Add builder pattern for AsyncToolSpecification and SyncToolSpecification
Add duplicate tool name validation during server building and runtime registration
Update all test files to use new callTool handlers and builder pattern
Add test coverage for new builder functionality and CallToolRequest handling

Related to #300

Motivation and Context

The current tool handler API only provides access to the arguments Map, limiting handlers to just the parameter values. This change introduces handlers that receive the full CallToolRequest object, giving access to the complete request context including tool name and arguments together. Additionally, the builder pattern improves API ergonomics and enables better validation during tool registration.

Key improvements:

Tool handlers can now access the complete request context, not just arguments
Builder pattern provides better API usability and validation
Duplicate tool name validation prevents runtime errors
Maintains full backward compatibility

How Has This Been Tested?

All existing integration tests updated to use new API and continue to pass
New comprehensive test coverage for builder pattern functionality
Tests for duplicate tool validation during both build-time and runtime registration
Backward compatibility verified through deprecated method testing
Cross-module testing across WebFlux, WebMVC, and core MCP modules

Breaking Changes

None - This change is fully backward compatible. Existing code using the deprecated constructors and tool() methods will continue to work unchanged. Users can migrate to the new API at their own pace.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

Migration Path:

Old API: new McpServerFeatures.SyncToolSpecification(toolDef, (exchange, args) -> ...)
New API: McpServerFeatures.SyncToolSpecification.builder().tool(toolDef).callTool((exchange, callToolReq) -> ...)).build()
Old API: new McpServerFeatures.AsyncToolSpecification(toolDef, (exchange, args) -> ...)
New API: McpServerFeatures.AsyncToolSpecification.builder().tool(toolDef).callTool((exchange, callToolReq) -> ...)).build()

…llToolRequest Tool handlers now receive CallToolRequest instead of raw arguments to enable access to additional metadata parameters like progressToken - Deprecate handlers that take only Map<String, Object> arguments - Introduce new handlers that receive the full CallToolRequest object - Maintain backward compatibility with deprecated call handlers - Enhance API to provide access to complete tool request context beyond just arguments - Add builder pattern for AsyncToolSpecification and SyncToolSpecification - Add duplicate tool name validation during server building and runtime registration - Update all test files to use new callTool handlers and builder pattern - Add test coverage for new builder functionality and CallToolRequest handling Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

134130

Thank you for your efforts!

134130 · 2025-07-07T02:05:54Z

mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java

+	 * @param call Deprecated. Uset he {@link AsyncToolCallSpecification#callTool}
+	 * instead.


Suggested change

* @param call Deprecated. Uset he {@link AsyncToolCallSpecification#callTool}

* instead.

* @param call Deprecated. Use the {@link AsyncToolSpecification#callTool}

* instead.

134130 · 2025-07-07T02:12:05Z

mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java

+			@Deprecated BiFunction<McpAsyncServerExchange, Map<String, Object>, Mono<McpSchema.CallToolResult>> call,
+			BiFunction<McpAsyncServerExchange, McpSchema.CallToolRequest, Mono<McpSchema.CallToolResult>> callTool) {


NIT:

handler or toolHandler can be used for instead of callTool

We are already using the handler as the parameter's name in McpServer builder.

https://github.com/modelcontextprotocol/java-sdk/blob/main/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java#L325-L326

Good point. toolHandler will be consistent with the other spec handler fields: readHandler, promptHandler, completionHandler ..

Isn't callHandler a more appropriate name?

Exactly. callHandler or callTollHandler. whatever!

134130 · 2025-07-07T02:20:59Z

mcp/src/test/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java

 			.serverInfo("test-server", "1.0.0")
 			.capabilities(ServerCapabilities.builder().tools(true).build())
-			.tool(too, (exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))
+			.toolCall(too, (exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))


NIT:

Suggested change

.toolCall(too, (exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))

.toolCall(too, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))

134130 · 2025-07-07T02:35:54Z

mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java

+		 * @deprecated Use {@link #AsyncToolSpecification(McpSchema.Tool, null,
+		 * BiFunction)} instead.


Suggested change

* @deprecated Use {@link #AsyncToolSpecification(McpSchema.Tool, null,

* BiFunction)} instead.

* @deprecated Use {@link AsyncToolSpecification(McpSchema.Tool, null,

* BiFunction)} instead.

134130 · 2025-07-07T02:36:57Z

mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java

 	 * @param tool The tool definition including name, description, and parameter schema
-	 * @param call The function that implements the tool's logic, receiving arguments and
-	 * returning results. The function's first argument is an
+	 * @param (deprecated) call The function that implements the tool's logic, receiving


Suggested change

* @param (deprecated) call The function that implements the tool's logic, receiving

* @param call Deprecated. The function that implements the tool's logic, receiving

134130 · 2025-07-07T02:37:28Z

mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java

+		/**
+		 * Adds a single tool with its implementation handler to the server. This is a
+		 * convenience method for registering individual tools without creating a
+		 * {@link McpServerFeatures.AsyncToolCallSpecification} explicitly.


Suggested change

* {@link McpServerFeatures.AsyncToolCallSpecification} explicitly.

* {@link McpServerFeatures.AsyncToolSpecification} explicitly.

Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

…llToolRequest (#375) Tool handlers now receive CallToolRequest instead of raw arguments to enable access to additional metadata parameters like progressToken - Deprecate handlers that take only Map<String, Object> arguments - Introduce new handlers that receive the full CallToolRequest object - Maintain backward compatibility with deprecated call handlers - Enhance API to provide access to complete tool request context beyond just arguments - Add builder pattern for AsyncToolSpecification and SyncToolSpecification - Add duplicate tool name validation during server building and runtime registration - Update all test files to use new callTool handlers and builder pattern - Add test coverage for new builder functionality and CallToolRequest handling Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

tzolov · 2025-07-11T09:45:37Z

rebased, squashed and merged at 901175e

134130 · 2025-07-11T10:06:29Z

Now it's my turn!

…redOutputCallToolHandler Follow up to #357 to update tool call handler signature from Map<String, Object> to McpSchema.CallToolRequest for consistency with changes in #375. - Change BiFunction parameter from Map<String, Object> to McpSchema.CallToolRequest for better type safety - Update method signature to accept CallToolRequest instead of raw arguments map - Replace toolSpecification.call() with toolSpecification.callHandler() - Migrate to builder pattern for AsyncToolSpecification construction Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

tzolov added this to the 0.11.0 milestone Jul 5, 2025

tzolov mentioned this pull request Jul 5, 2025

feat: refactor the tool specifications #351

Closed

9 tasks

134130 approved these changes Jul 7, 2025

View reviewed changes

134130 reviewed Jul 7, 2025

View reviewed changes

tzolov added 3 commits July 9, 2025 12:18

address review comments

f648d28

Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

address review recomendations

5f0d61b

Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

remove old toolCallSpec references

894e831

Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

tzolov closed this Jul 11, 2025

134130 mentioned this pull request Jul 11, 2025

Support progress flow #298

Closed

5 tasks

tzolov mentioned this pull request Jul 17, 2025

refactor: Replace Map<String, Object> with CallToolRequest in StructuredOutputCallToolHandler #408

Merged

tzolov mentioned this pull request Jul 22, 2025

Release 0.11.0 #386

Closed

		* @param call Deprecated. Uset he {@link AsyncToolCallSpecification#callTool}
		* instead.

		@Deprecated BiFunction<McpAsyncServerExchange, Map<String, Object>, Mono<McpSchema.CallToolResult>> call,
		BiFunction<McpAsyncServerExchange, McpSchema.CallToolRequest, Mono<McpSchema.CallToolResult>> callTool) {

	.toolCall(too, (exchange, args) -> Mono.just(new CallToolResult(List.of(), false)))
	.toolCall(too, (exchange, request) -> Mono.just(new CallToolResult(List.of(), false)))

		* @deprecated Use {@link #AsyncToolSpecification(McpSchema.Tool, null,
		* BiFunction)} instead.

	* @param (deprecated) call The function that implements the tool's logic, receiving
	* @param call Deprecated. The function that implements the tool's logic, receiving

	* {@link McpServerFeatures.AsyncToolCallSpecification} explicitly.
	* {@link McpServerFeatures.AsyncToolSpecification} explicitly.

Conversation

tzolov commented Jul 5, 2025

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

134130 left a comment

Choose a reason for hiding this comment

Uh oh!

134130 Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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 Jul 11, 2025

Uh oh!

134130 commented Jul 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

134130 Jul 7, 2025 •

edited

Loading