ruby-mcp-client 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 233c83227145cb76167e75784b7eaecef56828743f65f6256c84062bb2290b1e
-  data.tar.gz: 4fb49b0cc82f5bd2b07d15ec200da4f9dced0fce52ddfacd4860a5a689152328
+  metadata.gz: 87cf7d5701adff89363dd653d263189bded230a32232bbbb496d41b4092afdec
+  data.tar.gz: 9a3561d2f97f0ef518cf75dfce82a8521140c9cdc381aaef3f3b3658265a7298
 SHA512:
-  metadata.gz: bdd2b7223f25e4e8516f9bad648854a8e935b823d269762d769a545571960041041082f861a85e559a637e00bb9357541548bd87155bbe9df490c501fb755ade
-  data.tar.gz: 3aef9c1fd10b846e46cc183c072443946a5aa39bfae43245949204e15e89a132df676af927cdabd4cae9c65e4052d220d4012bf0dadaffeb988cddf2a5ab7cfc
+  metadata.gz: 361f1916a531f14ded3292e15ea4947b0e3715d71d2be71dd24ea198616a82c55e516379a59a455b6c14f9fb7b3b9a1d02bdd457fde0b975ece6320bbb6da23b
+  data.tar.gz: b38270ec5a9ddce3a3689e6c8fb6e86efaa35453b6bcc8a590612d02fe1ef86040d62fd30fb95ff02640bb7b822bf8f473ae24fd571ad696069657f98a9d5c20

data/README.md

@@ -55,6 +55,7 @@ client = MCPClient.create_client(
       read_timeout: 30, # Optional timeout in seconds (default: 30)
       retries: 3,       # Optional number of retry attempts (default: 0)
       retry_backoff: 1  # Optional backoff delay in seconds (default: 1)
+      # Native support for tool streaming via call_tool_streaming method
     )
   ]
 )
@@ -75,7 +76,8 @@ results = client.call_tools([
   { name: 'tool2', parameters: { key2: 'value2' } }
 ])
 
-# Stream results (for supported transports like SSE)
+# Stream results (supported by the SSE transport)
+# Returns an Enumerator that yields results as they become available
 client.call_tool_streaming('streaming_tool', { param: 'value' }).each do |chunk|
   # Process each chunk as it arrives
   puts chunk
@@ -85,6 +87,23 @@ end
 openai_tools = client.to_openai_tools
 anthropic_tools = client.to_anthropic_tools
 
+# Register for server notifications
+client.on_notification do |server, method, params|
+  puts "Server notification: #{server.class} - #{method} - #{params}"
+  # Handle specific notifications based on method name
+  # 'notifications/tools/list_changed' is handled automatically by the client
+end
+
+# Send custom JSON-RPC requests or notifications
+client.send_rpc('custom_method', params: { key: 'value' }, server: :sse) # Uses specific server
+result = client.send_rpc('another_method', params: { data: 123 }) # Uses first available server
+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
+
 # Clear cached tools to force fresh fetch on next list
 client.clear_cache
 # Clean up connections
@@ -192,11 +211,18 @@ This client works with any MCP-compatible server, including:
 
 The SSE client implementation provides these key features:
 
-- **Robust connection handling**: Properly manages HTTP/HTTPS connections with configurable timeouts
+- **Robust connection handling**: Properly manages HTTP/HTTPS connections with configurable timeouts and retries
 - **Thread safety**: All operations are thread-safe using monitors and synchronized access
 - **Reliable error handling**: Comprehensive error handling for network issues, timeouts, and malformed responses
-- **JSON-RPC over SSE**: Full implementation of JSON-RPC 2.0 over SSE transport
-- **Streaming support**: Native streaming for real-time updates
+- **JSON-RPC over SSE**: Full implementation of JSON-RPC 2.0 over SSE transport with initialize handshake
+- **Streaming support**: Native streaming for real-time updates via the `call_tool_streaming` method, which returns an Enumerator for processing results as they arrive
+- **Notification support**: Built-in handling for JSON-RPC notifications with automatic tool cache invalidation and custom notification callback support
+- **Custom RPC methods**: Send any custom JSON-RPC method or notification through `send_rpc` and `send_notification`
+- **Configurable retries**: All RPC requests support configurable retries with exponential backoff
+- **Consistent logging**: Tagged, leveled logging across all components for better debugging
+- **Graceful fallbacks**: Automatic fallback to synchronous HTTP when SSE connection fails
+- **URL normalization**: Consistent URL handling that respects user-provided formats
+- **Server connectivity check**: Built-in `ping` method to test server connectivity and health
 
 ## Requirements
 
@@ -211,6 +237,16 @@ To implement a compatible MCP server you must:
 - Respond to `list_tools` requests with a JSON list of tools
 - Respond to `call_tool` requests by executing the specified tool
 - Return results (or errors) in JSON format
+- Optionally send JSON-RPC notifications for events like tool updates
+
+### JSON-RPC Notifications
+
+The client supports JSON-RPC notifications from the server:
+
+- Default notification handler for `notifications/tools/list_changed` to automatically clear the tool cache
+- Custom notification handling via the `on_notification` method
+- Callbacks receive the server instance, method name, and parameters
+- Multiple notification listeners can be registered
 
 ## Tool Schema
 

data/lib/mcp_client/client.rb

@@ -19,11 +19,24 @@ module MCPClient
     # @param logger [Logger, nil] optional logger, defaults to STDOUT
     def initialize(mcp_server_configs: [], logger: nil)
       @logger = logger || Logger.new($stdout, level: Logger::WARN)
+      @logger.progname = self.class.name
+      @logger.formatter = proc { |severity, _datetime, progname, msg| "#{severity} [#{progname}] #{msg}\n" }
       @servers = mcp_server_configs.map do |config|
         @logger.debug("Creating server with config: #{config.inspect}")
         MCPClient::ServerFactory.create(config)
       end
       @tool_cache = {}
+      # JSON-RPC notification listeners
+      @notification_listeners = []
+      # 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
+          @notification_listeners.each { |cb| cb.call(server, method, params) }
+        end
+      end
     end
 
     # Lists all available tools from all connected MCP servers
@@ -92,6 +105,13 @@ module MCPClient
       @tool_cache.clear
     end
 
+    # Register a callback for JSON-RPC notifications from servers
+    # @yield [server, method, params]
+    # @return [void]
+    def on_notification(&block)
+      @notification_listeners << block
+    end
+
     # Find all tools whose name matches the given pattern (String or Regexp)
     # @param pattern [String, Regexp] pattern to match tool names
     # @return [Array<MCPClient::Tool>] matching tools
@@ -143,6 +163,28 @@ module MCPClient
       end
     end
 
+    # Ping the MCP server to check connectivity
+    # @param params [Hash] optional parameters for the ping request
+    # @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)
+      if server_index.nil?
+        # Ping first available server
+        raise MCPClient::Errors::ServerNotFound, 'No server available for ping' if @servers.empty?
+
+        @servers.first.ping(params)
+      else
+        # Ping specified server
+        if server_index >= @servers.length
+          raise MCPClient::Errors::ServerNotFound,
+                "Server at index #{server_index} not found"
+        end
+
+        @servers[server_index].ping(params)
+      end
+    end
+
     private
 
     # Validate parameters against tool JSON schema (checks required properties)

data/lib/mcp_client/server_base.rb

@@ -27,5 +27,36 @@ module MCPClient
     def cleanup
       raise NotImplementedError, 'Subclasses must implement cleanup'
     end
+
+    # Send a JSON-RPC request and return the result
+    # @param method [String] JSON-RPC method name
+    # @param params [Hash] parameters for the request
+    # @return [Object] result field from the JSON-RPC response
+    # @raise [MCPClient::Errors::ServerError, MCPClient::Errors::TransportError, MCPClient::Errors::ToolCallError]
+    def rpc_request(method, params = {})
+      raise NotImplementedError, 'Subclasses must implement rpc_request'
+    end
+
+    # Send a JSON-RPC notification (no response expected)
+    # @param method [String] JSON-RPC method name
+    # @param params [Hash] parameters for the notification
+    # @return [void]
+    def rpc_notify(method, params = {})
+      raise NotImplementedError, 'Subclasses must implement rpc_notify'
+    end
+
+    # Ping the MCP server to check connectivity
+    # @param params [Hash] optional parameters for the ping request
+    # @return [Object] result from the ping request
+    def ping(params = {})
+      rpc_request('ping', params)
+    end
+
+    # Register a callback to receive JSON-RPC notifications
+    # @yield [method, params] invoked when a notification is received
+    # @return [void]
+    def on_notification(&block)
+      @notification_callback = block
+    end
   end
 end

data/lib/mcp_client/server_factory.rb

@@ -9,7 +9,13 @@ module MCPClient
     def self.create(config)
       case config[:type]
       when 'stdio'
-        MCPClient::ServerStdio.new(command: config[:command])
+        MCPClient::ServerStdio.new(
+          command: config[:command],
+          retries: config[:retries] || 0,
+          retry_backoff: config[:retry_backoff] || 1,
+          read_timeout: config[:read_timeout] || MCPClient::ServerStdio::READ_TIMEOUT,
+          logger: config[:logger]
+        )
       when 'sse'
         MCPClient::ServerSSE.new(
           base_url: config[:base_url],

data/lib/mcp_client/server_sse.rb

@@ -11,7 +11,7 @@ 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
+    attr_reader :base_url, :tools, :session_id, :http_client, :server_info, :capabilities
 
     # @param base_url [String] The base URL of the MCP server
     # @param headers [Hash] Additional headers to include in requests
@@ -22,9 +22,12 @@ module MCPClient
     def initialize(base_url:, headers: {}, read_timeout: 30, retries: 0, retry_backoff: 1, logger: nil)
       super()
       @logger = logger || Logger.new($stdout, level: Logger::WARN)
+      @logger.progname = self.class.name
+      @logger.formatter = proc { |severity, _datetime, progname, msg| "#{severity} [#{progname}] #{msg}\n" }
       @max_retries = retries
       @retry_backoff = retry_backoff
-      @base_url = base_url.end_with?('/') ? base_url : "#{base_url}/"
+      # Normalize base_url: strip any trailing slash, use exactly as provided
+      @base_url = base_url.chomp('/')
       @headers = headers.merge({
                                  'Accept' => 'text/event-stream',
                                  'Cache-Control' => 'no-cache',
@@ -42,6 +45,9 @@ module MCPClient
       @sse_connected = false
       @connection_established = false
       @connection_cv = @mutex.new_cond
+      @initialized = false
+      # Whether to use SSE transport; may disable if handshake fails
+      @use_sse = true
     end
 
     # Stream tool call fallback for SSE transport (yields single result)
@@ -64,7 +70,7 @@ module MCPClient
         return @tools if @tools
       end
 
-      connect
+      ensure_initialized
 
       begin
         tools_data = request_tools_list
@@ -93,7 +99,7 @@ module MCPClient
     # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
     # @raise [MCPClient::Errors::ToolCallError] for other errors during tool execution
     def call_tool(tool_name, parameters)
-      connect
+      ensure_initialized
 
       begin
         request_id = @mutex.synchronize { @request_id += 1 }
@@ -179,8 +185,85 @@ module MCPClient
       end
     end
 
+    # Generic JSON-RPC request: send method with params and return result
+    # @param method [String] JSON-RPC method name
+    # @param params [Hash] parameters for the request
+    # @return [Object] result from JSON-RPC response
+    def rpc_request(method, params = {})
+      ensure_initialized
+      with_retry do
+        request_id = @mutex.synchronize { @request_id += 1 }
+        request = { jsonrpc: '2.0', id: request_id, method: method, params: params }
+        send_jsonrpc_request(request)
+      end
+    end
+
+    # Send a JSON-RPC notification (no response expected)
+    # @param method [String] JSON-RPC method name
+    # @param params [Hash] parameters for the notification
+    # @return [void]
+    def rpc_notify(method, params = {})
+      ensure_initialized
+      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
+      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}"
+        end
+      end
+    rescue StandardError => e
+      raise MCPClient::Errors::TransportError, "Failed to send notification: #{e.message}"
+    ensure
+      rpc_http.finish if rpc_http&.started?
+    end
+
     private
 
+    # Ensure SSE initialization handshake has been performed
+    def ensure_initialized
+      return if @initialized
+
+      connect
+      perform_initialize
+
+      @initialized = true
+    end
+
+    # Perform JSON-RPC initialize handshake with the MCP server
+    def perform_initialize
+      request_id = @mutex.synchronize { @request_id += 1 }
+      json_rpc_request = {
+        jsonrpc: '2.0',
+        id: request_id,
+        method: 'initialize',
+        params: {
+          'protocolVersion' => MCPClient::VERSION,
+          'capabilities' => {},
+          'clientInfo' => { 'name' => 'ruby-mcp-client', 'version' => MCPClient::VERSION }
+        }
+      }
+      @logger.debug("Performing initialize RPC: #{json_rpc_request}")
+      result = send_jsonrpc_request(json_rpc_request)
+      return unless result.is_a?(Hash)
+
+      @server_info = result['serverInfo'] if result.key?('serverInfo')
+      @capabilities = result['capabilities'] if result.key?('capabilities')
+    end
+
     # Start the SSE thread to listen for events
     def start_sse_thread
       return if @sse_thread&.alive?
@@ -207,6 +290,7 @@ module MCPClient
             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
@@ -214,7 +298,10 @@ module MCPClient
               end
 
               @mutex.synchronize do
+                # Signal connection established and SSE ready
                 @sse_connected = true
+                @connection_established = true
+                @connection_cv.broadcast
               end
 
               response.read_body do |chunk|
@@ -224,6 +311,11 @@ module MCPClient
             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?
@@ -272,6 +364,11 @@ module MCPClient
       when 'message'
         begin
           data = JSON.parse(event[:data])
+          # Dispatch JSON-RPC notifications (no id, has method)
+          if data['method'] && !data.key?('id')
+            @notification_callback&.call(data['method'], data['params'])
+            return
+          end
 
           @mutex.synchronize do
             @tools_data = data['result']['tools'] if data['result'] && data['result']['tools']
@@ -415,37 +512,31 @@ module MCPClient
             raise MCPClient::Errors::ServerError, "Server returned error: #{response.code} #{response.message}"
           end
 
-          if response.code == '202'
+          # If SSE transport is enabled, retrieve the result via the SSE channel
+          if @use_sse
             request_id = request[:id]
-
             start_time = Time.now
-            timeout = 10
+            timeout = @read_timeout || 10
             result = nil
 
             loop do
               @mutex.synchronize do
-                if @sse_results[request_id]
-                  result = @sse_results[request_id]
-                  @sse_results.delete(request_id)
-                end
+                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}"
-
-          else
-            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
+          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
         end
       ensure

data/lib/mcp_client/server_stdio.rb

@@ -16,8 +16,9 @@ module MCPClient
     # @param command [String, Array] the stdio command to launch the MCP JSON-RPC server
     # @param retries [Integer] number of retry attempts on transient errors
     # @param retry_backoff [Numeric] base delay in seconds for exponential backoff
+    # @param read_timeout [Numeric] timeout in seconds for reading responses
     # @param logger [Logger, nil] optional logger
-    def initialize(command:, retries: 0, retry_backoff: 1, logger: nil)
+    def initialize(command:, retries: 0, retry_backoff: 1, read_timeout: READ_TIMEOUT, logger: nil)
       super()
       @command = command.is_a?(Array) ? command.join(' ') : command
       @mutex = Mutex.new
@@ -26,8 +27,11 @@ module MCPClient
       @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" }
       @max_retries = retries
       @retry_backoff = retry_backoff
+      @read_timeout = read_timeout
     end
 
     # Connect to the MCP server by launching the command process via stdout/stdin
@@ -57,6 +61,12 @@ module MCPClient
     def handle_line(line)
       msg = JSON.parse(line)
       @logger.debug("Received line: #{line.chomp}")
+      # Dispatch JSON-RPC notifications (no id, has method)
+      if msg['method'] && !msg.key?('id')
+        @notification_callback&.call(msg['method'], msg['params'])
+        return
+      end
+      # Handle standard JSON-RPC responses
       id = msg['id']
       return unless id
 
@@ -188,7 +198,7 @@ module MCPClient
     end
 
     def wait_response(id)
-      deadline = Time.now + READ_TIMEOUT
+      deadline = Time.now + @read_timeout
       @mutex.synchronize do
         until @pending.key?(id)
           remaining = deadline - Time.now
@@ -213,5 +223,45 @@ module MCPClient
         yielder << call_tool(tool_name, parameters)
       end
     end
+
+    # Generic JSON-RPC request: send method with params and wait for result
+    # @param method [String] JSON-RPC method
+    # @param params [Hash] parameters for the request
+    # @return [Object] result from JSON-RPC response
+    def rpc_request(method, params = {})
+      ensure_initialized
+      attempts = 0
+      begin
+        req_id = next_id
+        req = { 'jsonrpc' => '2.0', 'id' => req_id, 'method' => method, 'params' => params }
+        send_request(req)
+        res = wait_response(req_id)
+        if (err = res['error'])
+          raise MCPClient::Errors::ServerError, err['message']
+        end
+
+        res['result']
+      rescue MCPClient::Errors::ServerError, MCPClient::Errors::TransportError, IOError, Errno::ETIMEDOUT,
+             Errno::ECONNRESET => e
+        attempts += 1
+        if attempts <= @max_retries
+          delay = @retry_backoff * (2**(attempts - 1))
+          @logger.debug("Retry attempt #{attempts} after error: #{e.message}, sleeping #{delay}s")
+          sleep(delay)
+          retry
+        end
+        raise
+      end
+    end
+
+    # Send a JSON-RPC notification (no response expected)
+    # @param method [String] JSON-RPC method
+    # @param params [Hash] parameters for the notification
+    # @return [void]
+    def rpc_notify(method, params = {})
+      ensure_initialized
+      notif = { 'jsonrpc' => '2.0', 'method' => method, 'params' => params }
+      @stdin.puts(notif.to_json)
+    end
   end
 end

data/lib/mcp_client/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-mcp-client
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Szymon Kurcab
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-23 00:00:00.000000000 Z
+date: 2025-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rdoc