Move MCPDeprecationWarning to mcp.shared.exceptions per @Kludex review

Drops the dedicated _warnings.py — the side-effect-free-module constraint that
justified it is moot now that the filter matches by message only.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dsfaccini

pyproject.toml

@@ -208,11 +208,11 @@ filterwarnings = [
     "ignore:getargs.*The 'u' format is deprecated:DeprecationWarning",
     # `mcp` prefers `httpx2`; importing `mcp.shared._httpx` warns when falling back to
     # `httpx`. The lockfile pins `httpx`, so CI always exercises the fallback. We match on
-    # the message string only — naming the category would force pytest to import
-    # `mcp.shared._warnings`, which cascades through `mcp/__init__.py` and triggers the
-    # very warning we're trying to filter (the same trap pydantic-ai documents). The
-    # dedicated test in `tests/shared/test_httpx_shim.py` covers emission. Remove this entry
-    # once `httpx2` is the dependency and the fallback is dropped.
+    # the message string only — naming the category would force pytest's filter parser to
+    # `__import__` the module hosting `MCPDeprecationWarning`, which cascades through
+    # `mcp/__init__.py` and triggers the very warning we're trying to filter (the same trap
+    # pydantic-ai documents). The dedicated test in `tests/shared/test_httpx_shim.py` covers
+    # emission. Remove this entry once `httpx2` is the dependency and the fallback is dropped.
     "ignore:Using `httpx` with `mcp` is deprecated",
 ]
 

src/mcp/shared/_httpx.py

@@ -9,18 +9,17 @@
 dependency to `httpx2`.
 
 The warning is emitted at module-import time and fires at most once per process via Python's
-module cache. `MCPDeprecationWarning` lives in `mcp.shared._warnings` so pytest's
-`filterwarnings` parser can resolve the category symbol without importing this shim.
+module cache.
 """
 
 from __future__ import annotations
 
 import warnings
 from typing import TYPE_CHECKING
 
-from mcp.shared._warnings import MCPDeprecationWarning
+from mcp.shared.exceptions import MCPDeprecationWarning
 
-__all__ = ["MCPDeprecationWarning", "httpx"]
+__all__ = ["httpx"]
 
 
 if TYPE_CHECKING:

src/mcp/shared/_warnings.py

@@ -41,6 +41,14 @@ def __str__(self) -> str:
         return self.message
 
 
+class MCPDeprecationWarning(UserWarning):
+    """Deprecation warning emitted by the `mcp` package.
+
+    Subclasses `UserWarning` (not `DeprecationWarning`) so it is visible by default —
+    `DeprecationWarning` is silenced at the Python level for non-`__main__` callers.
+    """
+
+
 class StatelessModeNotSupported(RuntimeError):
     """Raised when attempting to use a method that is not supported in stateless mode.
 

src/mcp/shared/exceptions.py

@@ -13,7 +13,7 @@
 
 import pytest
 
-from mcp.shared._warnings import MCPDeprecationWarning
+from mcp.shared.exceptions import MCPDeprecationWarning
 
 
 def _force_reimport_shim() -> None: