Merge pull request #254 from koic/support_progress_notification_per_mcp_spec

Support progress notifications per MCP specification

Author: koic

README.md

@@ -108,11 +108,12 @@ The server supports sending notifications to clients when lists of tools, prompt
 
 #### Notification Methods
 
-The server provides three notification methods:
+The server provides the following notification methods:
 
 - `notify_tools_list_changed` - Send a notification when the tools list changes
 - `notify_prompts_list_changed` - Send a notification when the prompts list changes
 - `notify_resources_list_changed` - Send a notification when the resources list changes
+- `notify_progress` - Send a progress notification for long-running operations
 - `notify_log_message` - Send a structured logging notification message
 
 #### Notification Format
@@ -122,8 +123,72 @@ Notifications follow the JSON-RPC 2.0 specification and use these method names:
 - `notifications/tools/list_changed`
 - `notifications/prompts/list_changed`
 - `notifications/resources/list_changed`
+- `notifications/progress`
 - `notifications/message`
 
+### Progress
+
+The MCP Ruby SDK supports progress tracking for long-running tool operations,
+following the [MCP Progress specification](https://modelcontextprotocol.io/specification/latest/server/utilities/progress).
+
+#### How Progress Works
+
+1. **Client Request**: The client sends a `progressToken` in the `_meta` field when calling a tool
+2. **Server Notification**: The server sends `notifications/progress` messages back to the client during tool execution
+3. **Tool Integration**: Tools call `server_context.report_progress` to report incremental progress
+
+#### Server-Side: Tool with Progress
+
+Tools that accept a `server_context:` parameter can call `report_progress` on it.
+The server automatically wraps the context in an `MCP::ServerContext` instance that provides this method:
+
+```ruby
+class LongRunningTool < MCP::Tool
+  description "A tool that reports progress during execution"
+  input_schema(
+    properties: {
+      count: { type: "integer" },
+    },
+    required: ["count"]
+  )
+
+  def self.call(count:, server_context:)
+    count.times do |i|
+      # Do work here.
+      server_context.report_progress(i + 1, total: count, message: "Processing item #{i + 1}")
+    end
+
+    MCP::Tool::Response.new([{ type: "text", text: "Done" }])
+  end
+end
+```
+
+The `server_context.report_progress` method accepts:
+
+- `progress` (required) — current progress value (numeric)
+- `total:` (optional) — total expected value, so clients can display a percentage
+- `message:` (optional) — human-readable status message
+
+#### Server-Side: Direct `notify_progress` Usage
+
+You can also call `notify_progress` directly on the server instance:
+
+```ruby
+server.notify_progress(
+  progress_token: "token-123",
+  progress: 50,
+  total: 100,        # optional
+  message: "halfway" # optional
+)
+```
+
+**Key Features:**
+
+- Tools report progress via `server_context.report_progress`
+- `report_progress` is a no-op when no `progressToken` was provided by the client
+- `notify_progress` is a no-op when no transport is configured
+- Supports both numeric and string progress tokens
+
 ### Logging
 
 The MCP Ruby SDK supports structured logging through the `notify_log_message` method, following the [MCP Logging specification](https://modelcontextprotocol.io/specification/latest/server/utilities/logging).
@@ -1049,8 +1114,17 @@ response = client.call_tool(
   tool: tools.first,
   arguments: { message: "Hello, world!" }
 )
+
+# Call a tool with progress tracking.
+response = client.call_tool(
+  tool: tools.first,
+  arguments: { count: 10 },
+  progress_token: "my-progress-token"
+)
 ```
 
+The server will send `notifications/progress` back to the client during execution.
+
 #### HTTP Authorization
 
 By default, the HTTP transport layer provides no authentication to the server, but you can provide custom headers if you need authentication. For example, to use Bearer token authentication:

conformance/expected_failures.yml

@@ -5,5 +5,3 @@ server:
   - tools-call-elicitation
   - elicitation-sep1034-defaults
   - elicitation-sep1330-enums
-  # TODO: The SDK does not extract `_meta.progressToken` from tool call requests or deliver `notifications/progress` to tools.
-  - tools-call-with-progress

conformance/server.rb

@@ -141,13 +141,16 @@ def call(server_context:, **_args)
       end
     end
 
-    # test_tool_with_progress: the actual progress dispatch is in `tools_call_handler`
     class TestToolWithProgress < MCP::Tool
       tool_name "test_tool_with_progress"
       description "A tool that reports progress notifications"
 
       class << self
-        def call(**_args)
+        def call(server_context:, **_args)
+          server_context.report_progress(0, total: 100)
+          server_context.report_progress(50, total: 100)
+          server_context.report_progress(100, total: 100)
+
           MCP::Tool::Response.new([MCP::Content::Text.new("Progress complete").to_h])
         end
       end

lib/mcp.rb

@@ -7,6 +7,7 @@
 require_relative "mcp/icon"
 require_relative "mcp/instrumentation"
 require_relative "mcp/methods"
+require_relative "mcp/progress"
 require_relative "mcp/prompt"
 require_relative "mcp/prompt/argument"
 require_relative "mcp/prompt/message"
@@ -16,6 +17,7 @@
 require_relative "mcp/resource/embedded"
 require_relative "mcp/resource_template"
 require_relative "mcp/server"
+require_relative "mcp/server_context"
 require_relative "mcp/server/transports/streamable_http_transport"
 require_relative "mcp/server/transports/stdio_transport"
 require_relative "mcp/string_utils"

lib/mcp/client.rb

@@ -90,6 +90,7 @@ def prompts
     #
     # @param tool [MCP::Client::Tool] The tool to be called.
     # @param arguments [Object, nil] The arguments to pass to the tool.
+    # @param progress_token [String, Integer, nil] A token to request progress notifications from the server during tool execution.
     # @return [Hash] The full JSON-RPC response from the transport.
     #
     # @example
@@ -100,12 +101,17 @@ def prompts
     # @note
     #   The exact requirements for `arguments` are determined by the transport layer in use.
     #   Consult the documentation for your transport (e.g., MCP::Client::HTTP) for details.
-    def call_tool(tool:, arguments: nil)
+    def call_tool(tool:, arguments: nil, progress_token: nil)
+      params = { name: tool.name, arguments: arguments }
+      if progress_token
+        params[:_meta] = { progressToken: progress_token }
+      end
+
       transport.send_request(request: {
         jsonrpc: JsonRpcHandler::Version::V2_0,
         id: request_id,
         method: "tools/call",
-        params: { name: tool.name, arguments: arguments },
+        params: params,
       })
     end
 

lib/mcp/progress.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module MCP
+  class Progress
+    def initialize(server:, progress_token:)
+      @server = server
+      @progress_token = progress_token
+    end
+
+    def report(progress, total: nil, message: nil)
+      return unless @progress_token
+
+      @server.notify_progress(
+        progress_token: @progress_token,
+        progress: progress,
+        total: total,
+        message: message,
+      )
+    end
+  end
+end

lib/mcp/server.rb

@@ -96,6 +96,7 @@ def initialize(
         Methods::INITIALIZE => method(:init),
         Methods::PING => ->(_) { {} },
         Methods::NOTIFICATIONS_INITIALIZED => ->(_) {},
+        Methods::NOTIFICATIONS_PROGRESS => ->(_) {},
         Methods::LOGGING_SET_LEVEL => method(:configure_logging_level),
 
         # No op handlers for currently unsupported methods
@@ -168,6 +169,21 @@ def notify_resources_list_changed
       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)
@@ -419,7 +435,9 @@ def call_tool(request)
         end
       end
 
-      call_tool_with_args(tool, arguments, server_context_with_meta(request))
+      progress_token = request.dig(:_meta, :progressToken)
+
+      call_tool_with_args(tool, arguments, server_context_with_meta(request), progress_token: progress_token)
     rescue RequestHandlerError
       raise
     rescue => e
@@ -488,10 +506,12 @@ def accepts_server_context?(method_object)
       parameters.any? { |type, name| type == :keyrest || name == :server_context }
     end
 
-    def call_tool_with_args(tool, arguments, server_context)
+    def call_tool_with_args(tool, arguments, context, progress_token: nil)
       args = arguments&.transform_keys(&:to_sym) || {}
 
       if accepts_server_context?(tool.method(:call))
+        progress = Progress.new(server: self, progress_token: progress_token)
+        server_context = ServerContext.new(context, progress: progress)
         tool.call(**args, server_context: server_context).to_h
       else
         tool.call(**args).to_h
@@ -508,13 +528,13 @@ def call_prompt_template_with_args(prompt, args, server_context)
 
     def server_context_with_meta(request)
       meta = request[:_meta]
-      if @server_context && meta
+      if meta && @server_context.is_a?(Hash)
         context = @server_context.dup
         context[:_meta] = meta
         context
-      elsif meta
+      elsif meta && @server_context.nil?
         { _meta: meta }
-      elsif @server_context
+      else
         @server_context
       end
     end

lib/mcp/server_context.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module MCP
+  class ServerContext
+    def initialize(context, progress:)
+      @context = context
+      @progress = progress
+    end
+
+    def report_progress(progress, total: nil, message: nil)
+      @progress.report(progress, total: total, message: message)
+    end
+
+    def method_missing(name, ...)
+      if @context.respond_to?(name)
+        @context.public_send(name, ...)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @context.respond_to?(name) || super
+    end
+  end
+end

test/mcp/client_test.rb

@@ -305,5 +305,43 @@ def test_get_prompt_returns_empty_hash
 
       assert_equal({}, contents)
     end
+
+    def test_call_tool_includes_meta_progress_token_when_provided
+      transport = mock
+      tool = MCP::Client::Tool.new(name: "tool1", description: "tool1", input_schema: {})
+      arguments = { foo: "bar" }
+      progress_token = "my-progress-token"
+      mock_response = {
+        "result" => { "content" => [{ "type": "text", "text": "Hello, world!" }] },
+      }
+
+      transport.expects(:send_request).with do |args|
+        args.dig(:request, :method) == "tools/call" &&
+          args.dig(:request, :params, :_meta, :progressToken) == progress_token &&
+          args.dig(:request, :params, :name) == "tool1" &&
+          args.dig(:request, :params, :arguments) == arguments
+      end.returns(mock_response).once
+
+      client = Client.new(transport: transport)
+      client.call_tool(tool: tool, arguments: arguments, progress_token: progress_token)
+    end
+
+    def test_call_tool_omits_meta_when_no_progress_token
+      transport = mock
+      tool = MCP::Client::Tool.new(name: "tool1", description: "tool1", input_schema: {})
+      arguments = { foo: "bar" }
+      mock_response = {
+        "result" => { "content" => [{ "type": "text", "text": "Hello, world!" }] },
+      }
+
+      transport.expects(:send_request).with do |args|
+        args.dig(:request, :method) == "tools/call" &&
+          args.dig(:request, :params, :name) == "tool1" &&
+          args.dig(:request, :params).key?(:_meta) == false
+      end.returns(mock_response).once
+
+      client = Client.new(transport: transport)
+      client.call_tool(tool: tool, arguments: arguments)
+    end
   end
 end