ruby-mcp-client 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87cf7d5701adff89363dd653d263189bded230a32232bbbb496d41b4092afdec
-  data.tar.gz: 9a3561d2f97f0ef518cf75dfce82a8521140c9cdc381aaef3f3b3658265a7298
+  metadata.gz: 79a86302428257274c4e620fae0b7ad45c6229cf381a956ef3b0a7e736f17f62
+  data.tar.gz: 80727b0aa48a992054dafd7c484eb611404b47d878ef2869e59e937a815718dc
 SHA512:
-  metadata.gz: 361f1916a531f14ded3292e15ea4947b0e3715d71d2be71dd24ea198616a82c55e516379a59a455b6c14f9fb7b3b9a1d02bdd457fde0b975ece6320bbb6da23b
-  data.tar.gz: b38270ec5a9ddce3a3689e6c8fb6e86efaa35453b6bcc8a590612d02fe1ef86040d62fd30fb95ff02640bb7b822bf8f473ae24fd571ad696069657f98a9d5c20
+  metadata.gz: 977acc1ae8ca48a17b7827f006ed82578eb7bc24bf9ba08b03e77493e3447febc82287242a410861fb675b1fb74b0b67525dc4f92c9f8b448cd1cad2e3afc875
+  data.tar.gz: f940ed03a52065a5d8687d1722a588693d69a9c69f820771b328fed3b1bb69068fc7110dbedc745ea4fc42d047afa8afe975b2ed821aa5d33ac8c4e25fac9da7

data/README.md

@@ -100,9 +100,8 @@ result = client.send_rpc('another_method', params: { data: 123 }) # Uses first a
 client.send_notification('status_update', params: { status: 'ready' })
 
 # Check server connectivity 
-client.ping # Basic connectivity check
-client.ping({ echo: "hello" }) # With optional parameters 
-client.ping({}, server_index: 1) # Ping a specific server by index
+client.ping # Basic connectivity check (zero-parameter heartbeat call)
+client.ping(server_index: 1) # Ping a specific server by index
 
 # Clear cached tools to force fresh fetch on next list
 client.clear_cache
@@ -110,6 +109,61 @@ client.clear_cache
 client.cleanup
 ```
 
+### Server-Sent Events (SSE) Example
+
+The SSE transport provides robust connection handling for remote MCP servers:
+
+```ruby
+require 'mcp_client'
+require 'logger'
+
+# Optional logger for debugging
+logger = Logger.new($stdout)
+logger.level = Logger::INFO
+
+# Create an MCP client that connects to a Playwright MCP server via SSE
+# First run: npx @playwright/mcp@latest --port 8931
+sse_client = MCPClient.create_client(
+  mcp_server_configs: [
+    MCPClient.sse_config(
+      base_url: 'http://localhost:8931/sse',
+      read_timeout: 30,  # Timeout in seconds
+    )
+  ]
+)
+
+# List available tools
+tools = sse_client.list_tools
+
+# Launch a browser
+result = sse_client.call_tool('browser_install', {})
+result = sse_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', {})
+# No page ID needed with these tool names
+
+# Navigate to a website
+sse_client.call_tool('browser_navigate', { url: 'https://example.com' })
+
+# Get page title
+title_result = sse_client.call_tool('browser_snapshot', {})
+puts "Page snapshot: #{title_result}"
+
+# Take a screenshot
+screenshot_result = sse_client.call_tool('browser_take_screenshot', {})
+
+# Ping the server to verify connectivity
+ping_result = sse_client.ping
+puts "Ping successful: #{ping_result.inspect}"
+
+# Clean up
+sse_client.cleanup
+```
+
+See `examples/mcp_sse_server_example.rb` for the full Playwright SSE example.
+
 ### Integration Examples
 
 The repository includes examples for integrating with popular AI APIs:
@@ -196,6 +250,7 @@ Complete examples can be found in the `examples/` directory:
 - `ruby_openai_mcp.rb` - Integration with alexrudall/ruby-openai gem
 - `openai_ruby_mcp.rb` - Integration with official openai/openai-ruby gem
 - `ruby_anthropic_mcp.rb` - Integration with alexrudall/ruby-anthropic gem
+- `mcp_sse_server_example.rb` - SSE transport with Playwright MCP
 
 ## MCP Server Compatibility
 
@@ -205,7 +260,20 @@ This client works with any MCP-compatible server, including:
 - [@playwright/mcp](https://www.npmjs.com/package/@playwright/mcp) - Browser automation
 - Custom servers implementing the MCP protocol
 
-### Server Implementation Features
+## Key Features
+
+### Client Features
+
+- **Multiple transports** - Support for both stdio and SSE transports
+- **Multiple servers** - Connect to multiple MCP servers simultaneously
+- **Tool discovery** - Find tools by name or pattern
+- **Atomic tool calls** - Simple API for invoking tools with parameters
+- **Batch support** - Call multiple tools in a single operation
+- **API conversions** - Built-in format conversion for OpenAI and Anthropic APIs
+- **Thread safety** - Synchronized access for thread-safe operation
+- **Server notifications** - Support for JSON-RPC notifications
+- **Custom RPC methods** - Send any custom JSON-RPC method
+- **Consistent error handling** - Rich error types for better exception handling
 
 ### Server-Sent Events (SSE) Implementation
 
@@ -226,7 +294,7 @@ The SSE client implementation provides these key features:
 
 ## Requirements
 
-- Ruby >= 2.7.0
+- Ruby >= 3.2.0
 - No runtime dependencies
 
 ## Implementing an MCP Server
@@ -274,4 +342,4 @@ This gem is available as open source under the [MIT License](LICENSE).
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at
-https://github.com/simonx1/ruby-mcp-client.
+https://github.com/simonx1/ruby-mcp-client.

data/lib/mcp_client/client.rb

@@ -31,9 +31,9 @@ module MCPClient
       # Register default and user-defined notification handlers on each server
       @servers.each do |server|
         server.on_notification do |method, params|
-          # Default handling: clear tool cache on tools list change
-          clear_cache if method == 'notifications/tools/list_changed'
-          # Invoke user listeners
+          # Default notification processing (e.g., cache invalidation, logging)
+          process_notification(server, method, params)
+          # Invoke user-defined listeners
           @notification_listeners.each { |cb| cb.call(server, method, params) }
         end
       end
@@ -163,17 +163,16 @@ module MCPClient
       end
     end
 
-    # Ping the MCP server to check connectivity
-    # @param params [Hash] optional parameters for the ping request
+    # Ping the MCP server to check connectivity (zero-parameter heartbeat call)
     # @param server_index [Integer, nil] optional index of a specific server to ping, nil for first available
     # @return [Object] result from the ping request
     # @raise [MCPClient::Errors::ServerNotFound] if no server is available
-    def ping(params = {}, server_index: nil)
+    def ping(server_index: nil)
       if server_index.nil?
         # Ping first available server
         raise MCPClient::Errors::ServerNotFound, 'No server available for ping' if @servers.empty?
 
-        @servers.first.ping(params)
+        @servers.first.ping
       else
         # Ping specified server
         if server_index >= @servers.length
@@ -181,12 +180,78 @@ module MCPClient
                 "Server at index #{server_index} not found"
         end
 
-        @servers[server_index].ping(params)
+        @servers[server_index].ping
       end
     end
 
+    # Send a raw JSON-RPC request to a server
+    # @param method [String] JSON-RPC method name
+    # @param params [Hash] parameters for the request
+    # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
+    # @return [Object] result from the JSON-RPC response
+    def send_rpc(method, params: {}, server: nil)
+      srv = select_server(server)
+      srv.rpc_request(method, params)
+    end
+
+    # Send a raw JSON-RPC notification to a server (no response expected)
+    # @param method [String] JSON-RPC method name
+    # @param params [Hash] parameters for the notification
+    # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
+    # @return [void]
+    def send_notification(method, params: {}, server: nil)
+      srv = select_server(server)
+      srv.rpc_notify(method, params)
+    end
+
     private
 
+    # Process incoming JSON-RPC notifications with default handlers
+    # @param server [MCPClient::ServerBase] the server that emitted the notification
+    # @param method [String] JSON-RPC notification method
+    # @param params [Hash] parameters for the notification
+    # @return [void]
+    def process_notification(server, method, params)
+      case method
+      when 'notifications/tools/list_changed'
+        logger.warn("[#{server.class}] Tool list has changed, clearing tool cache")
+        clear_cache
+      when 'notifications/resources/updated'
+        logger.warn("[#{server.class}] Resource #{params['uri']} updated")
+      when 'notifications/prompts/list_changed'
+        logger.warn("[#{server.class}] Prompt list has changed")
+      when 'notifications/resources/list_changed'
+        logger.warn("[#{server.class}] Resource list has changed")
+      end
+    end
+
+    # Select a server based on index, type, or instance
+    # @param server_arg [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
+    # @return [MCPClient::ServerBase]
+    def select_server(server_arg)
+      case server_arg
+      when nil
+        raise MCPClient::Errors::ServerNotFound, 'No server available' if @servers.empty?
+
+        @servers.first
+      when Integer
+        @servers.fetch(server_arg) do
+          raise MCPClient::Errors::ServerNotFound, "Server at index #{server_arg} not found"
+        end
+      when String, Symbol
+        key = server_arg.to_s.downcase
+        srv = @servers.find { |s| s.class.name.split('::').last.downcase.end_with?(key) }
+        raise MCPClient::Errors::ServerNotFound, "Server of type #{server_arg} not found" unless srv
+
+        srv
+      else
+        raise ArgumentError, "Invalid server argument: #{server_arg.inspect}" unless @servers.include?(server_arg)
+
+        server_arg
+
+      end
+    end
+
     # Validate parameters against tool JSON schema (checks required properties)
     # @param tool [MCPClient::Tool] tool definition with schema
     # @param parameters [Hash] parameters to validate

data/lib/mcp_client/server_base.rb

@@ -45,11 +45,10 @@ module MCPClient
       raise NotImplementedError, 'Subclasses must implement rpc_notify'
     end
 
-    # Ping the MCP server to check connectivity
-    # @param params [Hash] optional parameters for the ping request
+    # Ping the MCP server to check connectivity (zero-parameter heartbeat call)
     # @return [Object] result from the ping request
-    def ping(params = {})
-      rpc_request('ping', params)
+    def ping
+      rpc_request('ping')
     end
 
     # Register a callback to receive JSON-RPC notifications

data/lib/mcp_client/server_sse.rb

@@ -1,17 +1,17 @@
 # frozen_string_literal: true
 
 require 'uri'
-require 'net/http'
 require 'json'
-require 'openssl'
 require 'monitor'
 require 'logger'
+require 'faraday'
+require 'faraday/retry'
 
 module MCPClient
   # Implementation of MCP server that communicates via Server-Sent Events (SSE)
   # Useful for communicating with remote MCP servers over HTTP
   class ServerSSE < ServerBase
-    attr_reader :base_url, :tools, :session_id, :http_client, :server_info, :capabilities
+    attr_reader :base_url, :tools, :server_info, :capabilities
 
     # @param base_url [String] The base URL of the MCP server
     # @param headers [Hash] Additional headers to include in requests
@@ -33,10 +33,12 @@ module MCPClient
                                  'Cache-Control' => 'no-cache',
                                  'Connection' => 'keep-alive'
                                })
-      @http_client = nil
+      # HTTP client is managed via Faraday
       @tools = nil
       @read_timeout = read_timeout
-      @session_id = nil
+
+      # SSE-provided JSON-RPC endpoint path for POST requests
+      @rpc_endpoint = nil
       @tools_data = nil
       @request_id = 0
       @sse_results = {}
@@ -132,19 +134,7 @@ module MCPClient
       @mutex.synchronize do
         return true if @connection_established
 
-        uri = URI.parse(@base_url)
-        @http_client = Net::HTTP.new(uri.host, uri.port)
-
-        if uri.scheme == 'https'
-          @http_client.use_ssl = true
-          @http_client.verify_mode = OpenSSL::SSL::VERIFY_PEER
-        end
-
-        @http_client.open_timeout = 10
-        @http_client.read_timeout = @read_timeout
-        @http_client.keep_alive_timeout = 60
-
-        @http_client.start
+        # Start SSE listener using Faraday HTTP client
         start_sse_thread
 
         timeout = 10
@@ -179,7 +169,6 @@ module MCPClient
         end
 
         @tools = nil
-        @session_id = nil
         @connection_established = false
         @sse_connected = false
       end
@@ -204,31 +193,31 @@ module MCPClient
     # @return [void]
     def rpc_notify(method, params = {})
       ensure_initialized
-      url_base = @base_url.sub(%r{/sse/?$}, '')
-      uri = URI.parse("#{url_base}/messages?sessionId=#{@session_id}")
-      rpc_http = Net::HTTP.new(uri.host, uri.port)
-      if uri.scheme == 'https'
-        rpc_http.use_ssl = true
-        rpc_http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+      uri = URI.parse(@base_url)
+      base = "#{uri.scheme}://#{uri.host}:#{uri.port}"
+      rpc_ep = @mutex.synchronize { @rpc_endpoint }
+      @rpc_conn ||= Faraday.new(url: base) 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
-      rpc_http.open_timeout = 10
-      rpc_http.read_timeout = @read_timeout
-      rpc_http.keep_alive_timeout = 60
-      rpc_http.start do |http|
-        http_req = Net::HTTP::Post.new(uri)
-        http_req.content_type = 'application/json'
-        http_req.body = { jsonrpc: '2.0', method: method, params: params }.to_json
-        headers = @headers.dup
-        headers.except('Accept', 'Cache-Control').each { |k, v| http_req[k] = v }
-        response = http.request(http_req)
-        unless response.is_a?(Net::HTTPSuccess)
-          raise MCPClient::Errors::ServerError, "Notification failed: #{response.code} #{response.message}"
+      response = @rpc_conn.post(rpc_ep) 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 do |k, v|
+          req.headers[k] = v
         end
+        req.body = { jsonrpc: '2.0', method: method, params: params }.to_json
+      end
+      unless response.success?
+        raise MCPClient::Errors::ServerError, "Notification failed: #{response.status} #{response.reason_phrase}"
       end
     rescue StandardError => e
       raise MCPClient::Errors::TransportError, "Failed to send notification: #{e.message}"
-    ensure
-      rpc_http.finish if rpc_http&.started?
     end
 
     private
@@ -269,60 +258,31 @@ module MCPClient
       return if @sse_thread&.alive?
 
       @sse_thread = Thread.new do
-        sse_http = nil
-        begin
-          uri = URI.parse(@base_url)
-          sse_http = Net::HTTP.new(uri.host, uri.port)
-
-          if uri.scheme == 'https'
-            sse_http.use_ssl = true
-            sse_http.verify_mode = OpenSSL::SSL::VERIFY_PEER
-          end
-
-          sse_http.open_timeout = 10
-          sse_http.read_timeout = @read_timeout
-          sse_http.keep_alive_timeout = 60
-
-          sse_http.start do |http|
-            request = Net::HTTP::Get.new(uri)
-            @headers.each { |k, v| request[k] = v }
-
-            http.request(request) do |response|
-              unless response.is_a?(Net::HTTPSuccess) && response['content-type']&.start_with?('text/event-stream')
-                @mutex.synchronize do
-                  # Signal connection attempt completed (failed)
-                  @connection_established = false
-                  @connection_cv.broadcast
-                end
-                raise MCPClient::Errors::ServerError, 'Server response not OK or not text/event-stream'
-              end
+        uri = URI.parse(@base_url)
+        sse_base = "#{uri.scheme}://#{uri.host}:#{uri.port}"
+        sse_path = uri.request_uri
 
-              @mutex.synchronize do
-                # Signal connection established and SSE ready
-                @sse_connected = true
-                @connection_established = true
-                @connection_cv.broadcast
-              end
+        @sse_conn ||= Faraday.new(url: sse_base) do |f|
+          f.options.open_timeout = 10
+          f.options.timeout = nil
+          f.adapter Faraday.default_adapter
+        end
 
-              response.read_body do |chunk|
-                @logger.debug("SSE chunk received: #{chunk.inspect}")
-                process_sse_chunk(chunk.dup)
-              end
-            end
-          end
-        rescue StandardError
-          # On any SSE thread error, signal connection as established to unblock connect
-          @mutex.synchronize do
-            @connection_established = true
-            @connection_cv.broadcast
-          end
-          nil
-        ensure
-          sse_http&.finish if sse_http&.started?
-          @mutex.synchronize do
-            @sse_connected = false
+        @sse_conn.get(sse_path) do |req|
+          @headers.each { |k, v| req.headers[k] = v }
+          req.options.on_data = proc do |chunk, _bytes|
+            @logger.debug("SSE chunk received: #{chunk.inspect}")
+            process_sse_chunk(chunk.dup)
           end
         end
+      rescue StandardError
+        # On any SSE thread error, signal connection established to unblock connect
+        @mutex.synchronize do
+          @connection_established = true
+          @connection_cv.broadcast
+        end
+      ensure
+        @mutex.synchronize { @sse_connected = false }
       end
     end
 
@@ -352,14 +312,11 @@ module MCPClient
 
       case event[:event]
       when 'endpoint'
-        if event[:data].include?('sessionId=')
-          session_id = event[:data].split('sessionId=').last
-
-          @mutex.synchronize do
-            @session_id = session_id
-            @connection_established = true
-            @connection_cv.broadcast
-          end
+        ep = event[:data]
+        @mutex.synchronize do
+          @rpc_endpoint = ep
+          @connection_established = true
+          @connection_cv.broadcast
         end
       when 'message'
         begin
@@ -475,72 +432,56 @@ module MCPClient
     def send_jsonrpc_request(request)
       @logger.debug("Sending JSON-RPC request: #{request.to_json}")
       uri = URI.parse(@base_url)
-      rpc_http = Net::HTTP.new(uri.host, uri.port)
-
-      if uri.scheme == 'https'
-        rpc_http.use_ssl = true
-        rpc_http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+      base = "#{uri.scheme}://#{uri.host}:#{uri.port}"
+      rpc_ep = @mutex.synchronize { @rpc_endpoint }
+
+      @rpc_conn ||= Faraday.new(url: base) 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
 
-      rpc_http.open_timeout = 10
-      rpc_http.read_timeout = @read_timeout
-      rpc_http.keep_alive_timeout = 60
-
-      begin
-        rpc_http.start do |http|
-          session_id = @mutex.synchronize { @session_id }
-
-          url = if session_id
-                  "#{@base_url.sub(%r{/sse/?$}, '')}/messages?sessionId=#{session_id}"
-                else
-                  "#{@base_url.sub(%r{/sse/?$}, '')}/messages"
-                end
-
-          uri = URI.parse(url)
-          http_request = Net::HTTP::Post.new(uri)
-          http_request.content_type = 'application/json'
-          http_request.body = request.to_json
-
-          headers = @mutex.synchronize { @headers.dup }
-          headers.except('Accept', 'Cache-Control')
-                 .each { |k, v| http_request[k] = v }
+      response = @rpc_conn.post(rpc_ep) 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 do |k, v|
+          req.headers[k] = v
+        end
+        req.body = request.to_json
+      end
+      @logger.debug("Received JSON-RPC response: #{response.status} #{response.body}")
 
-          response = http.request(http_request)
-          @logger.debug("Received JSON-RPC response: #{response.code} #{response.body}")
+      unless response.success?
+        raise MCPClient::Errors::ServerError, "Server returned error: #{response.status} #{response.reason_phrase}"
+      end
 
-          unless response.is_a?(Net::HTTPSuccess)
-            raise MCPClient::Errors::ServerError, "Server returned error: #{response.code} #{response.message}"
+      if @use_sse
+        # Wait for result via SSE channel
+        request_id = request[:id]
+        start_time = Time.now
+        timeout = @read_timeout || 10
+        loop do
+          result = nil
+          @mutex.synchronize do
+            result = @sse_results.delete(request_id) if @sse_results.key?(request_id)
           end
+          return result if result
+          break if Time.now - start_time > timeout
 
-          # If SSE transport is enabled, retrieve the result via the SSE channel
-          if @use_sse
-            request_id = request[:id]
-            start_time = Time.now
-            timeout = @read_timeout || 10
-            result = nil
-
-            loop do
-              @mutex.synchronize do
-                result = @sse_results.delete(request_id) if @sse_results.key?(request_id)
-              end
-              break if result || (Time.now - start_time > timeout)
-
-              sleep 0.1
-            end
-            return result if result
-
-            raise MCPClient::Errors::ToolCallError, "Timeout waiting for SSE result for request #{request_id}"
-          end
-          # Fallback: parse synchronous HTTP JSON response
-          begin
-            data = JSON.parse(response.body)
-            return data['result']
-          rescue JSON::ParserError => e
-            raise MCPClient::Errors::TransportError, "Invalid JSON response from server: #{e.message}"
-          end
+          sleep 0.1
+        end
+        raise MCPClient::Errors::ToolCallError, "Timeout waiting for SSE result for request #{request_id}"
+      else
+        begin
+          data = JSON.parse(response.body)
+          data['result']
+        rescue JSON::ParserError => e
+          raise MCPClient::Errors::TransportError, "Invalid JSON response from server: #{e.message}"
         end
-      ensure
-        rpc_http.finish if rpc_http.started?
       end
     end
   end

data/lib/mcp_client/version.rb

@@ -2,5 +2,5 @@
 
 module MCPClient
   # Current version of the MCP client gem
-  VERSION = '0.4.1'
+  VERSION = '0.5.0'
 end

metadata

@@ -1,15 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: ruby-mcp-client
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Szymon Kurcab
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-24 00:00:00.000000000 Z
+date: 2025-04-25 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rdoc
   requirement: !ruby/object:Gem::Requirement
@@ -98,7 +126,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="