ruby-mcp-client 0.6.0 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6607aff3aa197734ac1b5fd4c2f51bb994df18ffcb0f18928c4f75197aaa8ed
-  data.tar.gz: 6921d74355c4497ca944374795469a767873ff8716e54fedbe3438104a4e5b79
+  metadata.gz: 15f194d4e1504310a998aeeb819e5851dea4f1f8049bf494368ad5494e611d3c
+  data.tar.gz: 93d8d00a95ab2436241b09253d7bb56d130122303c1e78c429cecc343d09fa82
 SHA512:
-  metadata.gz: cea51f3ff6046ac619197413ccbe50a18fc3aeef6f881180d9cc5b0ad49b67d1cbe93459005f93f3063ad2dfe699c06bb1556180dc3bd1437d67e38b89549c9a
-  data.tar.gz: 8de670f6d7f3fd5a3c9786365e19034ee6d8734ef8d938769818acb606c8f7c13529b8777cdff2a54483398d52dd7847ccddc957a8a4517c16ad31a1b35700b0
+  metadata.gz: f7edb3c0ae40b647c03d3a70af06e08b7d1290de0326fcf34b668b08f1fb156692799e1280f4a3a17c44b9afdb18b456d949a1cc39edec396877a25a00290c8f
+  data.tar.gz: a169f6e4f24c9f1f4ed52e7853f00285565cfcd2aa2d8fe6049c10191dd2fcbf571c8468dea65bf6504175f1ca1ce402ad9d7353660888db2f96e57831056598

data/lib/mcp_client/json_rpc_common.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module MCPClient
+  # Shared retry/backoff logic for JSON-RPC transports
+  module JsonRpcCommon
+    # Execute the block with retry/backoff for transient errors
+    # @yield block to execute
+    # @return [Object] result of block
+    # @raise original exception if max retries exceeded
+    def with_retry
+      attempts = 0
+      begin
+        yield
+      rescue MCPClient::Errors::ServerError, MCPClient::Errors::TransportError, IOError, Errno::ETIMEDOUT,
+             Errno::ECONNRESET => e
+        attempts += 1
+        if attempts <= @max_retries
+          delay = @retry_backoff * (2**(attempts - 1))
+          @logger.debug("Retry attempt #{attempts} after error: #{e.message}, sleeping #{delay}s")
+          sleep(delay)
+          retry
+        end
+        raise
+      end
+    end
+
+    # Ping the server to keep the connection alive
+    # @return [Hash] the result of the ping request
+    # @raise [MCPClient::Errors::ToolCallError] if ping times out or fails
+    # @raise [MCPClient::Errors::TransportError] if there's a connection error
+    # @raise [MCPClient::Errors::ServerError] if the server returns an error
+    def ping
+      rpc_request('ping')
+    end
+
+    # Build a JSON-RPC request object
+    # @param method [String] JSON-RPC method name
+    # @param params [Hash] parameters for the request
+    # @param id [Integer] request ID
+    # @return [Hash] the JSON-RPC request object
+    def build_jsonrpc_request(method, params, id)
+      {
+        jsonrpc: '2.0',
+        id: id,
+        method: method,
+        params: params
+      }
+    end
+
+    # Build a JSON-RPC notification object (no response expected)
+    # @param method [String] JSON-RPC method name
+    # @param params [Hash] parameters for the notification
+    # @return [Hash] the JSON-RPC notification object
+    def build_jsonrpc_notification(method, params)
+      {
+        jsonrpc: '2.0',
+        method: method,
+        params: params
+      }
+    end
+
+    # Generate initialization parameters for MCP protocol
+    # @return [Hash] the initialization parameters
+    def initialization_params
+      {
+        'protocolVersion' => MCPClient::PROTOCOL_VERSION,
+        'capabilities' => {},
+        'clientInfo' => { 'name' => 'ruby-mcp-client', 'version' => MCPClient::VERSION }
+      }
+    end
+
+    # Process JSON-RPC response
+    # @param response [Hash] the parsed JSON-RPC response
+    # @return [Object] the result field from the response
+    # @raise [MCPClient::Errors::ServerError] if the response contains an error
+    def process_jsonrpc_response(response)
+      if (err = response['error'])
+        raise MCPClient::Errors::ServerError, err['message']
+      end
+
+      response['result']
+    end
+  end
+end

data/lib/mcp_client/server_factory.rb

@@ -8,30 +8,64 @@ module MCPClient
     # @param logger [Logger, nil] optional logger to use for the server
     # @return [MCPClient::ServerBase] server instance
     def self.create(config, logger: nil)
+      logger_to_use = config[:logger] || logger
+
       case config[:type]
       when 'stdio'
-        MCPClient::ServerStdio.new(
-          command: config[:command],
-          retries: config[:retries] || 0,
-          retry_backoff: config[:retry_backoff] || 1,
-          read_timeout: config[:read_timeout] || MCPClient::ServerStdio::READ_TIMEOUT,
-          name: config[:name],
-          logger: config[:logger] || logger
-        )
+        create_stdio_server(config, logger_to_use)
       when 'sse'
-        MCPClient::ServerSSE.new(
-          base_url: config[:base_url],
-          headers: config[:headers] || {},
-          read_timeout: config[:read_timeout] || 30,
-          ping: config[:ping] || 10,
-          retries: config[:retries] || 0,
-          retry_backoff: config[:retry_backoff] || 1,
-          name: config[:name],
-          logger: config[:logger] || logger
-        )
+        create_sse_server(config, logger_to_use)
       else
         raise ArgumentError, "Unknown server type: #{config[:type]}"
       end
     end
+
+    # Create a stdio-based server
+    # @param config [Hash] server configuration
+    # @param logger [Logger, nil] logger to use
+    # @return [MCPClient::ServerStdio] server instance
+    def self.create_stdio_server(config, logger)
+      cmd = prepare_command(config)
+
+      MCPClient::ServerStdio.new(
+        command: cmd,
+        retries: config[:retries] || 0,
+        retry_backoff: config[:retry_backoff] || 1,
+        read_timeout: config[:read_timeout] || MCPClient::ServerStdio::READ_TIMEOUT,
+        name: config[:name],
+        logger: logger,
+        env: config[:env] || {}
+      )
+    end
+
+    # Create an SSE-based server
+    # @param config [Hash] server configuration
+    # @param logger [Logger, nil] logger to use
+    # @return [MCPClient::ServerSSE] server instance
+    def self.create_sse_server(config, logger)
+      # Handle both :url and :base_url (config parser uses :url)
+      base_url = config[:base_url] || config[:url]
+      MCPClient::ServerSSE.new(
+        base_url: base_url,
+        headers: config[:headers] || {},
+        read_timeout: config[:read_timeout] || 30,
+        ping: config[:ping] || 10,
+        retries: config[:retries] || 0,
+        retry_backoff: config[:retry_backoff] || 1,
+        name: config[:name],
+        logger: logger
+      )
+    end
+
+    # Prepare command by combining command and args
+    # @param config [Hash] server configuration
+    # @return [String, Array] prepared command
+    def self.prepare_command(config)
+      if config[:args] && !config[:args].empty?
+        [config[:command]] + Array(config[:args])
+      else
+        config[:command]
+      end
+    end
   end
 end

data/lib/mcp_client/server_sse/json_rpc_transport.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require 'mcp_client/json_rpc_common'
+
+module MCPClient
+  class ServerSSE
+    # JSON-RPC request/notification plumbing for SSE transport
+    module JsonRpcTransport
+      include JsonRpcCommon
+      # Generic JSON-RPC request: send method with params and return result
+      # @param method [String] JSON-RPC method name
+      # @param params [Hash] parameters for the request
+      # @return [Object] result from JSON-RPC response
+      # @raise [MCPClient::Errors::ConnectionError] if connection is not active or reconnect fails
+      # @raise [MCPClient::Errors::ServerError] if server returns an error
+      # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
+      # @raise [MCPClient::Errors::ToolCallError] for other errors during request execution
+      def rpc_request(method, params = {})
+        ensure_initialized
+
+        with_retry do
+          request_id = @mutex.synchronize { @request_id += 1 }
+          request = build_jsonrpc_request(method, params, request_id)
+          send_jsonrpc_request(request)
+        end
+      end
+
+      # Send a JSON-RPC notification (no response expected)
+      # @param method [String] JSON-RPC method name
+      # @param params [Hash] parameters for the notification
+      # @return [void]
+      def rpc_notify(method, params = {})
+        ensure_initialized
+        notif = build_jsonrpc_notification(method, params)
+        post_json_rpc_request(notif)
+      rescue MCPClient::Errors::ServerError, MCPClient::Errors::ConnectionError, Faraday::ConnectionFailed => e
+        raise MCPClient::Errors::TransportError, "Failed to send notification: #{e.message}"
+      end
+
+      private
+
+      # Ensure SSE initialization handshake has been performed.
+      # Attempts to reconnect and reinitialize if the SSE connection is not active.
+      #
+      # @raise [MCPClient::Errors::ConnectionError] if reconnect or initialization fails
+      def ensure_initialized
+        if !@connection_established || !@sse_connected
+          @logger.debug('Connection not active, attempting to reconnect before RPC request')
+          cleanup
+          connect
+          perform_initialize
+          @initialized = true
+          return
+        end
+
+        return if @initialized
+
+        perform_initialize
+        @initialized = true
+      end
+
+      # Perform JSON-RPC initialize handshake with the MCP server
+      # @return [void]
+      def perform_initialize
+        request_id = @mutex.synchronize { @request_id += 1 }
+        json_rpc_request = build_jsonrpc_request('initialize', initialization_params, request_id)
+        @logger.debug("Performing initialize RPC: #{json_rpc_request}")
+        result = send_jsonrpc_request(json_rpc_request)
+        return unless result.is_a?(Hash)
+
+        @server_info = result['serverInfo'] if result.key?('serverInfo')
+        @capabilities = result['capabilities'] if result.key?('capabilities')
+      end
+
+      # Send a JSON-RPC request to the server and wait for result
+      # @param request [Hash] the JSON-RPC request
+      # @return [Hash] the result of the request
+      # @raise [MCPClient::Errors::ConnectionError] if connection fails
+      # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
+      # @raise [MCPClient::Errors::ToolCallError] for other errors during request execution
+      def send_jsonrpc_request(request)
+        @logger.debug("Sending JSON-RPC request: #{request.to_json}")
+        record_activity
+
+        begin
+          response = post_json_rpc_request(request)
+
+          if @use_sse
+            wait_for_sse_result(request)
+          else
+            parse_direct_response(response)
+          end
+        rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+          raise
+        rescue JSON::ParserError => e
+          raise MCPClient::Errors::TransportError, "Invalid JSON response from server: #{e.message}"
+        rescue Errno::ECONNREFUSED => e
+          raise MCPClient::Errors::ConnectionError, "Server connection lost: #{e.message}"
+        rescue StandardError => e
+          method_name = request[:method] || request['method']
+          raise MCPClient::Errors::ToolCallError, "Error executing request '#{method_name}': #{e.message}"
+        end
+      end
+
+      # Post a JSON-RPC request to the server
+      # @param request [Hash] the JSON-RPC request
+      # @return [Faraday::Response] the HTTP response
+      # @raise [MCPClient::Errors::ConnectionError] if connection fails
+      def post_json_rpc_request(request)
+        uri = URI.parse(@base_url)
+        base = "#{uri.scheme}://#{uri.host}:#{uri.port}"
+        rpc_ep = @mutex.synchronize { @rpc_endpoint }
+
+        @rpc_conn ||= create_json_rpc_connection(base)
+
+        begin
+          response = send_http_request(@rpc_conn, rpc_ep, request)
+          record_activity
+
+          unless response.success?
+            raise MCPClient::Errors::ServerError, "Server returned error: #{response.status} #{response.reason_phrase}"
+          end
+
+          response
+        rescue Faraday::ConnectionFailed => e
+          raise MCPClient::Errors::ConnectionError, "Server connection lost: #{e.message}"
+        end
+      end
+
+      # Create a Faraday connection for JSON-RPC
+      # @param base_url [String] the base URL for the connection
+      # @return [Faraday::Connection] the configured connection
+      def create_json_rpc_connection(base_url)
+        Faraday.new(url: base_url) do |f|
+          f.request :retry, max: @max_retries, interval: @retry_backoff, backoff_factor: 2
+          f.options.open_timeout = @read_timeout
+          f.options.timeout = @read_timeout
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+      # Send an HTTP request with the proper headers and body
+      # @param conn [Faraday::Connection] the connection to use
+      # @param endpoint [String] the endpoint to post to
+      # @param request [Hash] the request data
+      # @return [Faraday::Response] the HTTP response
+      def send_http_request(conn, endpoint, request)
+        response = conn.post(endpoint) do |req|
+          req.headers['Content-Type'] = 'application/json'
+          req.headers['Accept'] = 'application/json'
+          (@headers.dup.tap do |h|
+            h.delete('Accept')
+            h.delete('Cache-Control')
+          end).each { |k, v| req.headers[k] = v }
+          req.body = request.to_json
+        end
+
+        msg = "Received JSON-RPC response: #{response.status}"
+        msg += " #{response.body}" if response.respond_to?(:body)
+        @logger.debug(msg)
+        response
+      end
+
+      # Wait for an SSE result to arrive
+      # @param request [Hash] the original JSON-RPC request
+      # @return [Hash] the result data
+      # @raise [MCPClient::Errors::ConnectionError, MCPClient::Errors::ToolCallError] on errors
+      def wait_for_sse_result(request)
+        request_id = request[:id]
+        start_time = Time.now
+        timeout = @read_timeout || 10
+
+        ensure_sse_connection_active
+
+        wait_for_result_with_timeout(request_id, start_time, timeout)
+      end
+
+      # Ensure the SSE connection is active, reconnect if needed
+      def ensure_sse_connection_active
+        return if connection_active?
+
+        @logger.warn('SSE connection is not active, reconnecting before waiting for result')
+        begin
+          cleanup
+          connect
+        rescue MCPClient::Errors::ConnectionError => e
+          raise MCPClient::Errors::ConnectionError, "Failed to reconnect SSE for result: #{e.message}"
+        end
+      end
+
+      # Wait for a result with timeout
+      # @param request_id [Integer] the request ID to wait for
+      # @param start_time [Time] when the wait started
+      # @param timeout [Integer] the timeout in seconds
+      # @return [Hash] the result when available
+      # @raise [MCPClient::Errors::ConnectionError, MCPClient::Errors::ToolCallError] on errors
+      def wait_for_result_with_timeout(request_id, start_time, timeout)
+        loop do
+          result = check_for_result(request_id)
+          return result if result
+
+          unless connection_active?
+            raise MCPClient::Errors::ConnectionError,
+                  'SSE connection lost while waiting for result'
+          end
+
+          time_elapsed = Time.now - start_time
+          break if time_elapsed > timeout
+
+          sleep 0.1
+        end
+
+        raise MCPClient::Errors::ToolCallError, "Timeout waiting for SSE result for request #{request_id}"
+      end
+
+      # Check if a result is available for the given request ID
+      # @param request_id [Integer] the request ID to check
+      # @return [Hash, nil] the result if available, nil otherwise
+      def check_for_result(request_id)
+        result = nil
+        @mutex.synchronize do
+          result = @sse_results.delete(request_id) if @sse_results.key?(request_id)
+        end
+
+        if result
+          record_activity
+          return result
+        end
+
+        nil
+      end
+
+      # Parse a direct (non-SSE) JSON-RPC response
+      # @param response [Faraday::Response] the HTTP response
+      # @return [Hash] the parsed result
+      # @raise [MCPClient::Errors::TransportError] if parsing fails
+      # @raise [MCPClient::Errors::ServerError] if the response contains an error
+      def parse_direct_response(response)
+        data = JSON.parse(response.body)
+        process_jsonrpc_response(data)
+      rescue JSON::ParserError => e
+        raise MCPClient::Errors::TransportError, "Invalid JSON response from server: #{e.message}"
+      end
+    end
+  end
+end

data/lib/mcp_client/server_sse/reconnect_monitor.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module MCPClient
+  class ServerSSE
+    # Extracted module for back-off, ping, and reconnection logic
+    module ReconnectMonitor
+      # Start an activity monitor thread to maintain the connection
+      # @return [void]
+      def start_activity_monitor
+        return if @activity_timer_thread&.alive?
+
+        @mutex.synchronize do
+          @last_activity_time = Time.now
+          @consecutive_ping_failures = 0
+          @max_ping_failures = DEFAULT_MAX_PING_FAILURES
+          @reconnect_attempts = 0
+          @max_reconnect_attempts = DEFAULT_MAX_RECONNECT_ATTEMPTS
+        end
+
+        @activity_timer_thread = Thread.new do
+          activity_monitor_loop
+        rescue StandardError => e
+          @logger.error("Activity monitor error: #{e.message}")
+        end
+      end
+
+      # Check if the connection is currently active
+      # @return [Boolean] true if connection is established and SSE is connected
+      def connection_active?
+        @mutex.synchronize { @connection_established && @sse_connected }
+      end
+
+      # Main loop for the activity monitor thread
+      # @return [void]
+      # @private
+      def activity_monitor_loop
+        loop do
+          sleep 1
+
+          unless connection_active?
+            @logger.debug('Activity monitor exiting: connection no longer active')
+            return
+          end
+
+          @mutex.synchronize do
+            @consecutive_ping_failures ||= 0
+            @reconnect_attempts ||= 0
+            @max_ping_failures ||= DEFAULT_MAX_PING_FAILURES
+            @max_reconnect_attempts ||= DEFAULT_MAX_RECONNECT_ATTEMPTS
+          end
+
+          return unless connection_active?
+
+          time_since_activity = Time.now - @last_activity_time
+
+          if @close_after && time_since_activity >= @close_after
+            @logger.info("Closing connection due to inactivity (#{time_since_activity.round(1)}s)")
+            cleanup
+            return
+          end
+
+          next unless @ping_interval && time_since_activity >= @ping_interval
+          return unless connection_active?
+
+          if @consecutive_ping_failures >= @max_ping_failures
+            attempt_reconnection
+          else
+            attempt_ping
+          end
+        end
+      end
+
+      # Attempt to reconnect with exponential backoff
+      # @return [void]
+      # @private
+      def attempt_reconnection
+        if @reconnect_attempts < @max_reconnect_attempts
+          begin
+            base_delay = BASE_RECONNECT_DELAY * (2**@reconnect_attempts)
+            jitter = rand * JITTER_FACTOR * base_delay
+            backoff_delay = [base_delay + jitter, MAX_RECONNECT_DELAY].min
+
+            reconnect_msg = "Attempting to reconnect (attempt #{@reconnect_attempts + 1}/#{@max_reconnect_attempts}) "
+            reconnect_msg += "after #{@consecutive_ping_failures} consecutive ping failures. "
+            reconnect_msg += "Waiting #{backoff_delay.round(2)}s before reconnect..."
+            @logger.warn(reconnect_msg)
+            sleep(backoff_delay)
+
+            cleanup
+
+            connect
+            @logger.info('Successfully reconnected after ping failures')
+
+            @mutex.synchronize do
+              @consecutive_ping_failures = 0
+              # Reset attempt counter after a successful reconnect
+              @reconnect_attempts = 0
+              @last_activity_time = Time.now
+            end
+          rescue StandardError => e
+            @logger.error("Failed to reconnect after ping failures: #{e.message}")
+            @mutex.synchronize { @reconnect_attempts += 1 }
+          end
+        else
+          @logger.error("Exceeded maximum reconnection attempts (#{@max_reconnect_attempts}). Closing connection.")
+          cleanup
+        end
+      end
+
+      # Attempt to ping the server to check if connection is still alive
+      # @return [void]
+      # @private
+      def attempt_ping
+        unless connection_active?
+          @logger.debug('Skipping ping - connection not active')
+          return
+        end
+
+        time_since = Time.now - @last_activity_time
+        @logger.debug("Sending ping after #{time_since.round(1)}s of inactivity")
+
+        begin
+          ping
+          @mutex.synchronize do
+            @last_activity_time = Time.now
+            @consecutive_ping_failures = 0
+          end
+        rescue StandardError => e
+          unless connection_active?
+            @logger.debug("Ignoring ping failure - connection already closed: #{e.message}")
+            return
+          end
+          handle_ping_failure(e)
+        end
+      end
+
+      # Handle ping failures by incrementing a counter and logging
+      # @param error [StandardError] the error that caused the ping failure
+      # @return [void]
+      # @private
+      def handle_ping_failure(error)
+        @mutex.synchronize { @consecutive_ping_failures += 1 }
+        consecutive_failures = @consecutive_ping_failures
+
+        if consecutive_failures == 1
+          @logger.error("Error sending ping: #{error.message}")
+        else
+          error_msg = error.message.split("\n").first
+          @logger.warn("Ping failed (#{consecutive_failures}/#{@max_ping_failures}): #{error_msg}")
+        end
+      end
+
+      # Record activity to prevent unnecessary pings
+      # @return [void]
+      def record_activity
+        @mutex.synchronize { @last_activity_time = Time.now }
+      end
+
+      # Wait for the connection to be established
+      # @param timeout [Numeric] timeout in seconds
+      # @return [void]
+      # @raise [MCPClient::Errors::ConnectionError] if connection times out or fails
+      def wait_for_connection(timeout:)
+        @mutex.synchronize do
+          deadline = Time.now + timeout
+
+          until @connection_established
+            remaining = [1, deadline - Time.now].min
+            break if remaining <= 0 || @connection_cv.wait(remaining) { @connection_established }
+          end
+
+          raise MCPClient::Errors::ConnectionError, @auth_error if @auth_error
+
+          unless @connection_established
+            cleanup
+            error_msg = "Failed to connect to MCP server at #{@base_url}"
+            error_msg += ': Timed out waiting for SSE connection to be established'
+            raise MCPClient::Errors::ConnectionError, error_msg
+          end
+        end
+      end
+
+      # Setup the SSE connection with Faraday
+      # @param uri [URI] the URI to connect to
+      # @return [Faraday::Connection] the configured connection
+      # @private
+      def setup_sse_connection(uri)
+        sse_base = "#{uri.scheme}://#{uri.host}:#{uri.port}"
+
+        @sse_conn ||= Faraday.new(url: sse_base) do |f|
+          f.options.open_timeout = 10
+          f.options.timeout = nil
+          f.request :retry, max: @max_retries, interval: @retry_backoff, backoff_factor: 2
+          f.adapter Faraday.default_adapter
+        end
+
+        @sse_conn.builder.use Faraday::Response::RaiseError
+        @sse_conn
+      end
+
+      # Handle authentication errors from SSE
+      # @param error [StandardError] the authentication error
+      # @return [void]
+      # @private
+      def handle_sse_auth_error(error)
+        error_message = "Authorization failed: HTTP #{error.response[:status]}"
+        @logger.error(error_message)
+
+        @mutex.synchronize do
+          @auth_error = error_message
+          @connection_established = false
+          @connection_cv.broadcast
+        end
+      end
+
+      # Reset the connection state
+      # @return [void]
+      # @private
+      def reset_connection_state
+        @mutex.synchronize do
+          @connection_established = false
+          @connection_cv.broadcast
+        end
+      end
+    end
+  end
+end