ValueError: not enough values to unpack (expected 3, got 2)

快速结论：llama-index-tools-mcp 0.5.0 在通过 streamable HTTP 传输协议连接 MCP 服务器时，因 mcp SDK 2.x 将 streamable_http_client() 的返回值从 3 元组改为 2 元组，导致代码仍按 3 元组解包而立即抛错。优先检查 client.py 中的解包语句是否已改为 as (read, write):。

适用环境：llama-index-tools-mcp 0.5.0、mcp 2.0.0、llama-index-core 0.14.x、Python 3.13。

最快修复方案：暂无官方发布的一步修复；可优先尝试将 client.py 中 streamable HTTP 分支的 as (read, write, _): 改为 as (read, write):，并在创建 ClientSession 时将 read_timeout_seconds 由 timedelta 改为 float(self.timeout)。

注意事项：该修复方案来自 Issue 评论的代码分析，尚未合并到 main 分支，也未在 Issue 中给出实际验证报告；改动前建议先确认本地的 client.py 行数与评论中引用的一致。

问题场景

用户在 llama-index-tools-mcp 0.5.0 中通过 BasicMCPClient 连接 streamable-HTTP 类型的 MCP 端点，然后调用 McpToolSpec.to_tool_list_async() 获取工具列表。由于 0.5.0 已迁移到 mcp 2.x SDK，而 streamable-HTTP 是该 SDK 推荐且最常用的传输方式，每次会话建立时都会立即触发异常。

报错原文

File ".../llama_index/tools/mcp/client.py", line 254, in _run_session) as (read, write, _):
ValueError: not enough values to unpack (expected 3, got 2)

原因分析

在 mcp 2.0.0 中，streamable_http_client(...) 返回的是 2 元组 (read, write)，但 llama-index-tools-mcp 的 client.py 仍然按 3 元组 (read, write, _) 解包，导致每次进入该分支时立即抛出 ValueError。该问题也关联到迁移跟踪 Issue #22515 中列出的第 1 项，虽然 PR #22557 声称修复了元组变化，但合并后的代码并没有真正修改这里。

同时，评论指出三个传输分支中仍将 timedelta 传给 read_timeout_seconds，说明 timedelta → float 的迁移在 main 分支上也没有完整落地。

环境排查

确认 llama-index-tools-mcp 版本为 0.5.0。
确认 mcp SDK 版本是否已更新到 2.0.0 或更高。
确认 llama-index-core 版本为 0.14.x。
检查本地 llama_index/tools/mcp/client.py 中 streamable_http_client 分支的元组解包处是否仍为 as (read, write, _):。
确认连接的目标 MCP 端点确实使用 streamable HTTP 传输。

解决步骤

定位到 llama-index-integrations/tools/llama-index-tools-mcp/llama_index/tools/mcp/client.py 中的 streamable HTTP 分支。
将 async with streamable_http_client(...) as (read, write, _): 改为 async with streamable_http_client(...) as (read, write):。
在创建 ClientSession 时，将 read_timeout_seconds 的参数由 timedelta 对象改为 float(self.timeout)。
如果使用 pip 安装的包，修改后可在本地 site-packages 中直接改动，或等待上游 PR 合并后升级新版本。

验证方法

修改后重新运行触发报错的代码（通过 BasicMCPClient 连接 streamable-HTTP 端点并调用 to_tool_list_async()），确认不再抛出 ValueError: not enough values to unpack，且能正常返回工具列表。若还有其他 transport 分支报错，需一并检查 read_timeout_seconds 是否为 float 类型。