ruby_llm-mcp 0.7.1 → 0.8.0

data/lib/ruby_llm/mcp/client.rb

@@ -17,6 +17,11 @@ module RubyLLM
         @transport_type = transport_type.to_sym
         @request_timeout = request_timeout
 
+        # Store OAuth config before coordinator setup
+        @oauth_config = config[:oauth] || config["oauth"]
+        @oauth_provider = nil
+        @oauth_storage = nil
+
         @coordinator = setup_coordinator
 
         @on = {}
@@ -49,6 +54,40 @@ module RubyLLM
         @coordinator.restart_transport
       end
 
+      # Get or create OAuth provider for this client
+      # @param type [Symbol] OAuth provider type (:standard or :browser, defaults to :standard)
+      # @param options [Hash] additional options passed to provider
+      # @return [OAuthProvider, BrowserOAuthProvider] OAuth provider instance
+      def oauth(type: :standard, **options)
+        # Return existing provider if already created
+        return @oauth_provider if @oauth_provider
+
+        # Get provider from transport if it already exists
+        transport_oauth = @coordinator.transport_oauth_provider
+        return transport_oauth if transport_oauth
+
+        # Create new provider lazily
+        server_url = @config[:url] || @config["url"]
+        unless server_url
+          raise Errors::ConfigurationError.new(
+            message: "Cannot create OAuth provider without server URL in config"
+          )
+        end
+
+        oauth_options = {
+          server_url: server_url,
+          scope: @oauth_config&.dig(:scope) || @oauth_config&.dig("scope"),
+          storage: oauth_storage,
+          **options
+        }
+
+        @oauth_provider = Auth.create_oauth(
+          server_url,
+          type: type,
+          **oauth_options
+        )
+      end
+
       def tools(refresh: false)
         return [] unless capabilities.tools_list?
 
@@ -260,6 +299,16 @@ module RubyLLM
         @on_logging_level = MCP.config.on_logging_level
         @on[:elicitation] = MCP.config.on_elicitation
       end
+
+      # Get or create OAuth storage shared with transport
+      def oauth_storage
+        # Try to get storage from transport's OAuth provider
+        transport_oauth = @coordinator.transport_oauth_provider
+        return transport_oauth.storage if transport_oauth
+
+        # Create new storage shared with client
+        @oauth_storage ||= Auth::MemoryStorage.new
+      end
     end
   end
 end

data/lib/ruby_llm/mcp/configuration.rb

@@ -42,6 +42,36 @@ module RubyLLM
         end
       end
 
+      class OAuth
+        attr_accessor :client_name,
+                      :client_uri,
+                      :software_id,
+                      :software_version,
+                      :logo_uri,
+                      :contacts,
+                      :tos_uri,
+                      :policy_uri,
+                      :jwks_uri,
+                      :jwks,
+                      :browser_success_page,
+                      :browser_error_page
+
+        def initialize
+          @client_name = "RubyLLM MCP Client"
+          @client_uri = nil
+          @software_id = "ruby_llm-mcp"
+          @software_version = RubyLLM::MCP::VERSION
+          @logo_uri = nil
+          @contacts = nil
+          @tos_uri = nil
+          @policy_uri = nil
+          @jwks_uri = nil
+          @jwks = nil
+          @browser_success_page = nil
+          @browser_error_page = nil
+        end
+      end
+
       class ConfigFile
         attr_reader :file_path
 
@@ -87,7 +117,6 @@ module RubyLLM
       attr_accessor :request_timeout,
                     :log_file,
                     :log_level,
-                    :has_support_complex_parameters,
                     :roots,
                     :sampling,
                     :max_connections,
@@ -95,7 +124,8 @@ module RubyLLM
                     :protocol_version,
                     :config_path,
                     :launch_control,
-                    :on_logging_level
+                    :on_logging_level,
+                    :oauth
 
       attr_writer :logger, :mcp_configuration
 
@@ -103,6 +133,7 @@ module RubyLLM
 
       def initialize
         @sampling = Sampling.new
+        @oauth = OAuth.new
         set_defaults
       end
 
@@ -110,14 +141,6 @@ module RubyLLM
         set_defaults
       end
 
-      def support_complex_parameters!
-        warn "[DEPRECATION] config.support_complex_parameters! is no longer needed and will be removed in version 0.8.0"
-        return if @has_support_complex_parameters
-
-        @has_support_complex_parameters = true
-        RubyLLM::MCP.support_complex_parameters!
-      end
-
       def logger
         @logger ||= Logger.new(
           log_file,
@@ -188,9 +211,6 @@ module RubyLLM
         @log_level = ENV["RUBYLLM_MCP_DEBUG"] ? Logger::DEBUG : Logger::INFO
         @logger = nil
 
-        # Complex parameters support
-        @has_support_complex_parameters = false
-
         # MCPs configuration
         @mcps_config_path = nil
         @mcp_configuration = []
@@ -201,6 +221,12 @@ module RubyLLM
         # Roots configuration
         @roots = []
 
+        # Protocol configuration
+        @protocol_version = Protocol.latest_version
+
+        # OAuth configuration
+        @oauth = OAuth.new
+
         # Sampling configuration
         @sampling.reset!
 

data/lib/ruby_llm/mcp/coordinator.rb

@@ -283,6 +283,17 @@ module RubyLLM
         @transport ||= RubyLLM::MCP::Transport.new(@transport_type, self, config: @config)
       end
 
+      # Get OAuth provider from transport if available
+      # @return [OAuthProvider, BrowserOAuthProvider, nil] OAuth provider or nil
+      def transport_oauth_provider
+        return nil unless @transport
+
+        transport_protocol = @transport.transport_protocol
+        return nil unless transport_protocol.respond_to?(:oauth_provider)
+
+        transport_protocol.oauth_provider
+      end
+
       private
 
       def sampling_enabled?

data/lib/ruby_llm/mcp/errors.rb

@@ -36,6 +36,17 @@ module RubyLLM
         end
       end
 
+      class AuthenticationRequiredError < BaseError
+        attr_reader :code
+
+        def initialize(message: "Authentication required", code: 401)
+          @code = code
+          super(message: message)
+        end
+      end
+
+      class ConfigurationError < BaseError; end
+
       class SessionExpiredError < BaseError; end
 
       class TimeoutError < BaseError

data/lib/ruby_llm/mcp/railtie.rb

@@ -3,17 +3,9 @@
 module RubyLLM
   module MCP
     class Railtie < Rails::Railtie
-      config.after_initialize do
-        if RubyLLM::MCP.config.launch_control == :automatic
-          RubyLLM::MCP.clients.each_value.map(&:start)
-          at_exit do
-            RubyLLM::MCP.clients.each_value.map(&:stop)
-          end
-        end
-      end
-
       generators do
-        require_relative "../../generators/ruby_llm/mcp/install_generator"
+        require_relative "../../generators/ruby_llm/mcp/install/install_generator"
+        require_relative "../../generators/ruby_llm/mcp/oauth/install_generator"
       end
     end
   end

data/lib/ruby_llm/mcp/tool.rb

@@ -25,7 +25,7 @@ module RubyLLM
     end
 
     class Tool < RubyLLM::Tool
-      attr_reader :name, :title, :description, :coordinator, :tool_response, :with_prefix
+      attr_reader :name, :title, :description, :annotations, :coordinator, :tool_response, :with_prefix
 
       def initialize(coordinator, tool_response, with_prefix: false)
         super()

data/lib/ruby_llm/mcp/transport.rb

@@ -50,8 +50,101 @@ module RubyLLM
           raise Errors::InvalidTransportType.new(message: message)
         end
 
+        transport_config = prepare_transport_config
         transport_klass = RubyLLM::MCP::Transport.transports[transport_type]
-        transport_klass.new(coordinator: coordinator, **config)
+        transport_klass.new(coordinator: coordinator, **transport_config)
+      end
+
+      def prepare_transport_config
+        transport_config = config.dup
+        oauth_provider = create_oauth_provider(transport_config) if oauth_config_present?(transport_config)
+
+        # Extract transport-specific parameters and consolidate into options
+        if %i[sse streamable streamable_http].include?(transport_type)
+          prepare_http_transport_config(transport_config, oauth_provider)
+        elsif transport_type == :stdio
+          prepare_stdio_transport_config(transport_config)
+        else
+          transport_config
+        end
+      end
+
+      def prepare_http_transport_config(config, oauth_provider)
+        options = {
+          version: config.delete(:version) || config.delete("version"),
+          headers: config.delete(:headers) || config.delete("headers"),
+          oauth_provider: oauth_provider,
+          reconnection: config.delete(:reconnection) || config.delete("reconnection"),
+          reconnection_options: config.delete(:reconnection_options) || config.delete("reconnection_options"),
+          rate_limit: config.delete(:rate_limit) || config.delete("rate_limit"),
+          session_id: config.delete(:session_id) || config.delete("session_id")
+        }.compact
+
+        config[:options] = options
+        config
+      end
+
+      def prepare_stdio_transport_config(config)
+        options = {
+          args: config.delete(:args) || config.delete("args"),
+          env: config.delete(:env) || config.delete("env")
+        }.compact
+
+        config[:options] = options unless options.empty?
+        config
+      end
+
+      # Check if OAuth configuration is present
+      def oauth_config_present?(config)
+        oauth_config = config[:oauth] || config["oauth"]
+        return false if oauth_config.nil?
+
+        # If it's an OAuth provider instance, it's present
+        return true if oauth_config.respond_to?(:access_token)
+
+        # If it's a hash, check if it's not empty
+        !oauth_config.empty?
+      end
+
+      # Create OAuth provider from configuration
+      # Accepts either a provider instance or a configuration hash
+      def create_oauth_provider(config)
+        oauth_config = config.delete(:oauth) || config.delete("oauth")
+        return nil unless oauth_config
+
+        # If provider key exists with an instance, use it
+        if oauth_config.is_a?(Hash) && (oauth_config[:provider] || oauth_config["provider"])
+          return oauth_config[:provider] || oauth_config["provider"]
+        end
+
+        # If oauth_config itself is a provider instance, use it directly
+        if oauth_config.respond_to?(:access_token) && oauth_config.respond_to?(:start_authorization_flow)
+          return oauth_config
+        end
+
+        # Otherwise create new provider from config hash
+        # Determine server URL based on transport type
+        server_url = determine_server_url(config)
+        return nil unless server_url
+
+        redirect_uri = oauth_config[:redirect_uri] || oauth_config["redirect_uri"] || "http://localhost:8080/callback"
+        scope = oauth_config[:scope] || oauth_config["scope"]
+        storage = oauth_config[:storage] || oauth_config["storage"]
+        grant_type = oauth_config[:grant_type] || oauth_config["grant_type"] || :authorization_code
+
+        RubyLLM::MCP::Auth::OAuthProvider.new(
+          server_url: server_url,
+          redirect_uri: redirect_uri,
+          scope: scope,
+          logger: MCP.logger,
+          storage: storage,
+          grant_type: grant_type
+        )
+      end
+
+      # Determine server URL from transport config
+      def determine_server_url(config)
+        config[:url] || config["url"]
       end
     end
   end

data/lib/ruby_llm/mcp/transports/sse.rb

@@ -12,26 +12,28 @@ module RubyLLM
       class SSE
         include Support::Timeout
 
-        attr_reader :headers, :id, :coordinator
+        attr_reader :headers, :id, :coordinator, :oauth_provider
 
-        def initialize(url:, coordinator:, request_timeout:, version: :http2, headers: {})
+        def initialize(url:, coordinator:, request_timeout:, options: {})
           @event_url = url
           @messages_url = nil
           @coordinator = coordinator
           @request_timeout = request_timeout
-          @version = version
+          @version = options[:version] || options["version"] || :http2
+          @oauth_provider = options[:oauth_provider] || options["oauth_provider"]
 
           uri = URI.parse(url)
           @root_url = "#{uri.scheme}://#{uri.host}"
           @root_url += ":#{uri.port}" if uri.port != uri.default_port
 
           @client_id = SecureRandom.uuid
-          @headers = headers.merge({
-                                     "Accept" => "text/event-stream",
-                                     "Content-Type" => "application/json",
-                                     "Cache-Control" => "no-cache",
-                                     "X-CLIENT-ID" => @client_id
-                                   })
+          custom_headers = options[:headers] || options["headers"] || {}
+          @headers = custom_headers.merge({
+                                            "Accept" => "text/event-stream",
+                                            "Content-Type" => "application/json",
+                                            "Cache-Control" => "no-cache",
+                                            "X-CLIENT-ID" => @client_id
+                                          })
 
           @id_counter = 0
           @id_mutex = Mutex.new
@@ -42,6 +44,7 @@ module RubyLLM
           @sse_thread = nil
 
           RubyLLM::MCP.logger.info "Initializing SSE transport to #{@event_url} with client ID #{@client_id}"
+          RubyLLM::MCP.logger.debug "OAuth provider: #{@oauth_provider ? 'present' : 'none'}" if @oauth_provider
         end
 
         def request(body, add_id: true, wait_for_response: true)
@@ -104,20 +107,53 @@ module RubyLLM
         private
 
         def send_request(body, request_id)
-          http_client = Support::HTTPClient.connection.with(timeout: { request_timeout: @request_timeout / 1000 },
-                                                            headers: @headers)
+          request_headers = build_request_headers
+          http_client = Support::HTTPClient.connection.with(
+            timeout: { request_timeout: @request_timeout / 1000 },
+            headers: request_headers
+          )
           response = http_client.post(@messages_url, body: JSON.generate(body))
           handle_httpx_error_response!(response,
                                        context: { location: "message endpoint request", request_id: request_id })
 
           unless [200, 202].include?(response.status)
-            message = "Failed to have a successful request to #{@messages_url}: #{response.status} - #{response.body}"
-            RubyLLM::MCP.logger.error(message)
+            handle_send_request_error(response)
+          end
+        end
+
+        def handle_send_request_error(response)
+          response_body = response.respond_to?(:body) ? response.body.to_s : "Unknown error"
+          status_code = response.respond_to?(:status) ? response.status : "Unknown"
+
+          # Try to parse JSON error
+          error_message = begin
+            error_body = JSON.parse(response_body)
+            if error_body.is_a?(Hash) && error_body["error"]
+              msg = error_body["error"]["message"] || error_body["error"]["code"] || error_body["error"].to_s
+              msg.to_s.strip.empty? ? "Empty error (full response: #{response_body})" : msg
+            else
+              response_body
+            end
+          rescue JSON::ParserError
+            response_body
+          end
+
+          full_message = "Failed to have a successful request to #{@messages_url}: #{status_code} - #{error_message}"
+          RubyLLM::MCP.logger.error(full_message)
+
+          # Special handling for 403 with OAuth
+          if status_code == 403 && @oauth_provider
             raise Errors::TransportError.new(
-              message: message,
-              code: response.status
+              message: "Authorization failed (403 Forbidden): #{error_message}. Check token scope and resource \
+                permissions at #{@oauth_provider.server_url}.",
+              code: status_code
             )
           end
+
+          raise Errors::TransportError.new(
+            message: full_message,
+            code: status_code
+          )
         end
 
         def start_sse_listener
@@ -173,28 +209,86 @@ module RubyLLM
         end
 
         def create_sse_client
-          sse_client = HTTPX.plugin(:stream).with(headers: @headers)
+          stream_headers = build_request_headers
+          sse_client = HTTPX.plugin(:stream).with(headers: stream_headers)
           return sse_client unless @version == :http1
 
           sse_client.with(ssl: { alpn_protocols: ["http/1.1"] })
         end
 
+        # Build request headers with OAuth authorization if available
+        def build_request_headers
+          headers = @headers.dup
+
+          if @oauth_provider
+            RubyLLM::MCP.logger.debug "OAuth provider present, attempting to get token..."
+            RubyLLM::MCP.logger.debug "  Server URL: #{@oauth_provider.server_url}"
+
+            token = @oauth_provider.access_token
+            if token
+              headers["Authorization"] = token.to_header
+              RubyLLM::MCP.logger.debug "✓ Applied OAuth authorization header: #{token.to_header[0..30]}..."
+            else
+              RubyLLM::MCP.logger.warn "✗ OAuth provider present but no valid token available!"
+              RubyLLM::MCP.logger.warn "  This means the token is not in storage or has expired"
+              RubyLLM::MCP.logger.warn "  Check that authentication completed successfully"
+            end
+          else
+            RubyLLM::MCP.logger.debug "No OAuth provider configured for this transport"
+          end
+
+          headers
+        end
+
         def validate_sse_response!(response)
           return unless response.status >= 400
 
           error_body = read_error_body(response)
-          error_message = "HTTP #{response.status} error from SSE endpoint: #{error_body}"
-          RubyLLM::MCP.logger.error error_message
 
-          handle_client_error!(error_message, response.status) if response.status < 500
+          # Try to parse as JSON to get better error details
+          error_message = begin
+            error_data = JSON.parse(error_body)
+            if error_data.is_a?(Hash) && error_data["error"]
+              msg = error_data["error"]["message"] || error_data["error"]["code"] || error_data["error"].to_s
+              # If we still don't have a message, include the full error object
+              msg.to_s.strip.empty? ? "Empty error (full response: #{error_body})" : msg
+            else
+              error_body
+            end
+          rescue JSON::ParserError
+            error_body
+          end
+
+          full_error_message = "HTTP #{response.status} error from SSE endpoint: #{error_message}"
+          RubyLLM::MCP.logger.error full_error_message
 
-          raise StandardError, error_message
+          handle_client_error!(full_error_message, response.status, error_message) if response.status < 500
+
+          raise StandardError, full_error_message
         end
 
-        def handle_client_error!(error_message, status_code)
+        def handle_client_error!(full_error_message, status_code, error_message)
           @running = false
+
+          # Special handling for 401 Unauthorized - OAuth authentication required
+          if status_code == 401
+            raise Errors::AuthenticationRequiredError.new(
+              message: "OAuth authentication required. Server returned 401 Unauthorized.",
+              code: 401
+            )
+          end
+
+          # Special handling for 403 Forbidden with OAuth
+          if status_code == 403 && @oauth_provider
+            raise Errors::TransportError.new(
+              message: "Authorization failed (403 Forbidden): #{error_message}. \
+                Check token scope and resource permissions at #{@oauth_provider.server_url}.",
+              code: status_code
+            )
+          end
+
           raise Errors::TransportError.new(
-            message: error_message,
+            message: full_error_message,
             code: status_code
           )
         end

data/lib/ruby_llm/mcp/transports/stdio.rb

@@ -13,13 +13,14 @@ module RubyLLM
 
         attr_reader :command, :stdin, :stdout, :stderr, :id, :coordinator
 
-        def initialize(command:, coordinator:, request_timeout:, args: [], env: {})
+        def initialize(command:, coordinator:, request_timeout:, options: {})
           @request_timeout = request_timeout
           @command = command
           @coordinator = coordinator
-          @args = args
-          @env = env || {}
+          @args = options[:args] || options["args"] || []
+          @env = options[:env] || options["env"] || {}
           @client_id = SecureRandom.uuid
+          # NOTE: Stdio transport doesn't use OAuth (local process communication)
 
           @id_counter = 0
           @id_mutex = Mutex.new