model-context-protocol-rb 0.5.1 → 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/cancellable.rb

@@ -24,8 +24,8 @@ module ModelContextProtocol
       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])
+        if context && context[:request_store] && context[:jsonrpc_request_id]
+          if context[:request_store].cancelled?(context[:jsonrpc_request_id])
             thread = executing_thread.get
             thread&.raise(CancellationError, "Request was cancelled") if thread&.alive?
           end
@@ -35,9 +35,9 @@ module ModelContextProtocol
       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"
+        if context && context[:request_store] && context[:jsonrpc_request_id]
+          if context[:request_store].cancelled?(context[:jsonrpc_request_id])
+            raise CancellationError, "Request #{context[:jsonrpc_request_id]} was cancelled"
           end
         end
 

data/lib/model_context_protocol/server/{mcp_logger.rb → client_logger.rb}

@@ -3,11 +3,13 @@ require "forwardable"
 require "json"
 
 module ModelContextProtocol
-  class Server::MCPLogger
+  class Server::ClientLogger
     extend Forwardable
 
     def_delegators :@internal_logger, :datetime_format=, :formatter=, :progname, :progname=
 
+    VALID_LOG_LEVELS = %w[debug info notice warning error critical alert emergency].freeze
+
     LEVEL_MAP = {
       "debug" => Logger::DEBUG,
       "info" => Logger::INFO,
@@ -28,12 +30,11 @@ module ModelContextProtocol
       Logger::UNKNOWN => "emergency"
     }.freeze
 
-    attr_accessor :transport
-    attr_reader :logger_name, :enabled
+    attr_reader :transport
+    attr_reader :logger_name
 
-    def initialize(logger_name: "server", level: "info", enabled: true)
+    def initialize(logger_name: "server", level: "info")
       @logger_name = logger_name
-      @enabled = enabled
       @internal_logger = Logger.new(nil)
       @internal_logger.level = LEVEL_MAP[level] || Logger::INFO
       @transport = nil
@@ -42,13 +43,11 @@ module ModelContextProtocol
 
     %i[debug info warn error fatal unknown].each do |severity|
       define_method(severity) do |message = nil, **data, &block|
-        return true unless @enabled
         add(Logger.const_get(severity.to_s.upcase), message, data, &block)
       end
     end
 
     def add(severity, message = nil, data = {}, &block)
-      return true unless @enabled
       return true if severity < @internal_logger.level
 
       message = block.call if message.nil? && block_given?
@@ -70,14 +69,12 @@ module ModelContextProtocol
 
     def connect_transport(transport)
       @transport = transport
-      flush_queued_messages if @enabled
+      flush_queued_messages
     end
 
     private
 
     def send_notification(severity, message, data)
-      return unless @enabled
-
       notification_params = {
         level: REVERSE_LEVEL_MAP[severity] || "info",
         logger: @logger_name,
@@ -99,7 +96,7 @@ module ModelContextProtocol
     end
 
     def flush_queued_messages
-      return unless @transport && @enabled
+      return unless @transport
       @queued_messages.each do |params|
         @transport.send_notification("notifications/message", params)
       end

data/lib/model_context_protocol/server/configuration.rb

@@ -1,90 +1,149 @@
-require_relative "mcp_logger"
-
 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 an invalid log level is provided
-    class InvalidLogLevelError < 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
 
-    # 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, :pagination, :title, :instructions
-    attr_reader :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
-      @logging_enabled = true
-      @default_log_level = "info"
-      @logger = ModelContextProtocol::Server::MCPLogger.new(
+      @client_logger = ModelContextProtocol::Server::ClientLogger.new(
         logger_name: "server",
-        level: @default_log_level,
-        enabled: @logging_enabled
+        level: "info"
       )
     end
 
-    def logging_enabled?
-      @logging_enabled
-    end
-
-    def logging_enabled=(value)
-      @logging_enabled = value
-      @logger = ModelContextProtocol::Server::MCPLogger.new(
-        logger_name: "server",
-        level: @default_log_level,
-        enabled: value
-      )
+    # 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 default_log_level=(level)
-      unless VALID_LOG_LEVELS.include?(level.to_s)
-        raise InvalidLogLevelError, "Invalid log level: #{level}. Valid levels are: #{VALID_LOG_LEVELS.join(", ")}"
-      end
-
-      @default_log_level = level.to_s
-      @logger.set_mcp_level(@default_log_level)
-    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
 
-    def transport_type
-      case transport
-      when Hash
-        transport[:type] || transport["type"]
-      when Symbol, String
-        transport.to_sym
-      end
-    end
+    # 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
 
-    def transport_options
-      case transport
-      when Hash
-        transport.except(:type, "type").transform_keys(&:to_sym)
-      else
-        {}
-      end
-    end
+    # 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?
 
@@ -98,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
@@ -119,94 +184,106 @@ 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?
       raise InvalidServerVersionError unless valid_version?
+
       validate_transport!
       validate_pagination!
       validate_title!
       validate_instructions!
-
-      validate_environment_variables!
     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 ||= []
+    # 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_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 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?
 
@@ -225,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)
@@ -232,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