model-context-protocol-rb 0.5.1 → 0.7.0

data/lib/model_context_protocol/server/tool.rb

@@ -9,13 +9,14 @@ module ModelContextProtocol
     include ModelContextProtocol::Server::ContentHelpers
     include ModelContextProtocol::Server::Progressable
 
-    attr_reader :arguments, :context, :logger
+    attr_reader :arguments, :context, :client_logger, :server_logger
 
-    def initialize(arguments, logger, context = {})
+    def initialize(arguments, client_logger, server_logger, context = {})
       validate!(arguments)
       @arguments = arguments
       @context = context
-      @logger = logger
+      @client_logger = client_logger
+      @server_logger = server_logger
     end
 
     def call
@@ -82,7 +83,7 @@ module ModelContextProtocol
     end
 
     class << self
-      attr_reader :name, :description, :title, :input_schema, :output_schema
+      attr_reader :name, :description, :title, :input_schema, :output_schema, :annotations, :security_schemes
 
       def define(&block)
         definition_dsl = DefinitionDSL.new
@@ -93,6 +94,8 @@ module ModelContextProtocol
         @title = definition_dsl.title
         @input_schema = definition_dsl.input_schema
         @output_schema = definition_dsl.output_schema
+        @annotations = definition_dsl.defined_annotations
+        @security_schemes = definition_dsl.security_schemes
       end
 
       def inherited(subclass)
@@ -101,10 +104,12 @@ module ModelContextProtocol
         subclass.instance_variable_set(:@title, @title)
         subclass.instance_variable_set(:@input_schema, @input_schema)
         subclass.instance_variable_set(:@output_schema, @output_schema)
+        subclass.instance_variable_set(:@annotations, @annotations&.dup)
+        subclass.instance_variable_set(:@security_schemes, @security_schemes)
       end
 
-      def call(arguments, logger, context = {})
-        new(arguments, logger, context).call
+      def call(arguments, client_logger, server_logger, context = {})
+        new(arguments, client_logger, server_logger, context).call
       rescue JSON::Schema::ValidationError => validation_error
         raise ModelContextProtocol::Server::ParameterValidationError, validation_error.message
       rescue OutputSchemaValidationError, ModelContextProtocol::Server::ResponseArgumentsError => tool_error
@@ -119,6 +124,9 @@ module ModelContextProtocol
         result = {name: @name, description: @description, inputSchema: @input_schema}
         result[:title] = @title if @title
         result[:outputSchema] = @output_schema if @output_schema
+        annotations_hash = @annotations&.serialized
+        result[:annotations] = annotations_hash if annotations_hash
+        result[:securitySchemes] = @security_schemes if @security_schemes
         result
       end
     end
@@ -148,6 +156,65 @@ module ModelContextProtocol
         @output_schema = instance_eval(&block) if block_given?
         @output_schema
       end
+
+      attr_reader :defined_annotations
+
+      def annotations(&block)
+        @defined_annotations = AnnotationsDSL.new
+        @defined_annotations.instance_eval(&block)
+        @defined_annotations
+      end
+
+      def security_schemes(&block)
+        @security_schemes = instance_eval(&block) if block_given?
+        @security_schemes
+      end
+    end
+
+    class AnnotationsDSL
+      def initialize
+        @read_only_hint = nil
+        @destructive_hint = nil
+        @idempotent_hint = nil
+        @open_world_hint = nil
+      end
+
+      def read_only_hint(value)
+        validate_boolean!(:read_only_hint, value)
+        @read_only_hint = value
+      end
+
+      def destructive_hint(value)
+        validate_boolean!(:destructive_hint, value)
+        @destructive_hint = value
+      end
+
+      def idempotent_hint(value)
+        validate_boolean!(:idempotent_hint, value)
+        @idempotent_hint = value
+      end
+
+      def open_world_hint(value)
+        validate_boolean!(:open_world_hint, value)
+        @open_world_hint = value
+      end
+
+      def serialized
+        result = {}
+        result[:readOnlyHint] = @read_only_hint unless @read_only_hint.nil?
+        result[:destructiveHint] = @destructive_hint unless @destructive_hint.nil?
+        result[:idempotentHint] = @idempotent_hint unless @idempotent_hint.nil?
+        result[:openWorldHint] = @open_world_hint unless @open_world_hint.nil?
+        result.empty? ? nil : result
+      end
+
+      private
+
+      def validate_boolean!(field, value)
+        unless value.is_a?(TrueClass) || value.is_a?(FalseClass)
+          raise ArgumentError, "#{field} must be a boolean, got: #{value.inspect}"
+        end
+      end
     end
   end
 end

data/lib/model_context_protocol/server.rb

@@ -1,5 +1,3 @@
-require "logger"
-
 module ModelContextProtocol
   class Server
     # Raised when invalid response arguments are provided.
@@ -8,284 +6,229 @@ module ModelContextProtocol
     # Raised when invalid parameters are provided.
     class ParameterValidationError < StandardError; end
 
-    attr_reader :configuration, :router, :transport
+    # Raised by class-level start and serve when no server instance has been configured
+    # via with_stdio_transport or with_streamable_http_transport.
+    class NotConfiguredError < StandardError; end
 
-    def initialize
-      @configuration = Configuration.new
-      yield(@configuration) if block_given?
-      @router = Router.new(configuration:)
-      map_handlers
-    end
+    # @return [Configuration] the transport-specific configuration (StdioConfiguration or StreamableHttpConfiguration)
+    # @return [Router] the message router that dispatches JSON-RPC methods to handlers
+    # @return [Transport, nil] the active transport (StdioTransport or StreamableHttpTransport), or nil if not started
+    attr_reader :configuration, :router, :transport
 
+    # Activate the transport layer to begin processing MCP protocol messages.
+    # For stdio: blocks the calling thread while handling stdin/stdout communication.
+    # For HTTP: spawns background threads for Redis polling and stream monitoring, then returns immediately.
+    #
+    # @raise [RuntimeError] if transport is already running (prevents double-initialization)
+    # @return [void]
     def start
-      configuration.validate!
+      raise "Server already running. Call shutdown first." if @transport
 
-      @transport = case configuration.transport_type
-      when :stdio, nil
-        StdioTransport.new(router: @router, configuration: @configuration)
+      case configuration.transport_type
+      when :stdio
+        @transport = StdioTransport.new(router: @router, configuration: @configuration)
+        @transport.handle
       when :streamable_http
-        StreamableHttpTransport.new(
-          router: @router,
-          configuration: @configuration
-        )
-      else
-        raise ArgumentError, "Unknown transport: #{configuration.transport_type}"
+        @transport = StreamableHttpTransport.new(router: @router, configuration: @configuration)
       end
-
-      @transport.handle
     end
 
-    private
-
-    SUPPORTED_PROTOCOL_VERSIONS = ["2025-06-18"].freeze
-    private_constant :SUPPORTED_PROTOCOL_VERSIONS
-
-    LATEST_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSIONS.first
-    private_constant :LATEST_PROTOCOL_VERSION
-
-    InitializeResponse = Data.define(:protocol_version, :capabilities, :server_info, :instructions) do
-      def serialized
-        response = {
-          protocolVersion: protocol_version,
-          capabilities: capabilities,
-          serverInfo: server_info
-        }
-        response[:instructions] = instructions if instructions
-        response
-      end
+    # Handle a single HTTP request through the streamable HTTP transport.
+    # Rack applications delegate each incoming request to this method.
+    #
+    # @param env [Hash] the Rack environment hash containing request details
+    # @param session_context [Hash] per-session data (e.g., user_id) stored during initialization
+    # @raise [RuntimeError] if transport hasn't been started via start
+    # @raise [RuntimeError] if called on stdio transport (HTTP-only method)
+    # @return [Hash] Rack response with :status, :headers, and either :json or :stream/:stream_proc
+    def serve(env:, session_context: {})
+      raise "Server not running. Call start first." unless @transport
+      raise "serve is only available for streamable_http transport" unless configuration.transport_type == :streamable_http
+
+      @transport.handle(env: env, session_context: session_context)
     end
 
-    PingResponse = Data.define do
-      def serialized
-        {}
-      end
+    # Tear down the transport and release resources.
+    # For stdio: no-ops (StdioTransport doesn't implement shutdown).
+    # For HTTP: stops background threads and closes active SSE streams.
+    #
+    # @return [void]
+    def shutdown
+      @transport.shutdown if @transport.respond_to?(:shutdown)
+      @transport = nil
     end
 
-    LoggingSetLevelResponse = Data.define do
-      def serialized
-        {}
-      end
+    # Query whether the server has been configured with a transport type.
+    # The Puma plugin checks this before attempting to start the server.
+    #
+    # @return [Boolean] true if with_stdio_transport or with_streamable_http_transport has been called
+    def configured?
+      !@configuration.nil?
     end
 
-    def map_handlers
-      router.map("initialize") do |message|
-        client_protocol_version = message["params"]&.dig("protocolVersion")
-
-        negotiated_version = if client_protocol_version && SUPPORTED_PROTOCOL_VERSIONS.include?(client_protocol_version)
-          client_protocol_version
-        else
-          LATEST_PROTOCOL_VERSION
-        end
-
-        server_info = {
-          name: configuration.name,
-          version: configuration.version
-        }
-        server_info[:title] = configuration.title if configuration.title
-
-        InitializeResponse[
-          protocol_version: negotiated_version,
-          capabilities: build_capabilities,
-          server_info: server_info,
-          instructions: configuration.instructions
-        ]
-      end
-
-      router.map("ping") do
-        PingResponse[]
-      end
-
-      router.map("logging/setLevel") do |message|
-        level = message["params"]["level"]
-
-        unless Configuration::VALID_LOG_LEVELS.include?(level)
-          raise ParameterValidationError, "Invalid log level: #{level}. Valid levels are: #{Configuration::VALID_LOG_LEVELS.join(", ")}"
-        end
-
-        configuration.logger.set_mcp_level(level)
-        LoggingSetLevelResponse[]
-      end
-
-      router.map("completion/complete") do |message|
-        type = message["params"]["ref"]["type"]
-
-        completion_source = case type
-        when "ref/prompt"
-          name = message["params"]["ref"]["name"]
-          configuration.registry.find_prompt(name)
-        when "ref/resource"
-          uri = message["params"]["ref"]["uri"]
-          configuration.registry.find_resource_template(uri)
-        else
-          raise ModelContextProtocol::Server::ParameterValidationError, "ref/type invalid"
-        end
-
-        arg_name, arg_value = message["params"]["argument"].values_at("name", "value")
-
-        if completion_source
-          completion_source.complete_for(arg_name, arg_value)
-        else
-          ModelContextProtocol::Server::NullCompletion.call(arg_name, arg_value)
-        end
-      end
-
-      router.map("resources/list") do |message|
-        params = message["params"] || {}
-
-        if configuration.pagination_enabled? && Server::Pagination.pagination_requested?(params)
-          opts = configuration.pagination_options
-
-          pagination_params = Server::Pagination.extract_pagination_params(
-            params,
-            default_page_size: opts[:default_page_size],
-            max_page_size: opts[:max_page_size]
-          )
-
-          configuration.registry.resources_data(
-            cursor: pagination_params[:cursor],
-            page_size: pagination_params[:page_size],
-            cursor_ttl: opts[:cursor_ttl]
-          )
-        else
-          configuration.registry.resources_data
-        end
-      rescue Server::Pagination::InvalidCursorError => e
-        raise ParameterValidationError, e.message
-      end
-
-      router.map("resources/read") do |message|
-        uri = message["params"]["uri"]
-        resource = configuration.registry.find_resource(uri)
-        unless resource
-          raise ModelContextProtocol::Server::ParameterValidationError, "resource not found for #{uri}"
-        end
-
-        resource.call
-      end
-
-      router.map("resources/templates/list") do |message|
-        params = message["params"] || {}
-
-        if configuration.pagination_enabled? && Server::Pagination.pagination_requested?(params)
-          opts = configuration.pagination_options
-
-          pagination_params = Server::Pagination.extract_pagination_params(
-            params,
-            default_page_size: opts[:default_page_size],
-            max_page_size: opts[:max_page_size]
-          )
-
-          configuration.registry.resource_templates_data(
-            cursor: pagination_params[:cursor],
-            page_size: pagination_params[:page_size],
-            cursor_ttl: opts[:cursor_ttl]
-          )
-        else
-          configuration.registry.resource_templates_data
-        end
-      rescue Server::Pagination::InvalidCursorError => e
-        raise ParameterValidationError, e.message
-      end
-
-      router.map("prompts/list") do |message|
-        params = message["params"] || {}
-
-        if configuration.pagination_enabled? && Server::Pagination.pagination_requested?(params)
-          opts = configuration.pagination_options
-
-          pagination_params = Server::Pagination.extract_pagination_params(
-            params,
-            default_page_size: opts[:default_page_size],
-            max_page_size: opts[:max_page_size]
-          )
-
-          configuration.registry.prompts_data(
-            cursor: pagination_params[:cursor],
-            page_size: pagination_params[:page_size],
-            cursor_ttl: opts[:cursor_ttl]
-          )
-        else
-          configuration.registry.prompts_data
-        end
-      rescue Server::Pagination::InvalidCursorError => e
-        raise ParameterValidationError, e.message
-      end
-
-      router.map("prompts/get") do |message|
-        arguments = message["params"]["arguments"]
-        symbolized_arguments = arguments.transform_keys(&:to_sym)
-        configuration
-          .registry
-          .find_prompt(message["params"]["name"])
-          .call(symbolized_arguments, configuration.logger, configuration.context)
-      end
-
-      router.map("tools/list") do |message|
-        params = message["params"] || {}
-
-        if configuration.pagination_enabled? && Server::Pagination.pagination_requested?(params)
-          opts = configuration.pagination_options
-
-          pagination_params = Server::Pagination.extract_pagination_params(
-            params,
-            default_page_size: opts[:default_page_size],
-            max_page_size: opts[:max_page_size]
-          )
-
-          configuration.registry.tools_data(
-            cursor: pagination_params[:cursor],
-            page_size: pagination_params[:page_size],
-            cursor_ttl: opts[:cursor_ttl]
-          )
-        else
-          configuration.registry.tools_data
-        end
-      rescue Server::Pagination::InvalidCursorError => e
-        raise ParameterValidationError, e.message
-      end
-
-      router.map("tools/call") do |message|
-        arguments = message["params"]["arguments"]
-        symbolized_arguments = arguments.transform_keys(&:to_sym)
-        configuration
-          .registry
-          .find_tool(message["params"]["name"])
-          .call(symbolized_arguments, configuration.logger, configuration.context)
-      end
+    # Query whether the server's transport layer is actively processing messages.
+    # The Puma plugin checks this to avoid redundant start calls and to guard shutdown.
+    #
+    # @return [Boolean] true if start has been called and transport is initialized
+    def running?
+      !@transport.nil?
     end
 
-    def build_capabilities
-      {}.tap do |capabilities|
-        capabilities[:completions] = {}
-        capabilities[:logging] = {} if configuration.logging_enabled?
-
-        registry = configuration.registry
-
-        if registry.prompts_options.any? && !registry.instance_variable_get(:@prompts).empty?
-          capabilities[:prompts] = {
-            listChanged: registry.prompts_options[:list_changed]
-          }.except(:completions).compact
-        end
-
-        if registry.resources_options.any? && !registry.instance_variable_get(:@resources).empty?
-          capabilities[:resources] = {
-            subscribe: registry.resources_options[:subscribe],
-            listChanged: registry.resources_options[:list_changed]
-          }.compact
-        end
-
-        if registry.tools_options.any? && !registry.instance_variable_get(:@tools).empty?
-          capabilities[:tools] = {
-            listChanged: registry.tools_options[:list_changed]
-          }.compact
-        end
+    class << self
+      # @return [Server, nil] the singleton server instance created by with_stdio_transport or with_streamable_http_transport
+      attr_accessor :instance
+
+      # Factory method for creating a server with standard input/output transport.
+      # For standalone scripts that communicate over stdin/stdout (e.g., Claude Desktop integration).
+      # Yields a StdioConfiguration for setting name, version, registry, and environment variables.
+      #
+      # @yieldparam config [StdioConfiguration] the configuration to populate
+      # @return [Server] the configured server instance (also stored in Server.instance)
+      # @example
+      #   server = ModelContextProtocol::Server.with_stdio_transport do |config|
+      #     config.name = "My MCP Server"
+      #     config.registry { tools { register MyTool } }
+      #   end
+      #   server.start  # blocks while handling stdio
+      def with_stdio_transport(&block)
+        build_server(StdioConfiguration.new, &block)
+      end
+
+      # Factory method for creating a server with streamable HTTP transport.
+      # For Rack applications that serve multiple clients over HTTP with Redis-backed session coordination.
+      # Yields a StreamableHttpConfiguration for setting name, version, registry, session requirements, and CORS.
+      #
+      # @yieldparam config [StreamableHttpConfiguration] the configuration to populate
+      # @return [Server] the configured server instance (also stored in Server.instance)
+      # @raise [InvalidTransportError] if redis_url is not set or invalid
+      # @example
+      #   server = ModelContextProtocol::Server.with_streamable_http_transport do |config|
+      #     config.name = "My HTTP MCP Server"
+      #     config.redis_url = ENV.fetch("REDIS_URL")
+      #     config.require_sessions = true
+      #     config.allowed_origins = ["*"]
+      #   end
+      #   server.start  # spawns background threads, returns immediately
+      def with_streamable_http_transport(&block)
+        build_server(StreamableHttpConfiguration.new, &block)
+      end
+
+      # Configure global server-side logging (distinct from client-facing logs sent via JSON-RPC).
+      # Applies to all server instances; typically called once per application.
+      # For stdio transport, logdev must not be $stdout (would corrupt protocol messages).
+      #
+      # @yieldparam config [GlobalConfig::ServerLogging] the logging configuration
+      # @return [void]
+      # @example
+      #   ModelContextProtocol::Server.configure_server_logging do |logger|
+      #     logger.level = Logger::DEBUG
+      #     logger.logdev = $stderr  # or a file for stdio transport
+      #   end
+      def configure_server_logging(&block)
+        Server::GlobalConfig::ServerLogging.configure(&block)
+        instance&.configuration&.instance_variable_set(:@server_logger, nil)
+      end
+
+      # Class-level delegations that forward to the singleton instance.
+      # Provided as a convenience for web server integrations (e.g., the Puma plugin in
+      # lib/puma/plugin/mcp.rb) that manage the server lifecycle through hooks rather
+      # than holding a direct reference to the server instance.
+
+      # Query whether any server instance has been configured.
+      # Returns false when no instance exists — the server genuinely isn't configured yet,
+      # so callers can use this as a guard before calling start.
+      #
+      # @return [Boolean] true if with_stdio_transport or with_streamable_http_transport has been called
+      def configured?
+        instance&.configured? || false
+      end
+
+      # Query whether any server instance is actively processing messages.
+      # Returns false when no instance exists, allowing callers to guard both
+      # start (to avoid redundant starts) and shutdown (to skip if not running).
+      #
+      # @return [Boolean] true if a server instance exists and its transport is initialized
+      def running?
+        instance&.running? || false
+      end
+
+      # Activate the transport layer to begin processing MCP protocol messages.
+      # Raises when no instance exists because a caller who forgot to invoke a factory method
+      # would otherwise get silent nil. Web server integrations like the Puma plugin guard
+      # with configured? first, but direct callers need the error.
+      #
+      # @raise [NotConfiguredError] if with_stdio_transport or with_streamable_http_transport hasn't been called
+      # @return [void]
+      def start
+        raise NotConfiguredError, "Server not configured. Call with_stdio_transport or with_streamable_http_transport first." unless instance
+        instance.start
+      end
+
+      # Handle a single HTTP request by forwarding to the instance's serve method.
+      # Used by Rails/Sinatra/Rack controllers as an alternative to calling Server.instance.serve directly.
+      # Raises when no instance exists for the same reason as start — a controller receiving
+      # requests without a configured server is always a misconfiguration.
+      #
+      # @param env [Hash] the Rack environment hash containing request details
+      # @param session_context [Hash] per-session data (e.g., user_id) stored during initialization
+      # @raise [NotConfiguredError] if with_streamable_http_transport hasn't been called
+      # @return [Hash] Rack response with :status, :headers, and either :json or :stream/:stream_proc
+      def serve(env:, session_context: {})
+        raise NotConfiguredError, "Server not configured. Call with_streamable_http_transport first." unless instance
+        instance.serve(env: env, session_context: session_context)
+      end
+
+      # Tear down the transport and release resources if a server is running.
+      # Safe-navigates when no instance exists because callers in cleanup paths
+      # (signal handlers, web server shutdown hooks, test teardown) need this to
+      # work unconditionally.
+      #
+      # @return [void]
+      def shutdown
+        instance&.shutdown
+      end
+
+      # Tear down the transport and clear the singleton instance to allow reconfiguration.
+      # Safe-navigates when no instance exists because test teardown (before/after hooks)
+      # must succeed even when a test fails before the server is initialized.
+      #
+      # @return [void]
+      def reset!
+        instance&.shutdown
+        self.instance = nil
+      end
+
+      private
+
+      # Internal factory logic shared by with_stdio_transport and with_streamable_http_transport.
+      # Validates configuration, creates a server instance without calling initialize (via allocate),
+      # initializes it with the configuration, and stores it in the singleton.
+      #
+      # @param config [Configuration] the transport-specific configuration subclass
+      # @yieldparam config [Configuration] if a block is given, yields for additional setup
+      # @return [Server] the configured and stored server instance
+      def build_server(config)
+        yield(config) if block_given?
+        config.validate!
+        config.send(:setup_transport!)
+        server = allocate
+        server.send(:initialize_from_configuration, config)
+        self.instance = server
+        server
       end
     end
 
-    class << self
-      def configure_redis(&block)
-        RedisConfig.configure(&block)
-      end
+    private
+
+    # Internal initializer called by build_server after allocate.
+    # Bypasses the standard initialize to allow configuration-driven construction.
+    # Creates the Router that maps JSON-RPC methods to handlers based on the registry.
+    #
+    # @param configuration [Configuration] the validated transport-specific configuration
+    # @return [void]
+    def initialize_from_configuration(configuration)
+      @configuration = configuration
+      @router = Router.new(configuration:)
     end
   end
 end

data/lib/model_context_protocol/version.rb

@@ -1,3 +1,3 @@
 module ModelContextProtocol
-  VERSION = "0.5.1"
+  VERSION = "0.7.0"
 end

data/lib/model_context_protocol.rb

@@ -1,6 +1,9 @@
 require "addressable/template"
 
-Dir[File.join(__dir__, "model_context_protocol/", "**", "*.rb")].sort.each { |file| require_relative file }
+Dir[File.join(__dir__, "model_context_protocol/", "**", "*.rb")]
+  .reject { |file| file.include?("/rspec") }
+  .sort
+  .each { |file| require_relative file }
 
 ##
 # Top-level namespace

data/lib/puma/plugin/mcp.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "puma/plugin"
+
+Puma::Plugin.create do
+  # Capture the DSL reference for deferred hook registration.
+  def config(dsl)
+    @dsl = dsl
+  end
+
+  # Register lifecycle hooks after configuration is finalized.
+  # Using launcher.clustered? ensures reliable mode detection,
+  # avoiding issues where config-time checks may not reflect
+  # the final runtime worker count.
+  def start(launcher)
+    if (launcher.options[:workers] || 0) > 0
+      @dsl.before_worker_boot { start_mcp_server }
+      @dsl.before_worker_shutdown { shutdown_mcp_server }
+    else
+      launcher.events.after_booted { start_mcp_server }
+      launcher.events.after_stopped { shutdown_mcp_server }
+    end
+  end
+
+  private
+
+  def start_mcp_server
+    return unless ModelContextProtocol::Server.configured?
+    return if ModelContextProtocol::Server.running?
+
+    ModelContextProtocol::Server.start
+  end
+
+  def shutdown_mcp_server
+    return unless ModelContextProtocol::Server.running?
+
+    ModelContextProtocol::Server.shutdown
+  end
+end