model_context_protocol_riccardo 0.7.0

data/lib/model_context_protocol/configuration.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module ModelContextProtocol
+  class Configuration
+    DEFAULT_PROTOCOL_VERSION = "2024-11-05"
+
+    attr_writer :exception_reporter, :instrumentation_callback, :protocol_version
+
+    def initialize(exception_reporter: nil, instrumentation_callback: nil, protocol_version: nil)
+      @exception_reporter = exception_reporter
+      @instrumentation_callback = instrumentation_callback
+      @protocol_version = protocol_version
+    end
+
+    def protocol_version
+      @protocol_version || DEFAULT_PROTOCOL_VERSION
+    end
+
+    def protocol_version?
+      !@protocol_version.nil?
+    end
+
+    def exception_reporter
+      @exception_reporter || default_exception_reporter
+    end
+
+    def exception_reporter?
+      !@exception_reporter.nil?
+    end
+
+    def instrumentation_callback
+      @instrumentation_callback || default_instrumentation_callback
+    end
+
+    def instrumentation_callback?
+      !@instrumentation_callback.nil?
+    end
+
+    def merge(other)
+      return self if other.nil?
+
+      exception_reporter = if other.exception_reporter?
+        other.exception_reporter
+      else
+        @exception_reporter
+      end
+      instrumentation_callback = if other.instrumentation_callback?
+        other.instrumentation_callback
+      else
+        @instrumentation_callback
+      end
+      protocol_version = if other.protocol_version?
+        other.protocol_version
+      else
+        @protocol_version
+      end
+
+      Configuration.new(
+        exception_reporter:,
+        instrumentation_callback:,
+        protocol_version:,
+      )
+    end
+
+    private
+
+    def default_exception_reporter
+      @default_exception_reporter ||= ->(exception, server_context) {}
+    end
+
+    def default_instrumentation_callback
+      @default_instrumentation_callback ||= ->(data) {}
+    end
+  end
+end

data/lib/model_context_protocol/content.rb

@@ -0,0 +1,33 @@
+# typed: true
+# frozen_string_literal: true
+
+module ModelContextProtocol
+  module Content
+    class Text
+      attr_reader :text, :annotations
+
+      def initialize(text, annotations: nil)
+        @text = text
+        @annotations = annotations
+      end
+
+      def to_h
+        { text:, annotations:, type: "text" }.compact
+      end
+    end
+
+    class Image
+      attr_reader :data, :mime_type, :annotations
+
+      def initialize(data, mime_type, annotations: nil)
+        @data = data
+        @mime_type = mime_type
+        @annotations = annotations
+      end
+
+      def to_h
+        { data:, mime_type:, annotations:, type: "image" }.compact
+      end
+    end
+  end
+end

data/lib/model_context_protocol/instrumentation.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ModelContextProtocol
+  module Instrumentation
+    def instrument_call(method, &block)
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      begin
+        @instrumentation_data = {}
+        add_instrumentation_data(method:)
+
+        result = yield block
+
+        result
+      ensure
+        end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        add_instrumentation_data(duration: end_time - start_time)
+
+        configuration.instrumentation_callback.call(@instrumentation_data)
+      end
+    end
+
+    def add_instrumentation_data(**kwargs)
+      @instrumentation_data.merge!(kwargs)
+    end
+  end
+end

data/lib/model_context_protocol/json_rpc.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "model_context_protocol/json_rpc/error"
+require "model_context_protocol/json_rpc/request"
+require "model_context_protocol/json_rpc/response"
+
+module ModelContextProtocol
+  module JsonRPC
+    VERSION = "2.0"
+  end
+end

data/lib/model_context_protocol/methods.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module ModelContextProtocol
+  module Methods
+    INITIALIZE = "initialize"
+    PING = "ping"
+    LOGGING_SET_LEVEL = "logging/setLevel"
+
+    PROMPTS_GET = "prompts/get"
+    PROMPTS_LIST = "prompts/list"
+    COMPLETION_COMPLETE = "completion/complete"
+
+    RESOURCES_LIST = "resources/list"
+    RESOURCES_READ = "resources/read"
+    RESOURCES_TEMPLATES_LIST = "resources/templates/list"
+    RESOURCES_SUBSCRIBE = "resources/subscribe"
+    RESOURCES_UNSUBSCRIBE = "resources/unsubscribe"
+
+    TOOLS_CALL = "tools/call"
+    TOOLS_LIST = "tools/list"
+
+    SAMPLING_CREATE_MESSAGE = "sampling/createMessage"
+
+    class MissingRequiredCapabilityError < StandardError
+      attr_reader :method
+      attr_reader :capability
+
+      def initialize(method, capability)
+        super("Server does not support #{capability} (required for #{method})")
+        @method = method
+        @capability = capability
+      end
+    end
+
+    extend self
+
+    ALL_METHODS = [
+      SAMPLING_CREATE_MESSAGE,
+      INITIALIZE,
+      LOGGING_SET_LEVEL,
+      PING,
+      PROMPTS_GET,
+      PROMPTS_LIST,
+      COMPLETION_COMPLETE,
+      RESOURCES_LIST,
+      RESOURCES_READ,
+      RESOURCES_TEMPLATES_LIST,
+      RESOURCES_SUBSCRIBE,
+      RESOURCES_UNSUBSCRIBE,
+      TOOLS_CALL,
+      TOOLS_LIST,
+    ]
+
+    def ensure_capability!(method, capabilities)
+      case method
+      when PROMPTS_GET, PROMPTS_LIST, COMPLETION_COMPLETE
+        unless capabilities[:prompts]
+          raise MissingRequiredCapabilityError.new(method, :prompts)
+        end
+      when RESOURCES_LIST, RESOURCES_TEMPLATES_LIST, RESOURCES_READ, RESOURCES_SUBSCRIBE, RESOURCES_UNSUBSCRIBE
+        unless capabilities[:resources]
+          raise MissingRequiredCapabilityError.new(method, :resources)
+        end
+
+        if method == RESOURCES_SUBSCRIBE && !capabilities[:resources][:subscribe]
+          raise MissingRequiredCapabilityError.new(method, :resources_subscribe)
+        end
+      when TOOLS_CALL, TOOLS_LIST
+        unless capabilities[:tools]
+          raise MissingRequiredCapabilityError.new(method, :tools)
+        end
+      when SAMPLING_CREATE_MESSAGE
+        unless capabilities[:sampling]
+          raise MissingRequiredCapabilityError.new(method, :sampling)
+        end
+      when LOGGING_SET_LEVEL
+        # Logging is unsupported by the Server
+        unless capabilities[:logging]
+          raise MissingRequiredCapabilityError.new(method, :logging)
+        end
+      when INITIALIZE, PING
+        # No specific capability required for initialize or ping
+      end
+    end
+  end
+end

data/lib/model_context_protocol/prompt/argument.rb

@@ -0,0 +1,21 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ModelContextProtocol
+  class Prompt
+    class Argument
+      attr_reader :name, :description, :required, :arguments
+
+      def initialize(name:, description: nil, required: false)
+        @name = name
+        @description = description
+        @required = required
+        @arguments = arguments
+      end
+
+      def to_h
+        { name:, description:, required: }.compact
+      end
+    end
+  end
+end

data/lib/model_context_protocol/prompt/message.rb

@@ -0,0 +1,19 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ModelContextProtocol
+  class Prompt
+    class Message
+      attr_reader :role, :content
+
+      def initialize(role:, content:)
+        @role = role
+        @content = content
+      end
+
+      def to_h
+        { role:, content: content.to_h }.compact
+      end
+    end
+  end
+end

data/lib/model_context_protocol/prompt/result.rb

@@ -0,0 +1,19 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ModelContextProtocol
+  class Prompt
+    class Result
+      attr_reader :description, :messages
+
+      def initialize(description: nil, messages: [])
+        @description = description
+        @messages = messages
+      end
+
+      def to_h
+        { description:, messages: messages.map(&:to_h) }.compact
+      end
+    end
+  end
+end

data/lib/model_context_protocol/prompt.rb

@@ -0,0 +1,82 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ModelContextProtocol
+  class Prompt
+    class << self
+      NOT_SET = Object.new
+
+      attr_reader :description_value
+      attr_reader :arguments_value
+
+      def template(args, server_context:)
+        raise NotImplementedError, "Subclasses must implement template"
+      end
+
+      def to_h
+        { name: name_value, description: description_value, arguments: arguments_value.map(&:to_h) }.compact
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@name_value, nil)
+        subclass.instance_variable_set(:@description_value, nil)
+        subclass.instance_variable_set(:@arguments_value, nil)
+      end
+
+      def prompt_name(value = NOT_SET)
+        if value == NOT_SET
+          @name_value
+        else
+          @name_value = value
+        end
+      end
+
+      def name_value
+        @name_value || StringUtils.handle_from_class_name(name)
+      end
+
+      def description(value = NOT_SET)
+        if value == NOT_SET
+          @description_value
+        else
+          @description_value = value
+        end
+      end
+
+      def arguments(value = NOT_SET)
+        if value == NOT_SET
+          @arguments_value
+        else
+          @arguments_value = value
+        end
+      end
+
+      def define(name: nil, description: nil, arguments: [], &block)
+        Class.new(self) do
+          prompt_name name
+          description description
+          arguments arguments
+          define_singleton_method(:template) do |args, server_context:|
+            instance_exec(args, server_context:, &block)
+          end
+        end
+      end
+
+      def validate_arguments!(args)
+        missing = required_args - args.keys
+        return if missing.empty?
+
+        raise ModelContextProtocol::Server::RequestHandlerError.new(
+          "Missing required arguments: #{missing.join(", ")}", nil, error_type: :missing_required_arguments
+        )
+      end
+
+      private
+
+      def required_args
+        arguments_value.filter_map { |arg| arg.name.to_sym if arg.required }
+      end
+    end
+  end
+end

data/lib/model_context_protocol/resource/contents.rb

@@ -0,0 +1,45 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ModelContextProtocol
+  class Resource
+    class Contents
+      attr_reader :uri, :mime_type
+
+      def initialize(uri:, mime_type: nil)
+        @uri = uri
+        @mime_type = mime_type
+      end
+
+      def to_h
+        { uri:, mime_type: }.compact
+      end
+    end
+
+    class TextContents < Contents
+      attr_reader :text
+
+      def initialize(text:, uri:, mime_type:)
+        super(uri: uri, mime_type: mime_type)
+        @text = text
+      end
+
+      def to_h
+        super.merge(text: text)
+      end
+    end
+
+    class BlobContents < Contents
+      attr_reader :data
+
+      def initialize(data:, uri:, mime_type:)
+        super(uri: uri, mime_type: mime_type)
+        @data = data
+      end
+
+      def to_h
+        super.merge(data: data)
+      end
+    end
+  end
+end

data/lib/model_context_protocol/resource/embedded.rb

@@ -0,0 +1,18 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ModelContextProtocol
+  class Resource
+    class Embedded
+      attr_reader :resource, :annotations
+
+      def initialize(resource:, annotations: nil)
+        @annotations = annotations
+      end
+
+      def to_h
+        { resource: resource.to_h, annotations: }.compact
+      end
+    end
+  end
+end

data/lib/model_context_protocol/resource.rb

@@ -0,0 +1,24 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ModelContextProtocol
+  class Resource
+    attr_reader :uri, :name, :description, :mime_type
+
+    def initialize(uri:, name:, description:, mime_type:)
+      @uri = uri
+      @name = name
+      @description = description
+      @mime_type = mime_type
+    end
+
+    def to_h
+      {
+        uri: @uri,
+        name: @name,
+        description: @description,
+        mimeType: @mime_type,
+      }
+    end
+  end
+end

data/lib/model_context_protocol/resource_template.rb

@@ -0,0 +1,24 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ModelContextProtocol
+  class ResourceTemplate
+    attr_reader :uri_template, :name, :description, :mime_type
+
+    def initialize(uri_template:, name:, description: nil, mime_type: nil)
+      @uri_template = uri_template
+      @name = name
+      @description = description
+      @mime_type = mime_type
+    end
+
+    def to_h
+      {
+        uriTemplate: @uri_template,
+        name: @name,
+        description: @description,
+        mimeType: @mime_type,
+      }.compact
+    end
+  end
+end