model-context-protocol-rb 0.3.4 → 0.5.0

data/lib/model_context_protocol/server/cancellable.rb

@@ -0,0 +1,54 @@
+require "concurrent-ruby"
+
+module ModelContextProtocol
+  module Server::Cancellable
+    # Raised when a request has been cancelled by the client
+    class CancellationError < StandardError; end
+
+    # Execute a block with automatic cancellation support for blocking I/O operations.
+    # This method uses Concurrent::TimerTask to poll for cancellation every 100ms
+    # and can interrupt even blocking operations like HTTP requests or database queries.
+    #
+    # @param interval [Float] polling interval in seconds (default: 0.1)
+    # @yield block to execute with cancellation support
+    # @return [Object] the result of the block
+    # @raise [CancellationError] if the request is cancelled during execution
+    #
+    # @example
+    #   cancellable do
+    #     response = Net::HTTP.get(URI('https://slow-api.example.com'))
+    #     process_response(response)
+    #   end
+    def cancellable(interval: 0.1, &block)
+      context = Thread.current[:mcp_context]
+      executing_thread = Concurrent::AtomicReference.new(nil)
+
+      timer_task = Concurrent::TimerTask.new(execution_interval: interval) do
+        if context && context[:request_store] && context[:request_id]
+          if context[:request_store].cancelled?(context[:request_id])
+            thread = executing_thread.get
+            thread&.raise(CancellationError, "Request was cancelled") if thread&.alive?
+          end
+        end
+      end
+
+      begin
+        executing_thread.set(Thread.current)
+
+        if context && context[:request_store] && context[:request_id]
+          if context[:request_store].cancelled?(context[:request_id])
+            raise CancellationError, "Request #{context[:request_id]} was cancelled"
+          end
+        end
+
+        timer_task.execute
+
+        result = block.call
+        result
+      ensure
+        executing_thread.set(nil)
+        timer_task&.shutdown if timer_task&.running?
+      end
+    end
+  end
+end

data/lib/model_context_protocol/server/configuration.rb

@@ -8,6 +8,12 @@ module ModelContextProtocol
     # Raised when configured with invalid version.
     class InvalidServerVersionError < StandardError; end
 
+    # Raised when configured with invalid title.
+    class InvalidServerTitleError < StandardError; end
+
+    # Raised when configured with invalid instructions.
+    class InvalidServerInstructionsError < StandardError; end
+
     # Raised when configured with invalid registry.
     class InvalidRegistryError < StandardError; end
 
@@ -20,14 +26,16 @@ module ModelContextProtocol
     # Raised when an invalid log level is provided
     class InvalidLogLevelError < StandardError; end
 
+    # Raised when pagination configuration is invalid
+    class InvalidPaginationError < StandardError; end
+
     # Valid MCP log levels per the specification
     VALID_LOG_LEVELS = %w[debug info notice warning error critical alert emergency].freeze
 
-    attr_accessor :name, :registry, :version, :transport
+    attr_accessor :name, :registry, :version, :transport, :pagination, :title, :instructions
     attr_reader :logger
 
     def initialize
-      # Always create a logger - enabled by default
       @logging_enabled = true
       @default_log_level = "info"
       @logger = ModelContextProtocol::Server::MCPLogger.new(
@@ -77,11 +85,48 @@ module ModelContextProtocol
       end
     end
 
+    def pagination_enabled?
+      return true if pagination.nil?
+
+      case pagination
+      when Hash
+        pagination[:enabled] != false
+      when false
+        false
+      else
+        true
+      end
+    end
+
+    def pagination_options
+      case pagination
+      when Hash
+        {
+          enabled: pagination[:enabled] != false,
+          default_page_size: pagination[:default_page_size] || 100,
+          max_page_size: pagination[:max_page_size] || 1000,
+          cursor_ttl: pagination[:cursor_ttl] || 3600
+        }
+      when false
+        {enabled: false}
+      else
+        {
+          enabled: true,
+          default_page_size: 100,
+          max_page_size: 1000,
+          cursor_ttl: 3600
+        }
+      end
+    end
+
     def validate!
       raise InvalidServerNameError unless valid_name?
       raise InvalidRegistryError unless valid_registry?
       raise InvalidServerVersionError unless valid_version?
       validate_transport!
+      validate_pagination!
+      validate_title!
+      validate_instructions!
 
       validate_environment_variables!
     end
@@ -155,16 +200,43 @@ module ModelContextProtocol
     end
 
     def validate_streamable_http_transport!
-      options = transport_options
+      unless ModelContextProtocol::Server::RedisConfig.configured?
+        raise InvalidTransportError,
+          "streamable_http transport requires Redis configuration. " \
+          "Call ModelContextProtocol::Server.configure_redis in an initializer."
+      end
+    end
+
+    def validate_pagination!
+      return unless pagination_enabled?
+
+      opts = pagination_options
+
+      if opts[:max_page_size] <= 0
+        raise InvalidPaginationError, "Invalid pagination max_page_size: must be positive"
+      end
 
-      unless options[:redis_client]
-        raise InvalidTransportError, "streamable_http transport requires redis_client option"
+      if opts[:default_page_size] <= 0 || opts[:default_page_size] > opts[:max_page_size]
+        raise InvalidPaginationError, "Invalid pagination default_page_size: must be between 1 and #{opts[:max_page_size]}"
       end
 
-      redis_client = options[:redis_client]
-      unless redis_client.respond_to?(:hset) && redis_client.respond_to?(:expire)
-        raise InvalidTransportError, "redis_client must be a Redis-compatible client"
+      if opts[:cursor_ttl] && opts[:cursor_ttl] <= 0
+        raise InvalidPaginationError, "Invalid pagination cursor_ttl: must be positive or nil"
       end
     end
+
+    def validate_title!
+      return if title.nil?
+      return if title.is_a?(String)
+
+      raise InvalidServerTitleError, "Server title must be a string"
+    end
+
+    def validate_instructions!
+      return if instructions.nil?
+      return if instructions.is_a?(String)
+
+      raise InvalidServerInstructionsError, "Server instructions must be a string"
+    end
   end
 end

data/lib/model_context_protocol/server/content.rb

@@ -0,0 +1,321 @@
+require "json-schema"
+
+module ModelContextProtocol
+  module Server::Content
+    class ContentValidationError < StandardError; end
+
+    Text = Data.define(:meta, :annotations, :text) do
+      def serialized
+        serialized_data = {
+          _meta: meta,
+          annotations:,
+          text:,
+          type: "text"
+        }.compact
+
+        validation_errors = JSON::Validator.fully_validate(schema, serialized_data)
+        if validation_errors.empty?
+          serialized_data
+        else
+          raise ContentValidationError, validation_errors.join(", ")
+        end
+      end
+
+      private
+
+      def schema
+        {
+          type: "object",
+          required: ["type", "text"],
+          properties: {
+            _meta: {
+              type: "object",
+              description: "Contains metadata about the content block"
+            },
+            annotations: {
+              type: "object",
+              description: "Optional metadata about the purpose and use of the content block"
+            },
+            text: {
+              type: "string",
+              description: "The text content of the content block"
+            },
+            type: {
+              type: "string",
+              description: "The type of content block",
+              pattern: "^text$"
+            }
+          }
+        }
+      end
+    end
+
+    Image = Data.define(:meta, :annotations, :data, :mime_type) do
+      def serialized
+        serialized_data = {
+          _meta: meta,
+          annotations:,
+          data:,
+          mimeType: mime_type,
+          type: "image"
+        }.compact
+
+        validation_errors = JSON::Validator.fully_validate(schema, serialized_data)
+        if validation_errors.empty?
+          serialized_data
+        else
+          raise ContentValidationError, validation_errors.join(", ")
+        end
+      end
+
+      private
+
+      def schema
+        {
+          type: "object",
+          required: ["data", "mimeType", "type"],
+          properties: {
+            _meta: {
+              type: "object",
+              description: "Contains metadata about the content block"
+            },
+            annotations: {
+              type: "object",
+              description: "Optional metadata about the purpose and use of the content block"
+            },
+            data: {
+              type: "string",
+              description: "The base64 encoded image data"
+            },
+            mimeType: {
+              type: "string",
+              description: "The mime type associated with the image data"
+            },
+            type: {
+              type: "string",
+              description: "The type of content block",
+              pattern: "^image$"
+            }
+          }
+        }
+      end
+    end
+
+    Audio = Data.define(:meta, :annotations, :data, :mime_type) do
+      def serialized
+        serialized_data = {
+          _meta: meta,
+          annotations:,
+          data:,
+          mimeType: mime_type,
+          type: "audio"
+        }.compact
+
+        validation_errors = JSON::Validator.fully_validate(schema, serialized_data)
+        if validation_errors.empty?
+          serialized_data
+        else
+          raise ContentValidationError, validation_errors.join(", ")
+        end
+      end
+
+      private
+
+      def schema
+        {
+          type: "object",
+          required: ["data", "mimeType", "type"],
+          properties: {
+            _meta: {
+              type: "object",
+              description: "Contains metadata about the content block"
+            },
+            annotations: {
+              type: "object",
+              description: "Optional metadata about the purpose and use of the content block"
+            },
+            data: {
+              type: "string",
+              description: "The base64 encoded image data"
+            },
+            mimeType: {
+              type: "string",
+              description: "The mime type associated with the image data"
+            },
+            type: {
+              type: "string",
+              description: "The type of content block",
+              pattern: "^audio$"
+            }
+          }
+        }
+      end
+    end
+
+    EmbeddedResource = Data.define(:meta, :resource) do
+      def serialized
+        serialized_data = {
+          _meta: meta,
+          resource:,
+          type: "resource"
+        }.compact
+
+        validation_errors = JSON::Validator.fully_validate(schema, serialized_data)
+        if validation_errors.empty?
+          serialized_data
+        else
+          raise ContentValidationError, validation_errors.join(", ")
+        end
+      end
+
+      private
+
+      def schema
+        {
+          type: "object",
+          required: ["type", "resource"],
+          properties: {
+            _meta: {
+              type: "object",
+              description: "Contains metadata about the content block"
+            },
+            resource: {
+              type: "object",
+              description: "The resource embedded in the content block"
+            },
+            type: {
+              type: "string",
+              description: "The type of content block",
+              pattern: "^resource$"
+            }
+          }
+        }
+      end
+    end
+
+    ResourceLink = Data.define(:meta, :annotations, :description, :mime_type, :name, :size, :title, :uri) do
+      def serialized
+        serialized_data = {
+          _meta: meta,
+          annotations:,
+          description:,
+          mimeType: mime_type,
+          name:,
+          size:,
+          title:,
+          type: "resource_link",
+          uri:
+        }.compact
+
+        validation_errors = JSON::Validator.fully_validate(schema, serialized_data)
+        if validation_errors.empty?
+          serialized_data
+        else
+          raise ContentValidationError, validation_errors.join(", ")
+        end
+      end
+
+      private
+
+      def schema
+        {
+          type: "object",
+          required: ["name", "type", "uri"],
+          properties: {
+            _meta: {
+              type: "object",
+              description: "Contains metadata about the content block"
+            },
+            annotations: {
+              type: "object",
+              description: "Optional metadata about the purpose and use of the content block"
+            },
+            description: {
+              type: "string",
+              description: "A description of what this resource represents"
+            },
+            mimeType: {
+              type: "string",
+              description: "The mime type of the resource in bytes (if known)"
+            },
+            name: {
+              type: "string",
+              description: "Name of the resource link, intended for programmatic use"
+            },
+            size: {
+              type: "number",
+              description: "The size of the raw resource content in bytes (if known)"
+            },
+            title: {
+              type: "string",
+              description: "Name of the resource link, intended for display purposes"
+            },
+            type: {
+              type: "string",
+              description: "The type of content block",
+              pattern: "^resource_link$"
+            },
+            uri: {
+              type: "string",
+              description: "The URI of this resource"
+            }
+          }
+        }
+      end
+    end
+
+    Annotations = Data.define(:audience, :last_modified, :priority) do
+      def serialized
+        serialized_data = {audience:, lastModified: last_modified, priority:}.compact
+
+        validation_errors = JSON::Validator.fully_validate(schema, serialized_data)
+        unless validation_errors.empty?
+          raise ContentValidationError, validation_errors.join(", ")
+        end
+
+        serialized_data.empty? ? nil : serialized_data
+      end
+
+      private
+
+      def schema
+        {
+          type: "object",
+          description: "Optional metadata about the purpose and use of the content block",
+          properties: {
+            audience: {
+              oneOf: [
+                {
+                  type: "string",
+                  enum: ["user", "assistant"]
+                },
+                {
+                  type: "array",
+                  items: {
+                    type: "string",
+                    enum: ["user", "assistant"]
+                  },
+                  minItems: 1,
+                  maxItems: 2,
+                  uniqueItems: true
+                }
+              ],
+              description: "The intended audience for the content block"
+            },
+            lastModified: {
+              type: "string",
+              pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z$",
+              description: "The date the content was last modified (in ISO 8601 format)"
+            },
+            priority: {
+              type: "number",
+              description: "The weight of importance the audience should place on the contents of the content block",
+              minimum: 0.0,
+              maximum: 1.0
+            }
+          }
+        }
+      end
+    end
+  end
+end

data/lib/model_context_protocol/server/content_helpers.rb

@@ -0,0 +1,84 @@
+module ModelContextProtocol
+  module Server::ContentHelpers
+    def text_content(text:, meta: nil, annotations: {})
+      serialized_annotations = ModelContextProtocol::Server::Content::Annotations[
+        audience: annotations[:audience],
+        last_modified: annotations[:last_modified],
+        priority: annotations[:priority]
+      ].serialized
+
+      ModelContextProtocol::Server::Content::Text[
+        meta:,
+        annotations: serialized_annotations,
+        text:
+      ]
+    end
+
+    def image_content(data:, mime_type:, meta: nil, annotations: {})
+      serialized_annotations = ModelContextProtocol::Server::Content::Annotations[
+        audience: annotations[:audience],
+        last_modified: annotations[:last_modified],
+        priority: annotations[:priority]
+      ].serialized
+
+      ModelContextProtocol::Server::Content::Image[
+        meta:,
+        annotations: serialized_annotations,
+        data:,
+        mime_type:
+      ]
+    end
+
+    def audio_content(data:, mime_type:, meta: nil, annotations: {})
+      serialized_annotations = ModelContextProtocol::Server::Content::Annotations[
+        audience: annotations[:audience],
+        last_modified: annotations[:last_modified],
+        priority: annotations[:priority]
+      ].serialized
+
+      ModelContextProtocol::Server::Content::Audio[
+        meta:,
+        annotations: serialized_annotations,
+        data:,
+        mime_type:
+      ]
+    end
+
+    def embedded_resource_content(resource:)
+      extracted_resource = resource.serialized[:contents].first
+      annotations = extracted_resource.key?(:annotations) ? extracted_resource.delete(:annotations) : {}
+
+      serialized_annotations = ModelContextProtocol::Server::Content::Annotations[
+        audience: annotations[:audience],
+        last_modified: annotations[:lastModified],
+        priority: annotations[:priority]
+      ].serialized
+
+      extracted_resource[:annotations] = serialized_annotations if serialized_annotations
+
+      ModelContextProtocol::Server::Content::EmbeddedResource[
+        meta: nil,
+        resource: extracted_resource
+      ]
+    end
+
+    def resource_link(name:, uri:, meta: nil, annotations: {}, description: nil, mime_type: nil, size: nil, title: nil)
+      serialized_annotations = ModelContextProtocol::Server::Content::Annotations[
+        audience: annotations[:audience],
+        last_modified: annotations[:last_modified],
+        priority: annotations[:priority]
+      ].serialized
+
+      ModelContextProtocol::Server::Content::ResourceLink[
+        meta:,
+        annotations: serialized_annotations,
+        description:,
+        mime_type:,
+        name:,
+        size:,
+        title:,
+        uri:
+      ].serialized
+    end
+  end
+end

data/lib/model_context_protocol/server/pagination.rb

@@ -0,0 +1,71 @@
+require "json"
+require "base64"
+
+module ModelContextProtocol
+  class Server::Pagination
+    # Raised when an invalid cursor is provided
+    class InvalidCursorError < StandardError; end
+
+    DEFAULT_PAGE_SIZE = 100
+    MAX_PAGE_SIZE = 1000
+
+    PaginatedResponse = Data.define(:items, :next_cursor) do
+      def serialized(key)
+        result = {key => items}
+        result[:nextCursor] = next_cursor if next_cursor
+        result
+      end
+    end
+
+    class << self
+      def paginate(items, cursor: nil, page_size: DEFAULT_PAGE_SIZE, cursor_ttl: nil)
+        page_size = [page_size, MAX_PAGE_SIZE].min
+        offset = cursor ? decode_cursor(cursor) : 0
+        page_items = items[offset, page_size] || []
+        next_offset = offset + page_items.length
+        next_cursor = if next_offset < items.length
+          encode_cursor(next_offset, items.length, ttl: cursor_ttl)
+        end
+
+        PaginatedResponse[items: page_items, next_cursor: next_cursor]
+      end
+
+      def encode_cursor(offset, total, ttl: nil)
+        data = {
+          offset: offset,
+          total: total,
+          timestamp: Time.now.to_i
+        }
+        data[:expires_at] = Time.now.to_i + ttl if ttl
+
+        Base64.urlsafe_encode64(JSON.generate(data), padding: false)
+      end
+
+      def decode_cursor(cursor, validate_ttl: true)
+        data = JSON.parse(Base64.urlsafe_decode64(cursor))
+
+        if validate_ttl && data["expires_at"] && Time.now.to_i > data["expires_at"]
+          raise InvalidCursorError, "Cursor has expired"
+        end
+
+        data["offset"]
+      rescue JSON::ParserError, ArgumentError => e
+        raise InvalidCursorError, "Invalid cursor format: #{e.message}"
+      end
+
+      def pagination_requested?(params)
+        params.key?("cursor") || params.key?("pageSize")
+      end
+
+      def extract_pagination_params(params, default_page_size: DEFAULT_PAGE_SIZE, max_page_size: MAX_PAGE_SIZE)
+        page_size = if params["pageSize"]
+          [params["pageSize"].to_i, max_page_size].min
+        else
+          default_page_size
+        end
+
+        {cursor: params["cursor"], page_size:}
+      end
+    end
+  end
+end