ruby-mcp-client 0.9.0 → 1.0.0

data/lib/mcp_client/task.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module MCPClient
+  # Represents an MCP Task for long-running operations with progress tracking
+  # Tasks follow the MCP 2025-11-25 specification for structured task management
+  #
+  # Task states: pending, running, completed, failed, cancelled
+  class Task
+    # Valid task states
+    VALID_STATES = %w[pending running completed failed cancelled].freeze
+
+    attr_reader :id, :state, :progress_token, :progress, :total, :message, :result, :server
+
+    # Create a new Task
+    # @param id [String] unique task identifier
+    # @param state [String] task state (pending, running, completed, failed, cancelled)
+    # @param progress_token [String, nil] optional token for tracking progress
+    # @param progress [Integer, nil] current progress value
+    # @param total [Integer, nil] total progress value
+    # @param message [String, nil] human-readable status message
+    # @param result [Object, nil] task result (when completed)
+    # @param server [MCPClient::ServerBase, nil] the server this task belongs to
+    def initialize(id:, state: 'pending', progress_token: nil, progress: nil, total: nil,
+                   message: nil, result: nil, server: nil)
+      validate_state!(state)
+      @id = id
+      @state = state
+      @progress_token = progress_token
+      @progress = progress
+      @total = total
+      @message = message
+      @result = result
+      @server = server
+    end
+
+    # Create a Task from a JSON hash
+    # @param json [Hash] the JSON hash with task fields
+    # @param server [MCPClient::ServerBase, nil] optional server reference
+    # @return [Task]
+    def self.from_json(json, server: nil)
+      new(
+        id: json['id'] || json[:id],
+        state: json['state'] || json[:state] || 'pending',
+        progress_token: json['progressToken'] || json[:progressToken] || json[:progress_token],
+        progress: json['progress'] || json[:progress],
+        total: json['total'] || json[:total],
+        message: json['message'] || json[:message],
+        result: json.key?('result') ? json['result'] : json[:result],
+        server: server
+      )
+    end
+
+    # Convert to JSON-serializable hash
+    # @return [Hash]
+    def to_h
+      result = { 'id' => @id, 'state' => @state }
+      result['progressToken'] = @progress_token if @progress_token
+      result['progress'] = @progress if @progress
+      result['total'] = @total if @total
+      result['message'] = @message if @message
+      result['result'] = @result unless @result.nil?
+      result
+    end
+
+    # Convert to JSON string
+    # @return [String]
+    def to_json(*)
+      to_h.to_json(*)
+    end
+
+    # Check if task is in a terminal state
+    # @return [Boolean]
+    def terminal?
+      %w[completed failed cancelled].include?(@state)
+    end
+
+    # Check if task is still active (pending or running)
+    # @return [Boolean]
+    def active?
+      %w[pending running].include?(@state)
+    end
+
+    # Calculate progress percentage
+    # @return [Float, nil] percentage (0.0-100.0) or nil if progress info unavailable
+    def progress_percentage
+      return nil unless @progress && @total&.positive?
+
+      (@progress.to_f / @total * 100).round(2)
+    end
+
+    # Check equality
+    def ==(other)
+      return false unless other.is_a?(Task)
+
+      id == other.id && state == other.state
+    end
+
+    alias eql? ==
+
+    def hash
+      [id, state].hash
+    end
+
+    # String representation
+    def to_s
+      parts = ["Task[#{@id}]: #{@state}"]
+      parts << "(#{@progress}/#{@total})" if @progress && @total
+      parts << "- #{@message}" if @message
+      parts.join(' ')
+    end
+
+    def inspect
+      "#<MCPClient::Task id=#{@id.inspect} state=#{@state.inspect}>"
+    end
+
+    private
+
+    # Validate task state
+    # @param state [String] the state to validate
+    # @raise [ArgumentError] if the state is not valid
+    def validate_state!(state)
+      return if VALID_STATES.include?(state)
+
+      raise ArgumentError, "Invalid task state: #{state.inspect}. Must be one of: #{VALID_STATES.join(', ')}"
+    end
+  end
+end

data/lib/mcp_client/tool.rb

@@ -5,6 +5,8 @@ module MCPClient
   class Tool
     # @!attribute [r] name
     #   @return [String] the name of the tool
+    # @!attribute [r] title
+    #   @return [String, nil] optional human-readable name of the tool for display purposes
     # @!attribute [r] description
     #   @return [String] the description of the tool
     # @!attribute [r] schema
@@ -15,17 +17,19 @@ module MCPClient
     #   @return [Hash, nil] optional annotations describing tool behavior (e.g., readOnly, destructive)
     # @!attribute [r] server
     #   @return [MCPClient::ServerBase, nil] the server this tool belongs to
-    attr_reader :name, :description, :schema, :output_schema, :annotations, :server
+    attr_reader :name, :title, :description, :schema, :output_schema, :annotations, :server
 
     # Initialize a new Tool
     # @param name [String] the name of the tool
     # @param description [String] the description of the tool
     # @param schema [Hash] the JSON schema for the tool inputs
+    # @param title [String, nil] optional human-readable name of the tool for display purposes
     # @param output_schema [Hash, nil] optional JSON schema for structured tool outputs (MCP 2025-06-18)
     # @param annotations [Hash, nil] optional annotations describing tool behavior
     # @param server [MCPClient::ServerBase, nil] the server this tool belongs to
-    def initialize(name:, description:, schema:, output_schema: nil, annotations: nil, server: nil)
+    def initialize(name:, description:, schema:, title: nil, output_schema: nil, annotations: nil, server: nil)
       @name = name
+      @title = title
       @description = description
       @schema = schema
       @output_schema = output_schema
@@ -43,10 +47,12 @@ module MCPClient
       schema = data['inputSchema'] || data[:inputSchema] || data['schema'] || data[:schema]
       output_schema = data['outputSchema'] || data[:outputSchema]
       annotations = data['annotations'] || data[:annotations]
+      title = data['title'] || data[:title]
       new(
         name: data['name'] || data[:name],
         description: data['description'] || data[:description],
         schema: schema,
+        title: title,
         output_schema: output_schema,
         annotations: annotations,
         server: server
@@ -67,12 +73,12 @@ module MCPClient
     end
 
     # Convert tool to Anthropic Claude tool specification format
-    # @return [Hash] Anthropic Claude tool specification
+    # @return [Hash] Anthropic Claude tool specification with cleaned schema
     def to_anthropic_tool
       {
         name: @name,
         description: @description,
-        input_schema: @schema
+        input_schema: cleaned_schema(@schema)
       }
     end
 
@@ -86,22 +92,62 @@ module MCPClient
       }
     end
 
-    # Check if the tool is marked as read-only
+    # Check if the tool is marked as read-only (legacy annotation field)
     # @return [Boolean] true if the tool is read-only
+    # @see #read_only_hint? for MCP 2025-11-25 annotation
     def read_only?
-      @annotations && @annotations['readOnly'] == true
+      !!(@annotations && @annotations['readOnly'] == true)
     end
 
-    # Check if the tool is marked as destructive
+    # Check if the tool is marked as destructive (legacy annotation field)
     # @return [Boolean] true if the tool is destructive
+    # @see #destructive_hint? for MCP 2025-11-25 annotation
     def destructive?
-      @annotations && @annotations['destructive'] == true
+      !!(@annotations && @annotations['destructive'] == true)
     end
 
     # Check if the tool requires confirmation before execution
     # @return [Boolean] true if the tool requires confirmation
     def requires_confirmation?
-      @annotations && @annotations['requiresConfirmation'] == true
+      !!(@annotations && @annotations['requiresConfirmation'] == true)
+    end
+
+    # Check the readOnlyHint annotation (MCP 2025-11-25)
+    # When true, the tool does not modify its environment.
+    # @return [Boolean] defaults to true when not specified
+    def read_only_hint?
+      return true unless @annotations
+
+      fetch_annotation_hint('readOnlyHint', :readOnlyHint, true)
+    end
+
+    # Check the destructiveHint annotation (MCP 2025-11-25)
+    # When true, the tool may perform destructive updates.
+    # Only meaningful when readOnlyHint is false.
+    # @return [Boolean] defaults to false when not specified
+    def destructive_hint?
+      return false unless @annotations
+
+      fetch_annotation_hint('destructiveHint', :destructiveHint, false)
+    end
+
+    # Check the idempotentHint annotation (MCP 2025-11-25)
+    # When true, calling the tool repeatedly with the same arguments has no additional effect.
+    # Only meaningful when readOnlyHint is false.
+    # @return [Boolean] defaults to false when not specified
+    def idempotent_hint?
+      return false unless @annotations
+
+      fetch_annotation_hint('idempotentHint', :idempotentHint, false)
+    end
+
+    # Check the openWorldHint annotation (MCP 2025-11-25)
+    # When true, the tool may interact with the "open world" (external entities).
+    # @return [Boolean] defaults to true when not specified
+    def open_world_hint?
+      return true unless @annotations
+
+      fetch_annotation_hint('openWorldHint', :openWorldHint, true)
     end
 
     # Check if the tool supports structured outputs (MCP 2025-06-18)
@@ -112,6 +158,24 @@ module MCPClient
 
     private
 
+    # Fetch a boolean annotation hint, checking both string and symbol keys.
+    # Uses Hash#key? to correctly handle false values.
+    # @param str_key [String] the string key to check
+    # @param sym_key [Symbol] the symbol key to check
+    # @param default [Boolean] the default value when the key is not present
+    # @return [Boolean] the annotation value, or the default
+    def fetch_annotation_hint(str_key, sym_key, default)
+      return default unless @annotations.is_a?(Hash)
+
+      if @annotations.key?(str_key)
+        @annotations[str_key]
+      elsif @annotations.key?(sym_key)
+        @annotations[sym_key]
+      else
+        default
+      end
+    end
+
     # Recursively remove "$schema" keys that are not accepted by Vertex AI
     # @param obj [Object] schema element (Hash/Array/other)
     # @return [Object] cleaned schema without "$schema" keys

data/lib/mcp_client/version.rb

@@ -2,8 +2,8 @@
 
 module MCPClient
   # Current version of the MCP client gem
-  VERSION = '0.9.0'
+  VERSION = '1.0.0'
 
   # MCP protocol version (date-based) - unified across all transports
-  PROTOCOL_VERSION = '2025-06-18'
+  PROTOCOL_VERSION = '2025-11-25'
 end

data/lib/mcp_client.rb

@@ -7,6 +7,11 @@ require_relative 'mcp_client/prompt'
 require_relative 'mcp_client/resource'
 require_relative 'mcp_client/resource_template'
 require_relative 'mcp_client/resource_content'
+require_relative 'mcp_client/audio_content'
+require_relative 'mcp_client/resource_link'
+require_relative 'mcp_client/root'
+require_relative 'mcp_client/elicitation_validator'
+require_relative 'mcp_client/task'
 require_relative 'mcp_client/server_base'
 require_relative 'mcp_client/server_stdio'
 require_relative 'mcp_client/server_sse'
@@ -23,6 +28,312 @@ require_relative 'mcp_client/oauth_client'
 # Provides a standardized way for agents to communicate with external tools and services
 # through a protocol-based approach
 module MCPClient
+  # Simplified connection API - auto-detects transport and returns connected client
+  #
+  # @param target [String, Array<String>] URL(s) or command for connection
+  #   - URLs ending in /sse -> SSE transport
+  #   - URLs ending in /mcp -> Streamable HTTP transport
+  #   - stdio://command or Array commands -> stdio transport
+  #   - Commands starting with npx, node, python, ruby, etc. -> stdio transport
+  #   - Other HTTP URLs -> Try Streamable HTTP, fallback to SSE, then HTTP
+  # Accepts keyword arguments for connection options:
+  # - headers [Hash] HTTP headers for remote transports
+  # - read_timeout [Integer] Request timeout in seconds (default: 30)
+  # - retries [Integer] Retry attempts
+  # - retry_backoff [Numeric] Backoff delay (default: 1)
+  # - name [String] Optional server name
+  # - logger [Logger] Optional logger
+  # - env [Hash] Environment variables for stdio
+  # - ping [Integer] Ping interval for SSE (default: 10)
+  # - endpoint [String] JSON-RPC endpoint path (default: '/rpc')
+  # - transport [Symbol] Force transport type (:stdio, :sse, :http, :streamable_http)
+  # - sampling_handler [Proc] Handler for sampling requests
+  # @yield [Faraday::Connection] Optional block for Faraday customization
+  # @return [MCPClient::Client] Connected client ready to use
+  # @raise [MCPClient::Errors::ConnectionError] if connection fails
+  # @raise [MCPClient::Errors::TransportDetectionError] if transport cannot be determined
+  #
+  # @example Connect to SSE server
+  #   client = MCPClient.connect('http://localhost:8000/sse')
+  #
+  # @example Connect to Streamable HTTP server
+  #   client = MCPClient.connect('http://localhost:8000/mcp')
+  #
+  # @example Connect with options
+  #   client = MCPClient.connect('http://api.example.com/mcp',
+  #     headers: { 'Authorization' => 'Bearer token' },
+  #     read_timeout: 60
+  #   )
+  #
+  # @example Connect to stdio server
+  #   client = MCPClient.connect('npx -y @modelcontextprotocol/server-filesystem /home')
+  #   # or with Array
+  #   client = MCPClient.connect(['npx', '-y', '@modelcontextprotocol/server-filesystem', '/home'])
+  #
+  # @example Connect to multiple servers
+  #   client = MCPClient.connect(['http://server1/mcp', 'http://server2/sse'])
+  #
+  # @example Force transport type
+  #   client = MCPClient.connect('http://custom-server.com', transport: :streamable_http)
+  #
+  # @example With Faraday customization
+  #   client = MCPClient.connect('https://internal.server.com/mcp') do |faraday|
+  #     faraday.ssl.cert_store = custom_cert_store
+  #   end
+  def self.connect(target, **, &)
+    # Handle array targets: either a single stdio command or multiple server URLs
+    if target.is_a?(Array)
+      # Check if it's a stdio command array (elements are command parts, not URLs)
+      if stdio_command_array?(target)
+        connect_single(target, **, &)
+      else
+        # It's an array of server URLs/commands
+        connect_multiple(target, **, &)
+      end
+    else
+      connect_single(target, **, &)
+    end
+  end
+
+  class << self
+    private
+
+    # Connect to a single server
+    def connect_single(target, **options, &)
+      transport = options[:transport]&.to_sym || detect_transport(target)
+
+      case transport
+      when :stdio
+        connect_stdio(target, **options)
+      when :sse
+        connect_sse(target, **options)
+      when :http
+        connect_http(target, **options, &)
+      when :streamable_http
+        connect_streamable_http(target, **options, &)
+      when :auto
+        connect_with_fallback(target, **options, &)
+      else
+        raise Errors::TransportDetectionError, "Unknown transport: #{transport}"
+      end
+    end
+
+    # Connect to multiple servers
+    def connect_multiple(targets, **options, &faraday_config)
+      configs = targets.map.with_index do |t, idx|
+        server_name = options[:name] ? "#{options[:name]}_#{idx}" : "server_#{idx}"
+        build_config_for_target(t, **options.merge(name: server_name), &faraday_config)
+      end
+
+      client = Client.new(
+        mcp_server_configs: configs,
+        logger: options[:logger],
+        sampling_handler: options[:sampling_handler]
+      )
+
+      # Connect all servers
+      client.servers.each(&:connect)
+      client
+    end
+
+    # Connect via stdio transport
+    def connect_stdio(target, **options)
+      command = parse_stdio_command(target)
+      config = stdio_config(command: command, **extract_stdio_options(options))
+      create_and_connect_client(config, options)
+    end
+
+    # Connect via SSE transport
+    def connect_sse(url, **options)
+      config = sse_config(base_url: url.to_s, **extract_sse_options(options))
+      create_and_connect_client(config, options)
+    end
+
+    # Connect via HTTP transport
+    def connect_http(url, **options, &)
+      config = http_config(base_url: url.to_s, **extract_http_options(options), &)
+      create_and_connect_client(config, options)
+    end
+
+    # Connect via Streamable HTTP transport
+    def connect_streamable_http(url, **options, &)
+      config = streamable_http_config(base_url: url.to_s, **extract_http_options(options), &)
+      create_and_connect_client(config, options)
+    end
+
+    # Create client and connect to server
+    def create_and_connect_client(config, options)
+      client = Client.new(
+        mcp_server_configs: [config],
+        logger: options[:logger],
+        sampling_handler: options[:sampling_handler]
+      )
+      client.servers.first.connect
+      client
+    end
+
+    # Try transports in order until one succeeds
+    def connect_with_fallback(url, **options, &)
+      require 'logger'
+      logger = options[:logger] || Logger.new($stderr, level: Logger::WARN)
+      errors = []
+
+      # Try Streamable HTTP first (most modern)
+      begin
+        logger.debug("MCPClient.connect: Attempting Streamable HTTP connection to #{url}")
+        return connect_streamable_http(url, **options, &)
+      rescue Errors::ConnectionError, Errors::TransportError => e
+        errors << "Streamable HTTP: #{e.message}"
+        logger.debug("MCPClient.connect: Streamable HTTP failed: #{e.message}")
+      end
+
+      # Try SSE second
+      begin
+        logger.debug("MCPClient.connect: Attempting SSE connection to #{url}")
+        return connect_sse(url, **options)
+      rescue Errors::ConnectionError, Errors::TransportError => e
+        errors << "SSE: #{e.message}"
+        logger.debug("MCPClient.connect: SSE failed: #{e.message}")
+      end
+
+      # Try plain HTTP last
+      begin
+        logger.debug("MCPClient.connect: Attempting HTTP connection to #{url}")
+        return connect_http(url, **options, &)
+      rescue Errors::ConnectionError, Errors::TransportError => e
+        errors << "HTTP: #{e.message}"
+        logger.debug("MCPClient.connect: HTTP failed: #{e.message}")
+      end
+
+      raise Errors::ConnectionError,
+            "Failed to connect to #{url}. Tried all transports:\n  #{errors.join("\n  ")}"
+    end
+
+    # Detect transport type from target
+    def detect_transport(target)
+      return :stdio if target.is_a?(Array) && stdio_command_array?(target)
+      return :stdio if stdio_target?(target)
+
+      uri = begin
+        URI.parse(target.to_s)
+      rescue URI::InvalidURIError
+        raise Errors::TransportDetectionError, "Invalid URL: #{target}"
+      end
+
+      unless http_url?(uri)
+        raise Errors::TransportDetectionError,
+              "Cannot detect transport for non-HTTP URL: #{target}. " \
+              'Use transport: option to specify explicitly.'
+      end
+
+      path = uri.path.to_s.downcase
+      return :sse if path.end_with?('/sse')
+      return :streamable_http if path.end_with?('/mcp')
+
+      # Ambiguous HTTP URL - use fallback strategy
+      :auto
+    end
+
+    # Check if target is a stdio command (string form)
+    def stdio_target?(target)
+      return false if target.is_a?(Array) # Arrays handled separately by stdio_command_array?
+
+      target_str = target.to_s
+      return true if target_str.start_with?('stdio://')
+      return true if target_str.match?(/^(npx|node|python|python3|ruby|php|java|cargo|go run)\b/)
+
+      false
+    end
+
+    # Check if an array represents a single stdio command (vs multiple server URLs)
+    # A stdio command array has elements that are command parts, not URLs
+    def stdio_command_array?(arr)
+      return false unless arr.is_a?(Array) && arr.any?
+
+      first = arr.first.to_s
+      # If the first element looks like a URL, it's not a stdio command array
+      return false if first.match?(%r{^https?://})
+      return false if first.start_with?('stdio://')
+
+      # If the first element is a known command executable, it's a stdio command array
+      return true if first.match?(/^(npx|node|python|python3|ruby|php|java|cargo|go)$/)
+
+      # If none of the elements look like URLs, assume it's a command array
+      arr.none? { |el| el.to_s.match?(%r{^https?://}) }
+    end
+
+    # Check if URI is HTTP/HTTPS
+    def http_url?(uri)
+      %w[http https].include?(uri.scheme&.downcase)
+    end
+
+    # Parse stdio command from various formats
+    def parse_stdio_command(target)
+      return target if target.is_a?(Array)
+
+      target_str = target.to_s
+      if target_str.start_with?('stdio://')
+        target_str.sub('stdio://', '')
+      else
+        target_str
+      end
+    end
+
+    # Extract common options shared by all transports
+    def extract_common_options(options)
+      {
+        name: options[:name],
+        logger: options[:logger],
+        read_timeout: options[:read_timeout],
+        retries: options[:retries],
+        retry_backoff: options[:retry_backoff]
+      }.compact
+    end
+
+    # Extract HTTP transport specific options
+    def extract_http_options(options)
+      extract_common_options(options).merge({
+        headers: options[:headers] || {},
+        endpoint: options[:endpoint]
+      }.compact)
+    end
+
+    # Extract SSE transport specific options
+    def extract_sse_options(options)
+      extract_common_options(options).merge({
+        headers: options[:headers] || {},
+        ping: options[:ping]
+      }.compact)
+    end
+
+    # Extract stdio transport specific options
+    def extract_stdio_options(options)
+      extract_common_options(options).merge({
+        env: options[:env] || {}
+      }.compact)
+    end
+
+    # Build config hash for a target
+    def build_config_for_target(target, **options, &)
+      transport = options[:transport]&.to_sym || detect_transport(target)
+
+      case transport
+      when :stdio
+        command = parse_stdio_command(target)
+        stdio_config(command: command, **extract_stdio_options(options))
+      when :sse
+        sse_config(base_url: target.to_s, **extract_sse_options(options))
+      when :http
+        http_config(base_url: target.to_s, **extract_http_options(options), &)
+      when :streamable_http, :auto
+        # For multi-server, default to streamable_http without fallback
+        streamable_http_config(base_url: target.to_s, **extract_http_options(options), &)
+      else
+        raise Errors::TransportDetectionError, "Unknown transport: #{transport}"
+      end
+    end
+  end
+
   # 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
@@ -112,9 +423,11 @@ module MCPClient
   # @param retry_backoff [Integer] backoff delay in seconds (default: 1)
   # @param name [String, nil] optional name for this server
   # @param logger [Logger, nil] optional logger for server operations
+  # @yieldparam faraday [Faraday::Connection] the configured connection instance for additional customization
+  #   (e.g., SSL settings, custom middleware). The block is called after default configuration is applied.
   # @return [Hash] server configuration
   def self.http_config(base_url:, endpoint: '/rpc', headers: {}, read_timeout: 30, retries: 3, retry_backoff: 1,
-                       name: nil, logger: nil)
+                       name: nil, logger: nil, &faraday_config)
     {
       type: 'http',
       base_url: base_url,
@@ -124,7 +437,8 @@ module MCPClient
       retries: retries,
       retry_backoff: retry_backoff,
       name: name,
-      logger: logger
+      logger: logger,
+      faraday_config: faraday_config
     }
   end
 
@@ -138,9 +452,11 @@ module MCPClient
   # @param retry_backoff [Integer] Backoff delay in seconds (default: 1)
   # @param name [String, nil] Optional name for this server
   # @param logger [Logger, nil] Optional logger for server operations
+  # @yieldparam faraday [Faraday::Connection] the configured connection instance for additional customization
+  #   (e.g., SSL settings, custom middleware). The block is called after default configuration is applied.
   # @return [Hash] server configuration
   def self.streamable_http_config(base_url:, endpoint: '/rpc', headers: {}, read_timeout: 30, retries: 3,
-                                  retry_backoff: 1, name: nil, logger: nil)
+                                  retry_backoff: 1, name: nil, logger: nil, &faraday_config)
     {
       type: 'streamable_http',
       base_url: base_url,
@@ -150,7 +466,31 @@ module MCPClient
       retries: retries,
       retry_backoff: retry_backoff,
       name: name,
-      logger: logger
+      logger: logger,
+      faraday_config: faraday_config
     }
   end
+
+  # Parse a single content item from a tool result into a typed object
+  # Recognizes 'resource_link' type and returns an MCPClient::ResourceLink.
+  # Unrecognized types are returned as-is (the original Hash).
+  # @param item [Hash] a content item with a 'type' field
+  # @return [MCPClient::ResourceLink, Hash] typed object or raw hash
+  def self.parse_content_item(item)
+    case item['type']
+    when 'resource_link'
+      ResourceLink.from_json(item)
+    else
+      item
+    end
+  end
+
+  # Parse the content array from a tool result into typed objects
+  # Each item with type 'resource_link' is converted to an MCPClient::ResourceLink.
+  # Other items are returned as-is.
+  # @param content [Array<Hash>] content array from a tool result
+  # @return [Array<MCPClient::ResourceLink, Hash>] array of typed objects or raw hashes
+  def self.parse_tool_content(content)
+    Array(content).map { |item| parse_content_item(item) }
+  end
 end