目录

1. 简介
2. 会话生命周期
3. 初始化与连接
4. 参数配置详解
5. 会话关闭与资源清理
6. 常见问题排查

简介

ClientSession类是MCP（Model Context Protocol）客户端的核心组件，负责管理客户端与服务器之间的通信会话。该类提供了完整的会话生命周期管理功能，包括初始化、连接建立、请求发送、响应接收以及会话关闭等操作。通过ClientSession，开发者可以方便地与MCP服务器进行交互，执行各种操作如调用工具、读取资源、获取提示等。

本节来源

• ClientSession

会话生命周期

ClientSession的生命周期遵循标准的异步上下文管理器模式，确保资源的正确分配和释放。会话的生命周期包括以下几个关键阶段：

1. 创建：通过构造函数创建ClientSession实例，传入读写流和相关配置参数。
2. 初始化：调用initialize()方法与服务器建立连接并完成协议版本协商。
3. 操作：在初始化成功后，可以执行各种业务操作，如调用工具、读取资源等。
4. 关闭：通过异步上下文管理器的__aexit__方法或显式调用关闭逻辑，确保所有资源被正确清理。

图源

• ClientSession

初始化与连接

会话的初始化是通过initialize()方法完成的，该方法执行以下关键步骤：

1. 能力声明：根据构造函数中提供的回调函数，向服务器声明客户端支持的功能能力，如采样、征询、根列表等。
2. 协议版本协商：使用最新的协议版本（LATEST_PROTOCOL_VERSION）发起初始化请求，并验证服务器返回的协议版本是否在支持的版本列表中。
3. 握手完成：在收到服务器的初始化响应后，发送InitializedNotification通知，完成握手过程。

如果服务器返回的协议版本不被支持，initialize()方法会抛出RuntimeError异常。初始化成功后，方法返回InitializeResult对象，包含服务器信息、支持的能力等。

图源

• ClientSession
• types.py

本节来源

• ClientSession

参数配置详解

ClientSession的__init__方法接受多个关键参数，用于配置会话行为和功能。

核心流参数

• read_stream：MemoryObjectReceiveStream类型，用于从服务器接收消息。
• write_stream：MemoryObjectSendStream类型，用于向服务器发送消息。

超时设置

• read_timeout_seconds：timedelta类型，可选参数，指定读取操作的超时时间。如果未设置，读取将永不超时。

回调函数

• sampling_callback：处理采样请求的回调函数，当服务器请求生成消息时调用。
• elicitation_callback：处理征询请求的回调函数，当服务器需要从用户获取信息时调用。
• list_roots_callback：处理根列表请求的回调函数，用于支持动态根列表功能。
• logging_callback：处理日志消息的回调函数，用于接收服务器发送的日志信息。
• message_handler：通用消息处理器，用于处理所有传入的消息。

客户端信息

• client_info：Implementation类型，可选参数，提供客户端的实现信息，包括名称、版本等。如果未提供，将使用默认值。

这些回调函数在初始化时用于确定客户端支持的功能能力。如果提供了非默认的回调函数，则在初始化请求中声明相应的功能能力。

本节来源

• ClientSession

会话关闭与资源清理

ClientSession实现了异步上下文管理器协议，确保会话在使用完毕后能够正确关闭和清理资源。

自动资源管理

当使用async with语句时，ClientSession会自动处理资源的分配和释放：

async with ClientSession(read_stream, write_stream) as session:
    result = await session.initialize()
    # 执行其他操作
# 会话在此处自动关闭，资源被清理

显式关闭机制

在__aexit__方法中，会执行以下清理操作：

1. 关闭内部的异步退出栈（_exit_stack）。
2. 取消任务组（task_group）以停止消息接收循环。
3. 确保会话不会在退出时阻塞，通过取消任务组来实现。

这种设计确保了即使在异常情况下，会话也能被正确关闭，避免资源泄漏。

本节来源

• BaseSession
• ClientSession

常见问题排查

连接失败

连接失败可能由多种原因引起：

• 网络问题：检查网络连接是否正常，服务器地址是否可达。
• 流配置错误：确保read_stream和write_stream正确配置并连接到服务器。
• 服务器未启动：确认MCP服务器正在运行并监听正确的端口。

超时处理

ClientSession提供了两级超时控制：

1. 会话级超时：通过read_timeout_seconds参数设置，影响所有读取操作。
2. 请求级超时：在send_request方法中通过request_read_timeout_seconds参数设置，优先级高于会话级超时。

当发生超时时，会抛出McpError异常，错误码为REQUEST_TIMEOUT。

错误码解读

ClientSession可能抛出的常见错误码包括：

• CONNECTION_CLOSED (-32000)：连接已关闭，通常在服务器断开连接时发生。
• REQUEST_TIMEOUT：请求超时，未在指定时间内收到响应。
• INVALID_PARAMS：无效的请求参数，通常在请求验证失败时发生。
• INTERNAL_ERROR：内部错误，服务器处理请求时发生未预期的错误。

协议版本不兼容

当客户端和服务器的协议版本不兼容时，initialize()方法会抛出RuntimeError异常。建议检查：

• 客户端使用的LATEST_PROTOCOL_VERSION是否与服务器支持的版本匹配。
• 服务器返回的协议版本是否在SUPPORTED_PROTOCOL_VERSIONS列表中。

本节来源

• BaseSession
• ClientSession
• types.py