ruby-mcp-client 1.0.1 → 2.0.0

data/lib/mcp_client/json_rpc_common.rb

@@ -3,16 +3,30 @@
 module MCPClient
   # Shared retry/backoff logic for JSON-RPC transports
   module JsonRpcCommon
-    # Execute the block with retry/backoff for transient errors
+    # Execute the block with retry/backoff for transient errors only.
+    #
+    # Retries genuinely transient failures where the request most likely did not
+    # complete at the server: transport/network errors (TransportError, IOError,
+    # Errno::ETIMEDOUT/ECONNRESET/EPIPE) and TransientServerError (HTTP 5xx).
+    #
+    # It deliberately does NOT retry a plain ServerError. A plain ServerError is
+    # raised for a JSON-RPC error response or an HTTP 4xx — cases where the
+    # server received and processed (or deterministically rejected) the request.
+    # Re-sending those would silently re-execute a non-idempotent operation
+    # (e.g. a tools/call), which JSON-RPC provides no way to make safe.
     # @yield block to execute
     # @return [Object] result of block
-    # @raise original exception if max retries exceeded
+    # @raise original exception if max retries exceeded or the error is not retryable
     def with_retry
       attempts = 0
       begin
         yield
-      rescue MCPClient::Errors::ServerError, MCPClient::Errors::TransportError, IOError, Errno::ETIMEDOUT,
-             Errno::ECONNRESET => e
+      rescue MCPClient::Errors::TransientServerError, MCPClient::Errors::TransportError, IOError,
+             Errno::ETIMEDOUT, Errno::ECONNRESET, Errno::EPIPE => e
+        # A timed-out request may still be executing server-side; re-sending
+        # it could run a non-idempotent operation twice. Never retry those.
+        raise if e.is_a?(MCPClient::Errors::RequestTimeoutError)
+
         attempts += 1
         if attempts <= @max_retries
           delay = @retry_backoff * (2**(attempts - 1))
@@ -33,6 +47,46 @@ module MCPClient
       rpc_request('ping')
     end
 
+    # Whether automatic notifications/cancelled on timeout is appropriate
+    # for this request: never for initialize (MUST NOT be cancelled), and
+    # never for task-augmented requests (tasks use tasks/cancel instead).
+    # @param method [String] JSON-RPC method
+    # @param params [Hash] request params
+    # @return [Boolean]
+    def cancellable_request?(method, params)
+      return false if method == 'initialize'
+      return false if params.is_a?(Hash) && (params.key?('task') || params.key?(:task))
+
+      true
+    end
+
+    # Split request-level _meta (RequestParams._meta, e.g. progressToken or
+    # related-task metadata) out of user-supplied tool/prompt arguments.
+    # Accepts both :_meta and '_meta' key spellings; per MCP, _meta belongs at
+    # the request params level, not inside the tool's arguments.
+    # @param arguments [Hash, nil] user-supplied arguments
+    # @return [Array(Hash, Hash|nil)] [arguments without _meta, _meta or nil]
+    def split_request_meta(arguments)
+      return [arguments, nil] unless arguments.is_a?(Hash)
+
+      meta = arguments[:_meta] || arguments['_meta']
+      return [arguments, nil] unless meta
+
+      [arguments.except(:_meta, '_meta'), meta]
+    end
+
+    # Build tools/call- or prompts/get-style params with request-level _meta
+    # hoisted out of the arguments (string keys, matching the JSON wire form).
+    # @param name [String] tool or prompt name
+    # @param arguments [Hash] user-supplied arguments (possibly carrying _meta)
+    # @return [Hash] params hash for the JSON-RPC request
+    def build_named_request_params(name, arguments)
+      args, meta = split_request_meta(arguments)
+      params = { 'name' => name, 'arguments' => args }
+      params['_meta'] = meta if meta
+      params
+    end
+
     # Build a JSON-RPC request object
     # @param method [String] JSON-RPC method name
     # @param params [Hash] parameters for the request
@@ -62,19 +116,93 @@ module MCPClient
     # Generate initialization parameters for MCP protocol
     # @return [Hash] the initialization parameters
     def initialization_params
-      capabilities = {
-        'elicitation' => {}, # MCP 2025-11-25: Support for server-initiated user interactions
-        'roots' => { 'listChanged' => true }, # MCP 2025-11-25: Support for roots
-        'sampling' => {} # MCP 2025-11-25: Support for server-initiated LLM sampling
-      }
-
       {
         'protocolVersion' => MCPClient::PROTOCOL_VERSION,
-        'capabilities' => capabilities,
-        'clientInfo' => { 'name' => 'ruby-mcp-client', 'version' => MCPClient::VERSION }
+        'capabilities' => client_capabilities,
+        'clientInfo' => client_info_payload
       }
     end
 
+    # Validate the protocol version the server negotiated in its initialize
+    # result. Per the MCP lifecycle, the server may answer with a different
+    # version than requested; if the client cannot support it, it MUST
+    # disconnect. Disconnects (via the transport's cleanup) and raises when
+    # the version is unsupported or absent.
+    # @param result [Hash] the initialize result
+    # @return [String] the negotiated protocol version
+    # @raise [MCPClient::Errors::ConnectionError] if the version is unsupported
+    def validate_protocol_version!(result)
+      version = result['protocolVersion']
+      return version if MCPClient::SUPPORTED_PROTOCOL_VERSIONS.include?(version)
+
+      begin
+        cleanup if respond_to?(:cleanup)
+      rescue StandardError => e
+        @logger.debug("Cleanup after protocol version mismatch failed: #{e.message}")
+      end
+      raise MCPClient::Errors::ConnectionError,
+            "Server negotiated unsupported protocol version #{version.inspect} " \
+            "(supported: #{MCPClient::SUPPORTED_PROTOCOL_VERSIONS.join(', ')}); disconnecting"
+    end
+
+    # The Implementation object sent as clientInfo: the host-provided info
+    # when configured (client_info=), otherwise the gem's identity.
+    # @return [Hash]
+    def client_info_payload
+      return @client_info if defined?(@client_info) && @client_info
+
+      { 'name' => 'ruby-mcp-client', 'version' => MCPClient::VERSION }
+    end
+
+    # Declared client capabilities, derived from the server-request callbacks
+    # the host actually registered before connecting. Per MCP 2025-11-25,
+    # clients that support a feature MUST declare it during initialization,
+    # and only negotiated capabilities may be used afterwards — so declaring
+    # a hardcoded set independent of host support violates the lifecycle in
+    # both directions.
+    # @return [Hash] the capabilities object for the initialize request
+    def client_capabilities
+      capabilities = {}
+      if registered_callback?(:@elicitation_request_callback)
+        # Both defined elicitation modes are implemented (an empty object
+        # would mean form-only per the spec's backwards-compatibility rule).
+        capabilities['elicitation'] = { 'form' => {}, 'url' => {} }
+      end
+      capabilities['roots'] = { 'listChanged' => true } if registered_callback?(:@roots_list_request_callback)
+      if registered_callback?(:@sampling_request_callback)
+        # SEP-1577: servers may only send tool-enabled sampling requests when
+        # the client declares the sampling.tools sub-capability.
+        capabilities['sampling'] = sampling_tools_supported? ? { 'tools' => {} } : {}
+      end
+      # NOTE: we intentionally do NOT declare a client `tasks` capability. That
+      # capability marks the client as a RECEIVER of task-augmented
+      # sampling/elicitation requests, which is not implemented here — this
+      # client only acts as a task REQUESTOR for tools/call (see
+      # Client#call_tool_as_task), which requires no client-side declaration.
+      capabilities
+    end
+
+    # Opt this transport into declaring tool-use support for sampling
+    # (ClientCapabilities.sampling.tools, MCP 2025-11-25 / SEP-1577). Call
+    # before connect so the initialize request advertises it; it only takes
+    # effect when a sampling request callback is also registered, since
+    # sampling.tools is a sub-capability of sampling.
+    # @return [void]
+    def declare_sampling_tools
+      @sampling_tools_supported = true
+    end
+
+    # @param ivar [Symbol] callback instance variable name
+    # @return [Boolean] whether the callback is registered on this transport
+    def registered_callback?(ivar)
+      instance_variable_defined?(ivar) && !instance_variable_get(ivar).nil?
+    end
+
+    # @return [Boolean] whether the host opted into sampling tool use
+    def sampling_tools_supported?
+      instance_variable_defined?(:@sampling_tools_supported) && @sampling_tools_supported
+    end
+
     # Process JSON-RPC response
     # @param response [Hash] the parsed JSON-RPC response
     # @return [Object] the result field from the response

data/lib/mcp_client/oauth_client.rb

@@ -20,6 +20,8 @@ module MCPClient
     # @option options [String, nil] :name Optional name for this server
     # @option options [Logger, nil] :logger Optional logger
     # @option options [Object, nil] :storage Storage backend for OAuth tokens and client info
+    # @option options [String, nil] :client_id_metadata_url HTTPS URL of this client's
+    #   Client ID Metadata Document (SEP-991)
     # @return [ServerHTTP] OAuth-enabled HTTP server
     def self.create_http_server(server_url:, **options)
       opts = default_server_options.merge(options)
@@ -29,7 +31,8 @@ module MCPClient
         redirect_uri: opts[:redirect_uri],
         scope: opts[:scope],
         logger: opts[:logger],
-        storage: opts[:storage]
+        storage: opts[:storage],
+        client_id_metadata_url: opts[:client_id_metadata_url]
       )
 
       ServerHTTP.new(
@@ -57,7 +60,8 @@ module MCPClient
         redirect_uri: opts[:redirect_uri],
         scope: opts[:scope],
         logger: opts[:logger],
-        storage: opts[:storage]
+        storage: opts[:storage],
+        client_id_metadata_url: opts[:client_id_metadata_url]
       )
 
       ServerStreamableHTTP.new(
@@ -120,7 +124,8 @@ module MCPClient
         retry_backoff: 1,
         name: nil,
         logger: nil,
-        storage: nil
+        storage: nil,
+        client_id_metadata_url: nil
       }
     end
   end

data/lib/mcp_client/prompt.rb

@@ -5,23 +5,35 @@ module MCPClient
   class Prompt
     # @!attribute [r] name
     #   @return [String] the name of the prompt
+    # @!attribute [r] title
+    #   @return [String, nil] optional human-readable name of the prompt for display purposes
     # @!attribute [r] description
     #   @return [String] the description of the prompt
     # @!attribute [r] arguments
     #   @return [Hash] the JSON arguments for the prompt
+    # @!attribute [r] icons
+    #   @return [Array<Hash>, nil] optional icons for display in user interfaces (MCP 2025-11-25, SEP-973)
+    # @!attribute [r] meta
+    #   @return [Hash, nil] optional `_meta` metadata attached to the prompt (MCP 2025-11-25)
     # @!attribute [r] server
     #   @return [MCPClient::ServerBase, nil] the server this prompt belongs to
-    attr_reader :name, :description, :arguments, :server
+    attr_reader :name, :title, :description, :arguments, :icons, :meta, :server
 
     # Initialize a new prompt
     # @param name [String] the name of the prompt
     # @param description [String] the description of the prompt
     # @param arguments [Hash] the JSON arguments for the prompt
+    # @param title [String, nil] optional human-readable name of the prompt for display purposes
+    # @param icons [Array<Hash>, nil] optional icons for display in user interfaces (MCP 2025-11-25)
+    # @param meta [Hash, nil] optional `_meta` metadata attached to the prompt (MCP 2025-11-25)
     # @param server [MCPClient::ServerBase, nil] the server this prompt belongs to
-    def initialize(name:, description:, arguments: {}, server: nil)
+    def initialize(name:, description:, arguments: {}, title: nil, icons: nil, meta: nil, server: nil)
       @name = name
+      @title = title
       @description = description
       @arguments = arguments
+      @icons = icons
+      @meta = meta
       @server = server
     end
 
@@ -32,8 +44,11 @@ module MCPClient
     def self.from_json(data, server: nil)
       new(
         name: data['name'],
+        title: data['title'],
         description: data['description'],
         arguments: data['arguments'] || {},
+        icons: data['icons'],
+        meta: data['_meta'],
         server: server
       )
     end

data/lib/mcp_client/resource.rb

@@ -17,9 +17,13 @@ module MCPClient
     #   @return [Integer, nil] optional size in bytes
     # @!attribute [r] annotations
     #   @return [Hash, nil] optional annotations that provide hints to clients
+    # @!attribute [r] icons
+    #   @return [Array<Hash>, nil] optional icons for display in user interfaces (MCP 2025-11-25, SEP-973)
+    # @!attribute [r] meta
+    #   @return [Hash, nil] optional `_meta` metadata attached to the resource (MCP 2025-11-25)
     # @!attribute [r] server
     #   @return [MCPClient::ServerBase, nil] the server this resource belongs to
-    attr_reader :uri, :name, :title, :description, :mime_type, :size, :annotations, :server
+    attr_reader :uri, :name, :title, :description, :mime_type, :size, :annotations, :icons, :meta, :server
 
     # Initialize a new resource
     # @param uri [String] unique identifier for the resource
@@ -29,8 +33,12 @@ module MCPClient
     # @param mime_type [String, nil] optional MIME type
     # @param size [Integer, nil] optional size in bytes
     # @param annotations [Hash, nil] optional annotations that provide hints to clients
+    # @param icons [Array<Hash>, nil] optional icons for display in user interfaces (MCP 2025-11-25)
+    # @param meta [Hash, nil] optional `_meta` metadata attached to the resource (MCP 2025-11-25)
     # @param server [MCPClient::ServerBase, nil] the server this resource belongs to
-    def initialize(uri:, name:, title: nil, description: nil, mime_type: nil, size: nil, annotations: nil, server: nil)
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(uri:, name:, title: nil, description: nil, mime_type: nil, size: nil, annotations: nil,
+                   icons: nil, meta: nil, server: nil)
       @uri = uri
       @name = name
       @title = title
@@ -38,8 +46,11 @@ module MCPClient
       @mime_type = mime_type
       @size = size
       @annotations = annotations
+      @icons = icons
+      @meta = meta
       @server = server
     end
+    # rubocop:enable Metrics/ParameterLists
 
     # Return the lastModified annotation value (ISO 8601 timestamp string)
     # @return [String, nil] the lastModified timestamp, or nil if not set
@@ -62,6 +73,8 @@ module MCPClient
         mime_type: data['mimeType'],
         size: data['size'],
         annotations: data['annotations'],
+        icons: data['icons'],
+        meta: data['_meta'],
         server: server
       )
     end

data/lib/mcp_client/resource_content.rb

@@ -18,7 +18,9 @@ module MCPClient
     #   @return [String, nil] base64-encoded binary content (mutually exclusive with text)
     # @!attribute [r] annotations
     #   @return [Hash, nil] optional annotations that provide hints to clients
-    attr_reader :uri, :name, :title, :mime_type, :text, :blob, :annotations
+    # @!attribute [r] meta
+    #   @return [Hash, nil] optional `_meta` metadata attached to the resource contents (MCP 2025-11-25)
+    attr_reader :uri, :name, :title, :mime_type, :text, :blob, :annotations, :meta
 
     # Initialize resource content
     # @param uri [String] unique identifier for the resource
@@ -28,7 +30,8 @@ module MCPClient
     # @param text [String, nil] text content (mutually exclusive with blob)
     # @param blob [String, nil] base64-encoded binary content (mutually exclusive with text)
     # @param annotations [Hash, nil] optional annotations that provide hints to clients
-    def initialize(uri:, name:, title: nil, mime_type: nil, text: nil, blob: nil, annotations: nil)
+    # @param meta [Hash, nil] optional `_meta` metadata attached to the resource contents (MCP 2025-11-25)
+    def initialize(uri:, name:, title: nil, mime_type: nil, text: nil, blob: nil, annotations: nil, meta: nil)
       raise ArgumentError, 'ResourceContent cannot have both text and blob' if text && blob
       raise ArgumentError, 'ResourceContent must have either text or blob' if !text && !blob
 
@@ -39,6 +42,7 @@ module MCPClient
       @text = text
       @blob = blob
       @annotations = annotations
+      @meta = meta
     end
 
     # Create a ResourceContent instance from JSON data
@@ -52,7 +56,8 @@ module MCPClient
         mime_type: data['mimeType'],
         text: data['text'],
         blob: data['blob'],
-        annotations: data['annotations']
+        annotations: data['annotations'],
+        meta: data['_meta']
       )
     end
 

data/lib/mcp_client/resource_link.rb

@@ -19,7 +19,11 @@ module MCPClient
     #   @return [String, nil] optional display title for the resource
     # @!attribute [r] size
     #   @return [Integer, nil] optional size of the resource in bytes
-    attr_reader :uri, :name, :description, :mime_type, :annotations, :title, :size
+    # @!attribute [r] icons
+    #   @return [Array<Hash>, nil] optional icons for display in user interfaces (MCP 2025-11-25, SEP-973)
+    # @!attribute [r] meta
+    #   @return [Hash, nil] optional `_meta` metadata attached to the resource link (MCP 2025-11-25)
+    attr_reader :uri, :name, :description, :mime_type, :annotations, :title, :size, :icons, :meta
 
     # Initialize a resource link
     # @param uri [String] URI of the linked resource
@@ -29,7 +33,11 @@ module MCPClient
     # @param annotations [Hash, nil] optional annotations that provide hints to clients
     # @param title [String, nil] optional display title for the resource
     # @param size [Integer, nil] optional size of the resource in bytes
-    def initialize(uri:, name:, description: nil, mime_type: nil, annotations: nil, title: nil, size: nil)
+    # @param icons [Array<Hash>, nil] optional icons for display in user interfaces (MCP 2025-11-25)
+    # @param meta [Hash, nil] optional `_meta` metadata attached to the resource link (MCP 2025-11-25)
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(uri:, name:, description: nil, mime_type: nil, annotations: nil, title: nil, size: nil,
+                   icons: nil, meta: nil)
       @uri = uri
       @name = name
       @description = description
@@ -37,7 +45,10 @@ module MCPClient
       @annotations = annotations
       @title = title
       @size = size
+      @icons = icons
+      @meta = meta
     end
+    # rubocop:enable Metrics/ParameterLists
 
     # Create a ResourceLink instance from JSON data
     # @param data [Hash] JSON data from MCP server (content item with type 'resource_link')
@@ -50,7 +61,9 @@ module MCPClient
         mime_type: data['mimeType'],
         annotations: data['annotations'],
         title: data['title'],
-        size: data['size']
+        size: data['size'],
+        icons: data['icons'],
+        meta: data['_meta']
       )
     end
 

data/lib/mcp_client/resource_template.rb

@@ -16,9 +16,13 @@ module MCPClient
     #   @return [String, nil] optional MIME type for resources created from this template
     # @!attribute [r] annotations
     #   @return [Hash, nil] optional annotations that provide hints to clients
+    # @!attribute [r] icons
+    #   @return [Array<Hash>, nil] optional icons for display in user interfaces (MCP 2025-11-25, SEP-973)
+    # @!attribute [r] meta
+    #   @return [Hash, nil] optional `_meta` metadata attached to the resource template (MCP 2025-11-25)
     # @!attribute [r] server
     #   @return [MCPClient::ServerBase, nil] the server this resource template belongs to
-    attr_reader :uri_template, :name, :title, :description, :mime_type, :annotations, :server
+    attr_reader :uri_template, :name, :title, :description, :mime_type, :annotations, :icons, :meta, :server
 
     # Initialize a new resource template
     # @param uri_template [String] URI template following RFC 6570
@@ -27,16 +31,23 @@ module MCPClient
     # @param description [String, nil] optional description
     # @param mime_type [String, nil] optional MIME type
     # @param annotations [Hash, nil] optional annotations that provide hints to clients
+    # @param icons [Array<Hash>, nil] optional icons for display in user interfaces (MCP 2025-11-25)
+    # @param meta [Hash, nil] optional `_meta` metadata attached to the resource template (MCP 2025-11-25)
     # @param server [MCPClient::ServerBase, nil] the server this resource template belongs to
-    def initialize(uri_template:, name:, title: nil, description: nil, mime_type: nil, annotations: nil, server: nil)
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(uri_template:, name:, title: nil, description: nil, mime_type: nil, annotations: nil,
+                   icons: nil, meta: nil, server: nil)
       @uri_template = uri_template
       @name = name
       @title = title
       @description = description
       @mime_type = mime_type
       @annotations = annotations
+      @icons = icons
+      @meta = meta
       @server = server
     end
+    # rubocop:enable Metrics/ParameterLists
 
     # Create a ResourceTemplate instance from JSON data
     # @param data [Hash] JSON data from MCP server
@@ -50,6 +61,8 @@ module MCPClient
         description: data['description'],
         mime_type: data['mimeType'],
         annotations: data['annotations'],
+        icons: data['icons'],
+        meta: data['_meta'],
         server: server
       )
     end

data/lib/mcp_client/root.rb

@@ -1,26 +1,39 @@
 # frozen_string_literal: true
 
+require 'uri'
+
 module MCPClient
   # Represents an MCP Root - a URI that defines a boundary where servers can operate
   # Roots are declared by clients to inform servers about relevant resources and their locations
   class Root
-    attr_reader :uri, :name
+    attr_reader :uri, :name, :meta
 
     # Create a new Root
-    # @param uri [String] The URI for the root (typically file:// URI)
+    # @param uri [String] The URI for the root. Per the MCP specification this
+    #   MUST be a file:// URI ("This **MUST** be a `file://` URI in the current
+    #   specification" - client/roots.mdx, 2025-11-25)
     # @param name [String, nil] Optional human-readable name for display purposes
-    def initialize(uri:, name: nil)
+    # @param meta [Hash, nil] Optional _meta field attached to the root (schema.ts Root._meta)
+    # @raise [ArgumentError] if uri is not a valid file:// URI or contains '..' path segments
+    def initialize(uri:, name: nil, meta: nil)
+      validate_uri!(uri)
+      # Root._meta is an object of arbitrary keys per the schema
+      raise ArgumentError, "Root _meta must be a Hash, got #{meta.class}" if meta && !meta.is_a?(Hash)
+
       @uri = uri
       @name = name
+      @meta = meta
     end
 
     # Create a Root from a JSON hash
-    # @param json [Hash] The JSON hash with 'uri' and optional 'name' keys
+    # @param json [Hash] The JSON hash with 'uri' and optional 'name' and '_meta' keys
     # @return [Root]
+    # @raise [ArgumentError] if the uri is missing or not a valid file:// URI
     def self.from_json(json)
       new(
         uri: json['uri'] || json[:uri],
-        name: json['name'] || json[:name]
+        name: json['name'] || json[:name],
+        meta: json['_meta'] || json[:_meta]
       )
     end
 
@@ -29,6 +42,7 @@ module MCPClient
     def to_h
       result = { 'uri' => @uri }
       result['name'] = @name if @name
+      result['_meta'] = @meta if @meta
       result
     end
 
@@ -42,13 +56,13 @@ module MCPClient
     def ==(other)
       return false unless other.is_a?(Root)
 
-      uri == other.uri && name == other.name
+      uri == other.uri && name == other.name && meta == other.meta
     end
 
     alias eql? ==
 
     def hash
-      [uri, name].hash
+      [uri, name, meta].hash
     end
 
     # String representation
@@ -59,5 +73,45 @@ module MCPClient
     def inspect
       "#<MCPClient::Root uri=#{uri.inspect} name=#{name.inspect}>"
     end
+
+    private
+
+    # Validate that the uri is a well-formed file:// URI without path traversal.
+    # Spec (client/roots.mdx, 2025-11-25): the root uri "MUST be a `file://` URI
+    # in the current specification", and clients "MUST ... Validate all root
+    # URIs to prevent path traversal".
+    # @param uri [Object] the uri to validate
+    # @return [void]
+    # @raise [ArgumentError] if the uri is invalid
+    def validate_uri!(uri)
+      raise ArgumentError, 'Root uri must be a String, got nil' if uri.nil?
+      raise ArgumentError, "Root uri must be a String, got #{uri.class}" unless uri.is_a?(String)
+
+      # The schema requires the literal file:// form ("must start with
+      # file://"), not merely a file scheme — file:relative and file:/path
+      # forms are rejected.
+      unless uri.downcase.start_with?('file://')
+        raise ArgumentError,
+              "Root uri must be a file:// URI (MCP spec: 'This MUST be a file:// URI'), got: #{uri.inspect}"
+      end
+
+      parsed = parse_uri(uri)
+      # Decode before the traversal check so percent-encoded segments
+      # (%2e%2e) cannot smuggle a '..' past validation.
+      decoded_path = URI::DEFAULT_PARSER.unescape(parsed.path.to_s)
+      return unless decoded_path.split('/').include?('..')
+
+      raise ArgumentError, "Root uri must not contain '..' path traversal segments, got: #{uri.inspect}"
+    end
+
+    # Parse a URI string, converting parse errors to ArgumentError
+    # @param uri [String] the uri string to parse
+    # @return [URI::Generic]
+    # @raise [ArgumentError] if the uri cannot be parsed
+    def parse_uri(uri)
+      URI.parse(uri)
+    rescue URI::InvalidURIError => e
+      raise ArgumentError, "Root uri is not a valid URI: #{uri.inspect} (#{e.message})"
+    end
   end
 end