model-context-protocol-rb 0.3.4 → 0.4.0

data/lib/model_context_protocol/server/prompt.rb

@@ -1,5 +1,7 @@
 module ModelContextProtocol
   class Server::Prompt
+    include Server::ContentHelpers
+
     attr_reader :arguments, :context, :logger
 
     def initialize(arguments, logger, context = {})
@@ -13,15 +15,23 @@ module ModelContextProtocol
       raise NotImplementedError, "Subclasses must implement the call method"
     end
 
-    Response = Data.define(:messages, :description) do
+    Response = Data.define(:messages, :description, :title) do
       def serialized
-        {description:, messages:}
+        result = {description:, messages:}
+        result[:title] = title if title
+        result
       end
     end
     private_constant :Response
 
+    def message_history(&block)
+      builder = MessageHistoryBuilder.new(self)
+      builder.instance_eval(&block)
+      builder.messages
+    end
+
     private def respond_with(messages:)
-      Response[messages:, description: self.class.description]
+      Response[messages:, description: self.class.description, title: self.class.title]
     end
 
     private def validate!(arguments = {})
@@ -43,16 +53,18 @@ module ModelContextProtocol
     end
 
     class << self
-      attr_reader :name, :description, :defined_arguments
+      attr_reader :name, :description, :title, :defined_arguments
 
-      def with_metadata(&block)
+      def define(&block)
         @defined_arguments ||= []
 
-        metadata_dsl = MetadataDSL.new
-        metadata_dsl.instance_eval(&block)
+        definition_dsl = DefinitionDSL.new
+        definition_dsl.instance_eval(&block)
 
-        @name = metadata_dsl.name
-        @description = metadata_dsl.description
+        @name = definition_dsl.name
+        @description = definition_dsl.description
+        @title = definition_dsl.title
+        @defined_arguments.concat(definition_dsl.arguments)
       end
 
       def with_argument(&block)
@@ -72,6 +84,7 @@ module ModelContextProtocol
       def inherited(subclass)
         subclass.instance_variable_set(:@name, @name)
         subclass.instance_variable_set(:@description, @description)
+        subclass.instance_variable_set(:@title, @title)
         subclass.instance_variable_set(:@defined_arguments, @defined_arguments&.dup)
       end
 
@@ -81,8 +94,10 @@ module ModelContextProtocol
         raise ModelContextProtocol::Server::ParameterValidationError, error.message
       end
 
-      def metadata
-        {name: @name, description: @description, arguments: @defined_arguments}
+      def definition
+        result = {name: @name, description: @description, arguments: @defined_arguments}
+        result[:title] = @title if @title
+        result
       end
 
       def complete_for(arg_name, value)
@@ -92,7 +107,52 @@ module ModelContextProtocol
       end
     end
 
-    class MetadataDSL
+    class MessageHistoryBuilder
+      include Server::ContentHelpers
+
+      attr_reader :messages
+
+      def initialize(prompt_instance)
+        @messages = []
+        @prompt_instance = prompt_instance
+      end
+
+      def arguments
+        @prompt_instance.arguments
+      end
+
+      def context
+        @prompt_instance.context
+      end
+
+      def logger
+        @prompt_instance.logger
+      end
+
+      def user_message(&block)
+        content = instance_eval(&block).serialized
+        @messages << {
+          role: "user",
+          content: content
+        }
+      end
+
+      def assistant_message(&block)
+        content = instance_eval(&block).serialized
+        @messages << {
+          role: "assistant",
+          content: content
+        }
+      end
+    end
+
+    class DefinitionDSL
+      attr_reader :arguments
+
+      def initialize
+        @arguments = []
+      end
+
       def name(value = nil)
         @name = value if value
         @name
@@ -102,6 +162,23 @@ module ModelContextProtocol
         @description = value if value
         @description
       end
+
+      def title(value = nil)
+        @title = value if value
+        @title
+      end
+
+      def argument(&block)
+        argument_dsl = ArgumentDSL.new
+        argument_dsl.instance_eval(&block)
+
+        @arguments << {
+          name: argument_dsl.name,
+          description: argument_dsl.description,
+          required: argument_dsl.required,
+          completion: argument_dsl.completion
+        }
+      end
     end
 
     class ArgumentDSL
@@ -120,10 +197,25 @@ module ModelContextProtocol
         @required
       end
 
-      def completion(klass = nil)
-        @completion = klass unless klass.nil?
+      def completion(klass_or_values = nil)
+        unless klass_or_values.nil?
+          @completion = if klass_or_values.is_a?(Array)
+            create_array_completion(klass_or_values)
+          else
+            klass_or_values
+          end
+        end
         @completion
       end
+
+      private
+
+      def create_array_completion(values)
+        ModelContextProtocol::Server::Completion.define do
+          filtered_values = values.grep(/#{argument_value}/)
+          respond_with values: filtered_values
+        end
+      end
     end
   end
 end

data/lib/model_context_protocol/server/registry.rb

@@ -39,8 +39,8 @@ module ModelContextProtocol
     end
 
     def register(klass)
-      metadata = klass.metadata
-      entry = {klass: klass}.merge(metadata)
+      definition = klass.definition
+      entry = {klass: klass}.merge(definition)
 
       case klass.ancestors
       when ->(ancestors) { ancestors.include?(ModelContextProtocol::Server::Prompt) }
@@ -74,45 +74,121 @@ module ModelContextProtocol
       find_by_name(@tools, name)
     end
 
-    def prompts_data
-      PromptsData[prompts: @prompts.map { |entry| entry.except(:klass) }]
+    def prompts_data(cursor: nil, page_size: nil, cursor_ttl: nil)
+      items = @prompts.map { |entry| entry.except(:klass) }
+
+      if cursor || page_size
+        paginated = Server::Pagination.paginate(
+          items,
+          cursor: cursor,
+          page_size: page_size || 100,
+          cursor_ttl: cursor_ttl
+        )
+
+        PromptsData[prompts: paginated.items, next_cursor: paginated.next_cursor]
+      else
+        PromptsData[prompts: items]
+      end
     end
 
-    def resources_data
-      ResourcesData[resources: @resources.map { |entry| entry.except(:klass) }]
+    def resources_data(cursor: nil, page_size: nil, cursor_ttl: nil)
+      items = @resources.map { |entry| entry.except(:klass) }
+
+      if cursor || page_size
+        paginated = Server::Pagination.paginate(
+          items,
+          cursor: cursor,
+          page_size: page_size || 100,
+          cursor_ttl: cursor_ttl
+        )
+
+        ResourcesData[resources: paginated.items, next_cursor: paginated.next_cursor]
+      else
+        ResourcesData[resources: items]
+      end
     end
 
-    def resource_templates_data
-      ResourceTemplatesData[resource_templates: @resource_templates.map { |entry| entry.except(:klass, :completions) }]
+    def resource_templates_data(cursor: nil, page_size: nil, cursor_ttl: nil)
+      items = @resource_templates.map { |entry| entry.except(:klass, :completions) }
+
+      if cursor || page_size
+        paginated = Server::Pagination.paginate(
+          items,
+          cursor: cursor,
+          page_size: page_size || 100,
+          cursor_ttl: cursor_ttl
+        )
+
+        ResourceTemplatesData[resource_templates: paginated.items, next_cursor: paginated.next_cursor]
+      else
+        ResourceTemplatesData[resource_templates: items]
+      end
     end
 
-    def tools_data
-      ToolsData[tools: @tools.map { |entry| entry.except(:klass) }]
+    def tools_data(cursor: nil, page_size: nil, cursor_ttl: nil)
+      items = @tools.map { |entry| entry.except(:klass) }
+
+      if cursor || page_size
+        paginated = Server::Pagination.paginate(
+          items,
+          cursor: cursor,
+          page_size: page_size || 100,
+          cursor_ttl: cursor_ttl
+        )
+
+        ToolsData[tools: paginated.items, next_cursor: paginated.next_cursor]
+      else
+        ToolsData[tools: items]
+      end
     end
 
     private
 
-    PromptsData = Data.define(:prompts) do
+    PromptsData = Data.define(:prompts, :next_cursor) do
+      def initialize(prompts:, next_cursor: nil)
+        super
+      end
+
       def serialized
-        {prompts:}
+        result = {prompts:}
+        result[:nextCursor] = next_cursor if next_cursor
+        result
       end
     end
 
-    ResourcesData = Data.define(:resources) do
+    ResourcesData = Data.define(:resources, :next_cursor) do
+      def initialize(resources:, next_cursor: nil)
+        super
+      end
+
       def serialized
-        {resources:}
+        result = {resources:}
+        result[:nextCursor] = next_cursor if next_cursor
+        result
       end
     end
 
-    ResourceTemplatesData = Data.define(:resource_templates) do
+    ResourceTemplatesData = Data.define(:resource_templates, :next_cursor) do
+      def initialize(resource_templates:, next_cursor: nil)
+        super
+      end
+
       def serialized
-        {resourceTemplates: resource_templates}
+        result = {resourceTemplates: resource_templates}
+        result[:nextCursor] = next_cursor if next_cursor
+        result
       end
     end
 
-    ToolsData = Data.define(:tools) do
+    ToolsData = Data.define(:tools, :next_cursor) do
+      def initialize(tools:, next_cursor: nil)
+        super
+      end
+
       def serialized
-        {tools:}
+        result = {tools:}
+        result[:nextCursor] = next_cursor if next_cursor
+        result
       end
     end
 

data/lib/model_context_protocol/server/resource.rb

@@ -1,12 +1,10 @@
 module ModelContextProtocol
   class Server::Resource
-    attr_reader :mime_type, :uri, :context, :logger
+    attr_reader :mime_type, :uri
 
-    def initialize(logger, context = {})
+    def initialize
       @mime_type = self.class.mime_type
       @uri = self.class.uri
-      @context = context
-      @logger = logger
     end
 
     def call
@@ -15,59 +13,76 @@ module ModelContextProtocol
 
     TextResponse = Data.define(:resource, :text) do
       def serialized
-        {contents: [{mimeType: resource.mime_type, text:, uri: resource.uri}]}
+        content = {mimeType: resource.mime_type, text:, uri: resource.uri}
+        content[:title] = resource.class.title if resource.class.title
+        annotations = resource.class.annotations&.serialized
+        content[:annotations] = annotations if annotations
+        {contents: [content]}
       end
     end
     private_constant :TextResponse
 
     BinaryResponse = Data.define(:blob, :resource) do
       def serialized
-        {contents: [{blob:, mimeType: resource.mime_type, uri: resource.uri}]}
+        content = {blob:, mimeType: resource.mime_type, uri: resource.uri}
+        content[:title] = resource.class.title if resource.class.title
+        annotations = resource.class.annotations&.serialized
+        content[:annotations] = annotations if annotations
+        {contents: [content]}
       end
     end
     private_constant :BinaryResponse
 
-    private def respond_with(type, **options)
-      case [type, options]
-      in [:text, {text:}]
+    private def respond_with(**kwargs)
+      case [kwargs]
+      in [{text:}]
         TextResponse[resource: self, text:]
-      in [:binary, {blob:}]
-        BinaryResponse[blob:, resource: self]
+      in [{binary:}]
+        BinaryResponse[blob: binary, resource: self]
       else
-        raise ModelContextProtocol::Server::ResponseArgumentsError, "Invalid arguments: #{type}, #{options}"
+        raise ModelContextProtocol::Server::ResponseArgumentsError, "Invalid arguments: #{options}"
       end
     end
 
     class << self
-      attr_reader :name, :description, :mime_type, :uri
+      attr_reader :name, :description, :title, :mime_type, :uri, :annotations
 
-      def with_metadata(&block)
-        metadata_dsl = MetadataDSL.new
-        metadata_dsl.instance_eval(&block)
+      def define(&block)
+        definition_dsl = DefinitionDSL.new
+        definition_dsl.instance_eval(&block)
 
-        @name = metadata_dsl.name
-        @description = metadata_dsl.description
-        @mime_type = metadata_dsl.mime_type
-        @uri = metadata_dsl.uri
+        @name = definition_dsl.name
+        @description = definition_dsl.description
+        @title = definition_dsl.title
+        @mime_type = definition_dsl.mime_type
+        @uri = definition_dsl.uri
+        @annotations = definition_dsl.defined_annotations
       end
 
       def inherited(subclass)
         subclass.instance_variable_set(:@name, @name)
         subclass.instance_variable_set(:@description, @description)
+        subclass.instance_variable_set(:@title, @title)
         subclass.instance_variable_set(:@mime_type, @mime_type)
         subclass.instance_variable_set(:@uri, @uri)
+        subclass.instance_variable_set(:@annotations, @annotations&.dup)
       end
 
-      def call(logger, context = {})
-        new(logger, context).call
+      def call
+        new.call
       end
 
-      def metadata
-        {name: @name, description: @description, mimeType: @mime_type, uri: @uri}
+      def definition
+        result = {name: @name, description: @description, mimeType: @mime_type, uri: @uri}
+        result[:title] = @title if @title
+        result[:annotations] = @annotations.serialized if @annotations
+        result
       end
     end
 
-    class MetadataDSL
+    class DefinitionDSL
+      attr_reader :defined_annotations
+
       def name(value = nil)
         @name = value if value
         @name
@@ -78,6 +93,11 @@ module ModelContextProtocol
         @description
       end
 
+      def title(value = nil)
+        @title = value if value
+        @title
+      end
+
       def mime_type(value = nil)
         @mime_type = value if value
         @mime_type
@@ -87,6 +107,56 @@ module ModelContextProtocol
         @uri = value if value
         @uri
       end
+
+      def annotations(&block)
+        @defined_annotations = AnnotationsDSL.new
+        @defined_annotations.instance_eval(&block)
+        @defined_annotations
+      end
+    end
+
+    class AnnotationsDSL
+      VALID_AUDIENCE_VALUES = [:user, :assistant].freeze
+
+      def initialize
+        @audience = nil
+        @priority = nil
+        @last_modified = nil
+      end
+
+      def audience(value)
+        normalized_value = Array(value).map(&:to_sym)
+        invalid_values = normalized_value - VALID_AUDIENCE_VALUES
+        unless invalid_values.empty?
+          raise ArgumentError, "Invalid audience values: #{invalid_values.join(", ")}. Valid values are: #{VALID_AUDIENCE_VALUES.join(", ")}"
+        end
+        @audience = normalized_value.map(&:to_s)
+      end
+
+      def priority(value)
+        unless value.is_a?(Numeric) && value >= 0.0 && value <= 1.0
+          raise ArgumentError, "Priority must be a number between 0.0 and 1.0, got: #{value}"
+        end
+        @priority = value.to_f
+      end
+
+      def last_modified(value)
+        # Validate ISO 8601 format
+        begin
+          Time.iso8601(value)
+        rescue ArgumentError
+          raise ArgumentError, "lastModified must be in ISO 8601 format (e.g., '2025-01-12T15:00:58Z'), got: #{value}"
+        end
+        @last_modified = value
+      end
+
+      def serialized
+        result = {}
+        result[:audience] = @audience if @audience
+        result[:priority] = @priority if @priority
+        result[:lastModified] = @last_modified if @last_modified
+        result.empty? ? nil : result
+      end
     end
   end
 end

data/lib/model_context_protocol/server/resource_template.rb

@@ -3,15 +3,15 @@ module ModelContextProtocol
     class << self
       attr_reader :name, :description, :mime_type, :uri_template, :completions
 
-      def with_metadata(&block)
-        metadata_dsl = MetadataDSL.new
-        metadata_dsl.instance_eval(&block)
-
-        @name = metadata_dsl.name
-        @description = metadata_dsl.description
-        @mime_type = metadata_dsl.mime_type
-        @uri_template = metadata_dsl.uri_template
-        @completions = metadata_dsl.completions
+      def define(&block)
+        definition_dsl = DefinitionDSL.new
+        definition_dsl.instance_eval(&block)
+
+        @name = definition_dsl.name
+        @description = definition_dsl.description
+        @mime_type = definition_dsl.mime_type
+        @uri_template = definition_dsl.uri_template
+        @completions = definition_dsl.completions
       end
 
       def inherited(subclass)
@@ -32,7 +32,7 @@ module ModelContextProtocol
         completion.call(param_name.to_s, value)
       end
 
-      def metadata
+      def definition
         {
           name: @name,
           description: @description,
@@ -43,7 +43,7 @@ module ModelContextProtocol
       end
     end
 
-    class MetadataDSL
+    class DefinitionDSL
       attr_reader :completions
 
       def initialize
@@ -85,8 +85,21 @@ module ModelContextProtocol
         @completions = {}
       end
 
-      def completion(param_name, completion_class)
-        @completions[param_name.to_s] = completion_class
+      def completion(param_name, completion_class_or_values)
+        @completions[param_name.to_s] = if completion_class_or_values.is_a?(Array)
+          create_array_completion(completion_class_or_values)
+        else
+          completion_class_or_values
+        end
+      end
+
+      private
+
+      def create_array_completion(values)
+        ModelContextProtocol::Server::Completion.define do
+          filtered_values = values.grep(/#{argument_value}/)
+          respond_with values: filtered_values
+        end
       end
     end
   end