fix: #3046 preserve MCP re-export import errors (#3048)

Author: seratch

src/agents/mcp/__init__.py

@@ -1,4 +1,9 @@
-try:
+from __future__ import annotations
+
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
     from .manager import MCPServerManager
     from .server import (
         LocalMCPApprovalCallable,
@@ -10,8 +15,6 @@
         MCPServerStreamableHttp,
         MCPServerStreamableHttpParams,
     )
-except ImportError:
-    pass
 
 from .util import (
     MCPToolMetaContext,
@@ -24,6 +27,18 @@
     create_static_tool_filter,
 )
 
+_LAZY_EXPORTS = {
+    "MCPServer": ".server",
+    "MCPServerSse": ".server",
+    "MCPServerSseParams": ".server",
+    "MCPServerStdio": ".server",
+    "MCPServerStdioParams": ".server",
+    "MCPServerStreamableHttp": ".server",
+    "MCPServerStreamableHttpParams": ".server",
+    "MCPServerManager": ".manager",
+    "LocalMCPApprovalCallable": ".server",
+}
+
 __all__ = [
     "MCPServer",
     "MCPServerSse",
@@ -43,3 +58,26 @@
     "ToolFilterStatic",
     "create_static_tool_filter",
 ]
+
+
+def __getattr__(name: str) -> Any:
+    if name not in _LAZY_EXPORTS:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    module_name = _LAZY_EXPORTS[name]
+    try:
+        module = import_module(module_name, __name__)
+    except ImportError as exc:
+        raise ImportError(
+            f"Failed to import {name} from agents.mcp. "
+            f"The agents.mcp{module_name} module could not be imported; "
+            "see the chained ImportError for details."
+        ) from exc
+
+    value = getattr(module, name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(__all__))

tests/mcp/test_mcp_imports.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import importlib
+import importlib.abc
+import sys
+from types import ModuleType
+
+import pytest
+
+_SERVER_EXPORTS = (
+    "LocalMCPApprovalCallable",
+    "MCPServer",
+    "MCPServerSse",
+    "MCPServerSseParams",
+    "MCPServerStdio",
+    "MCPServerStdioParams",
+    "MCPServerStreamableHttp",
+    "MCPServerStreamableHttpParams",
+)
+
+
+class _BrokenMCPServerImportFinder(importlib.abc.MetaPathFinder):
+    def find_spec(
+        self,
+        fullname: str,
+        path: object | None,
+        target: ModuleType | None = None,
+    ) -> None:
+        if fullname == "agents.mcp.server":
+            raise ImportError("simulated dependency import failure")
+        return None
+
+
+def _clear_mcp_server_imports(
+    monkeypatch: pytest.MonkeyPatch,
+    mcp_module: ModuleType,
+) -> None:
+    monkeypatch.delitem(sys.modules, "agents.mcp.server", raising=False)
+    monkeypatch.delitem(mcp_module.__dict__, "server", raising=False)
+    for name in _SERVER_EXPORTS:
+        monkeypatch.delitem(mcp_module.__dict__, name, raising=False)
+
+
+def test_mcp_package_import_does_not_eagerly_import_server(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    import agents.mcp as mcp_module
+
+    _clear_mcp_server_imports(monkeypatch, mcp_module)
+    finder = _BrokenMCPServerImportFinder()
+    monkeypatch.setattr(sys, "meta_path", [finder, *sys.meta_path])
+
+    reloaded_mcp = importlib.reload(mcp_module)
+
+    assert reloaded_mcp.MCPUtil is not None
+
+
+def test_mcp_server_reexport_preserves_underlying_import_error(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    import agents.mcp as mcp_module
+
+    _clear_mcp_server_imports(monkeypatch, mcp_module)
+    finder = _BrokenMCPServerImportFinder()
+    monkeypatch.setattr(sys, "meta_path", [finder, *sys.meta_path])
+    namespace: dict[str, object] = {}
+
+    with pytest.raises(ImportError) as exc_info:
+        exec("from agents.mcp import MCPServerStreamableHttp", namespace)
+
+    assert "Failed to import MCPServerStreamableHttp from agents.mcp" in str(exc_info.value)
+    assert isinstance(exc_info.value.__cause__, ImportError)
+    assert "simulated dependency import failure" in str(exc_info.value.__cause__)