ruby_llm-mcp 0.7.1 → 1.0.0

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

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Adapters
+      class BaseAdapter
+        class << self
+          def supported_features
+            @supported_features ||= {}
+          end
+
+          def supports(*features)
+            features.each { |f| supported_features[f] = true }
+          end
+
+          def support?(feature)
+            supported_features[feature] || false
+          end
+
+          def supported_transports
+            @supported_transports ||= []
+          end
+
+          def supports_transport(*transports)
+            @supported_transports = transports
+          end
+
+          def transport_supported?(transport)
+            supported_transports.include?(transport.to_sym)
+          end
+        end
+
+        attr_reader :client
+
+        def initialize(client, transport_type:, config: {})
+          @client = client
+          @transport_type = transport_type
+          @config = config
+        end
+
+        def supports?(feature)
+          self.class.support?(feature)
+        end
+
+        def supports_extension_negotiation?
+          false
+        end
+
+        def extension_mode
+          :none
+        end
+
+        def build_client_extensions_capabilities(protocol_version:) # rubocop:disable Lint/UnusedMethodArgument
+          {}
+        end
+
+        def validate_transport!(transport_type)
+          unless self.class.transport_supported?(transport_type)
+            raise Errors::UnsupportedTransport.new(
+              message: <<~MSG.strip
+                Transport '#{transport_type}' is not supported by #{self.class.name}.
+                Supported transports: #{self.class.supported_transports.join(', ')}
+              MSG
+            )
+          end
+        end
+
+        def start
+          raise NotImplementedError, "#{self.class.name} must implement #start"
+        end
+
+        def stop
+          raise NotImplementedError, "#{self.class.name} must implement #stop"
+        end
+
+        def restart!
+          raise NotImplementedError, "#{self.class.name} must implement #restart!"
+        end
+
+        def alive?
+          raise NotImplementedError, "#{self.class.name} must implement #alive?"
+        end
+
+        def ping
+          raise NotImplementedError, "#{self.class.name} must implement #ping"
+        end
+
+        def capabilities
+          raise NotImplementedError, "#{self.class.name} must implement #capabilities"
+        end
+
+        def client_capabilities
+          raise NotImplementedError, "#{self.class.name} must implement #client_capabilities"
+        end
+
+        def tool_list(cursor: nil)
+          raise NotImplementedError, "#{self.class.name} must implement #tool_list"
+        end
+
+        def execute_tool(name:, parameters:)
+          raise NotImplementedError, "#{self.class.name} must implement #execute_tool"
+        end
+
+        def resource_list(cursor: nil)
+          raise NotImplementedError, "#{self.class.name} must implement #resource_list"
+        end
+
+        def resource_read(uri:)
+          raise NotImplementedError, "#{self.class.name} must implement #resource_read"
+        end
+
+        def prompt_list(cursor: nil)
+          raise NotImplementedError, "#{self.class.name} must implement #prompt_list"
+        end
+
+        def execute_prompt(name:, arguments:)
+          raise NotImplementedError, "#{self.class.name} must implement #execute_prompt"
+        end
+
+        def resource_template_list(cursor: nil) # rubocop:disable Lint/UnusedMethodArgument
+          raise_unsupported_feature(:resource_templates)
+        end
+
+        def completion_resource(uri:, argument:, value:, context: nil) # rubocop:disable Lint/UnusedMethodArgument
+          raise_unsupported_feature(:completions)
+        end
+
+        def completion_prompt(name:, argument:, value:, context: nil) # rubocop:disable Lint/UnusedMethodArgument
+          raise_unsupported_feature(:completions)
+        end
+
+        def set_logging(level:) # rubocop:disable Lint/UnusedMethodArgument
+          raise_unsupported_feature(:logging)
+        end
+
+        def resources_subscribe(uri:) # rubocop:disable Lint/UnusedMethodArgument
+          raise_unsupported_feature(:subscriptions)
+        end
+
+        def resources_unsubscribe(uri:) # rubocop:disable Lint/UnusedMethodArgument
+          raise_unsupported_feature(:subscriptions)
+        end
+
+        def tasks_list(cursor: nil) # rubocop:disable Lint/UnusedMethodArgument
+          raise_unsupported_feature(:tasks)
+        end
+
+        def task_get(task_id:) # rubocop:disable Lint/UnusedMethodArgument
+          raise_unsupported_feature(:tasks)
+        end
+
+        def task_result(task_id:) # rubocop:disable Lint/UnusedMethodArgument
+          raise_unsupported_feature(:tasks)
+        end
+
+        def task_cancel(task_id:) # rubocop:disable Lint/UnusedMethodArgument
+          raise_unsupported_feature(:tasks)
+        end
+
+        def task_status_notification(task:) # rubocop:disable Lint/UnusedMethodArgument
+          raise_unsupported_feature(:tasks)
+        end
+
+        def initialize_notification
+          raise_unsupported_feature(:notifications)
+        end
+
+        def cancelled_notification(reason:, request_id:) # rubocop:disable Lint/UnusedMethodArgument
+          raise_unsupported_feature(:notifications)
+        end
+
+        def roots_list_change_notification
+          raise_unsupported_feature(:notifications)
+        end
+
+        def ping_response(id:) # rubocop:disable Lint/UnusedMethodArgument
+          raise_unsupported_feature(:responses)
+        end
+
+        def roots_list_response(id:) # rubocop:disable Lint/UnusedMethodArgument
+          raise_unsupported_feature(:responses)
+        end
+
+        def sampling_create_message_response(id:, model:, message:, **_options) # rubocop:disable Lint/UnusedMethodArgument
+          raise_unsupported_feature(:sampling)
+        end
+
+        def error_response(id:, message:, code: -32_000) # rubocop:disable Lint/UnusedMethodArgument
+          raise_unsupported_feature(:responses)
+        end
+
+        def elicitation_response(id:, elicitation:) # rubocop:disable Lint/UnusedMethodArgument
+          raise_unsupported_feature(:elicitation)
+        end
+
+        def register_resource(_resource)
+          raise_unsupported_feature(:resource_registration)
+        end
+
+        private
+
+        def raise_unsupported_feature(feature)
+          raise Errors::UnsupportedFeature.new(
+            message: <<~MSG.strip
+              Feature '#{feature}' is not supported by #{self.class.name}.
+
+              This feature requires the :ruby_llm adapter.
+              Change your configuration to use adapter: :ruby_llm
+            MSG
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,413 @@
+# frozen_string_literal: true
+
+require_relative "mcp_transports/coordinator_stub"
+require_relative "mcp_transports/stdio"
+require_relative "mcp_transports/sse"
+require_relative "mcp_transports/streamable_http"
+
+module RubyLLM
+  module MCP
+    module Adapters
+      class MCPSdkAdapter < BaseAdapter
+        # Only declare features the official MCP SDK supports
+        supports :tools, :resources, :prompts, :resource_templates, :logging
+
+        # Supported transports:
+        # - stdio: Via custom wrapper using native stdio transport ✓ FULLY TESTED
+        # - sse: Via custom wrapper using native SSE transport ✓ FUNCTIONAL
+        # - http: Via MCP::Client::HTTP (for simple JSON-only HTTP servers)
+        supports_transport :stdio, :http, :sse, :streamable, :streamable_http
+
+        attr_reader :transport_type, :config, :mcp_client
+
+        def initialize(client, transport_type:, config: {})
+          validate_transport!(transport_type)
+          require_mcp_gem!
+          super
+
+          @mcp_client = nil
+          @notification_handler = NotificationHandler.new(client)
+          warn_passive_extension_support! if configured_extensions?
+        end
+
+        def start
+          return if @mcp_client
+
+          transport = build_transport
+          transport.start if transport.respond_to?(:start)
+
+          @mcp_client = ::MCP::Client.new(transport: transport)
+          set_logging(level: client.on_logging_level) if client.logging_handler_enabled?
+        end
+
+        def stop
+          if @mcp_client && @mcp_client.transport.respond_to?(:close)
+            @mcp_client.transport.close
+          end
+          @mcp_client = nil
+        end
+
+        def restart!
+          stop
+          start
+        end
+
+        def alive?
+          !@mcp_client.nil?
+        end
+
+        def ping # rubocop:disable Naming/PredicateMethod
+          ensure_started
+          alive?
+        end
+
+        def capabilities
+          # Return minimal capabilities for official SDK
+          @capabilities ||= ServerCapabilities.new(
+            "tools" => {},
+            "resources" => {},
+            "prompts" => {},
+            "logging" => {}
+          )
+        end
+
+        def client_capabilities
+          {} # Official SDK handles this internally
+        end
+
+        def supports_extension_negotiation?
+          false
+        end
+
+        def extension_mode
+          :passive
+        end
+
+        def build_client_extensions_capabilities(protocol_version:) # rubocop:disable Lint/UnusedMethodArgument
+          {}
+        end
+
+        def tool_list(cursor: nil) # rubocop:disable Lint/UnusedMethodArgument
+          ensure_started
+          @mcp_client.tools.map { |tool| transform_tool(tool) }
+        end
+
+        def execute_tool(name:, parameters:)
+          ensure_started
+          tool = find_tool(name)
+          result = @mcp_client.call_tool(tool: tool, arguments: parameters)
+          transform_tool_result(result)
+        rescue RubyLLM::MCP::Errors::TimeoutError => e
+          native_transport = @mcp_client&.transport&.native_transport
+          if native_transport&.alive? && !e.request_id.nil?
+            cancelled_notification(reason: "Request timed out", request_id: e.request_id)
+          end
+          raise e
+        end
+
+        def resource_list(cursor: nil) # rubocop:disable Lint/UnusedMethodArgument
+          ensure_started
+          @mcp_client.resources.map { |resource| transform_resource(resource) }
+        end
+
+        def resource_read(uri:)
+          ensure_started
+          result = @mcp_client.read_resource(uri: uri)
+          transform_resource_content(result)
+        end
+
+        def prompt_list(cursor: nil) # rubocop:disable Lint/UnusedMethodArgument
+          ensure_started
+          @mcp_client.prompts.map { |prompt| transform_prompt(prompt) }
+        end
+
+        def execute_prompt(name:, arguments:)
+          ensure_started
+          response = @mcp_client.transport.send_request(
+            request: {
+              jsonrpc: "2.0",
+              id: SecureRandom.uuid,
+              method: "prompts/get",
+              params: {
+                name: name,
+                arguments: arguments
+              }
+            }
+          )
+
+          transform_prompt_result(response)
+        end
+
+        def resource_template_list(cursor: nil) # rubocop:disable Lint/UnusedMethodArgument
+          ensure_started
+          @mcp_client.resource_templates.map { |resource_template| transform_resource_template(resource_template) }
+        end
+
+        def set_logging(level:)
+          ensure_started
+          @mcp_client.transport.send_request(
+            request: {
+              jsonrpc: "2.0",
+              id: SecureRandom.uuid,
+              method: "logging/setLevel",
+              params: { level: level }
+            }
+          )
+        end
+
+        def cancelled_notification(reason:, request_id:)
+          return unless @mcp_client&.transport.respond_to?(:native_transport)
+
+          native_transport = @mcp_client.transport.native_transport
+          return unless native_transport
+
+          body = RubyLLM::MCP::Native::Messages::Notifications.cancelled(
+            request_id: request_id,
+            reason: reason
+          )
+          native_transport.request(body, wait_for_response: false)
+        end
+
+        # These methods remain as NotImplementedError from base class:
+        # - completion_resource
+        # - completion_prompt
+        # - resources_subscribe
+        # - initialize_notification
+        # - roots_list_change_notification
+        # - ping_response
+        # - roots_list_response
+        # - sampling_create_message_response
+        # - error_response
+        # - elicitation_response
+        # - register_resource
+
+        private
+
+        def ensure_started
+          start unless @mcp_client
+        end
+
+        def require_mcp_gem!
+          require "mcp"
+          if Gem::Version.new(::MCP::VERSION) < Gem::Version.new("0.7.0")
+            raise Errors::AdapterConfigurationError.new(message: <<~MSG)
+              The official MCP SDK version 0.7 or higher is required to use the :mcp_sdk adapter.
+            MSG
+          end
+        rescue LoadError
+          raise LoadError, <<~MSG
+            The official MCP SDK is required to use the :mcp_sdk adapter.
+
+            Add to your Gemfile:
+              gem 'mcp', '~> 0.7'
+
+            Then run: bundle install
+          MSG
+        end
+
+        def build_transport # rubocop:disable Metrics/MethodLength
+          protocol_version = @config[:protocol_version] || RubyLLM::MCP.config.protocol_version
+          notification_callback = lambda do |notification|
+            @notification_handler.execute(notification)
+          end
+
+          case @transport_type
+          when :http
+            # MCP::Client::HTTP is for simple JSON-only HTTP servers
+            # Use :streamable for servers that support the streamable HTTP/SSE protocol
+            ::MCP::Client::HTTP.new(
+              url: @config[:url],
+              headers: @config[:headers] || {}
+            )
+          when :stdio
+            MCPTransports::Stdio.new(
+              command: @config[:command],
+              args: @config[:args] || [],
+              env: @config[:env] || {},
+              request_timeout: @config[:request_timeout] || 10_000,
+              protocol_version: protocol_version,
+              notification_callback: notification_callback
+            )
+          when :sse
+            MCPTransports::SSE.new(
+              url: @config[:url],
+              headers: @config[:headers] || {},
+              version: @config[:version] || :http2,
+              request_timeout: @config[:request_timeout] || 10_000,
+              protocol_version: protocol_version,
+              notification_callback: notification_callback
+            )
+          when :streamable, :streamable_http
+            config_copy = @config.dup
+            oauth_provider = Auth::TransportOauthHelper.create_oauth_provider(config_copy) if Auth::TransportOauthHelper.oauth_config_present?(config_copy)
+
+            MCPTransports::StreamableHTTP.new(
+              url: @config[:url],
+              headers: @config[:headers] || {},
+              version: @config[:version] || :http2,
+              request_timeout: @config[:request_timeout] || 10_000,
+              reconnection: @config[:reconnection] || {},
+              oauth_provider: oauth_provider,
+              rate_limit: @config[:rate_limit],
+              session_id: @config[:session_id],
+              protocol_version: protocol_version,
+              notification_callback: notification_callback
+            )
+          end
+        end
+
+        def find_tool(name)
+          @mcp_client.tools.find { |t| t.name == name } ||
+            raise(Errors::ResponseError.new(
+                    message: "Tool '#{name}' not found",
+                    error: { "code" => -32_602, "message" => "Tool not found" }
+                  ))
+        end
+
+        # Transform methods to normalize official SDK objects
+        def transform_tool(tool)
+          {
+            "name" => tool.name,
+            "description" => tool.description,
+            "inputSchema" => tool.input_schema,
+            "outputSchema" => tool.output_schema,
+            "_meta" => extract_tool_meta(tool)
+          }.compact
+        end
+
+        def transform_resource(resource)
+          {
+            "name" => resource["name"],
+            "uri" => resource["uri"],
+            "title" => resource["title"],
+            "description" => resource["description"],
+            "mimeType" => resource["mimeType"],
+            "annotations" => resource["annotations"],
+            "icons" => resource["icons"],
+            "_meta" => resource["_meta"]
+          }.compact
+        end
+
+        def transform_prompt(prompt)
+          {
+            "name" => prompt["name"],
+            "title" => prompt["title"],
+            "description" => prompt["description"],
+            "arguments" => prompt["arguments"]
+          }.compact
+        end
+
+        def transform_resource_template(resource_template)
+          {
+            "name" => resource_template["name"],
+            "uriTemplate" => resource_template["uriTemplate"],
+            "title" => resource_template["title"],
+            "description" => resource_template["description"],
+            "mimeType" => resource_template["mimeType"],
+            "annotations" => resource_template["annotations"],
+            "icons" => resource_template["icons"],
+            "_meta" => resource_template["_meta"]
+          }.compact
+        end
+
+        def transform_tool_result(result)
+          # The MCP gem returns the full JSON-RPC response
+          # Extract the content from result["result"]["content"]
+          content = if result.is_a?(Hash) && result["result"] && result["result"]["content"]
+                      result["result"]["content"]
+                    elsif result.is_a?(Array)
+                      result.map { |item| transform_content_item(item) }
+                    else
+                      [{ "type" => "text", "text" => result.to_s }]
+                    end
+
+          is_error = if result.is_a?(Hash) && result["result"]
+                       result["result"]["isError"]
+                     end
+
+          result_data = { "content" => content }
+          result_data["isError"] = is_error unless is_error.nil?
+
+          Result.new({
+                       "result" => result_data
+                     })
+        end
+
+        def transform_content_item(item)
+          case item
+          when String
+            { "type" => "text", "text" => item }
+          when Hash
+            item
+          else
+            { "type" => "text", "text" => item.to_s }
+          end
+        end
+
+        def transform_resource_content(result)
+          contents = if result.is_a?(Array)
+                       result.map { |r| transform_single_resource_content(r) }
+                     else
+                       [transform_single_resource_content(result)]
+                     end
+
+          Result.new({
+                       "result" => {
+                         "contents" => contents
+                       }
+                     })
+        end
+
+        def transform_single_resource_content(result)
+          {
+            "uri" => result["uri"],
+            "mimeType" => result["mimeType"],
+            "text" => result["text"],
+            "blob" => result["blob"]
+          }
+        end
+
+        def transform_prompt_result(result)
+          if result.is_a?(Hash) && (result.key?("result") || result.key?("error"))
+            Result.new(result)
+          else
+            Result.new({
+                         "result" => result || {}
+                       })
+          end
+        end
+
+        def configured_extensions?
+          !Extensions::Registry.normalize_map(@config[:extensions]).empty?
+        end
+
+        def warn_passive_extension_support!
+          self.class.warn_passive_extension_support_once
+        end
+
+        def extract_tool_meta(tool)
+          return tool["_meta"] if tool.respond_to?(:[]) && tool["_meta"]
+          return tool.meta if tool.respond_to?(:meta)
+          return tool.instance_variable_get(:@meta) if tool.instance_variable_defined?(:@meta)
+
+          nil
+        end
+
+        class << self
+          def warn_passive_extension_support_once
+            @extensions_warning_mutex ||= Mutex.new
+
+            @extensions_warning_mutex.synchronize do
+              return if @extensions_warning_emitted
+
+              RubyLLM::MCP.logger.warn(
+                "MCP SDK adapter extension configuration is passive: extensions are accepted but not advertised."
+              )
+              @extensions_warning_emitted = true
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RubyLLM::MCP::Adapters::MCPTransports
+  # Minimal coordinator stub for MCP transports
+  # The native transports expect a coordinator object, but for the MCP SDK adapter
+  # we don't need to process results (just pass them through)
+  # as MCP SDK adapter doesn't methods that requires responsing to the MCP server as of yet.
+  class CoordinatorStub
+    attr_reader :name, :protocol_version
+    attr_accessor :transport
+
+    def initialize(protocol_version:, notification_callback: nil)
+      @name = "MCP-SDK-Adapter"
+      @protocol_version = protocol_version
+      @transport = nil
+      @notification_callback = notification_callback
+    end
+
+    def process_result(result)
+      if result&.notification?
+        @notification_callback&.call(result.notification)
+        return nil
+      end
+
+      return nil if result&.request?
+
+      result
+    end
+
+    def client_capabilities
+      {} # MCP SDK doesn't provide client capabilities
+    end
+
+    def request(body, **options)
+      # For notifications (cancelled, etc), we need to send them through the transport
+      return nil unless @transport
+
+      @transport.request(body, **options)
+    end
+  end
+end