ModuleNotFoundError: No module named ‘mcp.shared.session’

问题场景

用户在使用 LlamaIndex 的 llama-index-tools-mcp 集成包时，尝试将 MCP Python SDK 升级到 2.0.0（2026-07-28 发布）。由于集成包当前将 MCP SDK 锁定在 1.x 版本线（mcp>=1.24.0,<2），当强制安装 MCP 2.0.0 时，包无法正常导入。

报错原文

File ".../llama_index/tools/mcp/client.py", line 21, in <module>
    from mcp.shared.session import ProgressFnT
ModuleNotFoundError: No module named 'mcp.shared.session'

原因分析

MCP Python SDK 2.0 进行了大规模重构，移除了多个旧模块和 API。可能原因：

• mcp.shared.session 子模块在 2.0 中被移除，ProgressFnT 类型改为从 mcp.client.session 导入（已验证）。
• HTTP 客户端库从 httpx 迁移到 httpx2，影响 create_mcp_http_client 和 streamable_http_client 的签名与返回类型。
• 高级服务端 API 从 mcp.server.fastmcp.FastMCP 改为 mcp.server.mcpserver.MCPServer（已验证），且新 API 的 __init__ 不再接受 host / port 参数。
• 字段命名从 camelCase 改为 snake_case（如 inputSchema → input_schema、mimeType → mime_type），以及 resourceTemplates → resource_templates。其中 resourceTemplates 的变更不会抛出异常，但会导致静态资源模板功能静默失效。

环境排查

• 确认 MCP SDK 版本：运行环境中应检查 mcp 包当前实际安装的版本号（是否为 2.x）。
• 确认 llama-index-tools-mcp 集成包是否已更新到包含修复 PR（#22535）的版本。
• 若需使用 MCP 2.x，检查依赖下限：MCP 2.0 要求 pydantic>=2.12、anyio>=4.9、typing-extensions>=4.13，并新增 opentelemetry-api 和 mcp-types 依赖。
• 确认 HTTP 客户端库：MCP 2.0 不再传递依赖 httpx，改用 httpx2>=2.5.0。

解决步骤

1. 首选方案（临时）：保持 MCP SDK 版本在 mcp>=1.24.0,<2 范围内，等待集成包发布包含修复的版本。
2. 次选方案（需注意风险）：若必须使用 MCP 2.0，可优先尝试以下修改以解除导入阻塞：将 llama_index/tools/mcp/client.py 第 21 行的导入从 from mcp.shared.session import ProgressFnT 改为 from mcp.client.session import ProgressFnT。
3. 完整迁移需处理以下变更（参考 PR #22535 的方案）：将 utils.py 中的 from mcp.server.fastmcp import FastMCP, Context 替换为 mcp.server.mcpserver.MCPServer，并适配其 __init__ 参数；将 ClientSession 的 read_timeout_seconds 参数从 timedelta 改为 float（秒）；处理 streamable_http_client 返回 2 元组而非 3 元组的变更；将字段读取从 camelCase 改为 snake_case（input_schema、mime_type、resource_templates）；处理 Context.log(...) 第二个参数名从 message 改为 data 的变更。
4. 若将上述改动集中到一个内部 _compat 兼容模块中，可让同一份代码同时兼容 MCP 1.x 和 2.x（PR #22535 的做法）。

验证方法

在应用修改后，执行以下验证：

• 在 Python 环境中尝试 import llama_index.tools.mcp，确认不再抛出 ModuleNotFoundError。
• 运行 LlamaIndex 集成包的测试套件（参考 Issue 中 tests/test_client.py），确认在 MCP 1.x 和 2.x 下均全部通过（PR #22535 验证了 51/51 测试在两种版本下均通过）。
• 重点验证 McpToolSpec.fetch_resources() 是否正确返回资源模板（避免遇到 resourceTemplates → resource_templates 的静默回归问题）。

参考来源

run-llama/llama_index #22515：llama-index-tools-mcp: support mcp 2.x (Python SDK): pin blocks mcp 2.0.0

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。