fix: use TYPE_CHECKING for BaseExceptionGroup type safety

ROOT CAUSE:
Pyright strict mode couldn't resolve BaseExceptionGroup type from
try/except import blocks, causing 68 type errors across all files
using the pattern.

CHANGES:
- Use typing.TYPE_CHECKING to import BaseExceptionGroup from builtins
  at type-checking time (Pyright knows this type exists)
- Keep runtime try/except for Python 3.10 compatibility
- Apply to all 16 files using BaseExceptionGroup

IMPACT:
- All 68 Pyright type errors resolved
- Tests still pass (runtime behavior unchanged)
- Type checker now understands BaseExceptionGroup type

FILES MODIFIED:
- src/mcp/shared/exceptions.py
- src/mcp/client/_memory.py
- src/mcp/client/session_group.py
- src/mcp/client/sse.py
- src/mcp/client/stdio.py
- src/mcp/client/streamable_http.py
- src/mcp/client/websocket.py
- src/mcp/server/sse.py
- src/mcp/server/stdio.py
- src/mcp/server/streamable_http.py
- src/mcp/server/streamable_http_manager.py
- src/mcp/server/websocket.py
- src/mcp/server/experimental/task_result_handler.py
- src/mcp/server/experimental/task_support.py
- src/mcp/server/lowlevel/server.py
- tests/shared/test_exceptions.py

Author: peter-luminova

src/mcp/client/_memory.py

@@ -2,14 +2,18 @@
 
 from __future__ import annotations
 
-try:
-    from builtins import BaseExceptionGroup
-except ImportError:
-    from exceptiongroup import BaseExceptionGroup  # type: ignore[import-not-found]
 from collections.abc import AsyncIterator
 from contextlib import AbstractAsyncContextManager, asynccontextmanager
 from types import TracebackType
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from builtins import BaseExceptionGroup
+else:
+    try:
+        from builtins import BaseExceptionGroup
+    except ImportError:
+        from exceptiongroup import BaseExceptionGroup
 
 import anyio
 

src/mcp/client/session_group.py

@@ -8,15 +8,18 @@
 
 import contextlib
 import logging
-
-try:
-    from builtins import BaseExceptionGroup
-except ImportError:
-    from exceptiongroup import BaseExceptionGroup  # type: ignore[import-not-found]
 from collections.abc import Callable
 from dataclasses import dataclass
 from types import TracebackType
-from typing import Any, TypeAlias
+from typing import TYPE_CHECKING, Any, TypeAlias
+
+if TYPE_CHECKING:
+    from builtins import BaseExceptionGroup
+else:
+    try:
+        from builtins import BaseExceptionGroup
+    except ImportError:
+        from exceptiongroup import BaseExceptionGroup
 
 import anyio
 import httpx

src/mcp/client/sse.py

@@ -1,14 +1,17 @@
 import logging
-
-try:
-    from builtins import BaseExceptionGroup
-except ImportError:
-    from exceptiongroup import BaseExceptionGroup  # type: ignore[import-not-found]
 from collections.abc import Callable
 from contextlib import asynccontextmanager
-from typing import Any
+from typing import TYPE_CHECKING, Any
 from urllib.parse import parse_qs, urljoin, urlparse
 
+if TYPE_CHECKING:
+    from builtins import BaseExceptionGroup
+else:
+    try:
+        from builtins import BaseExceptionGroup
+    except ImportError:
+        from exceptiongroup import BaseExceptionGroup
+
 import anyio
 import httpx
 from anyio.abc import TaskStatus

src/mcp/client/stdio.py

@@ -1,14 +1,17 @@
 import logging
 import os
 import sys
-
-try:
-    from builtins import BaseExceptionGroup
-except ImportError:
-    from exceptiongroup import BaseExceptionGroup  # type: ignore[import-not-found]
 from contextlib import asynccontextmanager
 from pathlib import Path
-from typing import Literal, TextIO
+from typing import TYPE_CHECKING, Literal, TextIO
+
+if TYPE_CHECKING:
+    from builtins import BaseExceptionGroup
+else:
+    try:
+        from builtins import BaseExceptionGroup
+    except ImportError:
+        from exceptiongroup import BaseExceptionGroup
 
 import anyio
 import anyio.lowlevel

src/mcp/client/streamable_http.py

@@ -4,14 +4,18 @@
 
 import contextlib
 import logging
-
-try:
-    from builtins import BaseExceptionGroup
-except ImportError:
-    from exceptiongroup import BaseExceptionGroup  # type: ignore[import-not-found]
 from collections.abc import AsyncGenerator, Awaitable, Callable
 from contextlib import asynccontextmanager
 from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from builtins import BaseExceptionGroup
+else:
+    try:
+        from builtins import BaseExceptionGroup
+    except ImportError:
+        from exceptiongroup import BaseExceptionGroup
 
 import anyio
 import httpx

src/mcp/client/websocket.py

@@ -1,11 +1,15 @@
 import json
-
-try:
-    from builtins import BaseExceptionGroup
-except ImportError:
-    from exceptiongroup import BaseExceptionGroup  # type: ignore[import-not-found]
 from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from builtins import BaseExceptionGroup
+else:
+    try:
+        from builtins import BaseExceptionGroup
+    except ImportError:
+        from exceptiongroup import BaseExceptionGroup
 
 import anyio
 from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream

src/mcp/server/experimental/task_result_handler.py

@@ -10,12 +10,15 @@
 """
 
 import logging
+from typing import TYPE_CHECKING, Any
 
-try:
+if TYPE_CHECKING:
     from builtins import BaseExceptionGroup
-except ImportError:
-    from exceptiongroup import BaseExceptionGroup  # type: ignore[import-not-found]
-from typing import Any
+else:
+    try:
+        from builtins import BaseExceptionGroup
+    except ImportError:
+        from exceptiongroup import BaseExceptionGroup
 
 import anyio
 

src/mcp/server/experimental/task_support.py

@@ -4,13 +4,18 @@
 infrastructure needed for task-augmented requests: store, queue, and handler.
 """
 
-try:
-    from builtins import BaseExceptionGroup
-except ImportError:
-    from exceptiongroup import BaseExceptionGroup  # type: ignore[import-not-found]
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from builtins import BaseExceptionGroup
+else:
+    try:
+        from builtins import BaseExceptionGroup
+    except ImportError:
+        from exceptiongroup import BaseExceptionGroup
 
 import anyio
 from anyio.abc import TaskGroup

src/mcp/server/lowlevel/server.py

@@ -39,15 +39,18 @@ async def main():
 import contextvars
 import logging
 import warnings
-
-try:
-    from builtins import BaseExceptionGroup
-except ImportError:
-    from exceptiongroup import BaseExceptionGroup  # type: ignore[import-not-found]
 from collections.abc import AsyncIterator, Awaitable, Callable
 from contextlib import AbstractAsyncContextManager, AsyncExitStack, asynccontextmanager
 from importlib.metadata import version as importlib_version
-from typing import Any, Generic
+from typing import TYPE_CHECKING, Any, Generic
+
+if TYPE_CHECKING:
+    from builtins import BaseExceptionGroup
+else:
+    try:
+        from builtins import BaseExceptionGroup
+    except ImportError:
+        from exceptiongroup import BaseExceptionGroup
 
 import anyio
 from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream

src/mcp/server/sse.py

@@ -37,16 +37,19 @@ async def handle_sse(request):
 """
 
 import logging
-
-try:
-    from builtins import BaseExceptionGroup
-except ImportError:
-    from exceptiongroup import BaseExceptionGroup  # type: ignore[import-not-found]
 from contextlib import asynccontextmanager
-from typing import Any
+from typing import TYPE_CHECKING, Any
 from urllib.parse import quote
 from uuid import UUID, uuid4
 
+if TYPE_CHECKING:
+    from builtins import BaseExceptionGroup
+else:
+    try:
+        from builtins import BaseExceptionGroup
+    except ImportError:
+        from exceptiongroup import BaseExceptionGroup
+
 import anyio
 from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
 from pydantic import ValidationError