refactor: deprecate tool spec's arguments-only handler in favor of CallToolRequest

[tzolov]

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()