mcp 0.13.0 → 0.15.0

data/lib/mcp/client/http.rb

@@ -1,25 +1,134 @@
 # frozen_string_literal: true
 
+require "securerandom"
+require_relative "../../json_rpc_handler"
+require_relative "../configuration"
+require_relative "../methods"
+require_relative "../version"
+
 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, :server_info
 
       def initialize(url:, headers: {}, &block)
         @url = url
         @headers = headers
         @faraday_customizer = block
+        @session_id = nil
+        @protocol_version = nil
+        @server_info = nil
+        @connected = false
+      end
+
+      # Performs the MCP `initialize` handshake: sends an `initialize` request
+      # followed by the required `notifications/initialized` notification. The
+      # server's `InitializeResult` (protocol version, capabilities, server
+      # info, instructions) is cached on the transport and returned.
+      #
+      # Idempotent: a second call returns the cached `InitializeResult` without
+      # contacting the server. After `close`, state is cleared and `connect`
+      # will handshake again.
+      #
+      # @param client_info [Hash, nil] `{ name:, version: }` identifying the client.
+      #   Defaults to `{ name: "mcp-ruby-client", version: MCP::VERSION }`.
+      # @param protocol_version [String, nil] Protocol version to offer. Defaults
+      #   to `MCP::Configuration::LATEST_STABLE_PROTOCOL_VERSION`.
+      # @param capabilities [Hash] Capabilities advertised by the client. Defaults to `{}`.
+      # @return [Hash] The server's `InitializeResult`.
+      # @raise [RequestHandlerError] If the server responds with a JSON-RPC error
+      #   or a malformed result.
+      # https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#initialization
+      def connect(client_info: nil, protocol_version: nil, capabilities: {})
+        return @server_info if connected?
+
+        client_info ||= { name: "mcp-ruby-client", version: MCP::VERSION }
+        protocol_version ||= MCP::Configuration::LATEST_STABLE_PROTOCOL_VERSION
+
+        response = send_request(request: {
+          jsonrpc: JsonRpcHandler::Version::V2_0,
+          id: SecureRandom.uuid,
+          method: MCP::Methods::INITIALIZE,
+          params: {
+            protocolVersion: protocol_version,
+            capabilities: capabilities,
+            clientInfo: client_info,
+          },
+        })
+
+        if response.is_a?(Hash) && response.key?("error")
+          clear_session
+          error = response["error"]
+          raise RequestHandlerError.new(
+            "Server initialization failed: #{error["message"]}",
+            { method: MCP::Methods::INITIALIZE },
+            error_type: :internal_error,
+          )
+        end
+
+        unless response.is_a?(Hash) && response["result"].is_a?(Hash)
+          clear_session
+          raise RequestHandlerError.new(
+            "Server initialization failed: missing result in response",
+            { method: MCP::Methods::INITIALIZE },
+            error_type: :internal_error,
+          )
+        end
+
+        @server_info = response["result"]
+        negotiated_protocol_version = @server_info["protocolVersion"]
+        unless MCP::Configuration::SUPPORTED_STABLE_PROTOCOL_VERSIONS.include?(negotiated_protocol_version)
+          clear_session
+          raise RequestHandlerError.new(
+            "Server initialization failed: unsupported protocol version #{negotiated_protocol_version.inspect}",
+            { method: MCP::Methods::INITIALIZE },
+            error_type: :internal_error,
+          )
+        end
+
+        begin
+          send_request(request: {
+            jsonrpc: JsonRpcHandler::Version::V2_0,
+            method: MCP::Methods::NOTIFICATIONS_INITIALIZED,
+          })
+        rescue StandardError
+          clear_session
+          raise
+        end
+
+        @connected = true
+        @server_info
+      end
+
+      # Returns true once `connect` has completed the full handshake
+      # (`initialize` response received and `notifications/initialized` sent).
+      # Returns false before the first handshake and after `close`.
+      def connected?
+        @connected
       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 +151,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 +186,31 @@ 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
+        unless @session_id
+          clear_session
+          return
+        end
+
+        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 +231,33 @@ 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
+        @server_info = nil
+        @connected = false
+      end
+
       def require_faraday!
         require "faraday"
       rescue LoadError
@@ -92,14 +266,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/stdio.rb

@@ -19,7 +19,7 @@ module MCP
       CLOSE_TIMEOUT = 2
       STDERR_READ_SIZE = 4096
 
-      attr_reader :command, :args, :env
+      attr_reader :command, :args, :env, :server_info
 
       def initialize(command:, args: [], env: nil, read_timeout: nil)
         @command = command
@@ -33,11 +33,108 @@ module MCP
         @stderr_thread = nil
         @started = false
         @initialized = false
+        @server_info = nil
+      end
+
+      # Performs the MCP `initialize` handshake: sends an `initialize` request
+      # followed by the required `notifications/initialized` notification. The
+      # server's `InitializeResult` (protocol version, capabilities, server
+      # info, instructions) is cached on the transport and returned.
+      #
+      # Idempotent: a second call returns the cached `InitializeResult` without
+      # contacting the server. After `close`, state is cleared and `connect`
+      # will handshake again. Spawns the subprocess via `start` if it has not
+      # been started yet.
+      #
+      # @param client_info [Hash, nil] `{ name:, version: }` identifying the client.
+      #   Defaults to `{ name: "mcp-ruby-client", version: MCP::VERSION }`.
+      # @param protocol_version [String, nil] Protocol version to offer. Defaults
+      #   to `MCP::Configuration::LATEST_STABLE_PROTOCOL_VERSION`.
+      # @param capabilities [Hash] Capabilities advertised by the client. Defaults to `{}`.
+      # @return [Hash] The server's `InitializeResult`.
+      # @raise [RequestHandlerError] If the server responds with a JSON-RPC error,
+      #   a malformed result, or an unsupported protocol version.
+      # https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#initialization
+      def connect(client_info: nil, protocol_version: nil, capabilities: {})
+        return @server_info if @initialized
+
+        start unless @started
+
+        client_info ||= { name: "mcp-ruby-client", version: MCP::VERSION }
+        protocol_version ||= MCP::Configuration::LATEST_STABLE_PROTOCOL_VERSION
+
+        init_request = {
+          jsonrpc: JsonRpcHandler::Version::V2_0,
+          id: SecureRandom.uuid,
+          method: MCP::Methods::INITIALIZE,
+          params: {
+            protocolVersion: protocol_version,
+            capabilities: capabilities,
+            clientInfo: client_info,
+          },
+        }
+
+        write_message(init_request)
+        response = read_response(init_request)
+
+        if response.key?("error")
+          error = response["error"]
+          raise RequestHandlerError.new(
+            "Server initialization failed: #{error["message"]}",
+            { method: MCP::Methods::INITIALIZE },
+            error_type: :internal_error,
+          )
+        end
+
+        unless response["result"].is_a?(Hash)
+          raise RequestHandlerError.new(
+            "Server initialization failed: missing result in response",
+            { method: MCP::Methods::INITIALIZE },
+            error_type: :internal_error,
+          )
+        end
+
+        @server_info = response["result"]
+
+        negotiated_protocol_version = @server_info["protocolVersion"]
+        unless MCP::Configuration::SUPPORTED_STABLE_PROTOCOL_VERSIONS.include?(negotiated_protocol_version)
+          # Per spec, if the client does not support the server's returned protocol version,
+          # the client SHOULD disconnect. Roll back the cached `InitializeResult` before
+          # raising so a retry starts without a stale `server_info`.
+          # https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#version-negotiation
+          @server_info = nil
+          raise RequestHandlerError.new(
+            "Server initialization failed: unsupported protocol version #{negotiated_protocol_version.inspect}",
+            { method: MCP::Methods::INITIALIZE },
+            error_type: :internal_error,
+          )
+        end
+
+        begin
+          notification = {
+            jsonrpc: JsonRpcHandler::Version::V2_0,
+            method: MCP::Methods::NOTIFICATIONS_INITIALIZED,
+          }
+          write_message(notification)
+        rescue StandardError
+          @server_info = nil
+          raise
+        end
+
+        @initialized = true
+        @server_info
+      end
+
+      # Returns true once `connect` (or the implicit handshake on the first
+      # `send_request`) has completed. Returns false before the handshake
+      # and after `close`.
+      def connected?
+        @initialized
       end
 
       def send_request(request:)
         start unless @started
-        initialize_session unless @initialized
+        connect unless @initialized
 
         write_message(request)
         read_response(request)
@@ -98,57 +195,11 @@ module MCP
         @stderr_thread.join(CLOSE_TIMEOUT)
         @started = false
         @initialized = false
+        @server_info = nil
       end
 
       private
 
-      # The client MUST send a protocol version it supports. This SHOULD be the latest version.
-      # https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#version-negotiation
-      #
-      # Always sends `LATEST_STABLE_PROTOCOL_VERSION`, matching the Python and TypeScript SDKs:
-      # https://github.com/modelcontextprotocol/python-sdk/blob/v1.26.0/src/mcp/client/session.py#L175
-      # https://github.com/modelcontextprotocol/typescript-sdk/blob/v1.27.1/src/client/index.ts#L495
-      def initialize_session
-        init_request = {
-          jsonrpc: JsonRpcHandler::Version::V2_0,
-          id: SecureRandom.uuid,
-          method: MCP::Methods::INITIALIZE,
-          params: {
-            protocolVersion: MCP::Configuration::LATEST_STABLE_PROTOCOL_VERSION,
-            capabilities: {},
-            clientInfo: { name: "mcp-ruby-client", version: MCP::VERSION },
-          },
-        }
-
-        write_message(init_request)
-        response = read_response(init_request)
-
-        if response.key?("error")
-          error = response["error"]
-          raise RequestHandlerError.new(
-            "Server initialization failed: #{error["message"]}",
-            { method: MCP::Methods::INITIALIZE },
-            error_type: :internal_error,
-          )
-        end
-
-        unless response.key?("result")
-          raise RequestHandlerError.new(
-            "Server initialization failed: missing result in response",
-            { method: MCP::Methods::INITIALIZE },
-            error_type: :internal_error,
-          )
-        end
-
-        notification = {
-          jsonrpc: JsonRpcHandler::Version::V2_0,
-          method: MCP::Methods::NOTIFICATIONS_INITIALIZED,
-        }
-        write_message(notification)
-
-        @initialized = true
-      end
-
       def write_message(message)
         ensure_running!
         json = JSON.generate(message)