第七章 高级功能进度通知

简介

本文档系统阐述了MCP（Model Context Protocol）Python SDK中的进度通知机制。该机制旨在为长时间运行的任务提供阶段性状态更新，提升用户体验和系统透明度。通过分析progress.py中的核心类和logging_and_progress.py中的示例，详细说明了从服务器端发出进度事件、客户端接收并处理的完整流程。同时，解释了日志注入机制如何与进度系统协同工作，实现结构化的事件追踪。

核心组件

本节分析进度通知系统的核心组件，包括Progress数据模型和ProgressContext上下文管理器。

本节来源

• progress.py

进度通知机制

Progress类与ProgressContext类

Progress类是定义进度通知数据结构的核心模型。它继承自Pydantic的BaseModel，包含两个字段：progress表示当前进度值，total表示总进度值（可选）。这个类为进度数据提供了结构化和类型安全的表示。

ProgressContext是一个数据类，作为进度通知的上下文管理器。它封装了会话对象、进度令牌（progress_token）、总进度值（total）和当前进度值（current）。其核心方法progress用于更新进度。当调用此方法时，它会将指定的amount加到current值上，并通过会话的send_progress_notification方法向客户端发送进度更新。

图源

• progress.py

进度回调类型

progress函数是一个上下文管理器（@contextmanager），用于创建ProgressContext实例。它接收一个RequestContext和一个可选的total值。该函数首先检查上下文元数据中是否存在progressToken，如果不存在则抛出异常。然后，它创建一个ProgressContext实例，并在try...finally块中将其yield给调用者。这种设计模式确保了即使在处理过程中发生异常，也能正确地清理资源。

完整的进度事件流程

结合logging_and_progress.py示例，可以清晰地看到从服务器端发出进度事件到客户端接收的完整流程。

1. 初始化：当客户端发起一个请求时，MCP服务器会创建一个Context对象。这个Context对象包含了report_progress等方法。
2. 发送进度：在长时间运行的任务中（如echo工具函数），开发者可以调用ctx.report_progress(progress, total, message)来报告进度。例如，await ctx.report_progress(progress=0, total=100)表示任务开始。
3. 内部处理：Context.report_progress方法会从request_context.meta中提取progressToken，然后调用session.send_progress_notification。
4. 发送通知：ServerSession.send_progress_notification方法会构造一个ProgressNotification对象，其参数为ProgressNotificationParams，包含progressToken、progress、total和message。这个通知通过SSE（Server-Sent Events）或WebSocket等传输方式发送给客户端。
5. 客户端接收：客户端的ClientSession接收到ProgressNotification后，会根据配置的progress_callback进行处理，例如在UI中更新进度条。

图源

• logging_and_progress.py
• progress.py
• types.py

本节来源

• progress.py
• logging_and_progress.py

日志与进度协同

logging.py文件中的日志注入机制与进度系统紧密协同，共同提供全面的运行时信息。

get_logger函数用于获取一个嵌套在MCP命名空间下的日志记录器。configure_logging函数则用于配置日志的输出格式和级别。在Context类中，提供了info、debug、warning、error等便捷方法，这些方法最终会调用session.send_log_message发送日志消息。

这种设计使得开发者可以在报告进度的同时，发送相关的日志信息。例如，在logging_and_progress.py示例中，await ctx.info("Starting to process echo for input: " + text)与await ctx.report_progress(progress=0, total=100)配合使用，既更新了进度条，又在日志中记录了任务开始的详细信息。这实现了结构化的事件追踪，将进度更新与关键的业务日志结合在一起，为调试和监控提供了强大的支持。

图源

• logging.py
• logging_and_progress.py

本节来源

• logging.py

实际应用场景

文件处理

在处理大型文件上传或转换时，可以将total设置为文件总大小（字节），并在处理每个数据块后调用progress方法，传入已处理的字节数。message可以动态更新为“已处理 50MB / 100MB”。

模型推理

对于复杂的模型推理任务，可以将total设置为推理步骤的总数。在每个推理步骤完成后，更新进度。message可以描述当前正在执行的步骤，例如“正在加载模型…”、“正在处理输入…”、“正在生成输出…”。

数据同步

在执行数据库同步或数据迁移时，可以将total设置为需要处理的记录总数。每成功处理一条记录，就增加进度。这能让用户清晰地了解同步的进展和剩余时间。

指导原则：

• 合理设置百分比：确保progress值单调递增，避免出现进度倒退的情况。
• 提供有意义的消息：message应提供对用户有帮助的、人类可读的信息，解释当前正在进行的操作。
• 使用元数据：虽然在当前分析中未直接体现，但meta字段可用于传递额外的、结构化的上下文信息。

结论

MCP Python SDK的进度通知机制通过Progress、ProgressContext和Context等组件，为长时间运行的任务提供了强大且易用的状态更新功能。结合日志系统，开发者可以构建出信息丰富、用户体验良好的应用。通过在实际场景中合理应用此机制，可以显著提升系统的可观察性和用户满意度。