ruby-mcp-client 0.9.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79251746d1952caddd00b917b914d5ddb47c742c960914a39bf6a7f7a7073d35
-  data.tar.gz: 98522398f4bcb491c59d794f6e869d9570c0ddfc3fba40eb584e21079ea913e2
+  metadata.gz: e7e861ecba26ec407886fbb6d169b85c78ecba0768552b512cbe6c9c1f6216ad
+  data.tar.gz: d71bab971376849e2bf72e2598116087cdb4f072c556368471d1d9adfe1bd7b5
 SHA512:
-  metadata.gz: bb37b670e9e54baf9dfc280d0be09047e43236439ae94f0fd8acb1277a0acc1f0eba33661a3d1fa49c25d11493b6a70c283be66fab91420a1ba2b2fbe7360499
-  data.tar.gz: 840c2a9685114762396106e5e7cc327ac2e0c3639575cf4eb3f4a41b50d6bc3c19a705d5405bcd1f7504fa1961c3f5ce5796105e77d780b53515255a3151539c
+  metadata.gz: 20d61bad3b57193dbc1a8019b87ec85758c55f61edc7c37808e7f1bc3a4fb60f35532f694aa68334273da31245ef6541cddbf2c4d0dc720d122bfae09488b415
+  data.tar.gz: e3e3ec6840cf41e0b18d6112a7ff602a798cdcb6108b1c75afd5ecaf68724adee2109dca6782e884e7b2db51d8dd8ef09fd414e20d3d7ec0c1bc072225e33427

data/README.md

@@ -28,16 +28,18 @@ Built-in API conversions: `to_openai_tools()`, `to_anthropic_tools()`, `to_googl
 
 ## MCP Protocol Support
 
-Implements **MCP 2025-06-18** specification:
+Implements **MCP 2025-11-25** specification:
 
-- **Tools**: list, call, streaming, annotations, structured outputs
+- **Tools**: list, call, streaming, annotations (hint-style), structured outputs, title
 - **Prompts**: list, get with parameters
-- **Resources**: list, read, templates, subscriptions, pagination
+- **Resources**: list, read, templates, subscriptions, pagination, ResourceLink content
 - **Elicitation**: Server-initiated user interactions (stdio, SSE, Streamable HTTP)
 - **Roots**: Filesystem scope boundaries with change notifications
-- **Sampling**: Server-requested LLM completions
-- **Completion**: Autocomplete for prompts/resources
+- **Sampling**: Server-requested LLM completions with modelPreferences
+- **Completion**: Autocomplete for prompts/resources with context
 - **Logging**: Server log messages with level filtering
+- **Tasks**: Structured task management with progress tracking
+- **Audio**: Audio content type support
 - **OAuth 2.1**: PKCE, server discovery, dynamic registration
 
 ## Quick Connect API (Recommended)
@@ -114,12 +116,20 @@ contents.each do |content|
 end
 ```
 
-## MCP 2025-06-18 Features
+## MCP 2025-11-25 Features
 
 ### Tool Annotations
 
 ```ruby
 tool = client.find_tool('delete_user')
+
+# Hint-style annotations (MCP 2025-11-25)
+tool.read_only_hint?      # Defaults to true; tool does not modify environment
+tool.destructive_hint?    # Defaults to false; tool may perform destructive updates
+tool.idempotent_hint?     # Defaults to false; repeated calls have no additional effect
+tool.open_world_hint?     # Defaults to true; tool may interact with external entities
+
+# Legacy annotations
 tool.read_only?              # Safe to execute?
 tool.destructive?            # Warning: destructive operation
 tool.requires_confirmation?  # Needs user confirmation

data/lib/mcp_client/audio_content.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module MCPClient
+  # Representation of MCP audio content (MCP 2025-11-25)
+  # Used for base64-encoded audio data in messages and tool results
+  class AudioContent
+    # @!attribute [r] data
+    #   @return [String] base64-encoded audio data
+    # @!attribute [r] mime_type
+    #   @return [String] MIME type of the audio (e.g., 'audio/wav', 'audio/mpeg', 'audio/ogg')
+    # @!attribute [r] annotations
+    #   @return [Hash, nil] optional annotations that provide hints to clients
+    attr_reader :data, :mime_type, :annotations
+
+    # Initialize audio content
+    # @param data [String] base64-encoded audio data
+    # @param mime_type [String] MIME type of the audio
+    # @param annotations [Hash, nil] optional annotations that provide hints to clients
+    def initialize(data:, mime_type:, annotations: nil)
+      raise ArgumentError, 'AudioContent requires data' if data.nil? || data.empty?
+      raise ArgumentError, 'AudioContent requires mime_type' if mime_type.nil? || mime_type.empty?
+
+      @data = data
+      @mime_type = mime_type
+      @annotations = annotations
+    end
+
+    # Create an AudioContent instance from JSON data
+    # @param data [Hash] JSON data from MCP server
+    # @return [MCPClient::AudioContent] audio content instance
+    def self.from_json(json_data)
+      new(
+        data: json_data['data'],
+        mime_type: json_data['mimeType'],
+        annotations: json_data['annotations']
+      )
+    end
+
+    # Get the decoded audio content
+    # @return [String] decoded binary audio data
+    def content
+      require 'base64'
+      Base64.decode64(@data)
+    end
+  end
+end

data/lib/mcp_client/client.rb

@@ -25,7 +25,7 @@ module MCPClient
     # @param logger [Logger, nil] optional logger, defaults to STDOUT
     # @param elicitation_handler [Proc, nil] optional handler for elicitation requests (MCP 2025-06-18)
     # @param roots [Array<MCPClient::Root, Hash>, nil] optional list of roots (MCP 2025-06-18)
-    # @param sampling_handler [Proc, nil] optional handler for sampling requests (MCP 2025-06-18)
+    # @param sampling_handler [Proc, nil] optional handler for sampling requests (MCP 2025-11-25)
     def initialize(mcp_server_configs: [], logger: nil, elicitation_handler: nil, roots: nil, sampling_handler: nil)
       @logger = logger || Logger.new($stdout, level: Logger::WARN)
       @logger.progname = self.class.name
@@ -41,7 +41,7 @@ module MCPClient
       @notification_listeners = []
       # Elicitation handler (MCP 2025-06-18)
       @elicitation_handler = elicitation_handler
-      # Sampling handler (MCP 2025-06-18)
+      # Sampling handler (MCP 2025-11-25)
       @sampling_handler = sampling_handler
       # Roots (MCP 2025-06-18)
       @roots = normalize_roots(roots)
@@ -59,7 +59,7 @@ module MCPClient
         end
         # Register roots list handler on each server (MCP 2025-06-18)
         server.on_roots_list_request(&method(:handle_roots_list_request)) if server.respond_to?(:on_roots_list_request)
-        # Register sampling handler on each server (MCP 2025-06-18)
+        # Register sampling handler on each server (MCP 2025-11-25)
         server.on_sampling_request(&method(:handle_sampling_request)) if server.respond_to?(:on_sampling_request)
       end
     end
@@ -486,13 +486,85 @@ module MCPClient
     # Request completion suggestions from a server (MCP 2025-06-18)
     # @param ref [Hash] reference object (e.g., { 'type' => 'ref/prompt', 'name' => 'prompt_name' })
     # @param argument [Hash] the argument being completed (e.g., { 'name' => 'arg_name', 'value' => 'partial' })
+    # @param context [Hash, nil] optional context for the completion (MCP 2025-11-25),
+    #   e.g., { 'arguments' => { 'arg1' => 'value1' } } for previously-resolved arguments
     # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
     # @return [Hash] completion result with 'values', optional 'total', and 'hasMore' fields
     # @raise [MCPClient::Errors::ServerNotFound] if no server is available
     # @raise [MCPClient::Errors::ServerError] if server returns an error
-    def complete(ref:, argument:, server: nil)
+    def complete(ref:, argument:, context: nil, server: nil)
       srv = select_server(server)
-      srv.complete(ref: ref, argument: argument)
+      srv.complete(ref: ref, argument: argument, context: context)
+    end
+
+    # Create a new task on a server (MCP 2025-11-25)
+    # Tasks represent long-running operations that can report progress
+    # @param method [String] the method to execute as a task
+    # @param params [Hash] parameters for the task method
+    # @param progress_token [String, nil] optional token for receiving progress notifications
+    # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
+    # @return [MCPClient::Task] the created task
+    # @raise [MCPClient::Errors::ServerNotFound] if no server is available
+    # @raise [MCPClient::Errors::TaskError] if task creation fails
+    def create_task(method, params: {}, progress_token: nil, server: nil)
+      srv = select_server(server)
+      rpc_params = { method: method, params: params }
+      rpc_params[:progressToken] = progress_token if progress_token
+
+      begin
+        result = srv.rpc_request('tasks/create', rpc_params)
+        MCPClient::Task.from_json(result, server: srv)
+      rescue MCPClient::Errors::ServerError, MCPClient::Errors::TransportError, MCPClient::Errors::ConnectionError => e
+        raise MCPClient::Errors::TaskError, "Error creating task: #{e.message}"
+      end
+    end
+
+    # Get the current state of a task (MCP 2025-11-25)
+    # @param task_id [String] the ID of the task to query
+    # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
+    # @return [MCPClient::Task] the task with current state
+    # @raise [MCPClient::Errors::ServerNotFound] if no server is available
+    # @raise [MCPClient::Errors::TaskNotFound] if the task does not exist
+    # @raise [MCPClient::Errors::TaskError] if retrieving the task fails
+    def get_task(task_id, server: nil)
+      srv = select_server(server)
+
+      begin
+        result = srv.rpc_request('tasks/get', { id: task_id })
+        MCPClient::Task.from_json(result, server: srv)
+      rescue MCPClient::Errors::ServerError => e
+        if e.message.include?('not found') || e.message.include?('unknown task')
+          raise MCPClient::Errors::TaskNotFound, "Task '#{task_id}' not found"
+        end
+
+        raise MCPClient::Errors::TaskError, "Error getting task '#{task_id}': #{e.message}"
+      rescue MCPClient::Errors::TransportError, MCPClient::Errors::ConnectionError => e
+        raise MCPClient::Errors::TaskError, "Error getting task '#{task_id}': #{e.message}"
+      end
+    end
+
+    # Cancel a running task (MCP 2025-11-25)
+    # @param task_id [String] the ID of the task to cancel
+    # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
+    # @return [MCPClient::Task] the task with updated (cancelled) state
+    # @raise [MCPClient::Errors::ServerNotFound] if no server is available
+    # @raise [MCPClient::Errors::TaskNotFound] if the task does not exist
+    # @raise [MCPClient::Errors::TaskError] if cancellation fails
+    def cancel_task(task_id, server: nil)
+      srv = select_server(server)
+
+      begin
+        result = srv.rpc_request('tasks/cancel', { id: task_id })
+        MCPClient::Task.from_json(result, server: srv)
+      rescue MCPClient::Errors::ServerError => e
+        if e.message.include?('not found') || e.message.include?('unknown task')
+          raise MCPClient::Errors::TaskNotFound, "Task '#{task_id}' not found"
+        end
+
+        raise MCPClient::Errors::TaskError, "Error cancelling task '#{task_id}': #{e.message}"
+      rescue MCPClient::Errors::TransportError, MCPClient::Errors::ConnectionError => e
+        raise MCPClient::Errors::TaskError, "Error cancelling task '#{task_id}': #{e.message}"
+      end
     end
 
     # Set the logging level on all connected servers (MCP 2025-06-18)
@@ -606,7 +678,17 @@ module MCPClient
       required = schema['required'] || schema[:required]
       return unless required.is_a?(Array)
 
+      properties = schema['properties'] || schema[:properties] || {}
+
       missing = required.map(&:to_s) - parameters.keys.map(&:to_s)
+
+      # Exclude required params that have a default value in the schema,
+      # since the server will apply the default.
+      missing = missing.reject do |param|
+        prop = properties[param] || properties[param.to_sym]
+        prop.is_a?(Hash) && (prop.key?('default') || prop.key?(:default))
+      end
+
       return unless missing.any?
 
       raise MCPClient::Errors::ValidationError, "Missing required parameters: #{missing.join(', ')}"
@@ -683,7 +765,8 @@ module MCPClient
       end
     end
 
-    # Handle elicitation request from server (MCP 2025-06-18)
+    # Handle elicitation request from server (MCP 2025-11-25)
+    # Supports both form mode (structured data) and URL mode (out-of-band interaction).
     # @param _request_id [String, Integer] the JSON-RPC request ID (unused at client layer)
     # @param params [Hash] the elicitation parameters
     # @return [Hash] the elicitation response
@@ -694,43 +777,17 @@ module MCPClient
         return { 'action' => 'decline' }
       end
 
+      mode = params['mode'] || 'form'
       message = params['message']
-      schema = params['schema'] || params['requestedSchema']
-      metadata = params['metadata']
 
       begin
-        # Call the user-defined handler
-        result = case @elicitation_handler.arity
-                 when 0
-                   @elicitation_handler.call
-                 when 1
-                   @elicitation_handler.call(message)
-                 when 2, -1
-                   @elicitation_handler.call(message, schema)
+        result = if mode == 'url'
+                   handle_url_elicitation(params, message)
                  else
-                   @elicitation_handler.call(message, schema, metadata)
+                   handle_form_elicitation(params, message)
                  end
 
-        # Validate and format response
-        case result
-        when Hash
-          if result['action']
-            normalised_action_response(result)
-          elsif result[:action]
-            # Convert symbol keys to strings
-            {
-              'action' => result[:action].to_s,
-              'content' => result[:content]
-            }.compact.then { |payload| normalised_action_response(payload) }
-          else
-            # Assume it's content for an accept action
-            { 'action' => 'accept', 'content' => result }
-          end
-        when nil
-          { 'action' => 'cancel' }
-        else
-          { 'action' => 'accept', 'content' => result }
-        end
+        format_elicitation_response(result, params)
       rescue StandardError => e
         @logger.error("Elicitation handler error: #{e.message}")
         @logger.debug(e.backtrace.join("\n"))
@@ -738,6 +795,103 @@ module MCPClient
       end
     end
 
+    # Handle form mode elicitation (MCP 2025-11-25)
+    # @param params [Hash] the elicitation parameters
+    # @param message [String] the human-readable message
+    # @return [Object] handler result
+    def handle_form_elicitation(params, message)
+      schema = params['requestedSchema'] || params['schema']
+      metadata = params['metadata']
+
+      # Validate schema if present
+      if schema
+        schema_errors = ElicitationValidator.validate_schema(schema)
+        @logger.warn("Elicitation schema validation warnings: #{schema_errors.join('; ')}") unless schema_errors.empty?
+      end
+
+      # Call the user-defined handler
+      case @elicitation_handler.arity
+      when 0
+        @elicitation_handler.call
+      when 1
+        @elicitation_handler.call(message)
+      when 2, -1
+        @elicitation_handler.call(message, schema)
+      else
+        @elicitation_handler.call(message, schema, metadata)
+      end
+    end
+
+    # Handle URL mode elicitation (MCP 2025-11-25)
+    # @param params [Hash] the elicitation parameters
+    # @param message [String] the human-readable message
+    # @return [Object] handler result
+    def handle_url_elicitation(params, message)
+      url = params['url']
+      elicitation_id = params['elicitationId']
+
+      # Call handler with URL-mode specific params
+      case @elicitation_handler.arity
+      when 0
+        @elicitation_handler.call
+      when 1
+        @elicitation_handler.call(message)
+      when 2, -1
+        @elicitation_handler.call(message, { 'mode' => 'url', 'url' => url, 'elicitationId' => elicitation_id })
+      else
+        @elicitation_handler.call(message, { 'mode' => 'url', 'url' => url, 'elicitationId' => elicitation_id },
+                                  params['metadata'])
+      end
+    end
+
+    # Format and validate the elicitation response
+    # @param result [Object] handler result
+    # @param params [Hash] original request params (for schema validation)
+    # @return [Hash] formatted response
+    def format_elicitation_response(result, params)
+      response = case result
+                 when Hash
+                   if result['action']
+                     normalised_action_response(result)
+                   elsif result[:action]
+                     {
+                       'action' => result[:action].to_s,
+                       'content' => result[:content]
+                     }.compact.then { |payload| normalised_action_response(payload) }
+                   else
+                     { 'action' => 'accept', 'content' => result }
+                   end
+                 when nil
+                   { 'action' => 'cancel' }
+                 else
+                   { 'action' => 'accept', 'content' => result }
+                 end
+
+      # Validate content against schema for form mode accept responses
+      validate_elicitation_content(response, params)
+
+      response
+    end
+
+    # Validate elicitation response content against the requestedSchema
+    # @param response [Hash] the formatted response
+    # @param params [Hash] original request params
+    # @return [void]
+    def validate_elicitation_content(response, params)
+      return unless response['action'] == 'accept' && response['content'].is_a?(Hash)
+
+      mode = params['mode'] || 'form'
+      return unless mode == 'form'
+
+      schema = params['requestedSchema'] || params['schema']
+      return unless schema.is_a?(Hash)
+
+      errors = ElicitationValidator.validate_content(response['content'], schema)
+      return if errors.empty?
+
+      @logger.warn("Elicitation content validation warnings: #{errors.join('; ')}")
+    end
+
     # Ensure the action value conforms to MCP spec (accept, decline, cancel)
     # Falls back to accept for unknown action values.
     def normalised_action_response(result)
@@ -785,9 +939,9 @@ module MCPClient
       end
     end
 
-    # Handle sampling/createMessage request from server (MCP 2025-06-18)
+    # Handle sampling/createMessage request from server (MCP 2025-11-25)
     # @param _request_id [String, Integer] the JSON-RPC request ID (unused, kept for callback signature)
-    # @param params [Hash] the sampling parameters (messages, modelPreferences, systemPrompt, maxTokens)
+    # @param params [Hash] the sampling parameters
     # @return [Hash] the sampling response (role, content, model, stopReason)
     def handle_sampling_request(_request_id, params)
       # If no handler is configured, return an error
@@ -797,24 +951,18 @@ module MCPClient
       end
 
       messages = params['messages'] || []
-      model_preferences = params['modelPreferences']
+      model_preferences = normalize_model_preferences(params['modelPreferences'])
       system_prompt = params['systemPrompt']
       max_tokens = params['maxTokens']
+      include_context = params['includeContext']
+      temperature = params['temperature']
+      stop_sequences = params['stopSequences']
+      metadata = params['metadata']
 
       begin
-        # Call the user-defined handler
-        result = case @sampling_handler.arity
-                 when 0
-                   @sampling_handler.call
-                 when 1
-                   @sampling_handler.call(messages)
-                 when 2
-                   @sampling_handler.call(messages, model_preferences)
-                 when 3
-                   @sampling_handler.call(messages, model_preferences, system_prompt)
-                 else
-                   @sampling_handler.call(messages, model_preferences, system_prompt, max_tokens)
-                 end
+        # Call the user-defined handler with parameters based on arity
+        result = call_sampling_handler(messages, model_preferences, system_prompt, max_tokens,
+                                       include_context, temperature, stop_sequences, metadata)
 
         # Validate and format response
         validate_sampling_response(result)
@@ -825,7 +973,70 @@ module MCPClient
       end
     end
 
-    # Validate sampling response from handler (MCP 2025-06-18)
+    # Call sampling handler with appropriate arity
+    # @param messages [Array] the messages
+    # @param model_preferences [Hash, nil] normalized model preferences
+    # @param system_prompt [String, nil] system prompt
+    # @param max_tokens [Integer, nil] max tokens
+    # @param include_context [String, nil] context inclusion setting
+    # @param temperature [Float, nil] temperature
+    # @param stop_sequences [Array, nil] stop sequences
+    # @param metadata [Hash, nil] metadata
+    # @return [Hash] the handler result
+    def call_sampling_handler(messages, model_preferences, system_prompt, max_tokens,
+                              include_context, temperature, stop_sequences, metadata)
+      arity = @sampling_handler.arity
+      # Normalize negative arity (optional params) to minimum required args
+      arity = -(arity + 1) if arity.negative?
+      case arity
+      when 0
+        @sampling_handler.call
+      when 1
+        @sampling_handler.call(messages)
+      when 2
+        @sampling_handler.call(messages, model_preferences)
+      when 3
+        @sampling_handler.call(messages, model_preferences, system_prompt)
+      when 4
+        @sampling_handler.call(messages, model_preferences, system_prompt, max_tokens)
+      else
+        @sampling_handler.call(messages, model_preferences, system_prompt, max_tokens,
+                               { 'includeContext' => include_context, 'temperature' => temperature,
+                                 'stopSequences' => stop_sequences, 'metadata' => metadata })
+      end
+    end
+
+    # Normalize and validate modelPreferences from sampling request (MCP 2025-11-25)
+    # Ensures hints is an array of hashes with 'name', and priority values are clamped to 0.0..1.0
+    # @param prefs [Hash, nil] raw modelPreferences from request
+    # @return [Hash, nil] normalized modelPreferences or nil
+    def normalize_model_preferences(prefs)
+      return nil if prefs.nil?
+      return nil unless prefs.is_a?(Hash)
+
+      normalized = {}
+
+      # Normalize hints: array of { 'name' => String }
+      if prefs['hints']
+        normalized['hints'] = Array(prefs['hints']).filter_map do |hint|
+          next nil unless hint.is_a?(Hash) && hint['name']
+
+          { 'name' => hint['name'].to_s }
+        end
+      end
+
+      # Normalize priority values (0.0 to 1.0)
+      %w[costPriority speedPriority intelligencePriority].each do |key|
+        next unless prefs.key?(key)
+
+        value = prefs[key]
+        normalized[key] = value.is_a?(Numeric) ? value.to_f.clamp(0.0, 1.0) : nil
+      end
+
+      normalized
+    end
+
+    # Validate sampling response from handler (MCP 2025-11-25)
     # @param result [Hash] the result from the sampling handler
     # @return [Hash] validated sampling response
     def validate_sampling_response(result)