Skip to content

Commit 6a43d3d

Browse files
atesgoralQlaw
andcommitted
feat: deprecate roots sampling and logging
Warn when Roots, Sampling, or Logging APIs are used with MCP protocol version 2026-07-28 or newer. Add a shared protocol deprecation helper, YARD deprecation notes, and regression tests covering warnings at and after the deprecation threshold and no warnings for older or never-established protocol versions. Closes #390 Co-authored-by: Qlaw <noreply@qlaw.quick.shopify.io>
1 parent f4d939d commit 6a43d3d

15 files changed

Lines changed: 508 additions & 3 deletions

‎lib/mcp.rb‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
require_relative "json_rpc_handler"
44
require_relative "mcp/configuration"
5+
require_relative "mcp/protocol_deprecations"
56
require_relative "mcp/string_utils"
67
require_relative "mcp/transport"
78
require_relative "mcp/version"

‎lib/mcp/client/http.rb‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
require_relative "../../json_rpc_handler"
55
require_relative "../configuration"
66
require_relative "../methods"
7+
require_relative "../protocol_deprecations"
78
require_relative "../version"
89

910
module MCP
@@ -334,6 +335,8 @@ def connect(client_info: nil, protocol_version: nil, capabilities: {})
334335
)
335336
end
336337

338+
MCP::ProtocolDeprecations.warn_for_client_capabilities(capabilities, protocol_version: negotiated_protocol_version, uplevel: 1)
339+
337340
begin
338341
send_request(request: {
339342
jsonrpc: JsonRpcHandler::Version::V2_0,

‎lib/mcp/client/stdio.rb‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
require_relative "../../json_rpc_handler"
88
require_relative "../configuration"
99
require_relative "../methods"
10+
require_relative "../protocol_deprecations"
1011
require_relative "../version"
1112

1213
module MCP
@@ -128,6 +129,8 @@ def connect(client_info: nil, protocol_version: nil, capabilities: {})
128129
)
129130
end
130131

132+
MCP::ProtocolDeprecations.warn_for_client_capabilities(capabilities, protocol_version: negotiated_protocol_version, uplevel: 1)
133+
131134
begin
132135
notification = {
133136
jsonrpc: JsonRpcHandler::Version::V2_0,

‎lib/mcp/configuration.rb‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
module MCP
44
class Configuration
55
LATEST_STABLE_PROTOCOL_VERSION = "2026-07-28"
6+
ROOTS_SAMPLING_LOGGING_DEPRECATED_PROTOCOL_VERSION = "2026-07-28"
67
SUPPORTED_STABLE_PROTOCOL_VERSIONS = [
78
LATEST_STABLE_PROTOCOL_VERSION, "2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05",
89
].freeze

‎lib/mcp/protocol_deprecations.rb‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# frozen_string_literal: true
2+
3+
require_relative "configuration"
4+
5+
module MCP
6+
module ProtocolDeprecations
7+
extend self
8+
9+
ROOTS_MESSAGE =
10+
"MCP Roots (`roots/list` and `notifications/roots/list_changed`) is deprecated as of protocol version " \
11+
"2026-07-28 (SEP-2577). Use tool parameters, resource URIs, server configuration, or environment " \
12+
"variables instead."
13+
SAMPLING_MESSAGE =
14+
"MCP Sampling (`sampling/createMessage`) is deprecated as of protocol version 2026-07-28 (SEP-2577). " \
15+
"Use direct LLM provider APIs instead."
16+
LOGGING_MESSAGE =
17+
"MCP Logging (`logging/setLevel` and `notifications/message`) is deprecated as of protocol version " \
18+
"2026-07-28 (SEP-2577). Use stderr or OpenTelemetry instead."
19+
20+
MESSAGES = {
21+
roots: ROOTS_MESSAGE,
22+
sampling: SAMPLING_MESSAGE,
23+
logging: LOGGING_MESSAGE,
24+
}.freeze
25+
26+
def deprecated_roots_sampling_logging?(protocol_version)
27+
return false unless protocol_version
28+
29+
protocol_version >= Configuration::ROOTS_SAMPLING_LOGGING_DEPRECATED_PROTOCOL_VERSION
30+
end
31+
32+
def warn_for(feature, protocol_version:, uplevel: 1)
33+
return unless deprecated_roots_sampling_logging?(protocol_version)
34+
35+
Kernel.warn(MESSAGES.fetch(feature), uplevel: uplevel)
36+
end
37+
38+
def warn_for_client_capabilities(capabilities, protocol_version:, uplevel: 1)
39+
return unless deprecated_roots_sampling_logging?(protocol_version)
40+
return unless capabilities
41+
42+
warn_for(:roots, protocol_version: protocol_version, uplevel: uplevel) if capability?(capabilities, :roots)
43+
warn_for(:sampling, protocol_version: protocol_version, uplevel: uplevel) if capability?(capabilities, :sampling)
44+
end
45+
46+
private
47+
48+
def capability?(capabilities, key)
49+
capabilities.key?(key) || capabilities.key?(key.to_s)
50+
end
51+
end
52+
end

‎lib/mcp/server.rb‎

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
require_relative "methods"
88
require_relative "logging_message_notification"
99
require_relative "progress"
10+
require_relative "protocol_deprecations"
1011
require_relative "server_context"
1112
require_relative "server/capabilities"
1213
require_relative "server/pagination"
@@ -184,6 +185,7 @@ def initialize(
184185
self.cache_scope = cache_scope
185186
@configuration = MCP.configuration.merge(configuration)
186187
@client = nil
188+
@client_protocol_version = nil
187189

188190
validate!
189191

@@ -354,6 +356,8 @@ def notify_resources_list_changed
354356
# is deprecated as of MCP protocol version 2026-07-28 (SEP-2577).
355357
# Use stderr or OpenTelemetry instead.
356358
def notify_log_message(data:, level:, logger: nil)
359+
warn_if_deprecated_protocol_feature(:logging, uplevel: 1)
360+
357361
return unless @transport
358362
return unless logging_message_notification&.should_notify?(level)
359363

@@ -374,6 +378,8 @@ def notify_log_message(data:, level:, logger: nil)
374378
# version 2026-07-28 (SEP-2577). Use tool parameters, resource URIs,
375379
# server configuration, or environment variables instead.
376380
def roots_list_changed_handler(&block)
381+
warn_if_deprecated_protocol_feature(:roots, uplevel: 1)
382+
377383
@handlers[Methods::NOTIFICATIONS_ROOTS_LIST_CHANGED] = block
378384
end
379385

@@ -538,6 +544,13 @@ def handle_request(request, method, session: nil, related_request_id: nil)
538544
return ->(params) { handle_cancelled_notification(params, session: session) }
539545
end
540546

547+
case method
548+
when Methods::NOTIFICATIONS_ROOTS_LIST_CHANGED
549+
warn_if_deprecated_protocol_feature(:roots, session: session, uplevel: 2)
550+
when Methods::LOGGING_SET_LEVEL
551+
warn_if_deprecated_protocol_feature(:logging, session: session, uplevel: 2)
552+
end
553+
541554
handler = @handlers[method]
542555
unless handler
543556
instrument_call("unsupported_method", server_context: { request: request }) do
@@ -706,7 +719,11 @@ def init(params, session: nil)
706719
response_instructions = nil
707720
end
708721

709-
session&.mark_initialized!
722+
if session
723+
session.mark_initialized!(protocol_version: negotiated_version)
724+
else
725+
@client_protocol_version = negotiated_version
726+
end
710727

711728
{
712729
protocolVersion: negotiated_version,
@@ -773,6 +790,19 @@ def configure_logging_level(request, session: nil)
773790
{}
774791
end
775792

793+
def warn_if_deprecated_protocol_feature(feature, session: nil, uplevel: 1)
794+
protocol_version = effective_deprecation_protocol_version(session)
795+
MCP::ProtocolDeprecations.warn_for(feature, protocol_version: protocol_version, uplevel: uplevel)
796+
end
797+
798+
def effective_deprecation_protocol_version(session)
799+
session&.protocol_version || @client_protocol_version || explicit_protocol_version
800+
end
801+
802+
def explicit_protocol_version
803+
configuration.protocol_version if configuration.protocol_version?
804+
end
805+
776806
def list_tools(request)
777807
page = paginate(@tools.values, cursor: cursor_from(request), page_size: @page_size, request: request, &:to_h)
778808

‎lib/mcp/server_session.rb‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ module MCP
99
class ServerSession
1010
ERAS = [:legacy, :modern].freeze
1111

12-
attr_reader :session_id, :client, :logging_message_notification
12+
attr_reader :session_id, :client, :logging_message_notification, :protocol_version
1313

1414
# Connection-era lock of the dual-era serving model (SEP-2575): `nil` until the first era-distinctive message succeeds,
1515
# then `:legacy` or `:modern` for the connection's lifetime. Modern-era transports construct their per-request sessions
@@ -26,6 +26,7 @@ def initialize(server:, transport:, session_id: nil, era: nil)
2626
@client = nil
2727
@client_capabilities = nil
2828
@logging_message_notification = nil
29+
@protocol_version = nil
2930
@in_flight = {}
3031
@in_flight_mutex = Mutex.new
3132
@initialized = false
@@ -39,8 +40,9 @@ def initialized?
3940
# Called by `Server#init` after a successful `initialize` response, so subsequent
4041
# `initialize` requests on the same session can be rejected per MCP spec
4142
# (the initialization phase MUST be the first interaction).
42-
def mark_initialized!
43+
def mark_initialized!(protocol_version: nil)
4344
@initialized = true
45+
@protocol_version = protocol_version
4446
# A successful `initialize` is the legacy-distinctive message of the dual-era serving model (SEP-2575),
4547
# so it also locks the connection era.
4648
@era ||= :legacy
@@ -130,6 +132,7 @@ def client_capabilities
130132
# version 2026-07-28 (SEP-2577). Use tool parameters, resource URIs,
131133
# server configuration, or environment variables instead.
132134
def list_roots(related_request_id: nil)
135+
@server.send(:warn_if_deprecated_protocol_feature, :roots, session: self, uplevel: 2)
133136
warn_unassociated_request(__method__, related_request_id)
134137

135138
unless client_capabilities&.dig(:roots)
@@ -156,6 +159,7 @@ def ping(related_request_id: nil)
156159
# MCP protocol version 2026-07-28 (SEP-2577). Use direct LLM provider
157160
# APIs instead.
158161
def create_sampling_message(related_request_id: nil, **kwargs)
162+
@server.send(:warn_if_deprecated_protocol_feature, :sampling, session: self, uplevel: 2)
159163
warn_unassociated_request(__method__, related_request_id)
160164

161165
params = @server.build_sampling_params(client_capabilities, **kwargs)
@@ -246,6 +250,8 @@ def notify_progress(progress_token:, progress:, total: nil, message: nil, relate
246250
# is deprecated as of MCP protocol version 2026-07-28 (SEP-2577).
247251
# Use stderr or OpenTelemetry instead.
248252
def notify_log_message(data:, level:, logger: nil, related_request_id: nil)
253+
@server.send(:warn_if_deprecated_protocol_feature, :logging, session: self, uplevel: 2)
254+
249255
effective_logging = @logging_message_notification || @server.logging_message_notification
250256
return unless effective_logging&.should_notify?(level)
251257

‎test/mcp/client/http_test.rb‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@
1111
module MCP
1212
class Client
1313
class HTTPTest < Minitest::Test
14+
include DeprecationWarningTestHelper
15+
1416
def test_raises_load_error_when_faraday_not_available
1517
client = HTTP.new(url: url)
1618

@@ -1705,6 +1707,44 @@ def test_connect_accepts_custom_parameters
17051707
assert_requested(notification_stub)
17061708
end
17071709

1710+
def test_connect_warns_for_deprecated_capabilities_when_negotiated_protocol_version_is_2026_07_28
1711+
notification_stub = stub_notification
1712+
1713+
init_stub = stub_request(:post, url)
1714+
.with { |req| JSON.parse(req.body)["method"] == "initialize" }
1715+
.to_return(
1716+
status: 200,
1717+
headers: { "Content-Type" => "application/json" },
1718+
body: { result: { protocolVersion: "2026-07-28" } }.to_json,
1719+
)
1720+
1721+
assert_deprecation_warning(/MCP Roots .*2026-07-28.*MCP Sampling .*2026-07-28/m) do
1722+
client.connect(capabilities: { roots: { listChanged: true }, sampling: {} })
1723+
end
1724+
1725+
assert_requested(init_stub)
1726+
assert_requested(notification_stub)
1727+
end
1728+
1729+
def test_connect_does_not_warn_for_deprecated_capabilities_when_negotiated_protocol_version_is_older
1730+
notification_stub = stub_notification
1731+
1732+
init_stub = stub_request(:post, url)
1733+
.with { |req| JSON.parse(req.body)["method"] == "initialize" }
1734+
.to_return(
1735+
status: 200,
1736+
headers: { "Content-Type" => "application/json" },
1737+
body: { result: { protocolVersion: "2025-11-25" } }.to_json,
1738+
)
1739+
1740+
assert_no_deprecation_warning do
1741+
client.connect(capabilities: { roots: { listChanged: true }, sampling: {} })
1742+
end
1743+
1744+
assert_requested(init_stub)
1745+
assert_requested(notification_stub)
1746+
end
1747+
17081748
def test_connect_is_idempotent
17091749
init_stub = stub_initialize
17101750
notification_stub = stub_notification

‎test/mcp/client/stdio_test.rb‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@
99
module MCP
1010
class Client
1111
class StdioTest < Minitest::Test
12+
include DeprecationWarningTestHelper
13+
1214
def test_send_request_raises_when_connect_not_called
1315
Open3.expects(:popen3).never
1416

@@ -816,6 +818,38 @@ def test_connect_accepts_custom_parameters
816818
stdout_write.close
817819
end
818820

821+
def test_connect_warns_for_deprecated_capabilities_when_negotiated_protocol_version_is_2026_07_28
822+
stdin_read, stdin_write = IO.pipe
823+
stdout_read, stdout_write = IO.pipe
824+
stderr_read, _ = IO.pipe
825+
826+
Open3.stubs(:popen3).returns([stdin_write, stdout_read, stderr_read, mock_wait_thread])
827+
828+
transport = Stdio.new(command: "ruby", args: ["server.rb"])
829+
830+
server_thread = Thread.new do
831+
init_line = stdin_read.gets
832+
init_request = JSON.parse(init_line)
833+
stdout_write.puts(JSON.generate(
834+
jsonrpc: "2.0",
835+
id: init_request["id"],
836+
result: { protocolVersion: "2026-07-28" },
837+
))
838+
stdout_write.flush
839+
stdin_read.gets
840+
end
841+
842+
assert_deprecation_warning(/MCP Roots .*2026-07-28.*MCP Sampling .*2026-07-28/m) do
843+
transport.connect(capabilities: { roots: { listChanged: true }, sampling: {} })
844+
end
845+
ensure
846+
server_thread.join
847+
stdin_read.close
848+
stdin_write.close
849+
stdout_read.close
850+
stdout_write.close
851+
end
852+
819853
def test_connect_raises_on_jsonrpc_error_response
820854
stdin_read, stdin_write = IO.pipe
821855
stdout_read, stdout_write = IO.pipe
Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# frozen_string_literal: true
2+
3+
require "test_helper"
4+
5+
module MCP
6+
class ProtocolDeprecationsTest < ActiveSupport::TestCase
7+
test "roots, sampling, and logging are deprecated in 2026-07-28 and later" do
8+
refute ProtocolDeprecations.deprecated_roots_sampling_logging?(nil)
9+
refute ProtocolDeprecations.deprecated_roots_sampling_logging?("2025-11-25")
10+
assert ProtocolDeprecations.deprecated_roots_sampling_logging?("2026-07-28")
11+
assert ProtocolDeprecations.deprecated_roots_sampling_logging?("2027-01-01")
12+
end
13+
end
14+
end

0 commit comments

Comments
 (0)