1.MCP版本控制概述 #

Model Context Protocol (MCP) 采用基于日期的版本标识符系统，用于管理协议的不同版本和确保向后兼容性。

2.版本标识符格式 #

MCP使用 YYYY-MM-DD 格式的字符串作为版本标识符，其中：

• YYYY: 四位年份
• MM: 两位月份（01-12）
• DD: 两位日期（01-31）

这个日期表示最后一次做出向后不兼容更改的日期。

2.1 版本标识符示例 #

# 版本标识符示例
version_2025_06_18 = "2025-06-18"  # 2025年6月18日版本
version_2024_12_01 = "2024-12-01"  # 2024年12月1日版本
version_2023_09_15 = "2023-09-15"  # 2023年9月15日版本

3.版本策略 #

3.1 向后兼容性原则 #

重要提示: 协议版本不会在每次更新时递增，只要这些变更保持向后兼容性。这样可以在保持互操作性的同时实现渐进式改进。

这意味着：

• 添加新功能时，只要不破坏现有功能，版本号保持不变
• 只有在做出破坏性更改时，才会更新版本标识符
• 这种策略确保了系统的稳定性和可预测性

4.修订状态 #

MCP规范可能标记为以下三种状态之一：

1. 草稿 (Draft) #

• 状态: 进行中的规范，尚未准备就绪可供使用
• 特点: 可能包含不完整的功能或实验性特性
• 使用建议: 不建议在生产环境中使用

2. 当前 (Current) #

• 状态: 当前协议版本，已准备就绪可供使用
• 特点: 可能继续接收向后兼容的更改
• 使用建议: 推荐用于生产环境

3. 最终 (Final) #

• 状态: 过去已定稿且不再变更的完整规范
• 特点: 功能完整，稳定可靠
• 使用建议: 适合需要长期稳定性的项目

5.当前版本 #

当前MCP协议版本是 2025-06-18。

6.版本协商机制 #

6.1 协商过程 #

版本协商发生在客户端与服务器初始化阶段。虽然客户端和服务器可能支持同时处理多个协议版本，但它们必须就本次会话统一使用一个版本达成一致。

6.2 协商失败处理 #

当版本协商失败时，该协议提供了恰当的错误处理机制，允许客户端在无法找到与服务器兼容的版本时优雅地终止连接。

7. 代码示例 #

7.1 版本比较工具 #

version_comparator.py

# 版本比较工具类
# 用于比较两个MCP版本并确定兼容性
class MCPVersionComparator:
    # 构造函数，初始化支持的版本列表
    def __init__(self):
        # 支持的版本列表，按时间顺序排列
        self.supported_versions = ["2023-09-15", "2024-12-01", "2025-06-18"]

    # 解析版本字符串为日期对象
    def parse_version(self, version_string):
        """
        解析版本字符串为日期对象
        参数: version_string - 格式为YYYY-MM-DD的版本字符串
        返回: datetime对象
        """
        # 导入datetime模块
        from datetime import datetime

        # 使用strptime方法将字符串解析为datetime对象
        return datetime.strptime(version_string, "%Y-%m-%d")

    # 检查客户端和服务器版本是否兼容
    def is_compatible(self, client_version, server_version):
        """
        检查客户端和服务器版本是否兼容
        参数: client_version - 客户端版本
               server_version - 服务器版本
        返回: bool - 是否兼容
        """
        # 解析客户端版本为日期
        client_date = self.parse_version(client_version)
        # 解析服务器版本为日期
        server_date = self.parse_version(server_version)

        # 如果客户端版本早于或等于服务器版本，则兼容
        return client_date <= server_date

    # 获取客户端和服务器都支持的最新版本
    def get_latest_common_version(self, client_versions, server_versions):
        """
        获取客户端和服务器都支持的最新版本
        参数: client_versions - 客户端支持的版本列表
               server_versions - 服务器支持的版本列表
        返回: str - 最新的共同版本，如果没有则返回None
        """
        # 计算客户端和服务器的共同版本集合
        common_versions = set(client_versions) & set(server_versions)
        # 如果没有共同版本，返回None
        if not common_versions:
            return None

        # 找到最新的共同版本
        latest_version = max(common_versions, key=self.parse_version)
        # 返回最新的共同版本
        return latest_version


# 使用示例
# 创建MCPVersionComparator实例
comparator = MCPVersionComparator()
# 定义客户端版本
client_version = "2024-12-01"
# 定义服务器版本
server_version = "2025-06-18"

# 判断客户端版本和服务器版本是否兼容
if comparator.is_compatible(client_version, server_version):
    # 如果兼容，打印兼容信息
    print(f"版本兼容: {client_version} -> {server_version}")
else:
    # 如果不兼容，打印不兼容信息
    print(f"版本不兼容: {client_version} -> {server_version}")

7.2 版本协商客户端 #

version_negotiator.py

# MCP版本协商客户端
# 实现客户端与服务器的版本协商逻辑

# 导入异步IO模块
import asyncio

# 从typing模块导入类型提示
from typing import List, Optional

from version_comparator import MCPVersionComparator


# 定义MCP版本协商器类
class MCPVersionNegotiator:
    # 构造函数，初始化对象
    def __init__(self):
        # 客户端支持的版本列表
        self.supported_versions = ["2023-09-15", "2024-12-01", "2025-06-18"]
        # 创建版本比较器实例
        self.comparator = MCPVersionComparator()

    # 异步方法：与服务器协商版本
    async def negotiate_version(self, server_versions: List[str]) -> Optional[str]:
        """
        与服务器协商版本
        参数: server_versions - 服务器支持的版本列表
        返回: 协商成功的版本，如果失败则返回None
        """
        # 获取客户端与服务器共同支持的最新版本
        common_version = self.comparator.get_latest_common_version(
            self.supported_versions, server_versions
        )

        # 如果找到共同版本
        if common_version:
            # 打印协商成功信息
            print(f"版本协商成功: {common_version}")
            # 返回协商的版本
            return common_version
        else:
            # 打印协商失败信息
            print("版本协商失败: 没有找到兼容的版本")
            # 返回None表示协商失败
            return None

    # 异步方法：连接到服务器并进行版本协商
    async def connect_to_server(self, server_url: str) -> bool:
        """
        连接到MCP服务器并执行版本协商
        参数: server_url - 服务器URL
        返回: bool - 连接是否成功
        """
        try:
            # 异步获取服务器支持的版本列表
            server_versions = await self.get_server_versions(server_url)

            # 执行版本协商，获取协商结果
            negotiated_version = await self.negotiate_version(server_versions)

            # 如果协商成功
            if negotiated_version:
                # 使用协商的版本建立连接
                await self.establish_connection(server_url, negotiated_version)
                # 返回True表示连接成功
                return True
            else:
                # 协商失败，优雅地断开连接
                await self.graceful_disconnect()
                # 返回False表示连接失败
                return False

        # 捕获异常
        except Exception as e:
            # 打印连接失败信息
            print(f"连接失败: {e}")
            # 返回False表示连接失败
            return False

    # 异步方法：获取服务器支持的版本列表
    async def get_server_versions(self, server_url: str) -> List[str]:
        """
        获取服务器支持的版本列表
        参数: server_url - 服务器URL
        返回: 服务器支持的版本列表
        """
        # 这里应实现实际的网络请求获取服务器版本
        # 示例直接返回两个版本
        return ["2024-12-01", "2025-06-18"]

    # 异步方法：使用指定版本建立连接
    async def establish_connection(self, server_url: str, version: str):
        """
        使用指定版本建立连接
        参数: server_url - 服务器URL
               version - 协商的版本
        """
        # 打印建立连接的信息
        print(f"使用版本 {version} 建立连接到 {server_url}")
        # 这里应实现实际的连接逻辑

    # 异步方法：优雅地断开连接
    async def graceful_disconnect(self):
        """
        优雅地断开连接
        """
        # 打印断开连接的信息
        print("版本不兼容，优雅地断开连接")

# 定义主异步函数
async def main():
    # 创建协商器实例
    negotiator = MCPVersionNegotiator()
    # 尝试连接到服务器并进行版本协商
    success = await negotiator.connect_to_server("ws://localhost:8080")

    # 根据协商结果输出信息
    if success:
        print("连接成功建立")
    else:
        print("连接失败")


# 运行主异步函数
asyncio.run(main())

7.3 版本状态检查工具 #

version_status_checker.py

# 版本状态检查工具类定义
class MCPVersionStatusChecker:
    # 构造函数，初始化版本状态和草稿版本列表
    def __init__(self):
        # 定义各个版本的状态（final为最终版本，current为当前版本）
        self.version_status = {
            "2023-09-15": "final",    # 2023-09-15为最终版本
            "2024-12-01": "current",  # 2024-12-01为当前版本
            "2025-06-18": "current",  # 2025-06-18为当前版本
        }

        # 定义草稿版本列表（示例，未来可能发布的版本）
        self.draft_versions = [
            "2025-12-01",  # 2025-12-01为草稿版本
            "2026-03-15",  # 2026-03-15为草稿版本
        ]

    # 获取指定版本的状态（draft/current/final/unknown）
    def get_version_status(self, version: str) -> str:
        """
        获取指定版本的状态
        参数: version - 版本字符串
        返回: 版本状态（draft/current/final）
        """
        # 如果版本在草稿版本列表中，返回"draft"
        if version in self.draft_versions:
            return "draft"
        # 如果版本在已知状态映射中，返回对应状态
        elif version in self.version_status:
            return self.version_status[version]
        # 否则返回"unknown"
        else:
            return "unknown"

    # 判断版本是否适合生产环境（current或final为生产可用）
    def is_production_ready(self, version: str) -> bool:
        """
        检查版本是否适合生产环境
        参数: version - 版本字符串
        返回: bool - 是否适合生产环境
        """
        # 获取版本状态
        status = self.get_version_status(version)
        # 如果状态为current或final，则适合生产环境
        return status in ["current", "final"]

    # 获取推荐的版本（优先返回第一个current状态的版本，否则返回默认最新版本）
    def get_recommended_version(self) -> str:
        """
        获取推荐的版本（当前版本）
        返回: 推荐的版本字符串
        """
        # 遍历所有版本状态，查找状态为current的版本
        for version, status in self.version_status.items():
            if status == "current":
                return version
        # 如果没有current，返回默认最新版本
        return "2025-06-18"  # 默认返回最新版本

# 创建MCPVersionStatusChecker实例
status_checker = MCPVersionStatusChecker()

# 定义需要检查状态的版本列表
versions_to_check = ["2023-09-15", "2024-12-01", "2025-06-18", "2025-12-01"]

# 遍历每个版本，输出其状态和是否适合生产环境
for version in versions_to_check:
    # 获取版本状态
    status = status_checker.get_version_status(version)
    # 判断是否适合生产环境
    production_ready = status_checker.is_production_ready(version)

    # 打印版本号
    print(f"版本 {version}:")
    # 打印版本状态
    print(f"  状态: {status}")
    # 打印是否适合生产环境
    print(f"  生产就绪: {production_ready}")
    # 打印空行分隔
    print()

# 获取推荐版本
recommended = status_checker.get_recommended_version()
# 打印推荐版本
print(f"推荐版本: {recommended}")

8.最佳实践 #

8.1 版本选择策略 #

# 导入版本比较器
from version_comparator import MCPVersionComparator
# 导入版本状态检查器
from version_status_checker import MCPVersionStatusChecker

# 定义选择最优版本的函数
def select_optimal_version(client_versions, server_versions):
    """
    选择最优版本
    参数: client_versions - 客户端支持的版本列表
           server_versions - 服务器支持的版本列表
    返回: 选择的版本和选择原因
    """
    # 创建版本比较器实例
    comparator = MCPVersionComparator()
    # 创建版本状态检查器实例
    status_checker = MCPVersionStatusChecker()

    # 初始化兼容版本列表
    compatible_versions = []
    # 遍历客户端支持的每个版本
    for client_ver in client_versions:
        # 遍历服务器支持的每个版本
        for server_ver in server_versions:
            # 判断客户端版本是否与服务器版本兼容
            if comparator.is_compatible(client_ver, server_ver):
                # 如果兼容，则加入兼容版本列表
                compatible_versions.append(client_ver)

    # 如果没有任何兼容版本
    if not compatible_versions:
        # 返回None和原因
        return None, "没有兼容版本"

    # 从兼容版本中筛选出生产就绪的版本
    production_ready_versions = [
        ver for ver in compatible_versions if status_checker.is_production_ready(ver)
    ]

    # 如果存在生产就绪的版本
    if production_ready_versions:
        # 选择最新的生产就绪版本
        selected_version = max(production_ready_versions, key=comparator.parse_version)
        # 返回选择的版本和原因
        return selected_version, "选择最新的生产就绪版本"
    else:
        # 如果没有生产就绪版本，选择最新的兼容版本
        selected_version = max(compatible_versions, key=comparator.parse_version)
        # 返回选择的版本和原因
        return selected_version, "选择最新的兼容版本（非生产就绪）"

8.2 错误处理 #

# 导入MCP版本比较器
from version_comparator import MCPVersionComparator


# 定义MCP版本相关错误的基类
class MCPVersionError(Exception):
    """MCP版本相关错误的基类"""

    pass


# 定义版本协商失败错误
class VersionNegotiationError(MCPVersionError):
    """版本协商失败错误"""

    pass


# 定义版本不兼容错误
class IncompatibleVersionError(MCPVersionError):
    """版本不兼容错误"""

    pass


# 处理版本协商的函数
def handle_version_negotiation(client_version, server_version):
    """
    处理版本协商
    参数: client_version - 客户端版本
           server_version - 服务器版本
    """
    # 创建MCP版本比较器实例
    comparator = MCPVersionComparator()

    try:
        # 判断客户端和服务器版本是否兼容
        if not comparator.is_compatible(client_version, server_version):
            # 如果不兼容，抛出IncompatibleVersionError异常
            raise IncompatibleVersionError(
                f"客户端版本 {client_version} 与服务器版本 {server_version} 不兼容"
            )

        # 如果兼容，打印协商成功信息
        print(f"版本协商成功: {client_version} -> {server_version}")
        # 返回True表示协商成功
        return True

    # 捕获版本不兼容错误
    except IncompatibleVersionError as e:
        # 打印不兼容错误信息
        print(f"版本不兼容错误: {e}")
        # 实现优雅的错误处理逻辑
        return False
    # 捕获其他未知异常
    except Exception as e:
        # 打印未知错误信息
        print(f"版本协商过程中发生未知错误: {e}")
        return False

9.总结 #

MCP的版本控制系统设计简洁而有效：

1. 基于日期的版本标识符 提供了清晰的时间线
2. 向后兼容性原则 确保了系统的稳定性
3. 三种修订状态 为不同使用场景提供了明确指导
4. 版本协商机制 确保了客户端和服务器的一致性
5. 优雅的错误处理 提供了良好的用户体验

通过理解和正确使用这些版本控制机制，开发者可以构建稳定、可靠的MCP应用程序。