model-context-protocol-rb 0.6.0 → 0.7.0

data/lib/model_context_protocol/rspec/matchers/have_text_content.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module ModelContextProtocol
+  module RSpec
+    module Matchers
+      # Matcher that validates a tool response contains specific text content.
+      #
+      # @example With exact string match
+      #   expect(response).to have_text_content("Hello, World!")
+      #
+      # @example With regex match
+      #   expect(response).to have_text_content(/doubled is \d+/)
+      #
+      def have_text_content(expected_text)
+        HaveTextContent.new(expected_text)
+      end
+
+      class HaveTextContent
+        def initialize(expected_text)
+          @expected_text = expected_text
+          @failure_reasons = []
+        end
+
+        def matches?(actual)
+          @actual = actual
+          @failure_reasons = []
+          @serialized = serialize_response(actual)
+
+          return false if @serialized.nil?
+
+          validate_has_content &&
+            validate_has_text_content
+        end
+
+        def failure_message
+          "expected response to have text content matching #{@expected_text.inspect}, but:\n" +
+            @failure_reasons.map { |reason| "  - #{reason}" }.join("\n")
+        end
+
+        def failure_message_when_negated
+          "expected response not to have text content matching #{@expected_text.inspect}, but it did"
+        end
+
+        def description
+          "have text content matching #{@expected_text.inspect}"
+        end
+
+        private
+
+        def serialize_response(response)
+          if response.respond_to?(:serialized)
+            response.serialized
+          elsif response.is_a?(Hash)
+            response
+          else
+            @failure_reasons << "response must respond to :serialized or be a Hash"
+            nil
+          end
+        end
+
+        def validate_has_content
+          @content = @serialized[:content] || @serialized["content"]
+
+          unless @content
+            @failure_reasons << "response does not have :content key"
+            return false
+          end
+
+          unless @content.is_a?(Array)
+            @failure_reasons << "content must be an Array"
+            return false
+          end
+
+          true
+        end
+
+        def validate_has_text_content
+          text_items = @content.select do |item|
+            type = item[:type] || item["type"]
+            type == "text"
+          end
+
+          if text_items.empty?
+            @failure_reasons << "no text content found in response"
+            return false
+          end
+
+          matching_item = text_items.find do |item|
+            text = item[:text] || item["text"]
+            text_matches?(text)
+          end
+
+          unless matching_item
+            actual_texts = text_items.map { |item| item[:text] || item["text"] }
+            @failure_reasons << "no text content matched, found: #{actual_texts.inspect}"
+            return false
+          end
+
+          true
+        end
+
+        def text_matches?(text)
+          case @expected_text
+          when Regexp
+            @expected_text.match?(text)
+          else
+            text.include?(@expected_text.to_s)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/model_context_protocol/rspec/matchers.rb

@@ -0,0 +1,31 @@
+require_relative "matchers/be_valid_mcp_class"
+
+# Tool response matchers
+require_relative "matchers/be_valid_mcp_tool_response"
+require_relative "matchers/have_structured_content"
+require_relative "matchers/have_text_content"
+require_relative "matchers/have_image_content"
+require_relative "matchers/have_audio_content"
+require_relative "matchers/have_embedded_resource_content"
+require_relative "matchers/have_resource_link_content"
+require_relative "matchers/be_mcp_error_response"
+
+# Prompt response matchers
+require_relative "matchers/be_valid_mcp_prompt_response"
+require_relative "matchers/have_message_with_role"
+require_relative "matchers/have_message_count"
+
+# Resource response matchers
+require_relative "matchers/be_valid_mcp_resource_response"
+require_relative "matchers/have_resource_text"
+require_relative "matchers/have_resource_blob"
+require_relative "matchers/have_resource_mime_type"
+require_relative "matchers/have_resource_annotations"
+
+module ModelContextProtocol
+  module RSpec
+    module Matchers
+      # Include all matchers when this module is included
+    end
+  end
+end

data/lib/model_context_protocol/rspec.rb

@@ -0,0 +1,23 @@
+require "model_context_protocol"
+require_relative "rspec/matchers"
+require_relative "rspec/helpers"
+
+module ModelContextProtocol
+  module RSpec
+    # Convenience method to configure RSpec with MCP matchers and helpers.
+    #
+    # @example
+    #   # In spec_helper.rb
+    #   require "model_context_protocol/rspec"
+    #   ModelContextProtocol::RSpec.configure!
+    #
+    # @return [void]
+    def self.configure!
+      ::RSpec.configure do |config|
+        config.include ModelContextProtocol::RSpec::Matchers
+        config.include ModelContextProtocol::RSpec::Helpers, type: :mcp
+        config.include ModelContextProtocol::RSpec::Helpers, file_path: %r{spec/mcp/}
+      end
+    end
+  end
+end

data/lib/model_context_protocol/server/client_logger.rb

@@ -30,7 +30,7 @@ module ModelContextProtocol
       Logger::UNKNOWN => "emergency"
     }.freeze
 
-    attr_accessor :transport
+    attr_reader :transport
     attr_reader :logger_name
 
     def initialize(logger_name: "server", level: "info")

data/lib/model_context_protocol/server/configuration.rb

@@ -1,65 +1,149 @@
 module ModelContextProtocol
+  # Base settings container for MCP servers with two concrete subclasses:
+  # - {StdioConfiguration} for standalone scripts using stdin/stdout
+  # - {StreamableHttpConfiguration} for Rack applications using streamable HTTP with Redis
+  #
+  # Server.rb factory methods (with_stdio_transport, with_streamable_http_transport)
+  # instantiate the appropriate subclass, yield it to a block for population, validate
+  # it, then pass it to Router.new. Router reads pagination settings via pagination_options
+  # and queries transport capabilities via supports_list_changed? and apply_environment_variables?.
+  #
+  # The base class provides shared attributes (name, version, registry, pagination) and
+  # validation logic, while subclasses override transport_type and validate_transport! to
+  # enforce transport-specific constraints.
   class Server::Configuration
-    # Raised when configured with invalid name.
+    # Signals that the server's identifying name is missing or not a String.
+    # Raised by validate! when name is nil or non-String.
     class InvalidServerNameError < StandardError; end
 
-    # Raised when configured with invalid version.
+    # Signals that the server's version string is missing or not a String.
+    # Raised by validate! when version is nil or non-String.
     class InvalidServerVersionError < StandardError; end
 
-    # Raised when configured with invalid title.
+    # Signals that the optional UI title is non-nil but not a String.
+    # Raised by validate_title! when title is set to a non-String value.
     class InvalidServerTitleError < StandardError; end
 
-    # Raised when configured with invalid instructions.
+    # Signals that the optional LLM instructions are non-nil but not a String.
+    # Raised by validate_instructions! when instructions is set to a non-String value.
     class InvalidServerInstructionsError < StandardError; end
 
-    # Raised when configured with invalid registry.
+    # Signals that the registry is missing or not a Registry instance.
+    # Raised by validate! when registry is nil or not a ModelContextProtocol::Server::Registry.
     class InvalidRegistryError < StandardError; end
 
-    # Raised when a required environment variable is not set
+    # Signals that a required environment variable is absent (stdio transport only).
+    # Raised by StdioConfiguration#validate_environment_variables! when a variable
+    # declared via require_environment_variable is not set.
     class MissingRequiredEnvironmentVariable < StandardError; end
 
-    # Raised when transport configuration is invalid
+    # Signals transport-specific validation failure (Redis missing for HTTP, stdout conflict for stdio).
+    # Raised by subclass implementations of validate_transport! when prerequisites are unmet.
     class InvalidTransportError < StandardError; end
 
-    # Raised when pagination configuration is invalid
+    # Signals that pagination settings are invalid (negative sizes, out-of-range defaults).
+    # Raised by validate_pagination! when default_page_size exceeds max_page_size or values are non-positive.
     class InvalidPaginationError < StandardError; end
 
-    attr_accessor :name, :registry, :version, :transport, :pagination, :title, :instructions
-    attr_reader :client_logger, :server_logger
+    # @!attribute [rw] name
+    #   @return [String] the server's identifying name (sent in initialize response serverInfo.name)
+    attr_accessor :name
+
+    # @!attribute [rw] version
+    #   @return [String] the server's version string (sent in initialize response serverInfo.version)
+    attr_accessor :version
+
+    # @!attribute [rw] pagination
+    #   @return [Hash, false, nil] pagination settings or false to disable;
+    #     Router calls pagination_options to extract default_page_size, max_page_size, and cursor_ttl
+    #     when handling list requests (resources/list, prompts/list, tools/list).
+    #     Accepts Hash with :enabled, :default_page_size, :max_page_size, :cursor_ttl keys, or false to disable.
+    attr_accessor :pagination
+
+    # @!attribute [rw] title
+    #   @return [String, nil] optional human-readable display title for Claude Desktop UI
+    #     (sent in initialize response serverInfo.title if present)
+    attr_accessor :title
+
+    # @!attribute [rw] instructions
+    #   @return [String, nil] optional guidance for LLMs on how to use the server
+    #     (sent in initialize response instructions field if present)
+    attr_accessor :instructions
+
+    # @!attribute [r] client_logger
+    #   @return [ClientLogger] logger for sending notifications/message to MCP clients via JSON-RPC;
+    #     Router passes this to prompts, resources, and tools so they can log to the client
+    attr_reader :client_logger
+
+    # Lazily-built Ruby Logger for server-side diagnostics (not sent to clients).
+    # Reads from GlobalConfig::ServerLogging on first access so that
+    # Server.configure_server_logging can be called before or after the factory method.
+    #
+    # @return [ServerLogger] writes to stderr by default, or configured destination via configure_server_logging
+    def server_logger
+      @server_logger ||= begin
+        params = if ModelContextProtocol::Server::GlobalConfig::ServerLogging.configured?
+          ModelContextProtocol::Server::GlobalConfig::ServerLogging.logger_params
+        else
+          {}
+        end
+        ModelContextProtocol::Server::ServerLogger.new(**params)
+      end
+    end
 
+    # Initialize shared attributes and loggers for any configuration subclass.
+    # ClientLogger queues messages until a transport connects; ServerLogger is built
+    # lazily on first access via #server_logger.
     def initialize
       @client_logger = ModelContextProtocol::Server::ClientLogger.new(
         logger_name: "server",
         level: "info"
       )
-
-      server_logger_params = if ModelContextProtocol::Server::GlobalConfig::ServerLogging.configured?
-        ModelContextProtocol::Server::GlobalConfig::ServerLogging.logger_params
-      else
-        {}
-      end
-
-      @server_logger = ModelContextProtocol::Server::ServerLogger.new(**server_logger_params)
     end
 
-    def transport_type
-      case transport
-      when Hash
-        transport[:type] || transport["type"]
-      when Symbol, String
-        transport.to_sym
-      end
+    # Create and store a Registry from a block defining prompts, resources, and tools.
+    # Router queries the resulting registry to handle resources/list, tools/call, etc.
+    #
+    # @yieldparam (see Registry.new)
+    # @return [ModelContextProtocol::Server::Registry] the created registry
+    # @example
+    #   config.registry do
+    #     tools { register MyTool }
+    #   end
+    def registry(&block)
+      return @registry unless block
+
+      @registry = ModelContextProtocol::Server::Registry.new(&block)
     end
 
-    def transport_options
-      case transport
-      when Hash
-        transport.except(:type, "type").transform_keys(&:to_sym)
-      else
-        {}
-      end
-    end
+    # Identify the transport layer for this configuration.
+    # Subclasses return :stdio or :streamable_http; Server.start uses this to
+    # instantiate the correct Transport class (StdioTransport or StreamableHttpTransport).
+    #
+    # @return [Symbol, nil] nil in the base class (never instantiated directly)
+    def transport_type = nil
+
+    # Determine whether the transport supports notifications/resources/list_changed
+    # and notifications/tools/list_changed. Router queries this when building the
+    # initialize response capabilities hash (adding listChanged: true to prompts/resources/tools).
+    # Only HTTP transport returns true (stdio can't push unsolicited notifications).
+    #
+    # @return [Boolean] false in base class and StdioConfiguration, true in StreamableHttpConfiguration
+    def supports_list_changed? = false
 
+    # Determine whether Router should modify ENV before executing handlers.
+    # StdioConfiguration returns true because stdin/stdout scripts run single-threaded
+    # and ENV mutation is safe. StreamableHttpConfiguration returns false because
+    # ENV is global and modifying it in a multi-threaded Rack server creates race conditions.
+    #
+    # @return [Boolean] false in base class, overridden by subclasses
+    def apply_environment_variables? = false
+
+    # Check whether pagination is active for list responses (resources/list, prompts/list, tools/list).
+    # Router calls this before extracting pagination params; if false, it returns unpaginated results.
+    # Enabled by default (nil or true), or when pagination Hash has enabled != false.
+    #
+    # @return [Boolean] true unless pagination is explicitly set to false
     def pagination_enabled?
       return true if pagination.nil?
 
@@ -73,6 +157,12 @@ module ModelContextProtocol
       end
     end
 
+    # Extract normalized pagination settings for Router to pass to Pagination.extract_pagination_params.
+    # Router uses default_page_size and max_page_size to validate cursor and page size params from the client,
+    # and cursor_ttl to configure how long the Pagination module stores cursor state in memory.
+    #
+    # @return [Hash] pagination parameters with keys :enabled, :default_page_size, :max_page_size, :cursor_ttl;
+    #   defaults are 100, 1000, and 3600 (1 hour) respectively
     def pagination_options
       case pagination
       when Hash
@@ -94,6 +184,19 @@ module ModelContextProtocol
       end
     end
 
+    # Verify all required attributes and transport-specific constraints.
+    # Called by Server.build_server (the factory method's internal logic) after yielding
+    # the configuration block but before constructing the Router. Ensures the configuration
+    # is complete and internally consistent.
+    #
+    # @raise [InvalidServerNameError] if name is nil or non-String
+    # @raise [InvalidRegistryError] if registry is nil or not a Registry instance
+    # @raise [InvalidServerVersionError] if version is nil or non-String
+    # @raise [InvalidTransportError] if transport prerequisites fail (subclass-specific)
+    # @raise [InvalidPaginationError] if page sizes are negative or out of range
+    # @raise [InvalidServerTitleError] if title is non-nil but not a String
+    # @raise [InvalidServerInstructionsError] if instructions is non-nil but not a String
+    # @return [void]
     def validate!
       raise InvalidServerNameError unless valid_name?
       raise InvalidRegistryError unless valid_registry?
@@ -103,93 +206,84 @@ module ModelContextProtocol
       validate_pagination!
       validate_title!
       validate_instructions!
-      validate_environment_variables!
-      validate_server_logging_transport_constraints!
-    end
-
-    def environment_variables
-      @environment_variables ||= {}
     end
 
-    def environment_variable(key)
-      environment_variables[key.to_s.upcase] || ENV[key.to_s.upcase] || nil
-    end
-
-    def require_environment_variable(key)
-      required_environment_variables << key.to_s.upcase
-    end
-
-    # Programatically set an environment variable - useful if an alternative
-    # to environment variables is used for security purposes. Despite being
-    # more like 'configuration variables', these are called environment variables
-    # to align with the Model Context Protocol terminology.
-    #
-    # see: https://modelcontextprotocol.io/docs/tools/debugging#environment-variables
+    # Access server-wide key-value storage merged with per-request session_context by Router.
+    # Router.effective_context merges this with Thread.current[:mcp_context][:session_context],
+    # then passes the result to prompts, resources, and tools so they can access both
+    # server-level (shared across all requests) and session-level (specific to HTTP session) data.
     #
-    # @param key [String] The key to set the environment variable for
-    # @param value [String] The value to set the environment variable to
-    def set_environment_variable(key, value)
-      environment_variables[key.to_s.upcase] = value
-    end
-
+    # @return [Hash] the lazily-initialized context hash (defaults to {})
     def context
       @context ||= {}
     end
 
+    # Replace the server-wide context with a new hash.
+    # Router reads this via effective_context, merging it with session-level data before
+    # passing to handler implementations.
+    #
+    # @param context_hash [Hash] the new context to store (defaults to {})
+    # @return [Hash] the stored context
     def context=(context_hash = {})
       @context = context_hash
     end
 
     private
 
-    def required_environment_variables
-      @required_environment_variables ||= []
-    end
-
-    def validate_environment_variables!
-      required_environment_variables.each do |key|
-        raise MissingRequiredEnvironmentVariable, "#{key} is not set" unless environment_variable(key)
-      end
+    # Template method for subclass-specific transport validation.
+    # StdioConfiguration checks that required environment variables are set and that
+    # server_logger isn't writing to stdout (which would corrupt the stdio protocol).
+    # StreamableHttpConfiguration validates that redis_url is a valid Redis URL.
+    #
+    # @raise [InvalidTransportError] when transport prerequisites are unmet
+    # @raise [MissingRequiredEnvironmentVariable] when stdio transport requires an unset variable
+    # @return [void]
+    def validate_transport!
+      # Template method — subclasses override to add transport-specific validations
     end
 
-    def validate_server_logging_transport_constraints!
-      return unless transport_type == :stdio && server_logger.logdev == $stdout
-
-      raise ModelContextProtocol::Server::ServerLogger::StdoutNotAllowedError,
-        "StdioTransport cannot log to stdout. Use stderr or a file instead."
+    # Template method for subclass-specific transport setup (side effects).
+    # Called by Server.build_server after validate! passes. Separated from validate_transport!
+    # because validation should be pure (no side effects), while setup performs actions like
+    # creating connection pools.
+    # StreamableHttpConfiguration overrides this to configure the Redis connection pool.
+    #
+    # @return [void]
+    def setup_transport!
+      # Template method — subclasses override to perform transport-specific setup
     end
 
+    # Check that name attribute is a non-nil String.
+    # Called by validate! to ensure the initialize response can be constructed.
+    #
+    # @return [Boolean] true if name is a String
     def valid_name?
       name&.is_a?(String)
     end
 
+    # Check that registry attribute is a Registry instance.
+    # Called by validate! to ensure Router can query tools, prompts, and resources.
+    #
+    # @return [Boolean] true if registry is a ModelContextProtocol::Server::Registry
     def valid_registry?
       registry&.is_a?(ModelContextProtocol::Server::Registry)
     end
 
+    # Check that version attribute is a non-nil String.
+    # Called by validate! to ensure the initialize response can be constructed.
+    #
+    # @return [Boolean] true if version is a String
     def valid_version?
       version&.is_a?(String)
     end
 
-    def validate_transport!
-      case transport_type
-      when :streamable_http
-        validate_streamable_http_transport!
-      when :stdio, nil
-        # stdio transport has no required options
-      else
-        raise InvalidTransportError, "Unknown transport type: #{transport_type}" if transport_type
-      end
-    end
-
-    def validate_streamable_http_transport!
-      unless ModelContextProtocol::Server::RedisConfig.configured?
-        raise InvalidTransportError,
-          "streamable_http transport requires Redis configuration. " \
-          "Call ModelContextProtocol::Server.configure_redis in an initializer."
-      end
-    end
-
+    # Verify pagination settings are internally consistent (page sizes positive, defaults in range).
+    # Called by validate! only when pagination_enabled? is true; skipped if pagination is false.
+    # Ensures Router won't pass invalid params to Pagination.extract_pagination_params.
+    #
+    # @raise [InvalidPaginationError] if max_page_size <= 0, default_page_size <= 0,
+    #   default_page_size > max_page_size, or cursor_ttl < 0
+    # @return [void]
     def validate_pagination!
       return unless pagination_enabled?
 
@@ -208,6 +302,11 @@ module ModelContextProtocol
       end
     end
 
+    # Check that the optional title attribute is nil or a String.
+    # Called by validate! to ensure the initialize response serverInfo.title is valid.
+    #
+    # @raise [InvalidServerTitleError] if title is non-nil and not a String
+    # @return [void]
     def validate_title!
       return if title.nil?
       return if title.is_a?(String)
@@ -215,6 +314,11 @@ module ModelContextProtocol
       raise InvalidServerTitleError, "Server title must be a string"
     end
 
+    # Check that the optional instructions attribute is nil or a String.
+    # Called by validate! to ensure the initialize response instructions field is valid.
+    #
+    # @raise [InvalidServerInstructionsError] if instructions is non-nil and not a String
+    # @return [void]
     def validate_instructions!
       return if instructions.nil?
       return if instructions.is_a?(String)

data/lib/model_context_protocol/server/content_helpers.rb

@@ -78,7 +78,7 @@ module ModelContextProtocol
         size:,
         title:,
         uri:
-      ].serialized
+      ]
     end
   end
 end

data/lib/model_context_protocol/server/prompt.rb

@@ -70,20 +70,6 @@ module ModelContextProtocol
         @defined_arguments.concat(definition_dsl.arguments)
       end
 
-      def with_argument(&block)
-        @defined_arguments ||= []
-
-        argument_dsl = ArgumentDSL.new
-        argument_dsl.instance_eval(&block)
-
-        @defined_arguments << {
-          name: argument_dsl.name,
-          description: argument_dsl.description,
-          required: argument_dsl.required,
-          completion: argument_dsl.completion
-        }
-      end
-
       def inherited(subclass)
         subclass.instance_variable_set(:@name, @name)
         subclass.instance_variable_set(:@description, @description)

data/lib/model_context_protocol/server/redis_client_proxy.rb

@@ -39,8 +39,8 @@ module ModelContextProtocol
         with_connection { |redis| redis.hset(key, *args) }
       end
 
-      def hgetall(key)
-        with_connection { |redis| redis.hgetall(key) }
+      def hmget(key, *fields)
+        with_connection { |redis| redis.hmget(key, *fields) }
       end
 
       def lpush(key, *values)
@@ -67,10 +67,6 @@ module ModelContextProtocol
         with_connection { |redis| redis.incr(key) }
       end
 
-      def decr(key)
-        with_connection { |redis| redis.decr(key) }
-      end
-
       def keys(pattern)
         with_connection { |redis| redis.keys(pattern) }
       end
@@ -101,14 +97,6 @@ module ModelContextProtocol
         with_connection { |redis| redis.eval(script, keys: keys, argv: argv) }
       end
 
-      def ping
-        with_connection { |redis| redis.ping }
-      end
-
-      def flushdb
-        with_connection { |redis| redis.flushdb }
-      end
-
       private
 
       def with_connection(&block)

data/lib/model_context_protocol/server/redis_config.rb

@@ -6,7 +6,7 @@ module ModelContextProtocol
 
     class NotConfiguredError < StandardError
       def initialize
-        super("Redis not configured. Call ModelContextProtocol::Server.configure_redis first")
+        super("Redis not configured. Set redis_url in the StreamableHttpConfiguration block.")
       end
     end
 
@@ -36,10 +36,6 @@ module ModelContextProtocol
       instance.stats
     end
 
-    def self.pool_manager
-      instance.manager
-    end
-
     def initialize
       reset!
     end
@@ -53,7 +49,8 @@ module ModelContextProtocol
       @manager = Server::RedisPoolManager.new(
         redis_url: config.redis_url,
         pool_size: config.pool_size,
-        pool_timeout: config.pool_timeout
+        pool_timeout: config.pool_timeout,
+        ssl_params: config.ssl_params
       )
 
       if config.enable_reaper
@@ -93,7 +90,7 @@ module ModelContextProtocol
 
     class Configuration
       attr_accessor :redis_url, :pool_size, :pool_timeout,
-        :enable_reaper, :reaper_interval, :idle_timeout
+        :enable_reaper, :reaper_interval, :idle_timeout, :ssl_params
 
       def initialize
         @redis_url = nil
@@ -102,6 +99,7 @@ module ModelContextProtocol
         @enable_reaper = true
         @reaper_interval = 60
         @idle_timeout = 300
+        @ssl_params = nil
       end
     end
   end