ruby_llm-mcp 0.7.1 → 1.0.0

data/lib/ruby_llm/mcp/adapters/mcp_transports/sse.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module RubyLLM::MCP::Adapters::MCPTransports
+  # Custom SSE transport for MCP SDK adapter
+  # Wraps the native SSE transport to provide the interface expected by MCP::Client
+  class SSE
+    attr_reader :native_transport
+
+    def initialize(url:, headers: {}, version: :http2, request_timeout: 10_000, # rubocop:disable Metrics/ParameterLists
+                   protocol_version: RubyLLM::MCP.config.protocol_version, notification_callback: nil)
+      # Create a minimal coordinator-like object for the native transport
+      @coordinator = CoordinatorStub.new(
+        protocol_version: protocol_version,
+        notification_callback: notification_callback
+      )
+
+      @native_transport = RubyLLM::MCP::Native::Transports::SSE.new(
+        url: url,
+        coordinator: @coordinator,
+        request_timeout: request_timeout,
+        options: {
+          headers: headers,
+          version: version
+        }
+      )
+    end
+
+    def start
+      @native_transport.start
+    end
+
+    def close
+      @native_transport.close
+    end
+
+    # Send a JSON-RPC request and return the response
+    # This is the interface expected by MCP::Client
+    #
+    # @param request [Hash] A JSON-RPC request object
+    # @return [Hash] A JSON-RPC response object
+    def send_request(request:)
+      start unless @native_transport.alive?
+
+      unless request["id"] || request[:id]
+        request["id"] = SecureRandom.uuid
+      end
+      result = @native_transport.request(request, wait_for_response: true)
+
+      if result.is_a?(RubyLLM::MCP::Result)
+        result.response
+      else
+        result
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/adapters/mcp_transports/stdio.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module RubyLLM::MCP::Adapters::MCPTransports
+  # Custom Stdio transport for MCP SDK adapter
+  # Wraps the native Stdio transport to provide the interface expected by MCP::Client
+  class Stdio
+    attr_reader :native_transport
+
+    def initialize(command:, args: [], env: {}, request_timeout: 10_000, # rubocop:disable Metrics/ParameterLists
+                   protocol_version: RubyLLM::MCP.config.protocol_version, notification_callback: nil)
+      # Create a minimal coordinator-like object for the native transport
+      @coordinator = CoordinatorStub.new(
+        protocol_version: protocol_version,
+        notification_callback: notification_callback
+      )
+
+      @native_transport = RubyLLM::MCP::Native::Transports::Stdio.new(
+        command: command,
+        args: args,
+        env: env,
+        coordinator: @coordinator,
+        request_timeout: request_timeout
+      )
+
+      @coordinator.transport = @native_transport
+    end
+
+    def start
+      @native_transport.start
+    end
+
+    def close
+      @native_transport.close
+    end
+
+    # Send a JSON-RPC request and return the response
+    # This is the interface expected by MCP::Client
+    #
+    # @param request [Hash] A JSON-RPC request object
+    # @return [Hash] A JSON-RPC response object
+    def send_request(request:)
+      start unless @native_transport.alive?
+
+      unless request["id"] || request[:id]
+        request["id"] = SecureRandom.uuid
+      end
+      result = @native_transport.request(request, wait_for_response: true)
+
+      if result.is_a?(RubyLLM::MCP::Result)
+        result.response
+      else
+        result
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/adapters/mcp_transports/streamable_http.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module RubyLLM::MCP::Adapters::MCPTransports
+  # Custom Streamable HTTP transport for MCP SDK adapter
+  # Wraps the native StreamableHTTP transport to provide the interface expected by MCP::Client
+  class StreamableHTTP
+    attr_reader :native_transport
+
+    def initialize(url:, headers: {}, version: :http2, request_timeout: 10_000, # rubocop:disable Metrics/ParameterLists
+                   reconnection: {}, oauth_provider: nil, rate_limit: nil, session_id: nil,
+                   protocol_version: RubyLLM::MCP.config.protocol_version, notification_callback: nil)
+      # Create a minimal coordinator-like object for the native transport
+      @coordinator = CoordinatorStub.new(
+        protocol_version: protocol_version,
+        notification_callback: notification_callback
+      )
+      @initialized = false
+
+      @native_transport = RubyLLM::MCP::Native::Transports::StreamableHTTP.new(
+        url: url,
+        headers: headers,
+        version: version,
+        coordinator: @coordinator,
+        request_timeout: request_timeout,
+        reconnection: reconnection,
+        oauth_provider: oauth_provider,
+        rate_limit: rate_limit,
+        session_id: session_id
+      )
+
+      @coordinator.transport = @native_transport
+    end
+
+    def start
+      @native_transport.start
+    end
+
+    def close
+      @initialized = false
+      @native_transport.close
+    end
+
+    # Send a JSON-RPC request and return the response
+    # This is the interface expected by MCP::Client
+    #
+    # @param request [Hash] A JSON-RPC request object
+    # @return [Hash] A JSON-RPC response object
+    def send_request(request:)
+      # Auto-initialize on first non-initialize request
+      # Streamable HTTP servers require initialization before other requests
+      unless @initialized || request[:method] == "initialize" || request["method"] == "initialize"
+        perform_initialization
+      end
+
+      unless request["id"] || request[:id]
+        request["id"] = SecureRandom.uuid
+      end
+      result = @native_transport.request(request, wait_for_response: true)
+
+      if result.is_a?(RubyLLM::MCP::Result)
+        result.response
+      else
+        result
+      end
+    end
+
+    private
+
+    def perform_initialization
+      # Send initialization request
+      init_request = RubyLLM::MCP::Native::Messages::Requests.initialize(
+        protocol_version: @coordinator.protocol_version,
+        capabilities: @coordinator.client_capabilities
+      )
+      result = @native_transport.request(init_request, wait_for_response: true)
+
+      if result.is_a?(RubyLLM::MCP::Result) && result.error?
+        raise RubyLLM::MCP::Errors::TransportError.new(
+          message: "Initialization failed: #{result.error}",
+          error: result.error
+        )
+      end
+
+      initialized_notification = RubyLLM::MCP::Native::Messages::Notifications.initialized
+      @native_transport.request(initialized_notification, wait_for_response: false)
+
+      @initialized = true
+    end
+  end
+end

data/lib/ruby_llm/mcp/adapters/ruby_llm_adapter.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module RubyLLM
+  module MCP
+    module Adapters
+      # RubyLLM Adapter - wraps the Native protocol implementation
+      # This is a thin bridge between the public API and Native::Client
+      class RubyLLMAdapter < BaseAdapter
+        extend Forwardable
+
+        supports :tools, :prompts, :resources, :resource_templates,
+                 :completions, :logging, :sampling, :roots,
+                 :notifications, :progress_tracking, :human_in_the_loop,
+                 :elicitation, :subscriptions, :list_changed_notifications,
+                 :tasks
+
+        supports_transport :stdio, :sse, :streamable, :streamable_http
+
+        attr_reader :native_client
+
+        def initialize(client, transport_type:, config: {})
+          validate_transport!(transport_type)
+          super
+
+          request_timeout = config.delete(:request_timeout)
+          protocol_version = @config[:protocol_version]
+          extensions_capabilities = build_client_extensions_capabilities(protocol_version: protocol_version)
+          transport_config = prepare_transport_config(config, transport_type)
+
+          @native_client = Native::Client.new(
+            name: client.name,
+            transport_type: transport_type,
+            transport_config: transport_config,
+            request_timeout: request_timeout,
+            human_in_the_loop_callback: build_human_in_the_loop_callback(client),
+            roots_callback: -> { client.roots.paths },
+            logging_enabled: client.logging_handler_enabled?,
+            logging_level: client.on_logging_level,
+            # Always advertise elicitation capability for native adapter clients.
+            # If no handler is set, requests are safely rejected by the callback path.
+            elicitation_enabled: true,
+            progress_tracking_enabled: client.tracking_progress?,
+            elicitation_callback: build_elicitation_callback(client),
+            sampling_callback: build_sampling_callback(client),
+            notification_callback: ->(notification) { NotificationHandler.new(client).execute(notification) },
+            protocol_version: @config[:protocol_version],
+            extensions_capabilities: extensions_capabilities
+          )
+        end
+
+        def_delegators :@native_client,
+                       :start, :stop, :restart!, :alive?, :ping,
+                       :capabilities, :client_capabilities, :protocol_version,
+                       :tool_list, :execute_tool,
+                       :resource_list, :resource_read, :resource_template_list,
+                       :resources_subscribe, :resources_unsubscribe,
+                       :prompt_list, :execute_prompt,
+                       :tasks_list, :task_get, :task_result, :task_cancel, :task_status_notification,
+                       :completion_resource, :completion_prompt,
+                       :set_logging, :set_progress_tracking,
+                       :set_elicitation_enabled,
+                       :initialize_notification, :cancelled_notification,
+                       :roots_list_change_notification,
+                       :ping_response, :roots_list_response,
+                       :sampling_create_message_response,
+                       :error_response, :elicitation_response,
+                       :register_in_flight_request, :unregister_in_flight_request,
+                       :cancel_in_flight_request
+
+        def supports_extension_negotiation?
+          true
+        end
+
+        def extension_mode
+          :full
+        end
+
+        def build_client_extensions_capabilities(protocol_version:)
+          return {} unless Native::Protocol.extensions_supported?(protocol_version)
+
+          Extensions::Registry.normalize_map(@config[:extensions]).transform_values { |value| value || {} }
+        end
+
+        def register_resource(resource)
+          client.linked_resources << resource
+          client.resources[resource.name] = resource
+        end
+
+        private
+
+        def prepare_transport_config(config, transport_type)
+          transport_config = config.dup
+          transport_config.delete(:protocol_version)
+          transport_config.delete("protocol_version")
+          transport_config.delete(:extensions)
+          transport_config.delete("extensions")
+
+          if %i[sse streamable streamable_http].include?(transport_type)
+            oauth_provider = Auth::TransportOauthHelper.create_oauth_provider(transport_config) if Auth::TransportOauthHelper.oauth_config_present?(transport_config)
+
+            Auth::TransportOauthHelper.prepare_http_transport_config(transport_config, oauth_provider)
+          elsif transport_type == :stdio
+            Auth::TransportOauthHelper.prepare_stdio_transport_config(transport_config)
+          else
+            transport_config
+          end
+        end
+
+        def build_human_in_the_loop_callback(client)
+          lambda do |name, params|
+            return Handlers::ApprovalDecision.approved unless client.human_in_the_loop?
+
+            handler_config = normalize_human_in_the_loop_handler(client.on[:human_in_the_loop])
+            unless handler_config
+              RubyLLM::MCP.logger.error(
+                "Human-in-the-loop callback must be a handler class configuration"
+              )
+              return Handlers::ApprovalDecision.denied(reason: "Invalid approval handler configuration")
+            end
+
+            execute_handler_class(
+              handler_config[:class],
+              name,
+              params,
+              handler_options: handler_config[:options]
+            )
+          end
+        end
+
+        def build_sampling_callback(client)
+          lambda do |sample|
+            return nil unless client.sampling_callback_enabled?
+
+            handler_or_block = client.on[:sampling]
+
+            if Handlers.handler_class?(handler_or_block)
+              handler_or_block.new(sample: sample, coordinator: @native_client).call
+            else
+              handler_or_block.call(sample)
+            end
+          end
+        end
+
+        def build_elicitation_callback(client)
+          lambda do |elicitation|
+            return nil unless client.elicitation_enabled?
+
+            handler_or_block = client.on[:elicitation]
+            return false unless handler_or_block
+
+            if Handlers.handler_class?(handler_or_block)
+              handler_or_block.new(elicitation: elicitation, coordinator: @native_client).call
+            else
+              handler_or_block.call(elicitation)
+            end
+          end
+        end
+
+        def execute_handler_class(handler_class, name, params, handler_options: {})
+          approval_id = "#{@native_client.registry_owner_id}:#{SecureRandom.uuid}"
+
+          handler_instance = handler_class.new(
+            tool_name: name,
+            parameters: params,
+            approval_id: approval_id,
+            coordinator: @native_client,
+            **handler_options
+          )
+
+          result = handler_instance.call
+          decision = Handlers::ApprovalDecision.from_handler_result(
+            result,
+            approval_id: approval_id,
+            default_timeout: handler_instance.timeout
+          )
+
+          if decision.deferred?
+            promise = Handlers::Promise.new
+            @native_client.human_in_the_loop_registry.store(
+              approval_id,
+              {
+                promise: promise,
+                timeout: decision.timeout,
+                tool_name: name,
+                parameters: params
+              }
+            )
+            return decision.with_promise(promise)
+          end
+
+          decision
+        rescue Errors::InvalidApprovalDecision => e
+          RubyLLM::MCP.logger.error("Invalid human-in-the-loop handler decision: #{e.message}")
+          Handlers::ApprovalDecision.denied(reason: "Invalid approval decision")
+        rescue StandardError => e
+          RubyLLM::MCP.logger.error("Error in human-in-the-loop handler: #{e.message}\n#{e.backtrace.join("\n")}")
+          Handlers::ApprovalDecision.denied(reason: "Approval handler error")
+        end
+
+        def normalize_human_in_the_loop_handler(handler_config)
+          if handler_config.is_a?(Hash)
+            handler_class = handler_config[:class] || handler_config["class"]
+            options = handler_config[:options] || handler_config["options"] || {}
+            return nil unless Handlers.handler_class?(handler_class)
+
+            { class: handler_class, options: options }
+          elsif Handlers.handler_class?(handler_config)
+            { class: handler_config, options: {} }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/auth/browser/callback_handler.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Auth
+      module Browser
+        # Handles OAuth callback request processing
+        # Extracts and validates OAuth parameters from callback requests
+        class CallbackHandler
+          attr_reader :callback_path, :logger
+
+          def initialize(callback_path:, logger: nil)
+            @callback_path = callback_path
+            @logger = logger || MCP.logger
+          end
+
+          # Validate that the request path matches the expected callback path
+          # @param path [String] request path
+          # @return [Boolean] true if path is valid
+          def valid_callback_path?(path)
+            uri_path, = path.split("?", 2)
+            uri_path == @callback_path
+          end
+
+          # Parse callback parameters from path
+          # @param path [String] full request path with query string
+          # @param http_server [HttpServer] HTTP server instance for parsing
+          # @return [Hash] parsed parameters
+          def parse_callback_params(path, http_server)
+            _, query_string = path.split("?", 2)
+            params = http_server.parse_query_params(query_string || "")
+            @logger.debug("Callback params: #{params.keys.join(', ')}")
+            params
+          end
+
+          # Extract OAuth parameters from parsed params
+          # @param params [Hash] parsed query parameters
+          # @return [Hash] OAuth parameters (code, state, error, error_description)
+          def extract_oauth_params(params)
+            {
+              code: params["code"],
+              state: params["state"],
+              error: params["error"],
+              error_description: params["error_description"]
+            }
+          end
+
+          # Update result hash with OAuth parameters (thread-safe)
+          # @param oauth_params [Hash] OAuth parameters
+          # @param result [Hash] result container
+          # @param mutex [Mutex] synchronization mutex
+          # @param condition [ConditionVariable] wait condition
+          def update_result_with_oauth_params(oauth_params, result, mutex, condition)
+            mutex.synchronize do
+              if oauth_params[:error]
+                result[:error] = oauth_params[:error_description] || oauth_params[:error]
+              elsif oauth_params[:code] && oauth_params[:state]
+                result[:code] = oauth_params[:code]
+                result[:state] = oauth_params[:state]
+              else
+                result[:error] = "Invalid callback: missing code or state parameter"
+              end
+              result[:completed] = true
+              condition.signal
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/auth/browser/callback_server.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Auth
+      module Browser
+        # Callback server wrapper for clean shutdown
+        # Manages server lifecycle and thread coordination
+        class CallbackServer
+          def initialize(server, thread, stop_proc, start_proc = nil)
+            @server = server
+            @thread = thread
+            @stop_proc = stop_proc
+            @start_proc = start_proc || -> {}
+          end
+
+          # Start callback processing loop
+          def start
+            @start_proc.call
+          end
+
+          # Shutdown server and cleanup resources
+          # @return [nil] always returns nil
+          def shutdown
+            @stop_proc.call
+            @server.close unless @server.closed?
+            @thread.join(5) # Wait max 5 seconds for thread to finish
+          rescue StandardError
+            # Ignore shutdown errors
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/auth/browser/http_server.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Auth
+      module Browser
+        # HTTP server utilities for OAuth callback handling
+        # Provides lightweight HTTP server functionality without external dependencies
+        class HttpServer
+          attr_reader :port, :logger
+
+          def initialize(port:, logger: nil)
+            @port = port
+            @logger = logger || MCP.logger
+          end
+
+          # Start TCP server for OAuth callbacks
+          # @return [TCPServer] TCP server instance
+          # @raise [Errors::TransportError] if server cannot start
+          def start_server
+            TCPServer.new("127.0.0.1", @port)
+          rescue Errno::EADDRINUSE
+            raise Errors::TransportError.new(
+              message: "Cannot start OAuth callback server: port #{@port} is already in use. " \
+                       "Please close the application using this port or choose a different callback_port."
+            )
+          rescue StandardError => e
+            raise Errors::TransportError.new(
+              message: "Failed to start OAuth callback server on port #{@port}: #{e.message}"
+            )
+          end
+
+          # Configure client socket with timeout
+          # @param client [TCPSocket] client socket
+          def configure_client_socket(client)
+            client.setsockopt(Socket::SOL_SOCKET, Socket::SO_RCVTIMEO, [5, 0].pack("l_2"))
+          end
+
+          # Read HTTP request line from client
+          # @param client [TCPSocket] client socket
+          # @return [String, nil] request line
+          def read_request_line(client)
+            client.gets
+          end
+
+          # Extract method and path from request line
+          # @param request_line [String] HTTP request line
+          # @return [Array<String, String>, nil] method and path, or nil if invalid
+          def extract_request_parts(request_line)
+            parts = request_line.split
+            return nil unless parts.length >= 2
+
+            parts[0..1]
+          end
+
+          # Read HTTP headers from client
+          # @param client [TCPSocket] client socket
+          def read_http_headers(client)
+            header_count = 0
+            loop do
+              break if header_count >= 100
+
+              line = client.gets
+              break if line.nil? || line.strip.empty?
+
+              header_count += 1
+            end
+          end
+
+          # Parse URL query parameters
+          # @param query_string [String] query string
+          # @return [Hash] parsed parameters
+          def parse_query_params(query_string)
+            params = {}
+            query_string.split("&").each do |param|
+              next if param.empty?
+
+              key, value = param.split("=", 2)
+              params[CGI.unescape(key)] = CGI.unescape(value || "")
+            end
+            params
+          end
+
+          # Send HTTP response to client
+          # @param client [TCPSocket] client socket
+          # @param status [Integer] HTTP status code
+          # @param content_type [String] content type
+          # @param body [String] response body
+          def send_http_response(client, status, content_type, body)
+            status_text = case status
+                          when 200 then "OK"
+                          when 400 then "Bad Request"
+                          when 404 then "Not Found"
+                          else "Unknown"
+                          end
+
+            response = "HTTP/1.1 #{status} #{status_text}\r\n"
+            response += "Content-Type: #{content_type}\r\n"
+            response += "Content-Length: #{body.bytesize}\r\n"
+            response += "Connection: close\r\n"
+            response += "\r\n"
+            response += body
+
+            client.write(response)
+          rescue IOError, Errno::EPIPE => e
+            @logger.debug("Error sending response: #{e.message}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/auth/browser/opener.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Auth
+      module Browser
+        # Browser opening utilities for different operating systems
+        # Handles cross-platform browser launching
+        class Opener
+          attr_reader :logger
+
+          def initialize(logger: nil)
+            @logger = logger || MCP.logger
+          end
+
+          # Open browser to URL
+          # @param url [String] URL to open
+          # @return [Boolean] true if successful
+          def open_browser(url)
+            case RbConfig::CONFIG["host_os"]
+            when /darwin/
+              system("open", url)
+            when /linux|bsd/
+              system("xdg-open", url)
+            when /mswin|mingw|cygwin/
+              system("start", url)
+            else
+              @logger.warn("Unknown operating system, cannot open browser automatically")
+              false
+            end
+          rescue StandardError => e
+            @logger.warn("Failed to open browser: #{e.message}")
+            false
+          end
+        end
+      end
+    end
+  end
+end