ruby-mcp-client 0.7.2 → 0.8.0

data/lib/mcp_client/server_streamable_http.rb

@@ -9,9 +9,15 @@ require 'faraday/retry'
 require 'faraday/follow_redirects'
 
 module MCPClient
-  # Implementation of MCP server that communicates via Streamable HTTP transport
-  # This transport uses HTTP POST requests but expects Server-Sent Event formatted responses
-  # It's designed for servers that support streaming responses over HTTP
+  # Implementation of MCP server that communicates via Streamable HTTP transport (MCP 2025-03-26)
+  # This transport uses HTTP POST for RPC calls with optional SSE responses, and GET for event streams
+  # Compliant with MCP specification version 2025-03-26
+  #
+  # Key features:
+  # - Supports server-sent events (SSE) for real-time notifications
+  # - Handles ping/pong keepalive mechanism
+  # - Thread-safe connection management
+  # - Automatic reconnection with exponential backoff
   class ServerStreamableHTTP < ServerBase
     require_relative 'server_streamable_http/json_rpc_transport'
 
@@ -21,6 +27,12 @@ module MCPClient
     DEFAULT_READ_TIMEOUT = 30
     DEFAULT_MAX_RETRIES = 3
 
+    # SSE connection settings
+    SSE_CONNECTION_TIMEOUT = 300 # 5 minutes
+    SSE_RECONNECT_DELAY = 1        # Initial reconnect delay in seconds
+    SSE_MAX_RECONNECT_DELAY = 30   # Maximum reconnect delay in seconds
+    THREAD_JOIN_TIMEOUT = 5 # Timeout for thread cleanup
+
     # @!attribute [r] base_url
     #   @return [String] The base URL of the MCP server
     # @!attribute [r] endpoint
@@ -87,6 +99,10 @@ module MCPClient
       @read_timeout = opts[:read_timeout]
       @tools = nil
       @tools_data = nil
+      @prompts = nil
+      @prompts_data = nil
+      @resources = nil
+      @resources_data = nil
       @request_id = 0
       @mutex = Monitor.new
       @connection_established = false
@@ -95,6 +111,11 @@ module MCPClient
       @session_id = nil
       @last_event_id = nil
       @oauth_provider = opts[:oauth_provider]
+
+      # SSE events connection state
+      @events_connection = nil
+      @events_thread = nil
+      @buffer = '' # Buffer for partial SSE event data
     end
 
     # Connect to the MCP server over Streamable HTTP
@@ -115,6 +136,9 @@ module MCPClient
         # Perform MCP initialization handshake
         perform_initialize
 
+        # Start long-lived GET connection for server events
+        start_events_connection
+
         @mutex.synchronize do
           @connection_established = true
           @initialized = true
@@ -170,7 +194,8 @@ module MCPClient
     def call_tool(tool_name, parameters)
       rpc_request('tools/call', {
                     name: tool_name,
-                    arguments: parameters
+                    arguments: parameters.except(:_meta),
+                    **parameters.slice(:_meta)
                   })
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       # Re-raise connection/transport errors directly to match test expectations
@@ -190,6 +215,93 @@ module MCPClient
       end
     end
 
+    # List all prompts available from the MCP server
+    # @return [Array<MCPClient::Prompt>] list of available prompts
+    # @raise [MCPClient::Errors::PromptGetError] if prompts list retrieval fails
+    def list_prompts
+      @mutex.synchronize do
+        return @prompts if @prompts
+      end
+
+      begin
+        ensure_connected
+
+        prompts_data = request_prompts_list
+        @mutex.synchronize do
+          @prompts = prompts_data.map do |prompt_data|
+            MCPClient::Prompt.from_json(prompt_data, server: self)
+          end
+        end
+
+        @mutex.synchronize { @prompts }
+      rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+        # Re-raise these errors directly
+        raise
+      rescue StandardError => e
+        raise MCPClient::Errors::PromptGetError, "Error listing prompts: #{e.message}"
+      end
+    end
+
+    # Get a prompt with the given parameters
+    # @param prompt_name [String] the name of the prompt to get
+    # @param parameters [Hash] the parameters to pass to the prompt
+    # @return [Object] the result of the prompt (with string keys for backward compatibility)
+    # @raise [MCPClient::Errors::PromptGetError] if prompt retrieval fails
+    def get_prompt(prompt_name, parameters)
+      rpc_request('prompts/get', {
+                    name: prompt_name,
+                    arguments: parameters.except(:_meta),
+                    **parameters.slice(:_meta)
+                  })
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
+      # Re-raise connection/transport errors directly
+      raise
+    rescue StandardError => e
+      # For all other errors, wrap in PromptGetError
+      raise MCPClient::Errors::PromptGetError, "Error getting prompt '#{prompt_name}': #{e.message}"
+    end
+
+    # List all resources available from the MCP server
+    # @return [Array<MCPClient::Resource>] list of available resources
+    # @raise [MCPClient::Errors::ResourceReadError] if resources list retrieval fails
+    def list_resources
+      @mutex.synchronize do
+        return @resources if @resources
+      end
+
+      begin
+        ensure_connected
+
+        resources_data = request_resources_list
+        @mutex.synchronize do
+          @resources = resources_data.map do |resource_data|
+            MCPClient::Resource.from_json(resource_data, server: self)
+          end
+        end
+
+        @mutex.synchronize { @resources }
+      rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+        # Re-raise these errors directly
+        raise
+      rescue StandardError => e
+        raise MCPClient::Errors::ResourceReadError, "Error listing resources: #{e.message}"
+      end
+    end
+
+    # Read a resource by its URI
+    # @param uri [String] the URI of the resource to read
+    # @return [Object] the resource contents
+    # @raise [MCPClient::Errors::ResourceReadError] if resource reading fails
+    def read_resource(uri)
+      rpc_request('resources/read', { uri: uri })
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
+      # Re-raise connection/transport errors directly
+      raise
+    rescue StandardError => e
+      # For all other errors, wrap in ResourceReadError
+      raise MCPClient::Errors::ResourceReadError, "Error reading resource '#{uri}': #{e.message}"
+    end
+
     # Override apply_request_headers to add session and SSE headers for MCP protocol
     def apply_request_headers(req, request)
       super
@@ -238,28 +350,64 @@ module MCPClient
     end
 
     # Clean up the server connection
-    # Properly closes HTTP connections and clears cached state
+    # Properly closes HTTP connections, stops threads, and clears cached state
     def cleanup
       @mutex.synchronize do
-        # Attempt to terminate session before cleanup
-        terminate_session if @session_id
+        return unless @connection_established || @initialized
 
+        @logger.info('Cleaning up Streamable HTTP connection')
+
+        # Mark connection as closed to stop reconnection attempts
         @connection_established = false
         @initialized = false
 
-        @logger.debug('Cleaning up Streamable HTTP connection')
+        # Attempt to terminate session before cleanup
+        begin
+          terminate_session if @session_id
+        rescue StandardError => e
+          @logger.warn("Failed to terminate session: #{e.message}")
+        end
+
+        # Stop events thread gracefully
+        if @events_thread&.alive?
+          @logger.debug('Stopping events thread...')
+          @events_thread.kill
+          @events_thread.join(THREAD_JOIN_TIMEOUT)
+        end
+        @events_thread = nil
 
-        # Close HTTP connection if it exists
+        # Clear connections and state
         @http_conn = nil
+        @events_connection = nil
         @session_id = nil
+        @last_event_id = nil
 
+        # Clear cached data
         @tools = nil
         @tools_data = nil
+        @prompts = nil
+        @prompts_data = nil
+        @resources = nil
+        @resources_data = nil
+        @buffer = ''
+
+        @logger.info('Cleanup completed')
       end
     end
 
     private
 
+    def perform_initialize
+      super
+      # Send initialized notification to acknowledge completion of initialization
+      notification = build_jsonrpc_notification('notifications/initialized', {})
+      begin
+        send_http_request(notification)
+      rescue MCPClient::Errors::ServerError, MCPClient::Errors::ConnectionError, Faraday::ConnectionFailed => e
+        raise MCPClient::Errors::TransportError, "Failed to send initialized notification: #{e.message}"
+      end
+    end
+
     # Default options for server initialization
     # @return [Hash] Default options
     def default_options
@@ -327,5 +475,270 @@ module MCPClient
 
       raise MCPClient::Errors::ToolCallError, 'Failed to get tools list from JSON-RPC request'
     end
+
+    # Request the prompts list using JSON-RPC
+    # @return [Array<Hash>] the prompts data
+    # @raise [MCPClient::Errors::PromptGetError] if prompts list retrieval fails
+    def request_prompts_list
+      @mutex.synchronize do
+        return @prompts_data if @prompts_data
+      end
+
+      result = rpc_request('prompts/list')
+
+      if result.is_a?(Hash) && result['prompts']
+        @mutex.synchronize do
+          @prompts_data = result['prompts']
+        end
+        return @mutex.synchronize { @prompts_data.dup }
+      elsif result.is_a?(Array) || result
+        @mutex.synchronize do
+          @prompts_data = result
+        end
+        return @mutex.synchronize { @prompts_data.dup }
+      end
+
+      raise MCPClient::Errors::PromptGetError, 'Failed to get prompts list from JSON-RPC request'
+    end
+
+    # Request the resources list using JSON-RPC
+    # @return [Array<Hash>] the resources data
+    # @raise [MCPClient::Errors::ResourceReadError] if resources list retrieval fails
+    def request_resources_list
+      @mutex.synchronize do
+        return @resources_data if @resources_data
+      end
+
+      result = rpc_request('resources/list')
+
+      if result.is_a?(Hash) && result['resources']
+        @mutex.synchronize do
+          @resources_data = result['resources']
+        end
+        return @mutex.synchronize { @resources_data.dup }
+      elsif result.is_a?(Array) || result
+        @mutex.synchronize do
+          @resources_data = result
+        end
+        return @mutex.synchronize { @resources_data.dup }
+      end
+
+      raise MCPClient::Errors::ResourceReadError, 'Failed to get resources list from JSON-RPC request'
+    end
+
+    # Start the long-lived GET connection for server events
+    # Creates a separate thread to maintain SSE connection for server notifications
+    # @return [void]
+    def start_events_connection
+      return if @events_thread&.alive?
+
+      @logger.info('Starting SSE events connection thread')
+      @events_thread = Thread.new do
+        Thread.current.name = 'MCP-SSE-Events'
+        Thread.current.report_on_exception = false # We handle exceptions internally
+
+        begin
+          handle_events_connection
+        rescue StandardError => e
+          @logger.error("Events thread crashed: #{e.message}")
+          @logger.debug(e.backtrace.join("\n")) if @logger.level <= Logger::DEBUG
+        end
+      end
+    end
+
+    # Handle the events connection in a separate thread
+    # Maintains a persistent SSE connection for server notifications and ping/pong
+    # @return [void]
+    def handle_events_connection
+      reconnect_delay = SSE_RECONNECT_DELAY
+
+      loop do
+        # Create a Faraday connection specifically for SSE streaming
+        # Using net_http adapter for better streaming support
+        conn = Faraday.new(url: @base_url) do |f|
+          f.request :retry, max: 0 # No automatic retries for SSE stream
+          f.options.open_timeout = 10
+          f.options.timeout = SSE_CONNECTION_TIMEOUT
+          f.adapter :net_http do |http|
+            http.read_timeout = SSE_CONNECTION_TIMEOUT
+            http.open_timeout = 10
+          end
+        end
+
+        @logger.debug("Establishing SSE events connection to #{@endpoint}") if @logger.level <= Logger::DEBUG
+
+        response = conn.get(@endpoint) do |req|
+          apply_events_headers(req)
+
+          # Handle streaming response with on_data callback
+          req.options.on_data = proc do |chunk, _total_bytes|
+            if chunk && !chunk.empty?
+              @logger.debug("Received event chunk (#{chunk.bytesize} bytes)") if @logger.level <= Logger::DEBUG
+              process_event_chunk(chunk)
+            end
+          end
+        end
+
+        @logger.debug("Events connection completed with status: #{response.status}") if @logger.level <= Logger::DEBUG
+
+        # Connection closed normally, check if we should reconnect
+        break unless @mutex.synchronize { @connection_established }
+
+        @logger.info('Events connection closed, reconnecting...')
+        sleep reconnect_delay
+        reconnect_delay = [reconnect_delay * 2, SSE_MAX_RECONNECT_DELAY].min
+
+      # Intentional shutdown
+      rescue Net::ReadTimeout, Faraday::TimeoutError
+        # Timeout after inactivity - this is expected for long-lived connections
+        break unless @mutex.synchronize { @connection_established }
+
+        @logger.debug('Events connection timed out after inactivity, reconnecting...')
+        sleep reconnect_delay
+      rescue Faraday::ConnectionFailed => e
+        break unless @mutex.synchronize { @connection_established }
+
+        @logger.warn("Events connection failed: #{e.message}, retrying in #{reconnect_delay}s...")
+        sleep reconnect_delay
+        reconnect_delay = [reconnect_delay * 2, SSE_MAX_RECONNECT_DELAY].min
+      rescue StandardError => e
+        break unless @mutex.synchronize { @connection_established }
+
+        @logger.error("Unexpected error in events connection: #{e.class} - #{e.message}")
+        @logger.debug(e.backtrace.join("\n")) if @logger.level <= Logger::DEBUG
+        sleep reconnect_delay
+        reconnect_delay = [reconnect_delay * 2, SSE_MAX_RECONNECT_DELAY].min
+      end
+    ensure
+      @logger.info('Events connection thread terminated')
+    end
+
+    # Apply headers for events connection
+    # @param req [Faraday::Request] HTTP request
+    def apply_events_headers(req)
+      @headers.each { |k, v| req.headers[k] = v }
+      req.headers['Mcp-Session-Id'] = @session_id if @session_id
+    end
+
+    # Process event chunks from the server
+    # Buffers partial chunks and processes complete SSE events
+    # @param chunk [String] the chunk to process
+    def process_event_chunk(chunk)
+      @logger.debug("Processing event chunk: #{chunk.inspect}") if @logger.level <= Logger::DEBUG
+
+      @mutex.synchronize do
+        @buffer += chunk
+
+        # Extract complete events (SSE format: events end with double newline)
+        while (event_end = @buffer.index("\n\n") || @buffer.index("\r\n\r\n"))
+          event_data = extract_event(event_end)
+          parse_and_handle_event(event_data)
+        end
+      end
+    rescue StandardError => e
+      @logger.error("Error processing event chunk: #{e.message}")
+      @logger.debug(e.backtrace.join("\n")) if @logger.level <= Logger::DEBUG
+    end
+
+    # Extract a single event from the buffer
+    # @param event_end [Integer] the position where the event ends
+    # @return [String] the extracted event data
+    def extract_event(event_end)
+      # Determine the line ending style and extract accordingly
+      crlf_index = @buffer.index("\r\n\r\n")
+      lf_index = @buffer.index("\n\n")
+      if crlf_index && (lf_index.nil? || crlf_index < lf_index)
+        @buffer.slice!(0, event_end + 4) # \r\n\r\n is 4 chars
+      else
+        @buffer.slice!(0, event_end + 2) # \n\n is 2 chars
+      end
+    end
+
+    # Parse and handle an SSE event
+    # Parses SSE format according to the W3C specification
+    # @param event_data [String] the raw event data
+    def parse_and_handle_event(event_data)
+      event = { event: 'message', data: '', id: nil }
+      data_lines = []
+
+      event_data.each_line do |line|
+        line = line.chomp
+        next if line.empty? || line.start_with?(':') # Skip empty lines and comments
+
+        if line.start_with?('event:')
+          event[:event] = line[6..].strip
+        elsif line.start_with?('data:')
+          # SSE allows multiple data lines that should be joined with newlines
+          data_lines << line[5..].strip
+        elsif line.start_with?('id:')
+          # Track event ID for resumability (MCP future enhancement)
+          event[:id] = line[3..].strip
+          @last_event_id = event[:id]
+        elsif line.start_with?('retry:')
+          # Server can suggest reconnection delay (in milliseconds)
+          retry_ms = line[6..].strip.to_i
+          @logger.debug("Server suggested retry delay: #{retry_ms}ms") if @logger.level <= Logger::DEBUG
+        end
+      end
+
+      event[:data] = data_lines.join("\n")
+
+      # Only process non-empty data
+      handle_server_message(event[:data]) unless event[:data].empty?
+    end
+
+    # Handle server messages (notifications and requests)
+    # Processes ping/pong keepalive and server notifications
+    # @param data [String] the JSON data from SSE event
+    def handle_server_message(data)
+      return if data.empty?
+
+      begin
+        message = JSON.parse(data)
+
+        # Handle ping requests from server (keepalive mechanism)
+        if message['method'] == 'ping' && message.key?('id')
+          handle_ping_request(message['id'])
+        elsif message['method'] && !message.key?('id')
+          # Handle server notifications (messages without id)
+          @notification_callback&.call(message['method'], message['params'])
+        elsif message.key?('id')
+          # This might be a server-to-client request (future MCP versions)
+          @logger.warn("Received unhandled server request: #{message['method']}")
+        end
+      rescue JSON::ParserError => e
+        @logger.error("Invalid JSON in server message: #{e.message}")
+        @logger.debug("Raw data: #{data.inspect}") if @logger.level <= Logger::DEBUG
+      end
+    end
+
+    # Handle ping request from server
+    # Sends pong response to maintain session keepalive
+    # @param ping_id [Integer, String] the ping request ID
+    def handle_ping_request(ping_id)
+      pong_response = {
+        jsonrpc: '2.0',
+        id: ping_id,
+        result: {}
+      }
+
+      # Send pong response in a separate thread to avoid blocking event processing
+      Thread.new do
+        conn = http_connection
+        response = conn.post(@endpoint) do |req|
+          @headers.each { |k, v| req.headers[k] = v }
+          req.headers['Mcp-Session-Id'] = @session_id if @session_id
+          req.body = pong_response.to_json
+        end
+
+        if response.success?
+          @logger.debug("Sent pong response for ping ID: #{ping_id}") if @logger.level <= Logger::DEBUG
+        else
+          @logger.warn("Failed to send pong response: HTTP #{response.status}")
+        end
+      rescue StandardError => e
+        @logger.error("Failed to send pong response: #{e.message}")
+      end
+    end
   end
 end

data/lib/mcp_client/version.rb

@@ -2,7 +2,7 @@
 
 module MCPClient
   # Current version of the MCP client gem
-  VERSION = '0.7.2'
+  VERSION = '0.8.0'
 
   # MCP protocol version (date-based) - unified across all transports
   PROTOCOL_VERSION = '2025-03-26'

data/lib/mcp_client.rb

@@ -3,6 +3,8 @@
 # Load all MCPClient components
 require_relative 'mcp_client/errors'
 require_relative 'mcp_client/tool'
+require_relative 'mcp_client/prompt'
+require_relative 'mcp_client/resource'
 require_relative 'mcp_client/server_base'
 require_relative 'mcp_client/server_stdio'
 require_relative 'mcp_client/server_sse'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-mcp-client
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.8.0
 platform: ruby
 authors:
 - Szymon Kurcab
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-07-14 00:00:00.000000000 Z
+date: 2025-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -127,6 +127,8 @@ files:
 - lib/mcp_client/http_transport_base.rb
 - lib/mcp_client/json_rpc_common.rb
 - lib/mcp_client/oauth_client.rb
+- lib/mcp_client/prompt.rb
+- lib/mcp_client/resource.rb
 - lib/mcp_client/server_base.rb
 - lib/mcp_client/server_factory.rb
 - lib/mcp_client/server_http.rb