ruby_llm_swarm-mcp 0.8.0

data/lib/ruby_llm/mcp/native/json_rpc.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Native
+      module JsonRpc
+        VERSION = "2.0"
+
+        module ErrorCodes
+          PARSE_ERROR = -32_700
+          INVALID_REQUEST = -32_600
+          METHOD_NOT_FOUND = -32_601
+          INVALID_PARAMS = -32_602
+          INTERNAL_ERROR = -32_603
+
+          SERVER_ERROR_MIN = -32_099
+          SERVER_ERROR_MAX = -32_000
+
+          SERVER_ERROR = -32_000
+        end
+
+        class EnvelopeValidator
+          attr_reader :envelope, :errors
+
+          def initialize(envelope)
+            @envelope = envelope
+            @errors = []
+          end
+
+          def valid?
+            validate!
+            @errors.empty?
+          end
+
+          def error_message
+            @errors.join("; ") if @errors.any?
+          end
+
+          def notification?
+            !envelope.key?("id") && envelope.key?("method")
+          end
+
+          def request?
+            envelope.key?("id") && envelope.key?("method") &&
+              !envelope.key?("result") && !envelope.key?("error")
+          end
+
+          def response?
+            envelope.key?("id") && !envelope.key?("method") &&
+              (envelope.key?("result") || envelope.key?("error"))
+          end
+
+          private
+
+          def validate!
+            @errors = []
+
+            unless envelope.is_a?(Hash)
+              @errors << "Envelope must be an object"
+              return
+            end
+
+            unless envelope["jsonrpc"] == VERSION
+              @errors << "Missing or invalid 'jsonrpc' field (must be '#{VERSION}')"
+            end
+
+            # Determine message type and validate
+            # Priority: response > request > notification (to catch malformed messages)
+            if envelope.key?("id") && (envelope.key?("result") || envelope.key?("error"))
+              validate_response!
+            elsif envelope.key?("id") && envelope.key?("method")
+              validate_request!
+            elsif !envelope.key?("id") && envelope.key?("method")
+              validate_notification!
+            else
+              @errors << "Message must be a request, response, or notification"
+            end
+          end
+
+          def validate_notification!
+            unless envelope["method"].is_a?(String) && !envelope["method"].empty?
+              @errors << "Notification must have a non-empty 'method' string"
+            end
+
+            if envelope.key?("id")
+              @errors << "Notification must not have 'id' field"
+            end
+
+            if envelope.key?("params") && !structured_value?(envelope["params"])
+              @errors << "Notification 'params' must be an object or array"
+            end
+          end
+
+          def validate_request!
+            unless envelope["method"].is_a?(String) && !envelope["method"].empty?
+              @errors << "Request must have a non-empty 'method' string"
+            end
+
+            unless valid_id?(envelope["id"])
+              @errors << "Request 'id' must be a string, number, or null"
+            end
+
+            if envelope.key?("params") && !structured_value?(envelope["params"])
+              @errors << "Request 'params' must be an object or array"
+            end
+
+            if envelope.key?("result") || envelope.key?("error")
+              @errors << "Request must not have 'result' or 'error' fields"
+            end
+          end
+
+          def validate_response!
+            unless valid_id?(envelope["id"])
+              @errors << "Response 'id' must be a string, number, or null"
+            end
+
+            if envelope.key?("method")
+              @errors << "Response must not have 'method' field"
+            end
+
+            has_result = envelope.key?("result")
+            has_error = envelope.key?("error")
+
+            if has_result && has_error
+              @errors << "Response must have either 'result' or 'error', not both"
+            elsif !has_result && !has_error
+              @errors << "Response must have either 'result' or 'error'"
+            end
+
+            if has_error
+              validate_error_object!(envelope["error"])
+            end
+          end
+
+          def validate_error_object!(error)
+            unless error.is_a?(Hash)
+              @errors << "Error must be an object"
+              return
+            end
+
+            unless error["code"].is_a?(Integer)
+              @errors << "Error 'code' must be an integer"
+            end
+
+            unless error["message"].is_a?(String)
+              @errors << "Error 'message' must be a string"
+            end
+
+            if error.key?("data") && !valid_data_value?(error["data"])
+              @errors << "Error 'data' must be a valid JSON value"
+            end
+          end
+
+          def valid_id?(id)
+            id.is_a?(String) || id.is_a?(Numeric) || id.nil?
+          end
+
+          def structured_value?(value)
+            value.is_a?(Hash) || value.is_a?(Array)
+          end
+
+          def valid_data_value?(value)
+            value.is_a?(String) || value.is_a?(Numeric) || value.is_a?(TrueClass) ||
+              value.is_a?(FalseClass) || value.nil? || value.is_a?(Hash) || value.is_a?(Array)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/native/messages/helpers.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module RubyLLM
+  module MCP
+    module Native
+      module Messages
+        # Helper methods for message construction
+        module Helpers
+          def generate_id
+            SecureRandom.uuid
+          end
+
+          def add_progress_token(params, tracking_progress: false)
+            return params unless tracking_progress
+
+            params[:_meta] ||= {}
+            params[:_meta][:progressToken] = generate_id
+            params
+          end
+
+          def add_cursor(params, cursor)
+            return params unless cursor
+
+            params[:cursor] = cursor
+            params
+          end
+
+          def format_completion_context(context)
+            return nil if context.nil?
+
+            { arguments: context }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/native/messages/notifications.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Native
+      module Messages
+        # Notification message builders
+        # Notifications do not have IDs and do not expect responses
+        module Notifications
+          extend Helpers
+
+          module_function
+
+          def initialized
+            {
+              jsonrpc: JSONRPC_VERSION,
+              method: METHOD_NOTIFICATION_INITIALIZED
+            }
+          end
+
+          def cancelled(request_id:, reason:)
+            {
+              jsonrpc: JSONRPC_VERSION,
+              method: METHOD_NOTIFICATION_CANCELLED,
+              params: {
+                requestId: request_id,
+                reason: reason
+              }
+            }
+          end
+
+          def roots_list_changed
+            {
+              jsonrpc: JSONRPC_VERSION,
+              method: METHOD_NOTIFICATION_ROOTS_LIST_CHANGED
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/native/messages/requests.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Native
+      module Messages
+        # Request message builders
+        # All methods return a JSON-RPC request body ready to be sent
+        module Requests
+          extend Helpers
+
+          module_function
+
+          def initialize(protocol_version:, capabilities:)
+            {
+              jsonrpc: JSONRPC_VERSION,
+              id: generate_id,
+              method: METHOD_INITIALIZE,
+              params: {
+                protocolVersion: protocol_version,
+                capabilities: capabilities,
+                clientInfo: {
+                  name: "RubyLLM-MCP Client",
+                  version: RubyLLM::MCP::VERSION
+                }
+              }
+            }
+          end
+
+          def ping(tracking_progress: false)
+            params = add_progress_token({}, tracking_progress: tracking_progress)
+
+            {
+              jsonrpc: JSONRPC_VERSION,
+              id: generate_id,
+              method: METHOD_PING,
+              params: params
+            }.tap { |body| body.delete(:params) if params.empty? }
+          end
+
+          def tool_list(cursor: nil, tracking_progress: false)
+            params = {}
+            params = add_cursor(params, cursor)
+            params = add_progress_token(params, tracking_progress: tracking_progress)
+
+            {
+              jsonrpc: JSONRPC_VERSION,
+              id: generate_id,
+              method: METHOD_TOOLS_LIST,
+              params: params
+            }.tap { |body| body.delete(:params) if params.empty? }
+          end
+
+          def tool_call(name:, parameters: {}, tracking_progress: false)
+            params = {
+              name: name,
+              arguments: parameters
+            }
+            params = add_progress_token(params, tracking_progress: tracking_progress)
+
+            {
+              jsonrpc: JSONRPC_VERSION,
+              id: generate_id,
+              method: METHOD_TOOLS_CALL,
+              params: params
+            }
+          end
+
+          def resource_list(cursor: nil, tracking_progress: false)
+            params = {}
+            params = add_cursor(params, cursor)
+            params = add_progress_token(params, tracking_progress: tracking_progress)
+
+            {
+              jsonrpc: JSONRPC_VERSION,
+              id: generate_id,
+              method: METHOD_RESOURCES_LIST,
+              params: params
+            }.tap { |body| body.delete(:params) if params.empty? }
+          end
+
+          def resource_read(uri:, tracking_progress: false)
+            params = { uri: uri }
+            params = add_progress_token(params, tracking_progress: tracking_progress)
+
+            {
+              jsonrpc: JSONRPC_VERSION,
+              id: generate_id,
+              method: METHOD_RESOURCES_READ,
+              params: params
+            }
+          end
+
+          def resource_template_list(cursor: nil, tracking_progress: false)
+            params = {}
+            params = add_cursor(params, cursor)
+            params = add_progress_token(params, tracking_progress: tracking_progress)
+
+            {
+              jsonrpc: JSONRPC_VERSION,
+              id: generate_id,
+              method: METHOD_RESOURCES_TEMPLATES_LIST,
+              params: params
+            }.tap { |body| body.delete(:params) if params.empty? }
+          end
+
+          def resources_subscribe(uri:, tracking_progress: false)
+            params = { uri: uri }
+            params = add_progress_token(params, tracking_progress: tracking_progress)
+
+            {
+              jsonrpc: JSONRPC_VERSION,
+              id: generate_id,
+              method: METHOD_RESOURCES_SUBSCRIBE,
+              params: params
+            }
+          end
+
+          def prompt_list(cursor: nil, tracking_progress: false)
+            params = {}
+            params = add_cursor(params, cursor)
+            params = add_progress_token(params, tracking_progress: tracking_progress)
+
+            {
+              jsonrpc: JSONRPC_VERSION,
+              id: generate_id,
+              method: METHOD_PROMPTS_LIST,
+              params: params
+            }.tap { |body| body.delete(:params) if params.empty? }
+          end
+
+          def prompt_call(name:, arguments: {}, tracking_progress: false)
+            params = {
+              name: name,
+              arguments: arguments
+            }
+            params = add_progress_token(params, tracking_progress: tracking_progress)
+
+            {
+              jsonrpc: JSONRPC_VERSION,
+              id: generate_id,
+              method: METHOD_PROMPTS_GET,
+              params: params
+            }
+          end
+
+          def completion_resource(uri:, argument:, value:, context: nil, tracking_progress: false)
+            params = {
+              ref: {
+                type: REF_TYPE_RESOURCE,
+                uri: uri
+              },
+              argument: {
+                name: argument,
+                value: value
+              },
+              context: format_completion_context(context)
+            }.compact
+            params = add_progress_token(params, tracking_progress: tracking_progress)
+
+            {
+              jsonrpc: JSONRPC_VERSION,
+              id: generate_id,
+              method: METHOD_COMPLETION_COMPLETE,
+              params: params
+            }
+          end
+
+          def completion_prompt(name:, argument:, value:, context: nil, tracking_progress: false)
+            params = {
+              ref: {
+                type: REF_TYPE_PROMPT,
+                name: name
+              },
+              argument: {
+                name: argument,
+                value: value
+              },
+              context: format_completion_context(context)
+            }.compact
+            params = add_progress_token(params, tracking_progress: tracking_progress)
+
+            {
+              jsonrpc: JSONRPC_VERSION,
+              id: generate_id,
+              method: METHOD_COMPLETION_COMPLETE,
+              params: params
+            }
+          end
+
+          def logging_set_level(level:, tracking_progress: false)
+            params = { level: level }
+            params = add_progress_token(params, tracking_progress: tracking_progress)
+
+            {
+              jsonrpc: JSONRPC_VERSION,
+              id: generate_id,
+              method: METHOD_LOGGING_SET_LEVEL,
+              params: params
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/native/messages/responses.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Native
+      module Messages
+        # Response message builders
+        # Responses are sent in reply to requests from the server
+        module Responses
+          extend Helpers
+
+          module_function
+
+          def ping(id:)
+            {
+              jsonrpc: JSONRPC_VERSION,
+              id: id,
+              result: {}
+            }
+          end
+
+          def roots_list(id:, roots_paths:)
+            roots_response = roots_paths.map do |path|
+              {
+                uri: "file://#{path}",
+                name: File.basename(path, ".*")
+              }
+            end
+
+            {
+              jsonrpc: JSONRPC_VERSION,
+              id: id,
+              result: {
+                roots: roots_response
+              }
+            }
+          end
+
+          def sampling_create_message(id:, message:, model:)
+            stop_reason = if message.respond_to?(:stop_reason) && message.stop_reason
+                            snake_to_camel(message.stop_reason)
+                          else
+                            "endTurn"
+                          end
+
+            {
+              jsonrpc: JSONRPC_VERSION,
+              id: id,
+              result: {
+                role: message.role,
+                content: format_content(message.content),
+                model: model,
+                stopReason: stop_reason
+              }
+            }
+          end
+
+          def elicitation(id:, action:, content: nil)
+            {
+              jsonrpc: JSONRPC_VERSION,
+              id: id,
+              result: {
+                action: action,
+                content: content
+              }.compact
+            }
+          end
+
+          def error(id:, message:, code: JsonRpc::ErrorCodes::SERVER_ERROR, data: nil)
+            error_object = {
+              code: code,
+              message: message
+            }
+            error_object[:data] = data if data
+
+            {
+              jsonrpc: JSONRPC_VERSION,
+              id: id,
+              error: error_object
+            }
+          end
+
+          def format_content(content)
+            if content.is_a?(RubyLLM::Content)
+              if content.text.none? && content.attachments.any?
+                attachment = content.attachments.first
+                { type: attachment.type, data: attachment.content, mime_type: attachment.mime_type }
+              else
+                { type: "text", text: content.text }
+              end
+            else
+              { type: "text", text: content }
+            end
+          end
+          private_class_method :format_content
+
+          def snake_to_camel(str)
+            parts = str.split("_")
+            parts.first + parts[1..].map(&:capitalize).join
+          end
+          private_class_method :snake_to_camel
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/native/messages.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Native
+      # Centralized message builders for MCP JSON-RPC communication
+      # All message construction happens here, returning properly formatted bodies
+      module Messages
+        JSONRPC_VERSION = JsonRpc::VERSION
+
+        # Request methods
+        METHOD_INITIALIZE = "initialize"
+        METHOD_PING = "ping"
+        METHOD_TOOLS_LIST = "tools/list"
+        METHOD_TOOLS_CALL = "tools/call"
+        METHOD_RESOURCES_LIST = "resources/list"
+        METHOD_RESOURCES_READ = "resources/read"
+        METHOD_RESOURCES_TEMPLATES_LIST = "resources/templates/list"
+        METHOD_RESOURCES_SUBSCRIBE = "resources/subscribe"
+        METHOD_PROMPTS_LIST = "prompts/list"
+        METHOD_PROMPTS_GET = "prompts/get"
+        METHOD_COMPLETION_COMPLETE = "completion/complete"
+        METHOD_LOGGING_SET_LEVEL = "logging/setLevel"
+
+        # Notification methods
+        METHOD_NOTIFICATION_INITIALIZED = "notifications/initialized"
+        METHOD_NOTIFICATION_CANCELLED = "notifications/cancelled"
+        METHOD_NOTIFICATION_ROOTS_LIST_CHANGED = "notifications/roots/list_changed"
+
+        # Reference types
+        REF_TYPE_PROMPT = "ref/prompt"
+        REF_TYPE_RESOURCE = "ref/resource"
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/native/notification.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Native
+      class Notification
+        attr_reader :type, :params
+
+        def initialize(response)
+          @type = response["method"]
+          @params = response["params"]
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/native/protocol.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Native
+      module Protocol
+        module_function
+
+        LATEST_PROTOCOL_VERSION = "2025-06-18"
+        DEFAULT_NEGOTIATED_PROTOCOL_VERSION = "2025-03-26"
+        SUPPORTED_PROTOCOL_VERSIONS = [
+          LATEST_PROTOCOL_VERSION,
+          "2025-03-26",
+          "2024-11-05",
+          "2024-10-07"
+        ].freeze
+
+        def supported_version?(version)
+          SUPPORTED_PROTOCOL_VERSIONS.include?(version)
+        end
+
+        def supported_versions
+          SUPPORTED_PROTOCOL_VERSIONS
+        end
+
+        def latest_version
+          LATEST_PROTOCOL_VERSION
+        end
+
+        def default_negotiated_version
+          DEFAULT_NEGOTIATED_PROTOCOL_VERSION
+        end
+      end
+    end
+  end
+end