ruby-mcp-client 0.9.1 → 1.0.1

data/lib/mcp_client/http_transport_base.rb

@@ -58,6 +58,7 @@ module MCPClient
           # Apply base headers but prioritize session termination headers
           @headers.each { |k, v| req.headers[k] = v }
           req.headers['Mcp-Session-Id'] = @session_id
+          req.headers['Mcp-Protocol-Version'] = @protocol_version if @protocol_version
         end
 
         if response.success?
@@ -138,6 +139,7 @@ module MCPClient
 
       @server_info = result['serverInfo']
       @capabilities = result['capabilities']
+      @protocol_version = result['protocolVersion']
     end
 
     # Send a JSON-RPC request to the server and wait for result

data/lib/mcp_client/json_rpc_common.rb

@@ -63,9 +63,9 @@ module MCPClient
     # @return [Hash] the initialization parameters
     def initialization_params
       capabilities = {
-        'elicitation' => {}, # MCP 2025-06-18: Support for server-initiated user interactions
-        'roots' => { 'listChanged' => true }, # MCP 2025-06-18: Support for roots
-        'sampling' => {} # MCP 2025-06-18: Support for server-initiated LLM sampling
+        '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
       }
 
       {

data/lib/mcp_client/resource.rb

@@ -41,6 +41,14 @@ module MCPClient
       @server = server
     end
 
+    # Return the lastModified annotation value (ISO 8601 timestamp string)
+    # @return [String, nil] the lastModified timestamp, or nil if not set
+    def last_modified
+      return nil unless @annotations.is_a?(Hash)
+
+      @annotations['lastModified'] || @annotations[:lastModified]
+    end
+
     # Create a Resource instance from JSON data
     # @param data [Hash] JSON data from MCP server
     # @param server [MCPClient::ServerBase, nil] the server this resource belongs to

data/lib/mcp_client/resource_link.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module MCPClient
+  # Representation of an MCP resource link in tool result content
+  # A resource link references a server resource that can be read separately.
+  # Used in tool results to point clients to available resources (MCP 2025-11-25).
+  class ResourceLink
+    # @!attribute [r] uri
+    #   @return [String] URI of the linked resource
+    # @!attribute [r] name
+    #   @return [String] the name of the linked resource
+    # @!attribute [r] description
+    #   @return [String, nil] optional human-readable description
+    # @!attribute [r] mime_type
+    #   @return [String, nil] optional MIME type of the resource
+    # @!attribute [r] annotations
+    #   @return [Hash, nil] optional annotations that provide hints to clients
+    # @!attribute [r] title
+    #   @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
+
+    # Initialize a resource link
+    # @param uri [String] URI of the linked resource
+    # @param name [String] the name of the linked resource
+    # @param description [String, nil] optional human-readable description
+    # @param mime_type [String, nil] optional MIME type of the resource
+    # @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)
+      @uri = uri
+      @name = name
+      @description = description
+      @mime_type = mime_type
+      @annotations = annotations
+      @title = title
+      @size = size
+    end
+
+    # Create a ResourceLink instance from JSON data
+    # @param data [Hash] JSON data from MCP server (content item with type 'resource_link')
+    # @return [MCPClient::ResourceLink] resource link instance
+    def self.from_json(data)
+      new(
+        uri: data['uri'],
+        name: data['name'],
+        description: data['description'],
+        mime_type: data['mimeType'],
+        annotations: data['annotations'],
+        title: data['title'],
+        size: data['size']
+      )
+    end
+
+    # The content type identifier for this content type
+    # @return [String] 'resource_link'
+    def type
+      'resource_link'
+    end
+  end
+end

data/lib/mcp_client/server_http.rb

@@ -195,15 +195,22 @@ module MCPClient
       raise MCPClient::Errors::ToolCallError, "Error calling tool '#{tool_name}': #{e.message}"
     end
 
-    # Override apply_request_headers to add session headers for MCP protocol
+    # Override apply_request_headers to add session and protocol version headers
     def apply_request_headers(req, request)
       super
 
-      # Add session header if we have one (for non-initialize requests)
-      return unless @session_id && request['method'] != 'initialize'
+      # Add session and protocol version headers for non-initialize requests
+      return unless request['method'] != 'initialize'
 
-      req.headers['Mcp-Session-Id'] = @session_id
-      @logger.debug("Adding session header: Mcp-Session-Id: #{@session_id}")
+      if @session_id
+        req.headers['Mcp-Session-Id'] = @session_id
+        @logger.debug("Adding session header: Mcp-Session-Id: #{@session_id}")
+      end
+
+      return unless @protocol_version
+
+      req.headers['Mcp-Protocol-Version'] = @protocol_version
+      @logger.debug("Adding protocol version header: Mcp-Protocol-Version: #{@protocol_version}")
     end
 
     # Override handle_successful_response to capture session ID
@@ -325,10 +332,13 @@ module MCPClient
     # Request completion suggestions from the server (MCP 2025-06-18)
     # @param ref [Hash] reference to complete (prompt or resource)
     # @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)
     # @return [Hash] completion result with 'values', optional 'total', and 'hasMore' fields
     # @raise [MCPClient::Errors::ServerError] if server returns an error
-    def complete(ref:, argument:)
-      result = rpc_request('completion/complete', { ref: ref, argument: argument })
+    def complete(ref:, argument:, context: nil)
+      params = { ref: ref, argument: argument }
+      params[:context] = context if context
+      result = rpc_request('completion/complete', params)
       result['completion'] || { 'values' => [] }
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       raise

data/lib/mcp_client/server_sse.rb

@@ -106,7 +106,7 @@ module MCPClient
       @activity_timer_thread = nil
       @elicitation_request_callback = nil # MCP 2025-06-18
       @roots_list_request_callback = nil # MCP 2025-06-18
-      @sampling_request_callback = nil # MCP 2025-06-18
+      @sampling_request_callback = nil # MCP 2025-11-25
     end
 
     # Stream tool call fallback for SSE transport (yields single result)
@@ -330,10 +330,13 @@ module MCPClient
     # Request completion suggestions from the 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)
     # @return [Hash] completion result with 'values', optional 'total', and 'hasMore' fields
     # @raise [MCPClient::Errors::ServerError] if server returns an error
-    def complete(ref:, argument:)
-      result = rpc_request('completion/complete', { ref: ref, argument: argument })
+    def complete(ref:, argument:, context: nil)
+      params = { ref: ref, argument: argument }
+      params[:context] = context if context
+      result = rpc_request('completion/complete', params)
       result['completion'] || { 'values' => [] }
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       raise
@@ -455,7 +458,7 @@ module MCPClient
       @roots_list_request_callback = block
     end
 
-    # Register a callback for sampling requests (MCP 2025-06-18)
+    # Register a callback for sampling requests (MCP 2025-11-25)
     # @param block [Proc] callback that receives (request_id, params) and returns response hash
     # @return [void]
     def on_sampling_request(&block)
@@ -545,7 +548,7 @@ module MCPClient
       @logger.error("Error sending roots/list response: #{e.message}")
     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
     # @param params [Hash] the sampling parameters
     # @return [void]
@@ -564,7 +567,7 @@ module MCPClient
       send_sampling_response(request_id, result)
     end
 
-    # Send sampling response back to server via HTTP POST (MCP 2025-06-18)
+    # Send sampling response back to server via HTTP POST (MCP 2025-11-25)
     # @param request_id [String, Integer] the JSON-RPC request ID
     # @param result [Hash] the sampling result (role, content, model, stopReason)
     # @return [void]

data/lib/mcp_client/server_stdio.rb

@@ -48,7 +48,7 @@ module MCPClient
       @env           = env || {}
       @elicitation_request_callback = nil # MCP 2025-06-18
       @roots_list_request_callback = nil # MCP 2025-06-18
-      @sampling_request_callback = nil # MCP 2025-06-18
+      @sampling_request_callback = nil # MCP 2025-11-25
     end
 
     # Server info from the initialize response
@@ -345,16 +345,19 @@ module MCPClient
     # Request completion suggestions from the 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)
     # @return [Hash] completion result with 'values', optional 'total', and 'hasMore' fields
     # @raise [MCPClient::Errors::ServerError] if server returns an error
-    def complete(ref:, argument:)
+    def complete(ref:, argument:, context: nil)
       ensure_initialized
       req_id = next_id
+      params = { 'ref' => ref, 'argument' => argument }
+      params['context'] = context if context
       req = {
         'jsonrpc' => '2.0',
         'id' => req_id,
         'method' => 'completion/complete',
-        'params' => { 'ref' => ref, 'argument' => argument }
+        'params' => params
       }
       send_request(req)
       res = wait_response(req_id)
@@ -406,7 +409,7 @@ module MCPClient
       @roots_list_request_callback = block
     end
 
-    # Register a callback for sampling requests (MCP 2025-06-18)
+    # Register a callback for sampling requests (MCP 2025-11-25)
     # @param block [Proc] callback that receives (request_id, params) and returns response hash
     # @return [void]
     def on_sampling_request(&block)
@@ -477,7 +480,7 @@ module MCPClient
       send_roots_list_response(request_id, result)
     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
     # @param params [Hash] the sampling parameters
     # @return [void]
@@ -509,7 +512,7 @@ module MCPClient
       send_message(response)
     end
 
-    # Send sampling response back to server (MCP 2025-06-18)
+    # Send sampling response back to server (MCP 2025-11-25)
     # @param request_id [String, Integer] the JSON-RPC request ID
     # @param result [Hash] the sampling result (role, content, model, stopReason)
     # @return [void]

data/lib/mcp_client/server_streamable_http.rb

@@ -119,7 +119,7 @@ module MCPClient
       @buffer = '' # Buffer for partial SSE event data
       @elicitation_request_callback = nil # MCP 2025-06-18
       @roots_list_request_callback = nil # MCP 2025-06-18
-      @sampling_request_callback = nil # MCP 2025-06-18
+      @sampling_request_callback = nil # MCP 2025-11-25
     end
 
     # Connect to the MCP server over Streamable HTTP
@@ -222,10 +222,13 @@ module MCPClient
     # Request completion suggestions from the 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)
     # @return [Hash] completion result with 'values', optional 'total', and 'hasMore' fields
     # @raise [MCPClient::Errors::ServerError] if server returns an error
-    def complete(ref:, argument:)
-      result = rpc_request('completion/complete', { ref: ref, argument: argument })
+    def complete(ref:, argument:, context: nil)
+      params = { ref: ref, argument: argument }
+      params[:context] = context if context
+      result = rpc_request('completion/complete', params)
       result['completion'] || { 'values' => [] }
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       raise
@@ -393,10 +396,17 @@ module MCPClient
     def apply_request_headers(req, request)
       super
 
-      # Add session header if we have one (for non-initialize requests)
-      if @session_id && request['method'] != 'initialize'
-        req.headers['Mcp-Session-Id'] = @session_id
-        @logger.debug("Adding session header: Mcp-Session-Id: #{@session_id}")
+      # Add session and protocol version headers for non-initialize requests
+      if request['method'] != 'initialize'
+        if @session_id
+          req.headers['Mcp-Session-Id'] = @session_id
+          @logger.debug("Adding session header: Mcp-Session-Id: #{@session_id}")
+        end
+
+        if @protocol_version
+          req.headers['Mcp-Protocol-Version'] = @protocol_version
+          @logger.debug("Adding protocol version header: Mcp-Protocol-Version: #{@protocol_version}")
+        end
       end
 
       # Add Last-Event-ID header for resumability (if available)
@@ -496,7 +506,7 @@ module MCPClient
       @roots_list_request_callback = block
     end
 
-    # Register a callback for sampling requests (MCP 2025-06-18)
+    # Register a callback for sampling requests (MCP 2025-11-25)
     # @param block [Proc] callback that receives (request_id, params) and returns response hash
     # @return [void]
     def on_sampling_request(&block)
@@ -730,6 +740,7 @@ module MCPClient
     def apply_events_headers(req)
       @headers.each { |k, v| req.headers[k] = v }
       req.headers['Mcp-Session-Id'] = @session_id if @session_id
+      req.headers['Mcp-Protocol-Version'] = @protocol_version if @protocol_version
     end
 
     # Process event chunks from the server
@@ -840,6 +851,7 @@ module MCPClient
         response = conn.post(@endpoint) do |req|
           @headers.each { |k, v| req.headers[k] = v }
           req.headers['Mcp-Session-Id'] = @session_id if @session_id
+          req.headers['Mcp-Protocol-Version'] = @protocol_version if @protocol_version
           req.body = pong_response.to_json
         end
 
@@ -920,7 +932,7 @@ module MCPClient
       send_roots_list_response(request_id, result)
     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
     # @param params [Hash] the sampling parameters
     # @return [void]
@@ -956,7 +968,7 @@ module MCPClient
       @logger.error("Error sending roots/list response: #{e.message}")
     end
 
-    # Send sampling response back to server via HTTP POST (MCP 2025-06-18)
+    # Send sampling response back to server via HTTP POST (MCP 2025-11-25)
     # @param request_id [String, Integer] the JSON-RPC request ID
     # @param result [Hash] the sampling result (role, content, model, stopReason)
     # @return [void]
@@ -1040,6 +1052,7 @@ module MCPClient
         resp = conn.post(@endpoint) do |req|
           @headers.each { |k, v| req.headers[k] = v }
           req.headers['Mcp-Session-Id'] = @session_id if @session_id
+          req.headers['Mcp-Protocol-Version'] = @protocol_version if @protocol_version
           req.body = json_body
         end
 

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.1'
+  VERSION = '1.0.1'
 
   # MCP protocol version (date-based) - unified across all transports
-  PROTOCOL_VERSION = '2025-06-18'
+  PROTOCOL_VERSION = '2025-11-25'
 end