ruby-mcp-client 0.5.0 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79a86302428257274c4e620fae0b7ad45c6229cf381a956ef3b0a7e736f17f62
-  data.tar.gz: 80727b0aa48a992054dafd7c484eb611404b47d878ef2869e59e937a815718dc
+  metadata.gz: fbd3caf1e80f6c2caf625495072211b827ae08e3542fa33306537918d0b6eb5f
+  data.tar.gz: 1eea548ba10e7de3fec68a92d449e4552fde3c5920af045e2e828925dba2aad7
 SHA512:
-  metadata.gz: 977acc1ae8ca48a17b7827f006ed82578eb7bc24bf9ba08b03e77493e3447febc82287242a410861fb675b1fb74b0b67525dc4f92c9f8b448cd1cad2e3afc875
-  data.tar.gz: f940ed03a52065a5d8687d1722a588693d69a9c69f820771b328fed3b1bb69068fc7110dbedc745ea4fc42d047afa8afe975b2ed821aa5d33ac8c4e25fac9da7
+  metadata.gz: e8eae783bd1e6a4db013a934e0686641befaec435fb288531ce85899efc0a66023d3d174dedffae21f75089f406f6368f286f13644701fbdee747492b795535b
+  data.tar.gz: 534cc5c88f8f3737c5fc3e684174980af74ac18398532e4b5698490b451b5fc5ff0831ca48639119445c71f4afa94ba3fca94ff81edfa03d1e3ba34a73c4f1b1

data/README.md

@@ -56,10 +56,22 @@ client = MCPClient.create_client(
       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
-    )
-  ]
+)  ]
 )
 
+# Or load server definitions from a JSON file
+client = MCPClient.create_client(
+  server_definition_file: 'path/to/server_definition.json'
+)
+
+# MCP server configuration JSON format can be:
+# 1. A single server object: 
+#    { "type": "sse", "url": "http://example.com/sse" }
+# 2. An array of server objects: 
+#    [{ "type": "stdio", "command": "npx server" }, { "type": "sse", "url": "http://..." }]
+# 3. An object with "mcpServers" key containing named servers:
+#    { "mcpServers": { "server1": { "type": "sse", "url": "http://..." } } }
+
 # List available tools
 tools = client.list_tools
 
@@ -260,6 +272,62 @@ 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 Definition Files
+
+You can define MCP server configurations in JSON files for easier management:
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "type": "sse",
+      "url": "http://localhost:8931/sse",
+      "headers": {
+        "Authorization": "Bearer TOKEN"
+      }
+    },
+    "filesystem": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
+      "env": {
+        "DEBUG": "true"
+      }
+    }
+  }
+}
+```
+
+A simpler example used in the Playwright demo (found in `examples/sample_server_definition.json`):
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "url": "http://localhost:8931/sse",
+      "headers": {},
+      "comment": "Local Playwright MCP Server running on port 8931"
+    }
+  }
+}
+```
+
+Load this configuration with:
+
+```ruby
+client = MCPClient.create_client(server_definition_file: 'path/to/definition.json')
+```
+
+The JSON format supports:
+1. A single server object: `{ "type": "sse", "url": "..." }`
+2. An array of server objects: `[{ "type": "stdio", ... }, { "type": "sse", ... }]`
+3. An object with named servers under `mcpServers` key (as shown above)
+
+Special configuration options:
+- `comment` and `description` are reserved keys that are ignored during parsing and can be used for documentation
+- Server type can be inferred from the presence of either `command` (for stdio) or `url` (for SSE)
+- All string values in arrays (like `args`) are automatically converted to strings
+
 ## Key Features
 
 ### Client Features
@@ -274,6 +342,7 @@ This client works with any MCP-compatible server, including:
 - **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
+- **JSON configuration** - Support for server definition files in JSON format
 
 ### Server-Sent Events (SSE) Implementation
 

data/lib/mcp_client/config_parser.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'logger'
+
+module MCPClient
+  # Parses MCP server definition JSON files into configuration hashes
+  class ConfigParser
+    # Reserved JSON keys that shouldn't be included in final config
+    RESERVED_KEYS = %w[comment description].freeze
+
+    # @param file_path [String] path to JSON file containing 'mcpServers' definitions
+    # @param logger [Logger, nil] optional logger for warnings
+    def initialize(file_path, logger: nil)
+      @file_path = file_path
+      @logger = logger || Logger.new($stdout, level: Logger::WARN)
+    end
+
+    # Parse the JSON config and return a mapping of server names to clean config hashes
+    # @return [Hash<String, Hash>] server name => config hash with symbol keys
+    def parse
+      content = File.read(@file_path)
+      data = JSON.parse(content)
+
+      servers_data = extract_servers_data(data)
+      servers_data = filter_reserved_keys(servers_data)
+
+      result = {}
+      servers_data.each do |server_name, config|
+        next unless validate_server_config(config, server_name)
+
+        server_config = process_server_config(config, server_name)
+        result[server_name] = server_config if server_config
+      end
+
+      result
+    rescue Errno::ENOENT
+      raise Errno::ENOENT, "Server definition file not found: #{@file_path}"
+    rescue JSON::ParserError => e
+      raise JSON::ParserError, "Invalid JSON in #{@file_path}: #{e.message}"
+    end
+
+    # Extract server data from parsed JSON
+    # @param data [Object] parsed JSON data
+    # @return [Hash] normalized server data
+    def extract_servers_data(data)
+      if data.is_a?(Hash) && data.key?('mcpServers') && data['mcpServers'].is_a?(Hash)
+        data['mcpServers']
+      elsif data.is_a?(Array)
+        h = {}
+        data.each_with_index { |cfg, idx| h[idx.to_s] = cfg }
+        h
+      elsif data.is_a?(Hash)
+        { '0' => data }
+      else
+        @logger.warn("Invalid root JSON structure in #{@file_path}: #{data.class}")
+        {}
+      end
+    end
+
+    # Validate server configuration is a hash
+    # @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)
+      return true if config.is_a?(Hash)
+
+      @logger.warn("Configuration for server '#{server_name}' is not an object; skipping.")
+      false
+    end
+
+    # Process a single server configuration
+    # @param config [Hash] server configuration to process
+    # @param server_name [String] name of the server
+    # @return [Hash, nil] processed configuration or nil if invalid
+    def process_server_config(config, server_name)
+      type = determine_server_type(config, server_name)
+      return nil unless type
+
+      clean = { type: type.to_s }
+      case type.to_s
+      when 'stdio'
+        parse_stdio_config(clean, config, server_name)
+      when 'sse'
+        return nil unless parse_sse_config(clean, config, server_name)
+      else
+        @logger.warn("Unrecognized type '#{type}' for server '#{server_name}'; skipping.")
+        return nil
+      end
+
+      clean
+    end
+
+    # Determine the type of server from its configuration
+    # @param config [Hash] server configuration
+    # @param server_name [String] name of the server for logging
+    # @return [String, nil] determined server type or nil if cannot be determined
+    def determine_server_type(config, server_name)
+      type = config['type']
+      return type if type
+
+      inferred_type = if config.key?('command') || config.key?('args') || config.key?('env')
+                        'stdio'
+                      elsif config.key?('url')
+                        'sse'
+                      end
+
+      if inferred_type
+        @logger.warn("'type' not specified for server '#{server_name}', inferring as '#{inferred_type}'.")
+        return inferred_type
+      end
+
+      @logger.warn("Could not determine type for server '#{server_name}' (missing 'command' or 'url'); skipping.")
+      nil
+    end
+
+    private
+
+    # Parse stdio-specific configuration
+    # @param clean [Hash] clean configuration hash to update
+    # @param config [Hash] raw configuration from JSON
+    # @param server_name [String] name of the server for error reporting
+    def parse_stdio_config(clean, config, server_name)
+      # Command is required
+      cmd = config['command']
+      unless cmd.is_a?(String)
+        @logger.warn("'command' for server '#{server_name}' is not a string; converting to string.")
+        cmd = cmd.to_s
+      end
+
+      # Args are optional
+      args = config['args']
+      if args.is_a?(Array)
+        args = args.map(&:to_s)
+      elsif args
+        @logger.warn("'args' for server '#{server_name}' is not an array; treating as single argument.")
+        args = [args.to_s]
+      else
+        args = []
+      end
+
+      # Environment variables are optional
+      env = config['env']
+      env = env.is_a?(Hash) ? env.transform_keys(&:to_s) : {}
+
+      # Update clean config
+      clean[:command] = cmd
+      clean[:args] = args
+      clean[:env] = env
+    end
+
+    # Parse SSE-specific configuration
+    # @param clean [Hash] clean configuration hash to update
+    # @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)
+      # URL is required
+      source = config['url']
+      unless source
+        @logger.warn("SSE server '#{server_name}' is missing required 'url' property; skipping.")
+        return false
+      end
+
+      unless source.is_a?(String)
+        @logger.warn("'url' for server '#{server_name}' is not a string; converting to string.")
+        source = source.to_s
+      end
+
+      # Headers are optional
+      headers = config['headers']
+      headers = headers.is_a?(Hash) ? headers.transform_keys(&:to_s) : {}
+
+      # Update clean config
+      clean[:url] = source
+      clean[:headers] = headers
+      true
+    end
+
+    # Filter out reserved keys from configuration objects
+    # @param data [Hash] configuration data
+    # @return [Hash] filtered configuration data
+    def filter_reserved_keys(data)
+      return data unless data.is_a?(Hash)
+
+      result = {}
+      data.each do |key, value|
+        # Skip reserved keys at server level
+        next if RESERVED_KEYS.include?(key)
+
+        # If value is a hash, recursively filter its keys too
+        if value.is_a?(Hash)
+          filtered_value = value.dup
+          RESERVED_KEYS.each { |reserved| filtered_value.delete(reserved) }
+          result[key] = filtered_value
+        else
+          result[key] = value
+        end
+      end
+      result
+    end
+  end
+end

data/lib/mcp_client/server_sse.rb

@@ -48,6 +48,7 @@ module MCPClient
       @connection_established = false
       @connection_cv = @mutex.new_cond
       @initialized = false
+      @auth_error = nil
       # Whether to use SSE transport; may disable if handshake fails
       @use_sse = true
     end
@@ -131,25 +132,30 @@ module MCPClient
     # @return [Boolean] true if connection was successful
     # @raise [MCPClient::Errors::ConnectionError] if connection fails
     def connect
-      @mutex.synchronize do
-        return true if @connection_established
+      return true if @mutex.synchronize { @connection_established }
 
-        # Start SSE listener using Faraday HTTP client
+      begin
         start_sse_thread
+        effective_timeout = [@read_timeout || 30, 30].min
+        wait_for_connection(timeout: effective_timeout)
+        true
+      rescue MCPClient::Errors::ConnectionError => e
+        cleanup
+        # Check for stored auth error first, as it's more specific
+        auth_error = @mutex.synchronize { @auth_error }
+        raise MCPClient::Errors::ConnectionError, auth_error if auth_error
+
+        raise MCPClient::Errors::ConnectionError, e.message if e.message.include?('Authorization failed')
+
+        raise MCPClient::Errors::ConnectionError, "Failed to connect to MCP server at #{@base_url}: #{e.message}"
+      rescue StandardError => e
+        cleanup
+        # Check for stored auth error
+        auth_error = @mutex.synchronize { @auth_error }
+        raise MCPClient::Errors::ConnectionError, auth_error if auth_error
 
-        timeout = 10
-        success = @connection_cv.wait(timeout) { @connection_established }
-
-        unless success
-          cleanup
-          raise MCPClient::Errors::ConnectionError, 'Timed out waiting for SSE connection to be established'
-        end
-
-        @connection_established
+        raise MCPClient::Errors::ConnectionError, "Failed to connect to MCP server at #{@base_url}: #{e.message}"
       end
-    rescue StandardError => e
-      cleanup
-      raise MCPClient::Errors::ConnectionError, "Failed to connect to MCP server at #{@base_url}: #{e.message}"
     end
 
     # Clean up the server connection
@@ -171,6 +177,7 @@ module MCPClient
         @tools = nil
         @connection_established = false
         @sse_connected = false
+        # Don't clear auth error as we need it for reporting the correct error
       end
     end
 
@@ -222,6 +229,25 @@ module MCPClient
 
     private
 
+    # Wait for SSE connection to be established with periodic checks
+    # @param timeout [Integer] Maximum time to wait in seconds
+    # @raise [MCPClient::Errors::ConnectionError] if timeout expires
+    def wait_for_connection(timeout:)
+      @mutex.synchronize do
+        deadline = Time.now + timeout
+
+        until @connection_established
+          remaining = [1, deadline - Time.now].min
+          break if remaining <= 0 || @connection_cv.wait(remaining) { @connection_established }
+        end
+
+        unless @connection_established
+          cleanup
+          raise MCPClient::Errors::ConnectionError, 'Timed out waiting for SSE connection to be established'
+        end
+      end
+    end
+
     # Ensure SSE initialization handshake has been performed
     def ensure_initialized
       return if @initialized
@@ -253,34 +279,85 @@ module MCPClient
       @capabilities = result['capabilities'] if result.key?('capabilities')
     end
 
+    # Set up the SSE connection
+    # @param uri [URI] The parsed base URL
+    # @return [Faraday::Connection] The configured Faraday connection
+    def setup_sse_connection(uri)
+      sse_base = "#{uri.scheme}://#{uri.host}:#{uri.port}"
+
+      @sse_conn ||= Faraday.new(url: sse_base) do |f|
+        f.options.open_timeout = 10
+        f.options.timeout = nil
+        f.request :retry, max: @max_retries, interval: @retry_backoff, backoff_factor: 2
+        f.adapter Faraday.default_adapter
+      end
+
+      # Use response handling with status check
+      @sse_conn.builder.use Faraday::Response::RaiseError
+      @sse_conn
+    end
+
+    # Handle authorization errors from Faraday
+    # @param error [Faraday::Error] The authorization error
+    # @raise [MCPClient::Errors::ConnectionError] with appropriate message
+    def handle_sse_auth_error(error)
+      error_message = "Authorization failed: HTTP #{error.response[:status]}"
+      @logger.error(error_message)
+
+      @mutex.synchronize do
+        @auth_error = error_message
+        @connection_established = false
+        @connection_cv.broadcast
+      end
+      raise MCPClient::Errors::ConnectionError, error_message
+    end
+
+    # Reset connection state and signal waiting threads
+    def reset_connection_state
+      @mutex.synchronize do
+        @connection_established = false
+        @connection_cv.broadcast
+      end
+    end
+
     # Start the SSE thread to listen for events
     def start_sse_thread
       return if @sse_thread&.alive?
 
       @sse_thread = Thread.new do
         uri = URI.parse(@base_url)
-        sse_base = "#{uri.scheme}://#{uri.host}:#{uri.port}"
         sse_path = uri.request_uri
+        conn = setup_sse_connection(uri)
 
-        @sse_conn ||= Faraday.new(url: sse_base) do |f|
-          f.options.open_timeout = 10
-          f.options.timeout = nil
-          f.adapter Faraday.default_adapter
+        # Reset connection state
+        @mutex.synchronize do
+          @sse_connected = false
+          @connection_established = false
         end
 
-        @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)
+        begin
+          conn.get(sse_path) do |req|
+            @headers.each { |k, v| req.headers[k] = v }
+
+            req.options.on_data = proc do |chunk, _bytes|
+              process_sse_chunk(chunk.dup) if chunk && !chunk.empty?
+            end
           end
+        rescue Faraday::UnauthorizedError, Faraday::ForbiddenError => e
+          handle_sse_auth_error(e)
+        rescue Faraday::Error => e
+          @logger.error("Failed SSE connection: #{e.message}")
+          raise
         end
-      rescue StandardError
-        # On any SSE thread error, signal connection established to unblock connect
-        @mutex.synchronize do
-          @connection_established = true
-          @connection_cv.broadcast
-        end
+      rescue MCPClient::Errors::ConnectionError => e
+        # Re-raise connection errors to propagate them
+        # Signal connect method to stop waiting
+        reset_connection_state
+        raise e
+      rescue StandardError => e
+        @logger.error("SSE connection error: #{e.message}")
+        # Signal connect method to avoid deadlock
+        reset_connection_state
       ensure
         @mutex.synchronize { @sse_connected = false }
       end
@@ -290,18 +367,126 @@ module MCPClient
     # @param chunk [String] the chunk to process
     def process_sse_chunk(chunk)
       @logger.debug("Processing SSE chunk: #{chunk.inspect}")
-      local_buffer = nil
 
+      # 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'
+
+            @mutex.synchronize do
+              @auth_error = "Authorization failed: #{error_message}"
+
+              @connection_established = false
+              @connection_cv.broadcast
+            end
+
+            raise MCPClient::Errors::ConnectionError, "Authorization failed: #{error_message}"
+          end
+        rescue JSON::ParserError
+          # Not valid JSON, process normally
+        end
+      end
+
+      event_buffers = nil
       @mutex.synchronize do
         @buffer += chunk
 
+        # Extract all complete events from the buffer
+        event_buffers = []
         while (event_end = @buffer.index("\n\n"))
           event_data = @buffer.slice!(0, event_end + 2)
-          local_buffer = event_data
+          event_buffers << event_data
         end
       end
 
-      parse_and_handle_sse_event(local_buffer) if local_buffer
+      # Process extracted events outside the mutex to avoid deadlocks
+      event_buffers&.each { |event_data| parse_and_handle_sse_event(event_data) }
+    end
+
+    # Handle SSE endpoint event
+    # @param data [String] The endpoint path
+    def handle_endpoint_event(data)
+      @mutex.synchronize do
+        @rpc_endpoint = data
+        @sse_connected = true
+        @connection_established = true
+        @connection_cv.broadcast
+      end
+    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
+    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
+    end
+
+    # Handle authorization error in SSE message
+    # @param error_message [String] The error message from the server
+    def handle_sse_auth_error_message(error_message)
+      @mutex.synchronize do
+        @auth_error = "Authorization failed: #{error_message}"
+        @connection_established = false
+        @connection_cv.broadcast
+      end
+
+      raise MCPClient::Errors::ConnectionError, "Authorization failed: #{error_message}"
+    end
+
+    # Process error messages in SSE responses
+    # @param data [Hash] The parsed SSE message data
+    def process_error_in_message(data)
+      return unless data['error']
+
+      error_message = data['error']['message'] || 'Unknown server error'
+      error_code = data['error']['code']
+
+      # Handle unauthorized errors (close connection immediately)
+      handle_sse_auth_error_message(error_message) if authorization_error?(error_message, error_code)
+
+      @logger.error("Server error: #{error_message}")
+      true # Error was processed
+    end
+
+    # Process JSON-RPC notifications
+    # @param data [Hash] The parsed SSE message data
+    # @return [Boolean] True if a notification was processed
+    def process_notification(data)
+      return false unless data['method'] && !data.key?('id')
+
+      @notification_callback&.call(data['method'], data['params'])
+      true
+    end
+
+    # Process JSON-RPC responses
+    # @param data [Hash] The parsed SSE message data
+    # @return [Boolean] True if a response was processed
+    def process_response(data)
+      return false unless data['id']
+
+      @mutex.synchronize do
+        # Store tools data if present
+        @tools_data = data['result']['tools'] if data['result'] && data['result']['tools']
+
+        # Store response for the waiting request
+        if data['error']
+          @sse_results[data['id']] = {
+            'isError' => true,
+            'content' => [{ 'type' => 'text', 'text' => data['error'].to_json }]
+          }
+        elsif data['result']
+          @sse_results[data['id']] = data['result']
+        end
+      end
+
+      true
     end
 
     # Parse and handle an SSE event
@@ -312,38 +497,35 @@ module MCPClient
 
       case event[:event]
       when 'endpoint'
-        ep = event[:data]
-        @mutex.synchronize do
-          @rpc_endpoint = ep
-          @connection_established = true
-          @connection_cv.broadcast
-        end
+        handle_endpoint_event(event[:data])
+      when 'ping'
+        # Received ping event, no action needed
       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
+        handle_message_event(event)
+      end
+    end
 
-          @mutex.synchronize do
-            @tools_data = data['result']['tools'] if data['result'] && data['result']['tools']
-
-            if data['id']
-              if data['error']
-                @sse_results[data['id']] = {
-                  'isError' => true,
-                  'content' => [{ 'type' => 'text', 'text' => data['error'].to_json }]
-                }
-              elsif data['result']
-                @sse_results[data['id']] = data['result']
-              end
-            end
-          end
-        rescue JSON::ParserError
-          nil
-        end
+    # Handle a message event from SSE
+    # @param event [Hash] The parsed SSE event
+    def handle_message_event(event)
+      return if event[:data].empty?
+
+      begin
+        data = JSON.parse(event[:data])
+
+        # Process the message in order of precedence
+        return if process_error_in_message(data)
+
+        return if process_notification(data)
+
+        process_response(data)
+      rescue MCPClient::Errors::ConnectionError
+        # Re-raise connection errors to propagate to the calling code
+        raise
+      rescue JSON::ParserError => e
+        @logger.warn("Failed to parse JSON from event data: #{e.message}")
+      rescue StandardError => e
+        @logger.error("Error processing SSE event: #{e.message}")
       end
     end
 
@@ -351,14 +533,19 @@ module MCPClient
     # @param event_data [String] the event data to parse
     # @return [Hash, nil] the parsed event, or nil if the event is invalid
     def parse_sse_event(event_data)
-      @logger.debug("Parsing SSE event data: #{event_data.inspect}")
       event = { event: 'message', data: '', id: nil }
       data_lines = []
+      has_content = false
 
       event_data.each_line do |line|
         line = line.chomp
         next if line.empty?
 
+        # Skip SSE comments (lines starting with colon)
+        next if line.start_with?(':')
+
+        has_content = true
+
         if line.start_with?('event:')
           event[:event] = line[6..].strip
         elsif line.start_with?('data:')
@@ -369,8 +556,9 @@ module MCPClient
       end
 
       event[:data] = data_lines.join("\n")
-      @logger.debug("Parsed SSE event: #{event.inspect}")
-      event[:data].empty? ? nil : event
+
+      # Return the event even if data is empty as long as we had non-comment content
+      has_content ? event : nil
     end
 
     # Request the tools list using JSON-RPC

data/lib/mcp_client/version.rb

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

data/lib/mcp_client.rb

@@ -9,6 +9,7 @@ require_relative 'mcp_client/server_sse'
 require_relative 'mcp_client/server_factory'
 require_relative 'mcp_client/client'
 require_relative 'mcp_client/version'
+require_relative 'mcp_client/config_parser'
 
 # Model Context Protocol (MCP) Client module
 # Provides a standardized way for agents to communicate with external tools and services
@@ -16,9 +17,31 @@ require_relative 'mcp_client/version'
 module MCPClient
   # Create a new MCPClient client
   # @param mcp_server_configs [Array<Hash>] configurations for MCP servers
+  # @param server_definition_file [String, nil] optional path to a JSON file defining server configurations
+  #   The JSON may be a single server object or an array of server objects.
   # @return [MCPClient::Client] new client instance
-  def self.create_client(mcp_server_configs: [])
-    MCPClient::Client.new(mcp_server_configs: mcp_server_configs)
+  def self.create_client(mcp_server_configs: [], server_definition_file: nil)
+    require 'json'
+    # Start with any explicit configs provided
+    configs = Array(mcp_server_configs)
+    # Load additional configs from a JSON file if specified
+    if server_definition_file
+      # Parse JSON definitions into clean config hashes
+      parser = MCPClient::ConfigParser.new(server_definition_file)
+      parsed = parser.parse
+      parsed.each_value do |cfg|
+        case cfg[:type].to_s
+        when 'stdio'
+          # Build command list with args
+          cmd_list = [cfg[:command]] + Array(cfg[:args])
+          configs << MCPClient.stdio_config(command: cmd_list)
+        when 'sse'
+          # Use 'url' from parsed config as 'base_url' for SSE config
+          configs << MCPClient.sse_config(base_url: cfg[:url], headers: cfg[:headers] || {})
+        end
+      end
+    end
+    MCPClient::Client.new(mcp_server_configs: configs)
   end
 
   # Create a standard server configuration for stdio
@@ -35,13 +58,17 @@ module MCPClient
   # @param base_url [String] base URL for the server
   # @param headers [Hash] HTTP headers to include in requests
   # @param read_timeout [Integer] read timeout in seconds (default: 30)
+  # @param retries [Integer] number of retry attempts (default: 0)
+  # @param retry_backoff [Integer] backoff delay in seconds (default: 1)
   # @return [Hash] server configuration
-  def self.sse_config(base_url:, headers: {}, read_timeout: 30)
+  def self.sse_config(base_url:, headers: {}, read_timeout: 30, retries: 0, retry_backoff: 1)
     {
       type: 'sse',
       base_url: base_url,
       headers: headers,
-      read_timeout: read_timeout
+      read_timeout: read_timeout,
+      retries: retries,
+      retry_backoff: retry_backoff
     }
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-mcp-client
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.2
 platform: ruby
 authors:
 - Szymon Kurcab
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-25 00:00:00.000000000 Z
+date: 2025-05-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -106,6 +106,7 @@ files:
 - README.md
 - lib/mcp_client.rb
 - lib/mcp_client/client.rb
+- lib/mcp_client/config_parser.rb
 - lib/mcp_client/errors.rb
 - lib/mcp_client/server_base.rb
 - lib/mcp_client/server_factory.rb