Merge pull request #429 from atesgoral/issue-390-deprecation-annotations

docs: annotate Roots, Sampling, and Logging as deprecated per SEP-2577

Author: koic

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Deprecated
+
+- Annotate Roots, Sampling, and Logging APIs as deprecated per SEP-2577 (#429)
+
 ## [0.22.0] - 2026-06-27
 
 ### Added

lib/mcp/server.rb

@@ -256,6 +256,9 @@ def notify_resources_list_changed
       report_exception(e, { notification: "resources_list_changed" })
     end
 
+    # @deprecated MCP Logging (`logging/setLevel` and `notifications/message`)
+    #   is deprecated as of MCP protocol version 2026-07-28 (SEP-2577).
+    #   Use stderr or OpenTelemetry instead.
     def notify_log_message(data:, level:, logger: nil)
       return unless @transport
       return unless logging_message_notification&.should_notify?(level)
@@ -272,6 +275,10 @@ def notify_log_message(data:, level:, logger: nil)
     # Called when a client notifies the server that its filesystem roots have changed.
     #
     # @yield [params] The notification params (typically `nil`).
+    # @deprecated MCP Roots (`roots/list` and
+    #   `notifications/roots/list_changed`) is deprecated as of MCP protocol
+    #   version 2026-07-28 (SEP-2577). Use tool parameters, resource URIs,
+    #   server configuration, or environment variables instead.
     def roots_list_changed_handler(&block)
       @handlers[Methods::NOTIFICATIONS_ROOTS_LIST_CHANGED] = block
     end

lib/mcp/server_context.rb

@@ -35,6 +35,9 @@ def report_progress(progress, total: nil, message: nil)
     # @param data [Object] The log data to send.
     # @param level [String] Log level (e.g., `"debug"`, `"info"`, `"error"`).
     # @param logger [String, nil] Logger name.
+    # @deprecated MCP Logging (`logging/setLevel` and `notifications/message`)
+    #   is deprecated as of MCP protocol version 2026-07-28 (SEP-2577).
+    #   Use stderr or OpenTelemetry instead.
     def notify_log_message(data:, level:, logger: nil)
       return unless @notification_target
 
@@ -51,6 +54,10 @@ def notify_resources_updated(uri:)
     end
 
     # Delegates to the session so the request is scoped to the originating client.
+    # @deprecated MCP Roots (`roots/list` and
+    #   `notifications/roots/list_changed`) is deprecated as of MCP protocol
+    #   version 2026-07-28 (SEP-2577). Use tool parameters, resource URIs,
+    #   server configuration, or environment variables instead.
     def list_roots
       if @notification_target.respond_to?(:list_roots)
         @notification_target.list_roots(related_request_id: @related_request_id)
@@ -84,6 +91,9 @@ def ping
     # Delegates to the session so the request is scoped to the originating client.
     # Falls back to `@context` (via `method_missing`) when `@notification_target`
     # does not support sampling.
+    # @deprecated MCP Sampling (`sampling/createMessage`) is deprecated as of
+    #   MCP protocol version 2026-07-28 (SEP-2577). Use direct LLM provider
+    #   APIs instead.
     def create_sampling_message(**kwargs)
       if @notification_target.respond_to?(:create_sampling_message)
         @notification_target.create_sampling_message(**kwargs, related_request_id: @related_request_id)

lib/mcp/server_session.rb

@@ -98,6 +98,10 @@ def client_capabilities
     end
 
     # Sends a `roots/list` request scoped to this session.
+    # @deprecated MCP Roots (`roots/list` and
+    #   `notifications/roots/list_changed`) is deprecated as of MCP protocol
+    #   version 2026-07-28 (SEP-2577). Use tool parameters, resource URIs,
+    #   server configuration, or environment variables instead.
     def list_roots(related_request_id: nil)
       unless client_capabilities&.dig(:roots)
         raise "Client does not support roots."
@@ -115,6 +119,9 @@ def ping(related_request_id: nil)
     end
 
     # Sends a `sampling/createMessage` request scoped to this session.
+    # @deprecated MCP Sampling (`sampling/createMessage`) is deprecated as of
+    #   MCP protocol version 2026-07-28 (SEP-2577). Use direct LLM provider
+    #   APIs instead.
     def create_sampling_message(related_request_id: nil, **kwargs)
       params = @server.build_sampling_params(client_capabilities, **kwargs)
       send_to_transport_request(Methods::SAMPLING_CREATE_MESSAGE, params, related_request_id: related_request_id)
@@ -188,6 +195,9 @@ def notify_progress(progress_token:, progress:, total: nil, message: nil, relate
     end
 
     # Sends a log message notification to this session only.
+    # @deprecated MCP Logging (`logging/setLevel` and `notifications/message`)
+    #   is deprecated as of MCP protocol version 2026-07-28 (SEP-2577).
+    #   Use stderr or OpenTelemetry instead.
     def notify_log_message(data:, level:, logger: nil, related_request_id: nil)
       effective_logging = @logging_message_notification || @server.logging_message_notification
       return unless effective_logging&.should_notify?(level)