refactor: deprecate tool spec's arguments-only handler in favor of CallToolRequest #375
+1,680
−698
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…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 <[email protected]>
9 tasks
134130
approved these changes
Jul 7, 2025
Comment on lines
+210
to
+211
| * @param call Deprecated. Uset he {@link AsyncToolCallSpecification#callTool} | ||
| * instead. |
There was a problem hiding this comment.
Suggested change
| * @param call Deprecated. Uset he {@link AsyncToolCallSpecification#callTool} | |
| * instead. | |
| * @param call Deprecated. Use the {@link AsyncToolSpecification#callTool} | |
| * instead. |
Comment on lines
+220
to
+221
| @Deprecated BiFunction<McpAsyncServerExchange, Map<String, Object>, Mono<McpSchema.CallToolResult>> call, | ||
| BiFunction<McpAsyncServerExchange, McpSchema.CallToolRequest, Mono<McpSchema.CallToolResult>> callTool) { |
There was a problem hiding this comment.
NIT:
handler or toolHandler can be used for instead of callTool
There was a problem hiding this comment.
We are already using the handler as the parameter's name in McpServer builder.
| @Test | ||
| void testRemoveTool() { | ||
| Tool too = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema); | ||
|
|
||
| var mcpAsyncServer = McpServer.async(createMcpTransportProvider()) | ||
| .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))) |
There was a problem hiding this comment.
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
reviewed
Jul 7, 2025
Comment on lines
+224
to
+225
| * @deprecated Use {@link #AsyncToolSpecification(McpSchema.Tool, null, | ||
| * BiFunction)} instead. |
There was a problem hiding this comment.
Suggested change
| * @deprecated Use {@link #AsyncToolSpecification(McpSchema.Tool, null, | |
| * BiFunction)} instead. | |
| * @deprecated Use {@link AsyncToolSpecification(McpSchema.Tool, null, | |
| * BiFunction)} instead. |
| * }</pre> | ||
| * | ||
| * @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 |
There was a problem hiding this comment.
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 |
| /** | ||
| * 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. |
There was a problem hiding this comment.
Suggested change
| * {@link McpServerFeatures.AsyncToolCallSpecification} explicitly. | |
| * {@link McpServerFeatures.AsyncToolSpecification} explicitly. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Refactor tool specifications to use builder pattern and deprecate arguments-only handlers in favor of CallToolRequest
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
CallToolRequestobject, 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:
How Has This Been Tested?
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
Checklist
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()