mcp 0.10.0 → 0.14.0

data/lib/mcp/configuration.rb

@@ -7,11 +7,18 @@ module MCP
       LATEST_STABLE_PROTOCOL_VERSION, "2025-06-18", "2025-03-26", "2024-11-05",
     ]
 
-    attr_writer :exception_reporter, :instrumentation_callback
+    attr_writer :exception_reporter, :around_request
 
-    def initialize(exception_reporter: nil, instrumentation_callback: nil, protocol_version: nil,
+    # @deprecated Use {#around_request=} instead. `instrumentation_callback`
+    #   fires only after a request completes and cannot wrap execution in a
+    #   surrounding block (e.g. for Application Performance Monitoring (APM) spans).
+    # @see #around_request=
+    attr_writer :instrumentation_callback
+
+    def initialize(exception_reporter: nil, around_request: nil, instrumentation_callback: nil, protocol_version: nil,
       validate_tool_call_arguments: true)
       @exception_reporter = exception_reporter
+      @around_request = around_request
       @instrumentation_callback = instrumentation_callback
       @protocol_version = protocol_version
       if protocol_version
@@ -50,10 +57,24 @@ module MCP
       !@exception_reporter.nil?
     end
 
+    def around_request
+      @around_request || default_around_request
+    end
+
+    def around_request?
+      !@around_request.nil?
+    end
+
+    # @deprecated Use {#around_request} instead. `instrumentation_callback`
+    #   fires only after a request completes and cannot wrap execution in a
+    #   surrounding block (e.g. for Application Performance Monitoring (APM) spans).
+    # @see #around_request
     def instrumentation_callback
       @instrumentation_callback || default_instrumentation_callback
     end
 
+    # @deprecated Use {#around_request?} instead.
+    # @see #around_request?
     def instrumentation_callback?
       !@instrumentation_callback.nil?
     end
@@ -72,20 +93,30 @@ module MCP
       else
         @exception_reporter
       end
+
+      around_request = if other.around_request?
+        other.around_request
+      else
+        @around_request
+      end
+
       instrumentation_callback = if other.instrumentation_callback?
         other.instrumentation_callback
       else
         @instrumentation_callback
       end
+
       protocol_version = if other.protocol_version?
         other.protocol_version
       else
         @protocol_version
       end
+
       validate_tool_call_arguments = other.validate_tool_call_arguments
 
       Configuration.new(
         exception_reporter: exception_reporter,
+        around_request: around_request,
         instrumentation_callback: instrumentation_callback,
         protocol_version: protocol_version,
         validate_tool_call_arguments: validate_tool_call_arguments,
@@ -111,6 +142,11 @@ module MCP
       @default_exception_reporter ||= ->(exception, server_context) {}
     end
 
+    def default_around_request
+      @default_around_request ||= ->(_data, &request_handler) { request_handler.call }
+    end
+
+    # @deprecated Use {#default_around_request} instead.
     def default_instrumentation_callback
       @default_instrumentation_callback ||= ->(data) {}
     end

data/lib/mcp/content.rb

@@ -3,56 +3,60 @@
 module MCP
   module Content
     class Text
-      attr_reader :text, :annotations
+      attr_reader :text, :annotations, :meta
 
-      def initialize(text, annotations: nil)
+      def initialize(text, annotations: nil, meta: nil)
         @text = text
         @annotations = annotations
+        @meta = meta
       end
 
       def to_h
-        { text: text, annotations: annotations, type: "text" }.compact
+        { text: text, annotations: annotations, _meta: meta, type: "text" }.compact
       end
     end
 
     class Image
-      attr_reader :data, :mime_type, :annotations
+      attr_reader :data, :mime_type, :annotations, :meta
 
-      def initialize(data, mime_type, annotations: nil)
+      def initialize(data, mime_type, annotations: nil, meta: nil)
         @data = data
         @mime_type = mime_type
         @annotations = annotations
+        @meta = meta
       end
 
       def to_h
-        { data: data, mimeType: mime_type, annotations: annotations, type: "image" }.compact
+        { data: data, mimeType: mime_type, annotations: annotations, _meta: meta, type: "image" }.compact
       end
     end
 
     class Audio
-      attr_reader :data, :mime_type, :annotations
+      attr_reader :data, :mime_type, :annotations, :meta
 
-      def initialize(data, mime_type, annotations: nil)
+      def initialize(data, mime_type, annotations: nil, meta: nil)
         @data = data
         @mime_type = mime_type
         @annotations = annotations
+        @meta = meta
       end
 
       def to_h
-        { data: data, mimeType: mime_type, annotations: annotations, type: "audio" }.compact
+        { data: data, mimeType: mime_type, annotations: annotations, _meta: meta, type: "audio" }.compact
       end
     end
 
     class EmbeddedResource
-      attr_reader :resource, :annotations
+      attr_reader :resource, :annotations, :meta
 
-      def initialize(resource, annotations: nil)
+      def initialize(resource, annotations: nil, meta: nil)
         @resource = resource
         @annotations = annotations
+        @meta = meta
       end
 
       def to_h
-        { resource: resource.to_h, annotations: annotations, type: "resource" }.compact
+        { resource: resource.to_h, annotations: annotations, _meta: meta, type: "resource" }.compact
       end
     end
   end

data/lib/mcp/instrumentation.rb

@@ -2,19 +2,40 @@
 
 module MCP
   module Instrumentation
-    def instrument_call(method, &block)
+    def instrument_call(method, server_context: {}, exception_already_reported: nil, &block)
       start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       begin
         @instrumentation_data = {}
         add_instrumentation_data(method: method)
 
-        result = yield block
+        result = configuration.around_request.call(@instrumentation_data, &block)
 
         result
+      rescue => e
+        already_reported = begin
+          !!exception_already_reported&.call(e)
+        # rubocop:disable Lint/RescueException
+        rescue Exception
+          # rubocop:enable Lint/RescueException
+          # The predicate is expected to be side-effect-free and return a boolean.
+          # Any exception raised from it (including non-StandardError such as SystemExit)
+          # must not shadow the original exception.
+          false
+        end
+
+        unless already_reported
+          add_instrumentation_data(error: :internal_error) unless @instrumentation_data.key?(:error)
+          configuration.exception_reporter.call(e, server_context)
+        end
+
+        raise
       ensure
         end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         add_instrumentation_data(duration: end_time - start_time)
 
+        # Backward compatibility: `instrumentation_callback` is soft-deprecated
+        # in favor of `around_request`, but existing callers still expect it
+        # to fire after every request until it is removed in a future version.
         configuration.instrumentation_callback.call(@instrumentation_data)
       end
     end

data/lib/mcp/methods.rb

@@ -33,6 +33,7 @@ module MCP
     NOTIFICATIONS_MESSAGE = "notifications/message"
     NOTIFICATIONS_PROGRESS = "notifications/progress"
     NOTIFICATIONS_CANCELLED = "notifications/cancelled"
+    NOTIFICATIONS_ELICITATION_COMPLETE = "notifications/elicitation/complete"
 
     class MissingRequiredCapabilityError < StandardError
       attr_reader :method
@@ -72,15 +73,13 @@ module MCP
           require_capability!(method, capabilities, :completions)
         when ROOTS_LIST
           require_capability!(method, capabilities, :roots)
-        when NOTIFICATIONS_ROOTS_LIST_CHANGED
-          require_capability!(method, capabilities, :roots)
-          require_capability!(method, capabilities, :roots, :listChanged)
         when SAMPLING_CREATE_MESSAGE
           require_capability!(method, capabilities, :sampling)
         when ELICITATION_CREATE
           require_capability!(method, capabilities, :elicitation)
-        when INITIALIZE, PING, NOTIFICATIONS_INITIALIZED, NOTIFICATIONS_PROGRESS, NOTIFICATIONS_CANCELLED
-          # No specific capability required for initialize, ping, progress or cancelled
+        when INITIALIZE, PING, NOTIFICATIONS_INITIALIZED, NOTIFICATIONS_ROOTS_LIST_CHANGED,
+             NOTIFICATIONS_PROGRESS, NOTIFICATIONS_CANCELLED, NOTIFICATIONS_ELICITATION_COMPLETE
+          # No specific capability required.
         end
       end
 

data/lib/mcp/progress.rb

@@ -2,9 +2,10 @@
 
 module MCP
   class Progress
-    def initialize(notification_target:, progress_token:)
+    def initialize(notification_target:, progress_token:, related_request_id: nil)
       @notification_target = notification_target
       @progress_token = progress_token
+      @related_request_id = related_request_id
     end
 
     def report(progress, total: nil, message: nil)
@@ -16,6 +17,7 @@ module MCP
         progress: progress,
         total: total,
         message: message,
+        related_request_id: @related_request_id,
       )
     end
   end

data/lib/mcp/prompt/result.rb

@@ -3,15 +3,16 @@
 module MCP
   class Prompt
     class Result
-      attr_reader :description, :messages
+      attr_reader :description, :messages, :meta
 
-      def initialize(description: nil, messages: [])
+      def initialize(description: nil, messages: [], meta: nil)
         @description = description
         @messages = messages
+        @meta = meta
       end
 
       def to_h
-        { description: description, messages: messages.map(&:to_h) }.compact
+        { description: description, messages: messages.map(&:to_h), _meta: meta }.compact
       end
     end
   end

data/lib/mcp/resource/contents.rb

@@ -3,23 +3,24 @@
 module MCP
   class Resource
     class Contents
-      attr_reader :uri, :mime_type
+      attr_reader :uri, :mime_type, :meta
 
-      def initialize(uri:, mime_type: nil)
+      def initialize(uri:, mime_type: nil, meta: nil)
         @uri = uri
         @mime_type = mime_type
+        @meta = meta
       end
 
       def to_h
-        { uri: uri, mimeType: mime_type }.compact
+        { uri: uri, mimeType: mime_type, _meta: meta }.compact
       end
     end
 
     class TextContents < Contents
       attr_reader :text
 
-      def initialize(text:, uri:, mime_type:)
-        super(uri: uri, mime_type: mime_type)
+      def initialize(text:, uri:, mime_type:, meta: nil)
+        super(uri: uri, mime_type: mime_type, meta: meta)
         @text = text
       end
 
@@ -31,8 +32,8 @@ module MCP
     class BlobContents < Contents
       attr_reader :data
 
-      def initialize(data:, uri:, mime_type:)
-        super(uri: uri, mime_type: mime_type)
+      def initialize(data:, uri:, mime_type:, meta: nil)
+        super(uri: uri, mime_type: mime_type, meta: meta)
         @data = data
       end
 

data/lib/mcp/resource.rb

@@ -5,15 +5,16 @@ require_relative "resource/embedded"
 
 module MCP
   class Resource
-    attr_reader :uri, :name, :title, :description, :icons, :mime_type
+    attr_reader :uri, :name, :title, :description, :icons, :mime_type, :meta
 
-    def initialize(uri:, name:, title: nil, description: nil, icons: [], mime_type: nil)
+    def initialize(uri:, name:, title: nil, description: nil, icons: [], mime_type: nil, meta: nil)
       @uri = uri
       @name = name
       @title = title
       @description = description
       @icons = icons
       @mime_type = mime_type
+      @meta = meta
     end
 
     def to_h
@@ -24,6 +25,7 @@ module MCP
         description: description,
         icons: icons&.then { |icons| icons.empty? ? nil : icons.map(&:to_h) },
         mimeType: mime_type,
+        _meta: meta,
       }.compact
     end
   end

data/lib/mcp/resource_template.rb

@@ -2,15 +2,16 @@
 
 module MCP
   class ResourceTemplate
-    attr_reader :uri_template, :name, :title, :description, :icons, :mime_type
+    attr_reader :uri_template, :name, :title, :description, :icons, :mime_type, :meta
 
-    def initialize(uri_template:, name:, title: nil, description: nil, icons: [], mime_type: nil)
+    def initialize(uri_template:, name:, title: nil, description: nil, icons: [], mime_type: nil, meta: nil)
       @uri_template = uri_template
       @name = name
       @title = title
       @description = description
       @icons = icons
       @mime_type = mime_type
+      @meta = meta
     end
 
     def to_h
@@ -21,6 +22,7 @@ module MCP
         description: description,
         icons: icons&.then { |icons| icons.empty? ? nil : icons.map(&:to_h) },
         mimeType: mime_type,
+        _meta: meta,
       }.compact
     end
   end

data/lib/mcp/server/pagination.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module MCP
+  class Server
+    module Pagination
+      private
+
+      def cursor_from(request)
+        return if request.nil?
+
+        unless request.is_a?(Hash)
+          raise RequestHandlerError.new("Invalid params", request, error_type: :invalid_params)
+        end
+
+        request[:cursor]
+      end
+
+      def paginate(items, cursor:, page_size:, request:, &block)
+        start_index = 0
+
+        if cursor
+          unless cursor.is_a?(String)
+            raise RequestHandlerError.new("Invalid cursor", request, error_type: :invalid_params)
+          end
+
+          start_index = Integer(cursor, exception: false)
+          if start_index.nil? || start_index < 0 || start_index >= items.size
+            raise RequestHandlerError.new("Invalid cursor", request, error_type: :invalid_params)
+          end
+        end
+
+        end_index = page_size ? start_index + page_size : items.size
+        page = items[start_index...end_index]
+        page = page.map(&block) if block
+
+        result = { items: page }
+        result[:next_cursor] = end_index.to_s if end_index < items.size
+        result
+      end
+    end
+  end
+end

data/lib/mcp/server/transports/stdio_transport.rb

@@ -53,6 +53,41 @@ module MCP
           MCP.configuration.exception_reporter.call(e, { error: "Failed to send notification" })
           false
         end
+
+        def send_request(method, params = nil)
+          request_id = generate_request_id
+          request = { jsonrpc: "2.0", id: request_id, method: method }
+          request[:params] = params if params
+
+          begin
+            send_response(request)
+          rescue => e
+            MCP.configuration.exception_reporter.call(e, { error: "Failed to send request" })
+            raise
+          end
+
+          while @open && (line = $stdin.gets)
+            begin
+              parsed = JSON.parse(line.strip, symbolize_names: true)
+            rescue JSON::ParserError => e
+              MCP.configuration.exception_reporter.call(e, { error: "Failed to parse response" })
+              raise
+            end
+
+            if parsed[:id] == request_id && !parsed.key?(:method)
+              if parsed[:error]
+                raise StandardError, "Client returned an error for #{method} request (code: #{parsed[:error][:code]}): #{parsed[:error][:message]}"
+              end
+
+              return parsed[:result]
+            else
+              response = @session ? @session.handle(parsed) : @server.handle(parsed)
+              send_response(response) if response
+            end
+          end
+
+          raise "Transport closed while waiting for response to #{method} request."
+        end
       end
     end
   end