Deprecate Server.__init__ handlers for removed capabilities

Merged
KL
4mo ago
+221-16

The 2026-07-28 spec deprecates Logging and Roots (SEP-2577) and the client-to-server progress notification. This deprecates the corresponding lowlevel Server.__init__ handler parameters: on_set_logging_level (Logging), on_roots_list_changed (Roots), and on_progress (client-to-server progress).

What changed

  • Server.__init__ is split into two @overloads: a clean signature without the three deprecated parameters, and a typing_extensions.deprecated overload with them. Passing any of the three resolves to the deprecated overload, so type checkers and IDEs flag it.
  • The real constructor emits MCPDeprecationWarning at runtime when a deprecated handler is passed, with messages matching the existing SEP-2577 / progress wording (so the project's existing filterwarnings ignores already cover them).
  • The non-deprecated overload omits the parameters entirely, keeping the common case warning-free.
  • Existing call sites that intentionally register these handlers (to advertise the capability) carry # pyright: ignore[reportDeprecated]; the stdio subprocess test helper guards construction with warnings.catch_warnings() since the global pytest filter doesn't reach the child process.
  • Documented in docs/migration.md, grouped into the existing SEP-2577 section.

100% coverage on the touched module; pyright, ruff, strict-no-cover, and the full suite pass.

AI Disclaimer

This PR was developed with the assistance of either Claude or Codex. I've reviewed and verified the changes.