mcp 0.12.0 → 0.14.0

data/lib/json_rpc_handler.rb

@@ -117,20 +117,27 @@ module JsonRpcHandler
   end
 
   def handle_request_error(error, id, id_validation_pattern)
-    error_type = error.respond_to?(:error_type) ? error.error_type : nil
-
-    code, message = case error_type
-    when :invalid_request then [ErrorCode::INVALID_REQUEST, "Invalid Request"]
-    when :invalid_params then [ErrorCode::INVALID_PARAMS, "Invalid params"]
-    when :parse_error then [ErrorCode::PARSE_ERROR, "Parse error"]
-    when :internal_error then [ErrorCode::INTERNAL_ERROR, "Internal error"]
-    else [ErrorCode::INTERNAL_ERROR, "Internal error"]
+    if error.respond_to?(:error_code) && error.error_code
+      code = error.error_code
+      message = error.message
+    else
+      error_type = error.respond_to?(:error_type) ? error.error_type : nil
+
+      code, message = case error_type
+      when :invalid_request then [ErrorCode::INVALID_REQUEST, "Invalid Request"]
+      when :invalid_params then [ErrorCode::INVALID_PARAMS, "Invalid params"]
+      when :parse_error then [ErrorCode::PARSE_ERROR, "Parse error"]
+      when :internal_error then [ErrorCode::INTERNAL_ERROR, "Internal error"]
+      else [ErrorCode::INTERNAL_ERROR, "Internal error"]
+      end
     end
 
+    data = error.respond_to?(:error_data) && error.error_data ? error.error_data : error.message
+
     error_response(id: id, id_validation_pattern: id_validation_pattern, error: {
       code: code,
       message: message,
-      data: error.message,
+      data: data,
     })
   end
 

data/lib/mcp/client/http.rb

@@ -1,25 +1,42 @@
 # frozen_string_literal: true
 
+require_relative "../methods"
+
 module MCP
   class Client
+    # TODO: HTTP GET for SSE streaming is not yet implemented.
+    #   https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#listening-for-messages-from-the-server
+    # TODO: Resumability and redelivery with Last-Event-ID is not yet implemented.
+    #   https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#resumability-and-redelivery
     class HTTP
       ACCEPT_HEADER = "application/json, text/event-stream"
+      SESSION_ID_HEADER = "Mcp-Session-Id"
+      PROTOCOL_VERSION_HEADER = "MCP-Protocol-Version"
 
-      attr_reader :url
+      attr_reader :url, :session_id, :protocol_version
 
       def initialize(url:, headers: {}, &block)
         @url = url
         @headers = headers
         @faraday_customizer = block
+        @session_id = nil
+        @protocol_version = nil
       end
 
+      # Sends a JSON-RPC request and returns the parsed response body.
+      # After a successful `initialize` handshake, the session ID and protocol
+      # version returned by the server are captured and automatically included
+      # on subsequent requests.
       def send_request(request:)
         method = request[:method] || request["method"]
         params = request[:params] || request["params"]
 
-        response = client.post("", request)
-        validate_response_content_type!(response, method, params)
-        response.body
+        response = client.post("", request, session_headers)
+        body = parse_response_body(response, method, params)
+
+        capture_session_info(method, response, body)
+
+        body
       rescue Faraday::BadRequestError => e
         raise RequestHandlerError.new(
           "The #{method} request is invalid",
@@ -42,12 +59,25 @@ module MCP
           original_error: e,
         )
       rescue Faraday::ResourceNotFound => e
-        raise RequestHandlerError.new(
-          "The #{method} request is not found",
-          { method: method, params: params },
-          error_type: :not_found,
-          original_error: e,
-        )
+        # Per spec, 404 is the session-expired signal only when the request
+        # actually carried an `Mcp-Session-Id`. A 404 without a session attached
+        # (e.g. wrong URL or a stateless server) surfaces as a generic not-found.
+        # https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management
+        if @session_id
+          clear_session
+          raise SessionExpiredError.new(
+            "The #{method} request is not found",
+            { method: method, params: params },
+            original_error: e,
+          )
+        else
+          raise RequestHandlerError.new(
+            "The #{method} request is not found",
+            { method: method, params: params },
+            error_type: :not_found,
+            original_error: e,
+          )
+        end
       rescue Faraday::UnprocessableEntityError => e
         raise RequestHandlerError.new(
           "The #{method} request is unprocessable",
@@ -64,6 +94,28 @@ module MCP
         )
       end
 
+      # Terminates the session by sending an HTTP DELETE to the MCP endpoint
+      # with the current `Mcp-Session-Id` header, and clears locally tracked
+      # session state afterward. No-op when no session has been established.
+      #
+      # Per spec, the server MAY respond with HTTP 405 Method Not Allowed when
+      # it does not support client-initiated termination, and returns 404 for
+      # a session it has already terminated. Both mean the session is gone —
+      # the desired end state. Other errors surface to the caller; local
+      # session state is cleared either way.
+      # https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management
+      def close
+        return unless @session_id
+
+        begin
+          client.delete("", nil, session_headers)
+        rescue Faraday::ClientError => e
+          raise unless [404, 405].include?(e.response&.dig(:status))
+        ensure
+          clear_session
+        end
+      end
+
       private
 
       attr_reader :headers
@@ -84,6 +136,31 @@ module MCP
         end
       end
 
+      # Per spec, the client MUST include `MCP-Session-Id` (when the server assigned one)
+      # and `MCP-Protocol-Version` on all requests after `initialize`.
+      # https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management
+      # https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#protocol-version-header
+      def session_headers
+        request_headers = {}
+        request_headers[SESSION_ID_HEADER] = @session_id if @session_id
+        request_headers[PROTOCOL_VERSION_HEADER] = @protocol_version if @protocol_version
+        request_headers
+      end
+
+      def capture_session_info(method, response, body)
+        return unless method.to_s == Methods::INITIALIZE
+
+        # Faraday normalizes header names to lowercase.
+        session_id = response.headers[SESSION_ID_HEADER.downcase]
+        @session_id ||= session_id unless session_id.to_s.empty?
+        @protocol_version ||= body.is_a?(Hash) ? body.dig("result", "protocolVersion") : nil
+      end
+
+      def clear_session
+        @session_id = nil
+        @protocol_version = nil
+      end
+
       def require_faraday!
         require "faraday"
       rescue LoadError
@@ -92,14 +169,56 @@ module MCP
           "See https://rubygems.org/gems/faraday for more details."
       end
 
-      def validate_response_content_type!(response, method, params)
+      def require_event_stream_parser!
+        require "event_stream_parser"
+      rescue LoadError
+        raise LoadError, "The 'event_stream_parser' gem is required to parse SSE responses. " \
+          "Add it to your Gemfile: gem 'event_stream_parser', '>= 1.0'. " \
+          "See https://rubygems.org/gems/event_stream_parser for more details."
+      end
+
+      def parse_response_body(response, method, params)
+        # 202 Accepted is the server's ACK for a JSON-RPC notification or response; no body is expected.
+        # https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#sending-messages-to-the-server
+        return if response.status == 202
+
         content_type = response.headers["Content-Type"]
-        return if content_type&.include?("application/json")
+
+        if content_type&.include?("text/event-stream")
+          parse_sse_response(response.body, method, params)
+        elsif content_type&.include?("application/json")
+          response.body
+        else
+          raise RequestHandlerError.new(
+            "Unsupported Content-Type: #{content_type.inspect}. Expected application/json or text/event-stream.",
+            { method: method, params: params },
+            error_type: :unsupported_media_type,
+          )
+        end
+      end
+
+      def parse_sse_response(body, method, params)
+        require_event_stream_parser!
+
+        json_rpc_response = nil
+        parser = EventStreamParser::Parser.new
+        parser.feed(body.to_s) do |_type, data, _id|
+          next if data.empty?
+
+          begin
+            parsed = JSON.parse(data)
+            json_rpc_response = parsed if parsed.is_a?(Hash) && (parsed.key?("result") || parsed.key?("error"))
+          rescue JSON::ParserError
+            next
+          end
+        end
+
+        return json_rpc_response if json_rpc_response
 
         raise RequestHandlerError.new(
-          "Unsupported Content-Type: #{content_type.inspect}. This client only supports JSON responses.",
+          "No valid JSON-RPC response found in SSE stream",
           { method: method, params: params },
-          error_type: :unsupported_media_type,
+          error_type: :parse_error,
         )
       end
     end

data/lib/mcp/client/paginated_result.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module MCP
+  class Client
+    # Result objects returned by `list_tools`, `list_prompts`, `list_resources`, and `list_resource_templates`.
+    # Each carries the page items, an optional opaque `next_cursor` string for continuing pagination,
+    # and an optional `meta` hash mirroring the MCP `_meta` response field.
+    ListToolsResult = Struct.new(:tools, :next_cursor, :meta, keyword_init: true)
+    ListPromptsResult = Struct.new(:prompts, :next_cursor, :meta, keyword_init: true)
+    ListResourcesResult = Struct.new(:resources, :next_cursor, :meta, keyword_init: true)
+    ListResourceTemplatesResult = Struct.new(:resource_templates, :next_cursor, :meta, keyword_init: true)
+  end
+end

data/lib/mcp/client.rb

@@ -2,6 +2,7 @@
 
 require_relative "client/stdio"
 require_relative "client/http"
+require_relative "client/paginated_result"
 require_relative "client/tool"
 
 module MCP
@@ -27,6 +28,21 @@ module MCP
       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.
@@ -43,8 +59,41 @@ 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.
+    # 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.
     #
@@ -54,45 +103,151 @@ module MCP
     #     puts tool.name
     #   end
     def tools
-      response = request(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 = request(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
 
-      response.dig("result", "resources") || []
+    # 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"] || {}
+
+      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 = request(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 = request(method: "prompts/list")
+      # TODO: consider renaming to `list_all_prompts`.
+      all_prompts = []
+      seen = Set.new
+      cursor = nil
+
+      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
 
-      response.dig("result", "prompts") || []
+      all_prompts
     end
 
     # Calls a tool via the transport layer and returns the full response from the server.
@@ -163,6 +318,24 @@ module MCP
       response.dig("result", "completion") || { "values" => [], "hasMore" => false }
     end
 
+    # 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)
+
+      result
+    end
+
     private
 
     def request(method:, params: nil)

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