[SEP-1575] Changes to introduce Tool Versions

[malaykurwa]

This PR implements SEP-1575 Tool Versioning support, enabling MCP servers to declare semantic versions for their tools
and allowing clients to specify version constraints when making tool calls.

Motivation and Context

Currently, MCP tools lack versioning support, which can lead to breaking changes when tools are updated. This creates instability for clients that depend on specific tool behaviors. The tool
versioning feature addresses this by:

• Preventing Breaking Changes: Clients can specify version constraints to ensure compatibility
• Semantic Versioning: Tools can declare versions following SemVer 2.0.0 standard
• Backwards Compatibility: Existing un-versioned tools continue to work normally
• Clear Error Handling: Provides meaningful error messages when version requirements cannot be satisfied

How Has This Been Tested?

The implementation includes comprehensive testing:

• Unit Tests: Version parsing, constraint satisfaction, and version selection algorithms
• Error Scenarios: Testing version conflicts and unsatisfied requirements
  Test files:
• examples/test_versioning.py - Comprehensive test suite covering all versioning functionality
• examples/tool_versioning_example.py - Interactive demonstration of versioning features

Breaking Changes

No breaking changes - This implementation is fully backwards compatible:

• Existing un-versioned tools continue to work without modification
• Legacy clients without version requirements use the latest stable version
• All existing APIs remain unchanged
• New functionality is purely additive

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

Key Implementation Details

Schema Updates:

• Added optional version field to tool definitions
• Added optional tool_requirements field to tool call requests
• Added UNSATISFIED_TOOL_VERSION error code
  Version Constraint Syntax:
• Caret (^): Allows non-breaking updates (^1.2.3 ≡ >=1.2.3 <2.0.0)
• Tilde (~): Allows patch-level updates (~1.2.3 ≡ >=1.2.3 <1.3.0)
• Comparison Operators: >, >=, <, <=
• Exact Version: "1.2.3" (no operator)
  New Files:
• src/mcp/server/fastmcp/utilities/versioning.py - Core versioning utilities
• examples/test_versioning.py - Comprehensive test suite
• examples/tool_versioning_example.py - Interactive examples
• TOOL_VERSIONING.md - Complete implementation documentation
  Modified Files:
• src/mcp/types.py - Added version fields and error codes
• src/mcp/server/fastmcp/tools/base.py - Updated Tool class with version support
• src/mcp/server/fastmcp/tools/tool_manager.py - Enhanced tool management with versioning
• src/mcp/server/fastmcp/server.py - Updated FastMCP API with version parameters
• src/mcp/server/lowlevel/server.py - Low-level server versioning support

Usage Examples

Server-side (creating versioned tools):

  @server.tool(version="1.0.0")
  def get_weather_v1(location: str) -> str:
      return f"Weather in {location}: Sunny, 72°F"
  server.add_tool(get_weather_v2, version="2.0.0")

Client-side (using version constraints):

  result = await server.call_tool(
      "get_weather",
      {"location": "New York"},
      tool_requirements={"get_weather": "^1.0.0"}
  )

This implementation provides a solid foundation for tool versioning while maintaining full backwards compatibility with existing MCP deployments.

This PR description provides a comprehensive overview of your tool versioning implementation, highlighting the key features, testing approach, backwards compatibility, and technical details that
reviewers will need to understand the changes.