ruby_llm_swarm-mcp 0.8.0

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

@@ -0,0 +1,179 @@
+# 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 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 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,292 @@
+# 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
+        # Note: The MCP gem (as of v0.4) does NOT support prompts or resource templates
+        supports :tools, :resources
+
+        # 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
+
+        def initialize(client, transport_type:, config: {})
+          validate_transport!(transport_type)
+          require_mcp_gem!
+          super
+
+          @mcp_client = nil
+        end
+
+        def start
+          return if @mcp_client
+
+          transport = build_transport
+          transport.start if transport.respond_to?(:start)
+
+          @mcp_client = ::MCP::Client.new(transport: transport)
+        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
+          # Note: Prompts are not supported by the MCP gem
+          ServerCapabilities.new({
+                                   "tools" => {},
+                                   "resources" => {}
+                                 })
+        end
+
+        def client_capabilities
+          {} # Official SDK handles this internally
+        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
+          []
+        end
+
+        def execute_prompt(name:, arguments:)
+          raise NotImplementedError, "Prompts are not supported by the MCP SDK (gem 'mcp')"
+        end
+
+        def resource_template_list(cursor: nil) # rubocop:disable Lint/UnusedMethodArgument
+          []
+        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
+        # - set_logging
+        # - 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 ::MCP::VERSION < "0.4"
+            raise Errors::AdapterConfigurationError.new(message: <<~MSG)
+              The official MCP SDK version 0.4 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.4'
+
+            Then run: bundle install
+          MSG
+        end
+
+        def build_transport
+          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
+            )
+          when :sse
+            MCPTransports::SSE.new(
+              url: @config[:url],
+              headers: @config[:headers] || {},
+              version: @config[:version] || :http2,
+              request_timeout: @config[:request_timeout] || 10_000
+            )
+          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]
+            )
+          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
+          }
+        end
+
+        def transform_resource(resource)
+          {
+            "name" => resource["name"],
+            "uri" => resource["uri"],
+            "description" => resource["description"],
+            "mimeType" => resource["mimeType"]
+          }
+        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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# 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
+      @name = "MCP-SDK-Adapter"
+      @protocol_version = RubyLLM::MCP::Native::Protocol.default_negotiated_version
+      @transport = nil
+    end
+
+    def process_result(result)
+      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

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

@@ -0,0 +1,52 @@
+# 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)
+      # Create a minimal coordinator-like object for the native transport
+      @coordinator = CoordinatorStub.new
+
+      @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,52 @@
+# 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)
+      # Create a minimal coordinator-like object for the native transport
+      @coordinator = CoordinatorStub.new
+
+      @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,86 @@
+# 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)
+      # Create a minimal coordinator-like object for the native transport
+      @coordinator = CoordinatorStub.new
+      @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