ruby-mcp-client 0.7.1 → 0.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94f8597a5cddfa1f86b6e09401b652d2c7aa3bd4eefc8771712b7c03d99772a8
-  data.tar.gz: b303e3056719fea1a62cf4eeff76156e6e3ed68d134d48aa3ce969e8095d85be
+  metadata.gz: fd6b4269c644ed783b7d574e5a60b26ef0c749c3fe0a58fc86b4d7d5d8786a0d
+  data.tar.gz: 58eb4935ec413db8478dc29983f5baa68d7c28627968ffb5189d1b9754090a51
 SHA512:
-  metadata.gz: da1d04e7aee8207ff32a2db24df14c2b832b8f5fd6acf36c6b8f22b86cf802d99de5514a608a6336f1973949a34a8829c8f71a5b2dadc68ebff50ed7d4d23bc7
-  data.tar.gz: e75630074326e81fddbc006f3bcd8b848c474792ac73c2e9f883722b49b0aeb2da31bb824263234599b279974c7c2445ce6d4d06766a0e447753e8060b248d8f
+  metadata.gz: ee86e5f1e58fb98df9a9a7e715049eb8d7ae5f182430060633c9f97d7b2268d1a02859403ace69f6a400344cffad80dd9238169a638e27491a6bc99ce70fb462
+  data.tar.gz: 27e82788b84bc0887c273ab3c1277180e85f4930f413500fab4dbf2a7474dcb151bf510ec2509caf7a95bf53311dee587e65d8826b226e7ef164d9acd640582a

data/README.md

@@ -47,6 +47,8 @@ This Ruby MCP Client implements key features from the latest MCP specification (
 ### Implemented Features
 - **OAuth 2.1 Authorization Framework** - Complete authentication with PKCE, dynamic client registration, server discovery, and runtime configuration
 - **Streamable HTTP Transport** - Enhanced transport with Server-Sent Event formatted responses and session management
+- **HTTP Redirect Support** - Automatic redirect handling for both SSE and HTTP transports with configurable limits
+- **FastMCP Compatibility** - Full compatibility with FastMCP servers including proper line ending handling
 
 ## Usage
 
@@ -286,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)
@@ -302,37 +304,79 @@ 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.
 
+### FastMCP Example
+
+The repository includes a complete FastMCP server example that demonstrates the Ruby MCP client working with a Python FastMCP server:
+
+```ruby
+# Start the FastMCP server
+# python examples/echo_server.py
+
+# Run the Ruby client
+# bundle exec ruby examples/echo_server_client.rb
+
+require 'mcp_client'
+
+# Connect to FastMCP server
+client = MCPClient.create_client(
+  mcp_server_configs: [
+    MCPClient.sse_config(
+      base_url: 'http://127.0.0.1:8000/sse/',
+      read_timeout: 30
+    )
+  ]
+)
+
+# List available tools
+tools = client.list_tools
+puts "Found #{tools.length} tools:"
+tools.each { |tool| puts "- #{tool.name}: #{tool.description}" }
+
+# Use the tools
+result = client.call_tool('echo', { message: 'Hello from Ruby!' })
+result = client.call_tool('reverse', { text: 'FastMCP rocks!' })
+
+client.cleanup
+```
+
+The FastMCP example includes:
+- **`echo_server.py`** - A Python FastMCP server with 4 interactive tools
+- **`echo_server_client.rb`** - Ruby client demonstrating all features
+- **`README_ECHO_SERVER.md`** - Complete setup and usage instructions
+
+This example showcases redirect support, proper line ending handling, and seamless integration between Ruby and Python MCP implementations.
+
 ### Integration Examples
 
 The repository includes examples for integrating with popular AI APIs:
@@ -421,6 +465,7 @@ Complete examples can be found in the `examples/` directory:
 - `ruby_anthropic_mcp.rb` - Integration with alexrudall/ruby-anthropic gem
 - `gemini_ai_mcp.rb` - Integration with Google Vertex AI and Gemini models
 - `mcp_sse_server_example.rb` - SSE transport with Playwright MCP
+- `echo_server.py` & `echo_server_client.rb` - FastMCP server example with full setup
 
 ## MCP Server Compatibility
 
@@ -428,6 +473,7 @@ This client works with any MCP-compatible server, including:
 
 - [@modelcontextprotocol/server-filesystem](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) - File system access
 - [@playwright/mcp](https://www.npmjs.com/package/@playwright/mcp) - Browser automation
+- [FastMCP](https://github.com/jlowin/fastmcp) - Python framework for building MCP servers
 - Custom servers implementing the MCP protocol
 
 ### Server Definition Files
@@ -439,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"
       }
@@ -471,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"
     }
@@ -645,6 +691,7 @@ For complete OAuth documentation, see [OAUTH.md](OAUTH.md).
 The SSE client implementation provides these key features:
 
 - **Robust connection handling**: Properly manages HTTP/HTTPS connections with configurable timeouts and retries
+- **Automatic redirect support**: Follows HTTP redirects up to 3 hops for seamless server integration
 - **Advanced connection management**:
   - **Inactivity tracking**: Monitors connection activity to detect idle connections
   - **Automatic ping**: Sends ping requests after a configurable period of inactivity (default: 10 seconds)
@@ -674,6 +721,7 @@ The SSE client implementation provides these key features:
 The HTTP transport provides a simpler, stateless communication mechanism for MCP servers:
 
 - **Request/Response Model**: Standard HTTP request/response cycle for each JSON-RPC call
+- **Automatic redirect support**: Follows HTTP redirects up to 3 hops for seamless server integration
 - **JSON-Only Responses**: Accepts only `application/json` responses (no SSE support)
 - **Session Support**: Automatic session header (`Mcp-Session-Id`) capture and injection for session-based MCP servers
 - **Session Termination**: Proper session cleanup with HTTP DELETE requests during connection teardown

data/lib/mcp_client/config_parser.rb

@@ -27,7 +27,7 @@ module MCPClient
 
       result = {}
       servers_data.each do |server_name, config|
-        next unless validate_server_config(config, server_name)
+        next unless valid_server_config?(config, server_name)
 
         server_config = process_server_config(config, server_name)
         next unless server_config
@@ -66,7 +66,7 @@ module MCPClient
     # @param config [Object] server configuration to validate
     # @param server_name [String] name of the server
     # @return [Boolean] true if valid, false otherwise
-    def validate_server_config(config, server_name)
+    def valid_server_config?(config, server_name)
       return true if config.is_a?(Hash)
 
       @logger.warn("Configuration for server '#{server_name}' is not an object; skipping.")
@@ -86,11 +86,11 @@ module MCPClient
       when 'stdio'
         parse_stdio_config(clean, config, server_name)
       when 'sse'
-        return nil unless parse_sse_config(clean, config, server_name)
+        return nil unless parse_sse_config?(clean, config, server_name)
       when 'streamable_http'
-        return nil unless parse_streamable_http_config(clean, config, server_name)
+        return nil unless parse_streamable_http_config?(clean, config, server_name)
       when 'http'
-        return nil unless parse_http_config(clean, config, server_name)
+        return nil unless parse_http_config?(clean, config, server_name)
       else
         @logger.warn("Unrecognized type '#{type}' for server '#{server_name}'; skipping.")
         return nil
@@ -164,7 +164,7 @@ module MCPClient
     # @param config [Hash] raw configuration from JSON
     # @param server_name [String] name of the server for error reporting
     # @return [Boolean] true if parsing succeeded, false if required elements are missing
-    def parse_sse_config(clean, config, server_name)
+    def parse_sse_config?(clean, config, server_name)
       # URL is required
       source = config['url']
       unless source
@@ -192,7 +192,7 @@ module MCPClient
     # @param config [Hash] raw configuration from JSON
     # @param server_name [String] name of the server for error reporting
     # @return [Boolean] true if parsing succeeded, false if required elements are missing
-    def parse_streamable_http_config(clean, config, server_name)
+    def parse_streamable_http_config?(clean, config, server_name)
       # URL is required
       source = config['url']
       unless source
@@ -225,7 +225,7 @@ module MCPClient
     # @param config [Hash] raw configuration from JSON
     # @param server_name [String] name of the server for error reporting
     # @return [Boolean] true if parsing succeeded, false if required elements are missing
-    def parse_http_config(clean, config, server_name)
+    def parse_http_config?(clean, config, server_name)
       # URL is required
       source = config['url']
       unless source

data/lib/mcp_client/http_transport_base.rb

@@ -119,7 +119,7 @@ module MCPClient
     # @return [Hash] the initialization parameters
     def initialization_params
       {
-        'protocolVersion' => MCPClient::HTTP_PROTOCOL_VERSION,
+        'protocolVersion' => MCPClient::PROTOCOL_VERSION,
         'capabilities' => {},
         'clientInfo' => { 'name' => 'ruby-mcp-client', 'version' => MCPClient::VERSION }
       }

data/lib/mcp_client/server_base.rb

@@ -77,5 +77,23 @@ module MCPClient
     def on_notification(&block)
       @notification_callback = block
     end
+
+    protected
+
+    # Initialize logger with proper formatter handling
+    # Preserves custom formatter if logger is provided, otherwise sets a default formatter
+    # @param logger [Logger, nil] custom logger to use, or nil to create a default one
+    # @return [Logger] the configured logger
+    def initialize_logger(logger)
+      if logger
+        @logger = logger
+        @logger.progname = self.class.name
+      else
+        @logger = Logger.new($stdout, level: Logger::WARN)
+        @logger.progname = self.class.name
+        @logger.formatter = proc { |severity, _datetime, progname, msg| "#{severity} [#{progname}] #{msg}\n" }
+      end
+      @logger
+    end
   end
 end

data/lib/mcp_client/server_http.rb

@@ -6,6 +6,7 @@ require 'monitor'
 require 'logger'
 require 'faraday'
 require 'faraday/retry'
+require 'faraday/follow_redirects'
 
 module MCPClient
   # Implementation of MCP server that communicates via HTTP requests/responses
@@ -49,9 +50,7 @@ module MCPClient
     def initialize(base_url:, **options)
       opts = default_options.merge(options)
       super(name: opts[:name])
-      @logger = opts[:logger] || Logger.new($stdout, level: Logger::WARN)
-      @logger.progname = self.class.name
-      @logger.formatter = proc { |severity, _datetime, progname, msg| "#{severity} [#{progname}] #{msg}\n" }
+      initialize_logger(opts[:logger])
 
       @max_retries = opts[:retries]
       @retry_backoff = opts[:retry_backoff]

data/lib/mcp_client/server_sse/json_rpc_transport.rb

@@ -70,6 +70,13 @@ module MCPClient
 
         @server_info = result['serverInfo']
         @capabilities = result['capabilities']
+
+        # Send initialized notification to acknowledge completion of initialization
+        initialized_notification = build_jsonrpc_notification('notifications/initialized', {})
+        post_json_rpc_request(initialized_notification)
+
+        # Small delay to ensure server processes the notification
+        sleep(0.1)
       end
 
       # Send a JSON-RPC request to the server and wait for result
@@ -133,6 +140,7 @@ module MCPClient
       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.response :follow_redirects, limit: 3
           f.options.open_timeout = @read_timeout
           f.options.timeout = @read_timeout
           f.adapter Faraday.default_adapter

data/lib/mcp_client/server_sse/reconnect_monitor.rb

@@ -191,6 +191,7 @@ module MCPClient
           f.options.open_timeout = 10
           f.options.timeout = nil
           f.request :retry, max: @max_retries, interval: @retry_backoff, backoff_factor: 2
+          f.response :follow_redirects, limit: 3
           f.adapter Faraday.default_adapter
         end
 

data/lib/mcp_client/server_sse/sse_parser.rb

@@ -31,9 +31,9 @@ module MCPClient
           data = JSON.parse(event[:data])
 
           return if process_error_in_message(data)
-          return if process_notification(data)
+          return if process_notification?(data)
 
-          process_response(data)
+          process_response?(data)
         rescue MCPClient::Errors::ConnectionError
           raise
         rescue JSON::ParserError => e
@@ -61,7 +61,7 @@ module MCPClient
       # Process a JSON-RPC notification (no id => notification)
       # @param data [Hash] the parsed JSON payload
       # @return [Boolean] true if we saw & handled a notification
-      def process_notification(data)
+      def process_notification?(data)
         return false unless data['method'] && !data.key?('id')
 
         @notification_callback&.call(data['method'], data['params'])
@@ -71,7 +71,7 @@ module MCPClient
       # Process a JSON-RPC response (id => response)
       # @param data [Hash] the parsed JSON payload
       # @return [Boolean] true if we saw & handled a response
-      def process_response(data)
+      def process_response?(data)
         return false unless data['id']
 
         @mutex.synchronize do

data/lib/mcp_client/server_sse.rb

@@ -6,6 +6,7 @@ require 'monitor'
 require 'logger'
 require 'faraday'
 require 'faraday/retry'
+require 'faraday/follow_redirects'
 
 module MCPClient
   # Implementation of MCP server that communicates via Server-Sent Events (SSE)
@@ -56,13 +57,11 @@ module MCPClient
     def initialize(base_url:, headers: {}, read_timeout: 30, ping: 10,
                    retries: 0, retry_backoff: 1, name: nil, logger: nil)
       super(name: name)
-      @logger = logger || Logger.new($stdout, level: Logger::WARN)
-      @logger.progname = self.class.name
-      @logger.formatter = proc { |severity, _datetime, progname, msg| "#{severity} [#{progname}] #{msg}\n" }
+      initialize_logger(logger)
       @max_retries = retries
       @retry_backoff = retry_backoff
-      # Normalize base_url: strip any trailing slash, use exactly as provided
-      @base_url = base_url.chomp('/')
+      # Normalize base_url: preserve trailing slash if explicitly provided for SSE endpoints
+      @base_url = base_url
       @headers = headers.merge({
                                  'Accept' => 'text/event-stream',
                                  'Cache-Control' => 'no-cache',
@@ -369,53 +368,86 @@ module MCPClient
       record_activity if chunk.include?('event:')
 
       # Check for direct JSON error responses (which aren't proper SSE events)
-      if chunk.start_with?('{') && chunk.include?('"error"') &&
-         (chunk.include?('Unauthorized') || chunk.include?('authentication'))
-        begin
-          data = JSON.parse(chunk)
-          if data['error']
-            error_message = data['error']['message'] || 'Unknown server error'
+      handle_json_error_response(chunk)
+
+      event_buffers = extract_complete_events(chunk)
+
+      # Process extracted events outside the mutex to avoid deadlocks
+      event_buffers&.each { |event_data| parse_and_handle_sse_event(event_data) }
+    end
+
+    # Check if the error represents an authorization error
+    # @param error_message [String] The error message from the server
+    # @param error_code [Integer, nil] The error code if available
+    # @return [Boolean] True if it's an authorization error
+    # @private
+    def authorization_error?(error_message, error_code)
+      return true if error_message.include?('Unauthorized') || error_message.include?('authentication')
+      return true if [401, -32_000].include?(error_code)
 
-            @mutex.synchronize do
-              @auth_error = "Authorization failed: #{error_message}"
+      false
+    end
 
-              @connection_established = false
-              @connection_cv.broadcast
-            end
+    # Handle JSON error responses embedded in SSE chunks
+    # @param chunk [String] the chunk to check for JSON errors
+    # @return [void]
+    # @raise [MCPClient::Errors::ConnectionError] if authentication error is found
+    # @private
+    def handle_json_error_response(chunk)
+      return unless chunk.start_with?('{') && chunk.include?('"error"') &&
+                    (chunk.include?('Unauthorized') || chunk.include?('authentication'))
 
-            raise MCPClient::Errors::ConnectionError, "Authorization failed: #{error_message}"
+      begin
+        data = JSON.parse(chunk)
+        if data['error']
+          error_message = data['error']['message'] || 'Unknown server error'
+
+          @mutex.synchronize do
+            @auth_error = "Authorization failed: #{error_message}"
+            @connection_established = false
+            @connection_cv.broadcast
           end
-        rescue JSON::ParserError
-          # Not valid JSON, process normally
+
+          raise MCPClient::Errors::ConnectionError, "Authorization failed: #{error_message}"
         end
+      rescue JSON::ParserError
+        # Not valid JSON, process normally
       end
+    end
 
+    # Extract complete SSE events from the buffer
+    # @param chunk [String] the chunk to add to the buffer
+    # @return [Array<String>, nil] array of complete events or nil if none
+    # @private
+    def extract_complete_events(chunk)
       event_buffers = nil
       @mutex.synchronize do
         @buffer += chunk
 
         # Extract all complete events from the buffer
+        # Handle both Unix (\n\n) and Windows (\r\n\r\n) line endings
         event_buffers = []
-        while (event_end = @buffer.index("\n\n"))
-          event_data = @buffer.slice!(0, event_end + 2)
+        while (event_end = @buffer.index("\n\n") || @buffer.index("\r\n\r\n"))
+          event_data = extract_single_event(event_end)
           event_buffers << event_data
         end
       end
-
-      # Process extracted events outside the mutex to avoid deadlocks
-      event_buffers&.each { |event_data| parse_and_handle_sse_event(event_data) }
+      event_buffers
     end
 
-    # Check if the error represents an authorization error
-    # @param error_message [String] The error message from the server
-    # @param error_code [Integer, nil] The error code if available
-    # @return [Boolean] True if it's an authorization error
+    # Extract a single event from the buffer
+    # @param event_end [Integer] the position where the event ends
+    # @return [String] the extracted event data
     # @private
-    def authorization_error?(error_message, error_code)
-      return true if error_message.include?('Unauthorized') || error_message.include?('authentication')
-      return true if [401, -32_000].include?(error_code)
-
-      false
+    def extract_single_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
 
     # Handle authorization error in SSE message

data/lib/mcp_client/server_stdio.rb

@@ -39,9 +39,7 @@ module MCPClient
       @next_id = 1
       @pending = {}
       @initialized = false
-      @logger = logger || Logger.new($stdout, level: Logger::WARN)
-      @logger.progname = self.class.name
-      @logger.formatter = proc { |severity, _datetime, progname, msg| "#{severity} [#{progname}] #{msg}\n" }
+      initialize_logger(logger)
       @max_retries   = retries
       @retry_backoff = retry_backoff
       @read_timeout  = read_timeout

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

@@ -6,11 +6,18 @@ require 'monitor'
 require 'logger'
 require 'faraday'
 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'
 
@@ -20,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
@@ -41,9 +54,7 @@ module MCPClient
     def initialize(base_url:, **options)
       opts = default_options.merge(options)
       super(name: opts[:name])
-      @logger = opts[:logger] || Logger.new($stdout, level: Logger::WARN)
-      @logger.progname = self.class.name
-      @logger.formatter = proc { |severity, _datetime, progname, msg| "#{severity} [#{progname}] #{msg}\n" }
+      initialize_logger(opts[:logger])
 
       @max_retries = opts[:retries]
       @retry_backoff = opts[:retry_backoff]
@@ -96,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
@@ -116,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
@@ -171,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
@@ -239,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
@@ -328,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,11 +2,8 @@
 
 module MCPClient
   # Current version of the MCP client gem
-  VERSION = '0.7.1'
+  VERSION = '0.7.3'
 
-  # JSON-RPC handshake protocol version (date-based)
-  PROTOCOL_VERSION = '2024-11-05'
-
-  # Protocol version for HTTP and Streamable HTTP transports
-  HTTP_PROTOCOL_VERSION = '2025-03-26'
+  # MCP protocol version (date-based) - unified across all transports
+  PROTOCOL_VERSION = '2025-03-26'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-mcp-client
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.7.3
 platform: ruby
 authors:
 - Szymon Kurcab
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-06-20 00:00:00.000000000 Z
+date: 2025-09-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-follow_redirects
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
 - !ruby/object:Gem::Dependency
   name: faraday-retry
   requirement: !ruby/object:Gem::Requirement