ruby-mcp-client 0.8.0 → 0.9.0

data/lib/mcp_client/server_streamable_http.rb

@@ -9,9 +9,9 @@ require 'faraday/retry'
 require 'faraday/follow_redirects'
 
 module MCPClient
-  # Implementation of MCP server that communicates via Streamable HTTP transport (MCP 2025-03-26)
+  # Implementation of MCP server that communicates via Streamable HTTP transport (MCP 2025-06-18)
   # This transport uses HTTP POST for RPC calls with optional SSE responses, and GET for event streams
-  # Compliant with MCP specification version 2025-03-26
+  # Compliant with MCP specification version 2025-06-18
   #
   # Key features:
   # - Supports server-sent events (SSE) for real-time notifications
@@ -91,7 +91,7 @@ module MCPClient
       @headers = opts[:headers].merge({
                                         'Content-Type' => 'application/json',
                                         'Accept' => 'text/event-stream, application/json',
-                                        'Accept-Encoding' => 'gzip, deflate',
+                                        'Accept-Encoding' => 'gzip',
                                         'User-Agent' => "ruby-mcp-client/#{MCPClient::VERSION}",
                                         'Cache-Control' => 'no-cache'
                                       })
@@ -116,6 +116,7 @@ module MCPClient
       @events_connection = nil
       @events_thread = nil
       @buffer = '' # Buffer for partial SSE event data
+      @elicitation_request_callback = nil # MCP 2025-06-18
     end
 
     # Connect to the MCP server over Streamable HTTP
@@ -262,24 +263,32 @@ module MCPClient
     end
 
     # List all resources available from the MCP server
-    # @return [Array<MCPClient::Resource>] list of available resources
+    # @param cursor [String, nil] optional cursor for pagination
+    # @return [Hash] result containing resources array and optional nextCursor
     # @raise [MCPClient::Errors::ResourceReadError] if resources list retrieval fails
-    def list_resources
+    def list_resources(cursor: nil)
       @mutex.synchronize do
-        return @resources if @resources
+        return @resources_result if @resources_result && !cursor
       end
 
       begin
         ensure_connected
 
-        resources_data = request_resources_list
+        params = {}
+        params['cursor'] = cursor if cursor
+        result = rpc_request('resources/list', params)
+
+        resources = (result['resources'] || []).map do |resource_data|
+          MCPClient::Resource.from_json(resource_data, server: self)
+        end
+
+        resources_result = { 'resources' => resources, 'nextCursor' => result['nextCursor'] }
+
         @mutex.synchronize do
-          @resources = resources_data.map do |resource_data|
-            MCPClient::Resource.from_json(resource_data, server: self)
-          end
+          @resources_result = resources_result unless cursor
         end
 
-        @mutex.synchronize { @resources }
+        resources_result
       rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
         # Re-raise these errors directly
         raise
@@ -290,10 +299,12 @@ module MCPClient
 
     # Read a resource by its URI
     # @param uri [String] the URI of the resource to read
-    # @return [Object] the resource contents
+    # @return [Array<MCPClient::ResourceContent>] array of resource contents
     # @raise [MCPClient::Errors::ResourceReadError] if resource reading fails
     def read_resource(uri)
-      rpc_request('resources/read', { uri: uri })
+      result = rpc_request('resources/read', { uri: uri })
+      contents = result['contents'] || []
+      contents.map { |content| MCPClient::ResourceContent.from_json(content) }
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       # Re-raise connection/transport errors directly
       raise
@@ -302,6 +313,52 @@ module MCPClient
       raise MCPClient::Errors::ResourceReadError, "Error reading resource '#{uri}': #{e.message}"
     end
 
+    # List all resource templates available from the MCP server
+    # @param cursor [String, nil] optional cursor for pagination
+    # @return [Hash] result containing resourceTemplates array and optional nextCursor
+    # @raise [MCPClient::Errors::ResourceReadError] for other errors during resource template listing
+    def list_resource_templates(cursor: nil)
+      params = {}
+      params['cursor'] = cursor if cursor
+      result = rpc_request('resources/templates/list', params)
+
+      templates = (result['resourceTemplates'] || []).map do |template_data|
+        MCPClient::ResourceTemplate.from_json(template_data, server: self)
+      end
+
+      { 'resourceTemplates' => templates, 'nextCursor' => result['nextCursor'] }
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::ResourceReadError, "Error listing resource templates: #{e.message}"
+    end
+
+    # Subscribe to resource updates
+    # @param uri [String] the URI of the resource to subscribe to
+    # @return [Boolean] true if subscription successful
+    # @raise [MCPClient::Errors::ResourceReadError] for other errors during subscription
+    def subscribe_resource(uri)
+      rpc_request('resources/subscribe', { uri: uri })
+      true
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::ResourceReadError, "Error subscribing to resource '#{uri}': #{e.message}"
+    end
+
+    # Unsubscribe from resource updates
+    # @param uri [String] the URI of the resource to unsubscribe from
+    # @return [Boolean] true if unsubscription successful
+    # @raise [MCPClient::Errors::ResourceReadError] for other errors during unsubscription
+    def unsubscribe_resource(uri)
+      rpc_request('resources/unsubscribe', { uri: uri })
+      true
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::ResourceReadError, "Error unsubscribing from resource '#{uri}': #{e.message}"
+    end
+
     # Override apply_request_headers to add session and SSE headers for MCP protocol
     def apply_request_headers(req, request)
       super
@@ -395,6 +452,13 @@ module MCPClient
       end
     end
 
+    # Register a callback for elicitation requests (MCP 2025-06-18)
+    # @param block [Proc] callback that receives (request_id, params) and returns response hash
+    # @return [void]
+    def on_elicitation_request(&block)
+      @elicitation_request_callback = block
+    end
+
     private
 
     def perform_initialize
@@ -699,12 +763,12 @@ module MCPClient
         # Handle ping requests from server (keepalive mechanism)
         if message['method'] == 'ping' && message.key?('id')
           handle_ping_request(message['id'])
+        elsif message['method'] && message.key?('id')
+          # Handle server-to-client requests (MCP 2025-06-18)
+          handle_server_request(message)
         elsif message['method'] && !message.key?('id')
           # Handle server notifications (messages without id)
           @notification_callback&.call(message['method'], message['params'])
-        elsif message.key?('id')
-          # This might be a server-to-client request (future MCP versions)
-          @logger.warn("Received unhandled server request: #{message['method']}")
         end
       rescue JSON::ParserError => e
         @logger.error("Invalid JSON in server message: #{e.message}")
@@ -740,5 +804,123 @@ module MCPClient
         @logger.error("Failed to send pong response: #{e.message}")
       end
     end
+
+    # Handle incoming JSON-RPC request from server (MCP 2025-06-18)
+    # @param msg [Hash] the JSON-RPC request message
+    # @return [void]
+    def handle_server_request(msg)
+      request_id = msg['id']
+      method = msg['method']
+      params = msg['params'] || {}
+
+      @logger.debug("Received server request: #{method} (id: #{request_id})")
+
+      case method
+      when 'elicitation/create'
+        handle_elicitation_create(request_id, params)
+      else
+        # Unknown request method, send error response
+        send_error_response(request_id, -32_601, "Method not found: #{method}")
+      end
+    rescue StandardError => e
+      @logger.error("Error handling server request: #{e.message}")
+      send_error_response(request_id, -32_603, "Internal error: #{e.message}")
+    end
+
+    # Handle elicitation/create request from server (MCP 2025-06-18)
+    # @param request_id [String, Integer] the JSON-RPC request ID (used as elicitationId)
+    # @param params [Hash] the elicitation parameters
+    # @return [void]
+    def handle_elicitation_create(request_id, params)
+      # The request_id is the elicitationId per MCP spec
+      elicitation_id = request_id
+
+      # If no callback is registered, decline the request
+      unless @elicitation_request_callback
+        @logger.warn('Received elicitation request but no callback registered, declining')
+        send_elicitation_response(elicitation_id, { 'action' => 'decline' })
+        return
+      end
+
+      # Call the registered callback
+      result = @elicitation_request_callback.call(request_id, params)
+
+      # Send the response back to the server
+      send_elicitation_response(elicitation_id, result)
+    end
+
+    # Send elicitation response back to server via HTTP POST (MCP 2025-06-18)
+    # For streamable HTTP, this is sent as a JSON-RPC request (not response)
+    # because HTTP is unidirectional.
+    # @param elicitation_id [String] the elicitation ID from the server
+    # @param result [Hash] the elicitation result (action and optional content)
+    # @return [void]
+    def send_elicitation_response(elicitation_id, result)
+      params = {
+        'elicitationId' => elicitation_id,
+        'action' => result['action']
+      }
+
+      # Only include content if present (typically for 'accept' action)
+      params['content'] = result['content'] if result['content']
+
+      request = {
+        'jsonrpc' => '2.0',
+        'method' => 'elicitation/response',
+        'params' => params
+      }
+
+      # Send as a JSON-RPC request via HTTP POST
+      post_jsonrpc_response(request)
+    rescue StandardError => e
+      @logger.error("Error sending elicitation response: #{e.message}")
+    end
+
+    # Send error response back to server via HTTP POST (MCP 2025-06-18)
+    # @param request_id [String, Integer] the JSON-RPC request ID
+    # @param code [Integer] the error code
+    # @param message [String] the error message
+    # @return [void]
+    def send_error_response(request_id, code, message)
+      response = {
+        'jsonrpc' => '2.0',
+        'id' => request_id,
+        'error' => {
+          'code' => code,
+          'message' => message
+        }
+      }
+
+      # Send response via HTTP POST to the endpoint
+      post_jsonrpc_response(response)
+    rescue StandardError => e
+      @logger.error("Error sending error response: #{e.message}")
+    end
+
+    # Post a JSON-RPC response message to the server via HTTP
+    # @param response [Hash] the JSON-RPC response
+    # @return [void]
+    # @private
+    def post_jsonrpc_response(response)
+      # Send response in a separate thread to avoid blocking event processing
+      Thread.new do
+        conn = http_connection
+        json_body = JSON.generate(response)
+
+        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.body = json_body
+        end
+
+        if resp.success?
+          @logger.debug("Sent JSON-RPC response: #{json_body}")
+        else
+          @logger.warn("Failed to send JSON-RPC response: HTTP #{resp.status}")
+        end
+      rescue StandardError => e
+        @logger.error("Failed to send JSON-RPC response: #{e.message}")
+      end
+    end
   end
 end

data/lib/mcp_client/tool.rb

@@ -8,20 +8,28 @@ module MCPClient
     # @!attribute [r] description
     #   @return [String] the description of the tool
     # @!attribute [r] schema
-    #   @return [Hash] the JSON schema for the tool
+    #   @return [Hash] the JSON schema for the tool inputs
+    # @!attribute [r] output_schema
+    #   @return [Hash, nil] optional JSON schema for structured tool outputs (MCP 2025-06-18)
+    # @!attribute [r] annotations
+    #   @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, :server
+    attr_reader :name, :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
+    # @param schema [Hash] the JSON schema for the tool inputs
+    # @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:, server: nil)
+    def initialize(name:, description:, schema:, output_schema: nil, annotations: nil, server: nil)
       @name = name
       @description = description
       @schema = schema
+      @output_schema = output_schema
+      @annotations = annotations
       @server = server
     end
 
@@ -33,10 +41,14 @@ module MCPClient
       # Some servers (Playwright MCP CLI) use 'inputSchema' instead of 'schema'
       # Handle both string and symbol keys
       schema = data['inputSchema'] || data[:inputSchema] || data['schema'] || data[:schema]
+      output_schema = data['outputSchema'] || data[:outputSchema]
+      annotations = data['annotations'] || data[:annotations]
       new(
         name: data['name'] || data[:name],
         description: data['description'] || data[:description],
         schema: schema,
+        output_schema: output_schema,
+        annotations: annotations,
         server: server
       )
     end
@@ -74,6 +86,30 @@ module MCPClient
       }
     end
 
+    # Check if the tool is marked as read-only
+    # @return [Boolean] true if the tool is read-only
+    def read_only?
+      @annotations && @annotations['readOnly'] == true
+    end
+
+    # Check if the tool is marked as destructive
+    # @return [Boolean] true if the tool is destructive
+    def destructive?
+      @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
+    end
+
+    # Check if the tool supports structured outputs (MCP 2025-06-18)
+    # @return [Boolean] true if the tool has an output schema defined
+    def structured_output?
+      !@output_schema.nil? && !@output_schema.empty?
+    end
+
     private
 
     # Recursively remove "$schema" keys that are not accepted by Vertex AI

data/lib/mcp_client/version.rb

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

data/lib/mcp_client.rb

@@ -5,6 +5,8 @@ require_relative 'mcp_client/errors'
 require_relative 'mcp_client/tool'
 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/server_base'
 require_relative 'mcp_client/server_stdio'
 require_relative 'mcp_client/server_sse'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-mcp-client
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Szymon Kurcab
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-09-16 00:00:00.000000000 Z
+date: 2025-11-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -120,6 +120,7 @@ files:
 - README.md
 - lib/mcp_client.rb
 - lib/mcp_client/auth.rb
+- lib/mcp_client/auth/browser_oauth.rb
 - lib/mcp_client/auth/oauth_provider.rb
 - lib/mcp_client/client.rb
 - lib/mcp_client/config_parser.rb
@@ -129,6 +130,8 @@ files:
 - lib/mcp_client/oauth_client.rb
 - lib/mcp_client/prompt.rb
 - lib/mcp_client/resource.rb
+- lib/mcp_client/resource_content.rb
+- lib/mcp_client/resource_template.rb
 - lib/mcp_client/server_base.rb
 - lib/mcp_client/server_factory.rb
 - lib/mcp_client/server_http.rb