Remove Server#notify_progress broadcast API
## Motivation and Context `Server#notify_progress` broadcasts progress notifications to all connected clients. Progress notifications are tied to a specific request's `progressToken` and have no meaningful broadcast use case. Neither the Python SDK nor the TypeScript SDK provides a server-level progress broadcast capability. The MCP specification requires that progress notifications only reference tokens provided in an active request: > Progress notifications MUST only reference tokens that: > - Were provided in an active request > - Are associated with an in-progress operation Ref: https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/progress Broadcasting progress to all clients does not comply with this requirement, since clients that did not originate the request have no matching `progressToken`. The introduction of `ServerSession` for per-connection state (#275) made this removal possible: `Progress` and `ServerContext` now use `notification_target:` (a `ServerSession`) to route notifications to the originating session only. ### Changes - Removed `Server#notify_progress` entirely. The method is no longer needed as `notification_target` in `call_tool_with_args` now passes `session` directly (nil when no session is available, in which case `Progress#report` and `ServerContext#notify_log_message` are no-ops). - Removed `ServerContext#notify_progress` as well. Progress notifications should only be sent via `server_context.report_progress`, which enforces the correct `progressToken` from the originating request. - Added nil guards to `Progress#report` and `ServerContext#notify_log_message` for when no session is available. - Rewrote progress tests to use `ServerSession#handle` instead of `Server#handle`, reflecting that progress notifications are always session-scoped. - Removed 4 tests that called `server.notify_progress` directly as a public broadcast API. - Removed `notify_progress` from the README.md notification methods list. - Removed the "Server-Side: Direct `notify_progress` Usage" section from the README.md. Progress notifications should be sent via `server_context.report_progress` inside tool handlers, which automatically scopes them to the originating client session. ## Breaking Changes Progress notifications are scoped to a specific request via `progressToken` per the MCP specification, so the broadcast behavior of `Server#notify_progress` was a spec violation. This is treated as a bug fix and is made without a deprecation period. This aligns the Ruby SDK with the Python and TypeScript SDKs, neither of which provides a server-level progress broadcast API. `Server#notify_progress` and `ServerContext#notify_progress` are no longer available. Users should use `server_context.report_progress` inside tool handlers instead, which provides session-scoped delivery with the correct `progressToken`. This feature was only recently introduced in mcp 0.9.0: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v0.9.0 So an early release should help limit its impact on adoption.
This commit is contained in:
parent
8969edf4b9
commit
b89f6e315d
3 changed files with 39 additions and 109 deletions
|
|
@ -9,6 +9,7 @@ module MCP
|
|||
|
||||
def report(progress, total: nil, message: nil)
|
||||
return unless @progress_token
|
||||
return unless @notification_target
|
||||
|
||||
@notification_target.notify_progress(
|
||||
progress_token: @progress_token,
|
||||
|
|
|
|||
|
|
@ -116,7 +116,7 @@ module MCP
|
|||
# @param request [Hash] A parsed JSON-RPC request.
|
||||
# @param session [ServerSession, nil] Per-connection session. Passed by
|
||||
# `ServerSession#handle` for session-scoped notification delivery.
|
||||
# When `nil`, notifications broadcast to all sessions.
|
||||
# When `nil`, progress and logging notifications from tool handlers are silently skipped.
|
||||
# @return [Hash, nil] The JSON-RPC response, or `nil` for notifications.
|
||||
def handle(request, session: nil)
|
||||
JsonRpcHandler.handle(request) do |method|
|
||||
|
|
@ -129,7 +129,7 @@ module MCP
|
|||
# @param request [String] A JSON-RPC request as a JSON string.
|
||||
# @param session [ServerSession, nil] Per-connection session. Passed by
|
||||
# `ServerSession#handle_json` for session-scoped notification delivery.
|
||||
# When `nil`, notifications broadcast to all sessions.
|
||||
# When `nil`, progress and logging notifications from tool handlers are silently skipped.
|
||||
# @return [String, nil] The JSON-RPC response as JSON, or `nil` for notifications.
|
||||
def handle_json(request, session: nil)
|
||||
JsonRpcHandler.handle_json(request) do |method|
|
||||
|
|
@ -186,21 +186,6 @@ module MCP
|
|||
report_exception(e, { notification: "resources_list_changed" })
|
||||
end
|
||||
|
||||
def notify_progress(progress_token:, progress:, total: nil, message: nil)
|
||||
return unless @transport
|
||||
|
||||
params = {
|
||||
"progressToken" => progress_token,
|
||||
"progress" => progress,
|
||||
"total" => total,
|
||||
"message" => message,
|
||||
}.compact
|
||||
|
||||
@transport.send_notification(Methods::NOTIFICATIONS_PROGRESS, params)
|
||||
rescue => e
|
||||
report_exception(e, notification: "progress")
|
||||
end
|
||||
|
||||
def notify_log_message(data:, level:, logger: nil)
|
||||
return unless @transport
|
||||
return unless logging_message_notification&.should_notify?(level)
|
||||
|
|
@ -524,9 +509,8 @@ module MCP
|
|||
args = arguments&.transform_keys(&:to_sym) || {}
|
||||
|
||||
if accepts_server_context?(tool.method(:call))
|
||||
notification_target = session || self
|
||||
progress = Progress.new(notification_target: notification_target, progress_token: progress_token)
|
||||
server_context = ServerContext.new(context, progress: progress, notification_target: notification_target)
|
||||
progress = Progress.new(notification_target: session, progress_token: progress_token)
|
||||
server_context = ServerContext.new(context, progress: progress, notification_target: session)
|
||||
tool.call(**args, server_context: server_context).to_h
|
||||
else
|
||||
tool.call(**args).to_h
|
||||
|
|
|
|||
|
|
@ -18,22 +18,14 @@ module MCP
|
|||
@progress.report(progress, total: total, message: message)
|
||||
end
|
||||
|
||||
# Sends a progress notification scoped to the originating session.
|
||||
#
|
||||
# @param progress_token [String, Integer] The token identifying the operation.
|
||||
# @param progress [Numeric] Current progress value.
|
||||
# @param total [Numeric, nil] Total expected value.
|
||||
# @param message [String, nil] Human-readable status message.
|
||||
def notify_progress(progress_token:, progress:, total: nil, message: nil)
|
||||
@notification_target.notify_progress(progress_token: progress_token, progress: progress, total: total, message: message)
|
||||
end
|
||||
|
||||
# Sends a log message notification scoped to the originating session.
|
||||
#
|
||||
# @param data [Object] The log data to send.
|
||||
# @param level [String] Log level (e.g., `"debug"`, `"info"`, `"error"`).
|
||||
# @param logger [String, nil] Logger name.
|
||||
def notify_log_message(data:, level:, logger: nil)
|
||||
return unless @notification_target
|
||||
|
||||
@notification_target.notify_log_message(data: data, level: level, logger: logger)
|
||||
end
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue