ruby-mcp-client 0.7.2 → 0.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e71d5420a77345079ef2da077240e6a578900c3acfd2c16c904b0a2bf84a8bb7
-  data.tar.gz: ea4f41ebef3d5898d3dd0786d50d08dbbd19057bbbd5b7aa8cc046d5a1608d7c
+  metadata.gz: fd6b4269c644ed783b7d574e5a60b26ef0c749c3fe0a58fc86b4d7d5d8786a0d
+  data.tar.gz: 58eb4935ec413db8478dc29983f5baa68d7c28627968ffb5189d1b9754090a51
 SHA512:
-  metadata.gz: a837ba7337913a453e5ae2567c67fed453b5e1cab3712705689c74b2efff27fa5c257750c834b5ac5bfff04333f08f1999b6813982d0c548ee92f4992c4d6aad
-  data.tar.gz: e10f2262b5dd10f0323dbbf870daa9f2d25d2d9f6a7f0c053870a8e0a5453ed9c5ed2c667211dfcf094c4fd56e7c12fbc1407c358e955fb14b4cbf4601312226
+  metadata.gz: ee86e5f1e58fb98df9a9a7e715049eb8d7ae5f182430060633c9f97d7b2268d1a02859403ace69f6a400344cffad80dd9238169a638e27491a6bc99ce70fb462
+  data.tar.gz: 27e82788b84bc0887c273ab3c1277180e85f4930f413500fab4dbf2a7474dcb151bf510ec2509caf7a95bf53311dee587e65d8826b226e7ef164d9acd640582a

data/README.md

@@ -288,12 +288,12 @@ require 'logger'
 logger = Logger.new($stdout)
 logger.level = Logger::INFO
 
-# Create an MCP client that connects to a Playwright MCP server via SSE
+# Create an MCP client that connects to a Playwright MCP server via Streamable HTTP
 # First run: npx @playwright/mcp@latest --port 8931
-sse_client = MCPClient.create_client(
+mcp_client = MCPClient.create_client(
   mcp_server_configs: [
-    MCPClient.sse_config(
-      base_url: 'http://localhost:8931/sse',
+    MCPClient.streamable_http_config(
+      base_url: 'http://localhost:8931/mcp',
       read_timeout: 30,  # Timeout in seconds for request fulfillment
       ping: 10,          # Send ping after 10 seconds of inactivity
                          # Connection closes automatically after inactivity (2.5x ping interval)
@@ -304,33 +304,33 @@ sse_client = MCPClient.create_client(
 )
 
 # List available tools
-tools = sse_client.list_tools
+tools = mcp_client.list_tools
 
 # Launch a browser
-result = sse_client.call_tool('browser_install', {})
-result = sse_client.call_tool('browser_navigate', { url: 'about:blank' })
+result = mcp_client.call_tool('browser_install', {})
+result = mcp_client.call_tool('browser_navigate', { url: 'about:blank' })
 # No browser ID needed with these tool names
 
 # Create a new page
-page_result = sse_client.call_tool('browser_tab_new', {})
+page_result = mcp_client.call_tool('browser_tab', {action: 'create'})
 # No page ID needed with these tool names
 
 # Navigate to a website
-sse_client.call_tool('browser_navigate', { url: 'https://example.com' })
+mcp_client.call_tool('browser_navigate', { url: 'https://example.com' })
 
 # Get page title
-title_result = sse_client.call_tool('browser_snapshot', {})
+title_result = mcp_client.call_tool('browser_snapshot', {})
 puts "Page snapshot: #{title_result}"
 
 # Take a screenshot
-screenshot_result = sse_client.call_tool('browser_take_screenshot', {})
+screenshot_result = mcp_client.call_tool('browser_take_screenshot', {})
 
 # Ping the server to verify connectivity
-ping_result = sse_client.ping
+ping_result = mcp_client.ping
 puts "Ping successful: #{ping_result.inspect}"
 
 # Clean up
-sse_client.cleanup
+mcp_client.cleanup
 ```
 
 See `examples/mcp_sse_server_example.rb` for the full Playwright SSE example.
@@ -485,7 +485,7 @@ You can define MCP server configurations in JSON files for easier management:
   "mcpServers": {
     "playwright": {
       "type": "sse",
-      "url": "http://localhost:8931/sse",
+      "url": "http://localhost:8931/mcp",
       "headers": {
         "Authorization": "Bearer TOKEN"
       }
@@ -517,7 +517,7 @@ A simpler example used in the Playwright demo (found in `examples/sample_server_
 {
   "mcpServers": {
     "playwright": {
-      "url": "http://localhost:8931/sse",
+      "url": "http://localhost:8931/mcp",
       "headers": {},
       "comment": "Local Playwright MCP Server running on port 8931"
     }

data/lib/mcp_client/server_streamable_http/json_rpc_transport.rb

@@ -45,30 +45,44 @@ module MCPClient
       # @return [Hash] the parsed JSON data
       # @raise [MCPClient::Errors::TransportError] if no data found in SSE response
       def parse_sse_response(sse_body)
-        # Extract JSON data and event ID from SSE format
+        # Extract JSON data from SSE format, processing events separately
         # SSE format: event: message\nid: 123\ndata: {...}\n\n
-        data_lines = []
-        event_id = nil
+        events = []
+        current_event = { type: nil, data_lines: [], id: nil }
 
         sse_body.lines.each do |line|
           line = line.strip
-          if line.start_with?('data:')
-            data_lines << line.sub(/^data:\s*/, '').strip
+
+          if line.empty?
+            # Empty line marks end of an event
+            events << current_event.dup if current_event[:type] && !current_event[:data_lines].empty?
+            current_event = { type: nil, data_lines: [], id: nil }
+          elsif line.start_with?('event:')
+            current_event[:type] = line.sub(/^event:\s*/, '').strip
+          elsif line.start_with?('data:')
+            current_event[:data_lines] << line.sub(/^data:\s*/, '').strip
           elsif line.start_with?('id:')
-            event_id = line.sub(/^id:\s*/, '').strip
+            current_event[:id] = line.sub(/^id:\s*/, '').strip
           end
         end
 
-        raise MCPClient::Errors::TransportError, 'No data found in SSE response' if data_lines.empty?
+        # Handle last event if no trailing empty line
+        events << current_event if current_event[:type] && !current_event[:data_lines].empty?
+
+        # Find the first 'message' event which contains the JSON-RPC response
+        message_event = events.find { |e| e[:type] == 'message' }
+
+        raise MCPClient::Errors::TransportError, 'No data found in SSE response' unless message_event
+        raise MCPClient::Errors::TransportError, 'No data found in message event' if message_event[:data_lines].empty?
 
-        # Track the last event ID for resumability
-        if event_id && !event_id.empty?
-          @last_event_id = event_id
-          @logger.debug("Tracking event ID for resumability: #{event_id}")
+        # Track the event ID for resumability
+        if message_event[:id] && !message_event[:id].empty?
+          @last_event_id = message_event[:id]
+          @logger.debug("Tracking event ID for resumability: #{message_event[:id]}")
         end
 
         # Join multiline data fields according to SSE spec
-        json_data = data_lines.join("\n")
+        json_data = message_event[:data_lines].join("\n")
         JSON.parse(json_data)
       end
     end

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
@@ -95,6 +107,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 +132,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 +190,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
@@ -238,28 +259,60 @@ 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
 
-        # Close HTTP connection if it exists
+        # 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
+
+        # 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
+        @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 +380,220 @@ module MCPClient
 
       raise MCPClient::Errors::ToolCallError, 'Failed to get tools 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.7.3'
 
   # MCP protocol version (date-based) - unified across all transports
   PROTOCOL_VERSION = '2025-03-26'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-mcp-client
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.7.3
 platform: ruby
 authors:
 - Szymon Kurcab
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-07-14 00:00:00.000000000 Z
+date: 2025-09-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday