mcp 0.10.0 → 0.15.0

data/lib/mcp/client.rb

@@ -2,10 +2,47 @@
 
 require_relative "client/stdio"
 require_relative "client/http"
+require_relative "client/paginated_result"
 require_relative "client/tool"
 
 module MCP
   class Client
+    class ServerError < StandardError
+      attr_reader :code, :data
+
+      def initialize(message, code:, data: nil)
+        super(message)
+        @code = code
+        @data = data
+      end
+    end
+
+    class RequestHandlerError < StandardError
+      attr_reader :error_type, :original_error, :request
+
+      def initialize(message, request, error_type: :internal_error, original_error: nil)
+        super(message)
+        @request = request
+        @error_type = error_type
+        @original_error = original_error
+      end
+    end
+
+    # Raised when a server response fails client-side validation, e.g., a success response
+    # whose `result` field is missing or has the wrong type. This is distinct from a
+    # server-returned JSON-RPC error, which is raised as `ServerError`.
+    class ValidationError < StandardError; end
+
+    # Raised when the server responds 404 to a request containing a session ID,
+    # indicating the session has expired. Inherits from `RequestHandlerError` for
+    # backward compatibility with callers that rescue the generic error. Per spec,
+    # clients MUST start a new session with a fresh `initialize` request in response.
+    class SessionExpiredError < RequestHandlerError
+      def initialize(message, request, original_error: nil)
+        super(message, request, error_type: :not_found, original_error: original_error)
+      end
+    end
+
     # Initializes a new MCP::Client instance.
     #
     # @param transport [Object] The transport object to use for communication with the server.
@@ -22,8 +59,81 @@ module MCP
     # So keeping it public
     attr_reader :transport
 
-    # Returns the list of tools available from the server.
-    # Each call will make a new request – the result is not cached.
+    # The server's `InitializeResult` (protocol version, capabilities, server info,
+    # instructions), as reported by the transport after a successful `connect`.
+    # Returns `nil` before `connect`, after `close`, or when the transport does
+    # not expose a cached handshake result.
+    def server_info
+      transport.server_info if transport.respond_to?(:server_info)
+    end
+
+    # Performs the MCP `initialize` handshake by delegating to the transport
+    # (e.g. `MCP::Client::HTTP`, `MCP::Client::Stdio`). Returns the server's
+    # `InitializeResult`.
+    #
+    # When the transport does not respond to `:connect`, this is a no-op and
+    # returns `nil`.
+    #
+    # @param client_info [Hash, nil] `{ name:, version: }` identifying the client.
+    # @param protocol_version [String, nil] Protocol version to offer.
+    # @param capabilities [Hash] Capabilities advertised by the client.
+    # @return [Hash, nil] The server's `InitializeResult`, or `nil` when the transport
+    #   does not expose an explicit handshake.
+    # https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#initialization
+    def connect(client_info: nil, protocol_version: nil, capabilities: {})
+      return unless transport.respond_to?(:connect)
+
+      transport.connect(
+        client_info: client_info,
+        protocol_version: protocol_version,
+        capabilities: capabilities,
+      )
+    end
+
+    # Returns true once `connect` has completed the handshake on the underlying
+    # transport. Transports that do not expose connection state are assumed
+    # connected and return `true`.
+    def connected?
+      return transport.connected? if transport.respond_to?(:connected?)
+
+      true
+    end
+
+    # Returns a single page of tools from the server.
+    #
+    # @param cursor [String, nil] Cursor from a previous page response.
+    # @return [MCP::Client::ListToolsResult] Result with `tools` (Array<MCP::Client::Tool>)
+    #   and `next_cursor` (String or nil).
+    #
+    # @example Iterate all pages
+    #   cursor = nil
+    #   loop do
+    #     page = client.list_tools(cursor: cursor)
+    #     page.tools.each { |tool| puts tool.name }
+    #     cursor = page.next_cursor
+    #     break unless cursor
+    #   end
+    def list_tools(cursor: nil)
+      params = cursor ? { cursor: cursor } : nil
+      response = request(method: "tools/list", params: params)
+      result = response["result"] || {}
+
+      tools = (result["tools"] || []).map do |tool|
+        Tool.new(
+          name: tool["name"],
+          description: tool["description"],
+          input_schema: tool["inputSchema"],
+        )
+      end
+
+      ListToolsResult.new(tools: tools, next_cursor: result["nextCursor"], meta: result["_meta"])
+    end
+
+    # Returns every tool available on the server. Iterates through all pages automatically
+    # when the server paginates, so the full collection is returned regardless of the server's `page_size` setting.
+    # Use {#list_tools} when you need fine-grained cursor control.
+    #
+    # Each call will make a new request - the result is not cached.
     #
     # @return [Array<MCP::Client::Tool>] An array of available tools.
     #
@@ -33,61 +143,151 @@ module MCP
     #     puts tool.name
     #   end
     def tools
-      response = transport.send_request(request: {
-        jsonrpc: JsonRpcHandler::Version::V2_0,
-        id: request_id,
-        method: "tools/list",
-      })
+      # TODO: consider renaming to `list_all_tools`.
+      all_tools = []
+      seen = Set.new
+      cursor = nil
 
-      response.dig("result", "tools")&.map do |tool|
-        Tool.new(
-          name: tool["name"],
-          description: tool["description"],
-          input_schema: tool["inputSchema"],
-        )
-      end || []
+      loop do
+        page = list_tools(cursor: cursor)
+        all_tools.concat(page.tools)
+        next_cursor = page.next_cursor
+        break if next_cursor.nil? || seen.include?(next_cursor)
+
+        seen << next_cursor
+        cursor = next_cursor
+      end
+
+      all_tools
     end
 
-    # Returns the list of resources available from the server.
-    # Each call will make a new request – the result is not cached.
+    # Returns a single page of resources from the server.
+    #
+    # @param cursor [String, nil] Cursor from a previous page response.
+    # @return [MCP::Client::ListResourcesResult] Result with `resources` (Array<Hash>)
+    #   and `next_cursor` (String or nil).
+    def list_resources(cursor: nil)
+      params = cursor ? { cursor: cursor } : nil
+      response = request(method: "resources/list", params: params)
+      result = response["result"] || {}
+
+      ListResourcesResult.new(
+        resources: result["resources"] || [],
+        next_cursor: result["nextCursor"],
+        meta: result["_meta"],
+      )
+    end
+
+    # Returns every resource available on the server. Iterates through all pages automatically
+    # when the server paginates, so the full collection is returned regardless of the server's `page_size` setting.
+    # Use {#list_resources} when you need fine-grained cursor control.
+    #
+    # Each call will make a new request - the result is not cached.
     #
     # @return [Array<Hash>] An array of available resources.
     def resources
-      response = transport.send_request(request: {
-        jsonrpc: JsonRpcHandler::Version::V2_0,
-        id: request_id,
-        method: "resources/list",
-      })
+      # TODO: consider renaming to `list_all_resources`.
+      all_resources = []
+      seen = Set.new
+      cursor = nil
+
+      loop do
+        page = list_resources(cursor: cursor)
+        all_resources.concat(page.resources)
+        next_cursor = page.next_cursor
+        break if next_cursor.nil? || seen.include?(next_cursor)
+
+        seen << next_cursor
+        cursor = next_cursor
+      end
+
+      all_resources
+    end
+
+    # Returns a single page of resource templates from the server.
+    #
+    # @param cursor [String, nil] Cursor from a previous page response.
+    # @return [MCP::Client::ListResourceTemplatesResult] Result with `resource_templates`
+    #   (Array<Hash>) and `next_cursor` (String or nil).
+    def list_resource_templates(cursor: nil)
+      params = cursor ? { cursor: cursor } : nil
+      response = request(method: "resources/templates/list", params: params)
+      result = response["result"] || {}
 
-      response.dig("result", "resources") || []
+      ListResourceTemplatesResult.new(
+        resource_templates: result["resourceTemplates"] || [],
+        next_cursor: result["nextCursor"],
+        meta: result["_meta"],
+      )
     end
 
-    # Returns the list of resource templates available from the server.
-    # Each call will make a new request – the result is not cached.
+    # Returns every resource template available on the server. Iterates through all pages automatically
+    # when the server paginates, so the full collection is returned regardless of the server's `page_size` setting.
+    # Use {#list_resource_templates} when you need fine-grained cursor control.
+    #
+    # Each call will make a new request - the result is not cached.
     #
     # @return [Array<Hash>] An array of available resource templates.
     def resource_templates
-      response = transport.send_request(request: {
-        jsonrpc: JsonRpcHandler::Version::V2_0,
-        id: request_id,
-        method: "resources/templates/list",
-      })
+      # TODO: consider renaming to `list_all_resource_templates`.
+      all_templates = []
+      seen = Set.new
+      cursor = nil
+
+      loop do
+        page = list_resource_templates(cursor: cursor)
+        all_templates.concat(page.resource_templates)
+        next_cursor = page.next_cursor
+        break if next_cursor.nil? || seen.include?(next_cursor)
+
+        seen << next_cursor
+        cursor = next_cursor
+      end
+
+      all_templates
+    end
+
+    # Returns a single page of prompts from the server.
+    #
+    # @param cursor [String, nil] Cursor from a previous page response.
+    # @return [MCP::Client::ListPromptsResult] Result with `prompts` (Array<Hash>)
+    #   and `next_cursor` (String or nil).
+    def list_prompts(cursor: nil)
+      params = cursor ? { cursor: cursor } : nil
+      response = request(method: "prompts/list", params: params)
+      result = response["result"] || {}
 
-      response.dig("result", "resourceTemplates") || []
+      ListPromptsResult.new(
+        prompts: result["prompts"] || [],
+        next_cursor: result["nextCursor"],
+        meta: result["_meta"],
+      )
     end
 
-    # Returns the list of prompts available from the server.
-    # Each call will make a new request – the result is not cached.
+    # Returns every prompt available on the server. Iterates through all pages automatically
+    # when the server paginates, so the full collection is returned regardless of the server's `page_size` setting.
+    # Use {#list_prompts} when you need fine-grained cursor control.
+    #
+    # Each call will make a new request - the result is not cached.
     #
     # @return [Array<Hash>] An array of available prompts.
     def prompts
-      response = transport.send_request(request: {
-        jsonrpc: JsonRpcHandler::Version::V2_0,
-        id: request_id,
-        method: "prompts/list",
-      })
+      # TODO: consider renaming to `list_all_prompts`.
+      all_prompts = []
+      seen = Set.new
+      cursor = nil
 
-      response.dig("result", "prompts") || []
+      loop do
+        page = list_prompts(cursor: cursor)
+        all_prompts.concat(page.prompts)
+        next_cursor = page.next_cursor
+        break if next_cursor.nil? || seen.include?(next_cursor)
+
+        seen << next_cursor
+        cursor = next_cursor
+      end
+
+      all_prompts
     end
 
     # Calls a tool via the transport layer and returns the full response from the server.
@@ -119,12 +319,7 @@ module MCP
         params[:_meta] = { progressToken: progress_token }
       end
 
-      transport.send_request(request: {
-        jsonrpc: JsonRpcHandler::Version::V2_0,
-        id: request_id,
-        method: "tools/call",
-        params: params,
-      })
+      request(method: "tools/call", params: params)
     end
 
     # Reads a resource from the server by URI and returns the contents.
@@ -132,12 +327,7 @@ module MCP
     # @param uri [String] The URI of the resource to read.
     # @return [Array<Hash>] An array of resource contents (text or blob).
     def read_resource(uri:)
-      response = transport.send_request(request: {
-        jsonrpc: JsonRpcHandler::Version::V2_0,
-        id: request_id,
-        method: "resources/read",
-        params: { uri: uri },
-      })
+      response = request(method: "resources/read", params: { uri: uri })
 
       response.dig("result", "contents") || []
     end
@@ -147,31 +337,68 @@ module MCP
     # @param name [String] The name of the prompt to get.
     # @return [Hash] A hash containing the prompt details.
     def get_prompt(name:)
-      response = transport.send_request(request: {
-        jsonrpc: JsonRpcHandler::Version::V2_0,
-        id: request_id,
-        method: "prompts/get",
-        params: { name: name },
-      })
+      response = request(method: "prompts/get", params: { name: name })
 
       response.fetch("result", {})
     end
 
-    private
+    # Requests completion suggestions from the server for a prompt argument or resource template URI.
+    #
+    # @param ref [Hash] The reference, e.g. `{ type: "ref/prompt", name: "my_prompt" }`
+    #   or `{ type: "ref/resource", uri: "file:///{path}" }`.
+    # @param argument [Hash] The argument being completed, e.g. `{ name: "language", value: "py" }`.
+    # @param context [Hash, nil] Optional context with previously resolved arguments.
+    # @return [Hash] The completion result with `"values"`, `"hasMore"`, and optionally `"total"`.
+    def complete(ref:, argument:, context: nil)
+      params = { ref: ref, argument: argument }
+      params[:context] = context if context
 
-    def request_id
-      SecureRandom.uuid
+      response = request(method: "completion/complete", params: params)
+
+      response.dig("result", "completion") || { "values" => [], "hasMore" => false }
     end
 
-    class RequestHandlerError < StandardError
-      attr_reader :error_type, :original_error, :request
+    # Sends a `ping` request to the server to verify the connection is alive.
+    # Per the MCP spec, the server responds with an empty result.
+    #
+    # @return [Hash] An empty hash on success.
+    # @raise [ServerError] If the server returns a JSON-RPC error.
+    # @raise [ValidationError] If the response `result` is missing or not a Hash.
+    #
+    # @example
+    #   client.ping # => {}
+    #
+    # @see https://modelcontextprotocol.io/specification/latest/basic/utilities/ping
+    def ping
+      result = request(method: Methods::PING)["result"]
+      raise ValidationError, "Response validation failed: missing or invalid `result`" unless result.is_a?(Hash)
 
-      def initialize(message, request, error_type: :internal_error, original_error: nil)
-        super(message)
-        @request = request
-        @error_type = error_type
-        @original_error = original_error
+      result
+    end
+
+    private
+
+    def request(method:, params: nil)
+      request_body = {
+        jsonrpc: JsonRpcHandler::Version::V2_0,
+        id: request_id,
+        method: method,
+      }
+      request_body[:params] = params if params
+
+      response = transport.send_request(request: request_body)
+
+      # Guard with `is_a?(Hash)` because custom transports may return non-Hash values.
+      if response.is_a?(Hash) && response.key?("error")
+        error = response["error"]
+        raise ServerError.new(error["message"], code: error["code"], data: error["data"])
       end
+
+      response
+    end
+
+    def request_id
+      SecureRandom.uuid
     end
   end
 end

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