mcp 0.8.0 → 0.10.0

data/lib/mcp/server/transports/streamable_http_transport.rb

@@ -1,25 +1,37 @@
 # frozen_string_literal: true
 
-require_relative "../../transport"
 require "json"
 require "securerandom"
+require_relative "../../transport"
 
 module MCP
   class Server
     module Transports
       class StreamableHTTPTransport < Transport
-        def initialize(server, stateless: false)
+        def initialize(server, stateless: false, session_idle_timeout: nil)
           super(server)
-          # { session_id => { stream: stream_object }
+          # Maps `session_id` to `{ stream: stream_object, server_session: ServerSession, last_active_at: float_from_monotonic_clock }`.
           @sessions = {}
           @mutex = Mutex.new
 
           @stateless = stateless
+          @session_idle_timeout = session_idle_timeout
+
+          if @session_idle_timeout
+            if @stateless
+              raise ArgumentError, "session_idle_timeout is not supported in stateless mode."
+            elsif @session_idle_timeout <= 0
+              raise ArgumentError, "session_idle_timeout must be a positive number."
+            end
+          end
+
+          start_reaper_thread if @session_idle_timeout
         end
 
         REQUIRED_POST_ACCEPT_TYPES = ["application/json", "text/event-stream"].freeze
         REQUIRED_GET_ACCEPT_TYPES = ["text/event-stream"].freeze
         STREAM_WRITE_ERRORS = [IOError, Errno::EPIPE, Errno::ECONNRESET].freeze
+        SESSION_REAP_INTERVAL = 60
 
         def handle_request(request)
           case request.env["REQUEST_METHOD"]
@@ -35,6 +47,9 @@ module MCP
         end
 
         def close
+          @reaper_thread&.kill
+          @reaper_thread = nil
+
           @mutex.synchronize do
             @sessions.each_key { |session_id| cleanup_session_unsafe(session_id) }
           end
@@ -56,6 +71,11 @@ module MCP
               session = @sessions[session_id]
               return false unless session && session[:stream]
 
+              if session_expired?(session)
+                cleanup_session_unsafe(session_id)
+                return false
+              end
+
               begin
                 send_to_stream(session[:stream], notification)
                 true
@@ -75,6 +95,11 @@ module MCP
               @sessions.each do |sid, session|
                 next unless session[:stream]
 
+                if session_expired?(session)
+                  failed_sessions << sid
+                  next
+                end
+
                 begin
                   send_to_stream(session[:stream], notification)
                   sent_count += 1
@@ -97,6 +122,39 @@ module MCP
 
         private
 
+        def start_reaper_thread
+          @reaper_thread = Thread.new do
+            loop do
+              sleep(SESSION_REAP_INTERVAL)
+              reap_expired_sessions
+            rescue StandardError => e
+              MCP.configuration.exception_reporter.call(e, error: "Session reaper error")
+            end
+          end
+        end
+
+        def reap_expired_sessions
+          return unless @session_idle_timeout
+
+          expired_streams = @mutex.synchronize do
+            @sessions.each_with_object([]) do |(session_id, session), streams|
+              next unless session_expired?(session)
+
+              streams << session[:stream] if session[:stream]
+              @sessions.delete(session_id)
+            end
+          end
+
+          expired_streams.each do |stream|
+            # Closing outside the mutex is safe because expired sessions are already
+            # removed from `@sessions` above, so other threads will not find them
+            # and will not attempt to close the same stream.
+            stream.close
+          rescue
+            nil
+          end
+        end
+
         def send_to_stream(stream, data)
           message = data.is_a?(String) ? data : data.to_json
           stream.write("data: #{message}\n\n")
@@ -120,10 +178,14 @@ module MCP
 
           if body["method"] == "initialize"
             handle_initialization(body_string, body)
-          elsif notification?(body) || response?(body)
-            handle_accepted
           else
-            handle_regular_request(body_string, session_id)
+            return missing_session_id_response if !@stateless && !session_id
+
+            if notification?(body) || response?(body)
+              handle_accepted
+            else
+              handle_regular_request(body_string, session_id)
+            end
           end
         rescue StandardError => e
           MCP.configuration.exception_reporter.call(e, { request: body_string })
@@ -141,7 +203,10 @@ module MCP
           session_id = extract_session_id(request)
 
           return missing_session_id_response unless session_id
-          return session_not_found_response unless session_exists?(session_id)
+
+          error_response = validate_and_touch_session(session_id)
+          return error_response if error_response
+          return session_already_connected_response if get_session_stream(session_id)
 
           setup_sse_stream(session_id)
         end
@@ -154,15 +219,11 @@ module MCP
             return success_response
           end
 
-          session_id = request.env["HTTP_MCP_SESSION_ID"]
-
-          return [
-            400,
-            { "Content-Type" => "application/json" },
-            [{ error: "Missing session ID" }.to_json],
-          ] unless session_id
+          return missing_session_id_response unless (session_id = request.env["HTTP_MCP_SESSION_ID"])
+          return session_not_found_response unless session_exists?(session_id)
 
           cleanup_session(session_id)
+
           success_response
         end
 
@@ -193,6 +254,8 @@ module MCP
           return not_acceptable_response(required_types) unless accept_header
 
           accepted_types = parse_accept_header(accept_header)
+          return if accepted_types.include?("*/*")
+
           missing_types = required_types - accepted_types
           return not_acceptable_response(required_types) unless missing_types.empty?
 
@@ -229,18 +292,26 @@ module MCP
 
         def handle_initialization(body_string, body)
           session_id = nil
+          server_session = nil
 
           unless @stateless
             session_id = SecureRandom.uuid
+            server_session = ServerSession.new(server: @server, transport: self, session_id: session_id)
 
             @mutex.synchronize do
               @sessions[session_id] = {
                 stream: nil,
+                server_session: server_session,
+                last_active_at: Process.clock_gettime(Process::CLOCK_MONOTONIC),
               }
             end
           end
 
-          response = @server.handle_json(body_string)
+          response = if server_session
+            server_session.handle_json(body_string)
+          else
+            @server.handle_json(body_string)
+          end
 
           headers = {
             "Content-Type" => "application/json",
@@ -256,30 +327,49 @@ module MCP
         end
 
         def handle_regular_request(body_string, session_id)
+          server_session = nil
+          stream = nil
+
           unless @stateless
-            # If session ID is provided, but not in the sessions hash, return an error
-            if session_id && !@sessions.key?(session_id)
-              return [400, { "Content-Type" => "application/json" }, [{ error: "Invalid session ID" }.to_json]]
+            if session_id
+              error_response = validate_and_touch_session(session_id)
+              return error_response if error_response
+
+              @mutex.synchronize do
+                session = @sessions[session_id]
+                server_session = session[:server_session] if session
+                stream = session[:stream] if session
+              end
             end
           end
 
-          response = @server.handle_json(body_string) || ""
-
-          # Stream can be nil since stateless mode doesn't retain streams
-          stream = get_session_stream(session_id) if session_id
+          response = if server_session
+            server_session.handle_json(body_string)
+          else
+            @server.handle_json(body_string)
+          end
 
           if stream
             send_response_to_stream(stream, response, session_id)
-          elsif response.nil? && notification_request?(body_string)
-            [202, { "Content-Type" => "application/json" }, [response]]
           else
             [200, { "Content-Type" => "application/json" }, [response]]
           end
         end
 
-        def notification_request?(body_string)
-          body = parse_request_body(body_string)
-          body.is_a?(Hash) && body["method"].start_with?("notifications/")
+        def validate_and_touch_session(session_id)
+          @mutex.synchronize do
+            return session_not_found_response unless (session = @sessions[session_id])
+            return unless @session_idle_timeout
+
+            if session_expired?(session)
+              cleanup_session_unsafe(session_id)
+              return session_not_found_response
+            end
+
+            session[:last_active_at] = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          end
+
+          nil
         end
 
         def get_session_stream(session_id)
@@ -315,6 +405,14 @@ module MCP
           [404, { "Content-Type" => "application/json" }, [{ error: "Session not found" }.to_json]]
         end
 
+        def session_already_connected_response
+          [
+            409,
+            { "Content-Type" => "application/json" },
+            [{ error: "Conflict: Only one SSE stream is allowed per session" }.to_json],
+          ]
+        end
+
         def setup_sse_stream(session_id)
           body = create_sse_body(session_id)
 
@@ -329,17 +427,22 @@ module MCP
 
         def create_sse_body(session_id)
           proc do |stream|
-            store_stream_for_session(session_id, stream)
-            start_keepalive_thread(session_id)
+            stored = store_stream_for_session(session_id, stream)
+            start_keepalive_thread(session_id) if stored
           end
         end
 
         def store_stream_for_session(session_id, stream)
           @mutex.synchronize do
-            if @sessions[session_id]
-              @sessions[session_id][:stream] = stream
+            session = @sessions[session_id]
+            if session && !session[:stream]
+              session[:stream] = stream
             else
+              # Either session was removed, or another request already established a stream.
               stream.close
+              # `stream.close` may return a truthy value depending on the stream class.
+              # Explicitly return nil to guarantee a falsy return for callers.
+              nil
             end
           end
         end
@@ -374,6 +477,12 @@ module MCP
           )
           raise # Re-raise to exit the keepalive loop
         end
+
+        def session_expired?(session)
+          return false unless @session_idle_timeout
+
+          Process.clock_gettime(Process::CLOCK_MONOTONIC) - session[:last_active_at] > @session_idle_timeout
+        end
       end
     end
   end

data/lib/mcp/server/transports.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module MCP
+  class Server
+    module Transports
+      autoload :StdioTransport, "mcp/server/transports/stdio_transport"
+      autoload :StreamableHTTPTransport, "mcp/server/transports/streamable_http_transport"
+    end
+  end
+end

data/lib/mcp/server.rb

@@ -4,6 +4,9 @@ require_relative "../json_rpc_handler"
 require_relative "instrumentation"
 require_relative "methods"
 require_relative "logging_message_notification"
+require_relative "progress"
+require_relative "server_context"
+require_relative "server/transports"
 
 module MCP
   class ToolNotUnique < StandardError
@@ -96,6 +99,7 @@ module MCP
         Methods::INITIALIZE => method(:init),
         Methods::PING => ->(_) { {} },
         Methods::NOTIFICATIONS_INITIALIZED => ->(_) {},
+        Methods::NOTIFICATIONS_PROGRESS => ->(_) {},
         Methods::LOGGING_SET_LEVEL => method(:configure_logging_level),
 
         # No op handlers for currently unsupported methods
@@ -107,15 +111,29 @@ module MCP
       @transport = transport
     end
 
-    def handle(request)
+    # Processes a parsed JSON-RPC request and returns the response as a Hash.
+    #
+    # @param request [Hash] A parsed JSON-RPC request.
+    # @param session [ServerSession, nil] Per-connection session. Passed by
+    #   `ServerSession#handle` for session-scoped notification delivery.
+    #   When `nil`, progress and logging notifications from tool handlers are silently skipped.
+    # @return [Hash, nil] The JSON-RPC response, or `nil` for notifications.
+    def handle(request, session: nil)
       JsonRpcHandler.handle(request) do |method|
-        handle_request(request, method)
+        handle_request(request, method, session: session)
       end
     end
 
-    def handle_json(request)
+    # Processes a JSON-RPC request string and returns the response as a JSON string.
+    #
+    # @param request [String] A JSON-RPC request as a JSON string.
+    # @param session [ServerSession, nil] Per-connection session. Passed by
+    #   `ServerSession#handle_json` for session-scoped notification delivery.
+    #   When `nil`, progress and logging notifications from tool handlers are silently skipped.
+    # @return [String, nil] The JSON-RPC response as JSON, or `nil` for notifications.
+    def handle_json(request, session: nil)
       JsonRpcHandler.handle_json(request) do |method|
-        handle_request(request, method)
+        handle_request(request, method, session: session)
       end
     end
 
@@ -180,34 +198,16 @@ module MCP
       report_exception(e, { notification: "log_message" })
     end
 
-    def resources_list_handler(&block)
-      @handlers[Methods::RESOURCES_LIST] = block
-    end
-
+    # Sets a custom handler for `resources/read` requests.
+    # The block receives the parsed request params and should return resource
+    # contents. The return value is set as the `contents` field of the response.
+    #
+    # @yield [params] The request params containing `:uri`.
+    # @yieldreturn [Array<Hash>, Hash] Resource contents.
     def resources_read_handler(&block)
       @handlers[Methods::RESOURCES_READ] = block
     end
 
-    def resources_templates_list_handler(&block)
-      @handlers[Methods::RESOURCES_TEMPLATES_LIST] = block
-    end
-
-    def tools_list_handler(&block)
-      @handlers[Methods::TOOLS_LIST] = block
-    end
-
-    def tools_call_handler(&block)
-      @handlers[Methods::TOOLS_CALL] = block
-    end
-
-    def prompts_list_handler(&block)
-      @handlers[Methods::PROMPTS_LIST] = block
-    end
-
-    def prompts_get_handler(&block)
-      @handlers[Methods::PROMPTS_GET] = block
-    end
-
     private
 
     def validate!
@@ -278,11 +278,12 @@ module MCP
       end
     end
 
-    def handle_request(request, method)
+    def handle_request(request, method, session: nil)
       handler = @handlers[method]
       unless handler
         instrument_call("unsupported_method") do
-          add_instrumentation_data(client: @client) if @client
+          client = session&.client || @client
+          add_instrumentation_data(client: client) if client
         end
         return
       end
@@ -292,6 +293,8 @@ module MCP
       ->(params) {
         instrument_call(method) do
           result = case method
+          when Methods::INITIALIZE
+            init(params, session: session)
           when Methods::TOOLS_LIST
             { tools: @handlers[Methods::TOOLS_LIST].call(params) }
           when Methods::PROMPTS_LIST
@@ -302,10 +305,15 @@ module MCP
             { contents: @handlers[Methods::RESOURCES_READ].call(params) }
           when Methods::RESOURCES_TEMPLATES_LIST
             { resourceTemplates: @handlers[Methods::RESOURCES_TEMPLATES_LIST].call(params) }
+          when Methods::TOOLS_CALL
+            call_tool(params, session: session)
+          when Methods::LOGGING_SET_LEVEL
+            configure_logging_level(params, session: session)
           else
             @handlers[method].call(params)
           end
-          add_instrumentation_data(client: @client) if @client
+          client = session&.client || @client
+          add_instrumentation_data(client: client) if client
 
           result
         rescue => e
@@ -341,8 +349,14 @@ module MCP
       }.compact
     end
 
-    def init(params)
-      @client = params[:clientInfo] if params
+    def init(params, session: nil)
+      if params
+        if session
+          session.store_client_info(client: params[:clientInfo], capabilities: params[:capabilities])
+        else
+          @client = params[:clientInfo]
+        end
+      end
 
       protocol_version = params[:protocolVersion] if params
       negotiated_version = if Configuration::SUPPORTED_STABLE_PROTOCOL_VERSIONS.include?(protocol_version)
@@ -370,7 +384,7 @@ module MCP
       }.compact
     end
 
-    def configure_logging_level(request)
+    def configure_logging_level(request, session: nil)
       if capabilities[:logging].nil?
         raise RequestHandlerError.new("Server does not support logging", request, error_type: :internal_error)
       end
@@ -380,6 +394,7 @@ module MCP
         raise RequestHandlerError.new("Invalid log level #{request[:level]}", request, error_type: :invalid_params)
       end
 
+      session&.configure_logging(logging_message_notification)
       @logging_message_notification = logging_message_notification
 
       {}
@@ -389,7 +404,7 @@ module MCP
       @tools.values.map(&:to_h)
     end
 
-    def call_tool(request)
+    def call_tool(request, session: nil)
       tool_name = request[:name]
 
       tool = tools[tool_name]
@@ -419,7 +434,9 @@ module MCP
         end
       end
 
-      call_tool_with_args(tool, arguments)
+      progress_token = request.dig(:_meta, :progressToken)
+
+      call_tool_with_args(tool, arguments, server_context_with_meta(request), progress_token: progress_token, session: session)
     rescue RequestHandlerError
       raise
     rescue => e
@@ -445,7 +462,7 @@ module MCP
       prompt_args = request[:arguments]
       prompt.validate_arguments!(prompt_args)
 
-      call_prompt_template_with_args(prompt, prompt_args)
+      call_prompt_template_with_args(prompt, prompt_args, server_context_with_meta(request))
     end
 
     def list_resources(request)
@@ -488,22 +505,37 @@ module MCP
       parameters.any? { |type, name| type == :keyrest || name == :server_context }
     end
 
-    def call_tool_with_args(tool, arguments)
+    def call_tool_with_args(tool, arguments, context, progress_token: nil, session: nil)
       args = arguments&.transform_keys(&:to_sym) || {}
 
       if accepts_server_context?(tool.method(:call))
+        progress = Progress.new(notification_target: session, progress_token: progress_token)
+        server_context = ServerContext.new(context, progress: progress, notification_target: session)
         tool.call(**args, server_context: server_context).to_h
       else
         tool.call(**args).to_h
       end
     end
 
-    def call_prompt_template_with_args(prompt, args)
+    def call_prompt_template_with_args(prompt, args, server_context)
       if accepts_server_context?(prompt.method(:template))
         prompt.template(args, server_context: server_context).to_h
       else
         prompt.template(args).to_h
       end
     end
+
+    def server_context_with_meta(request)
+      meta = request[:_meta]
+      if meta && server_context.is_a?(Hash)
+        context = server_context.dup
+        context[:_meta] = meta
+        context
+      elsif meta && server_context.nil?
+        { _meta: meta }
+      else
+        server_context
+      end
+    end
   end
 end

data/lib/mcp/server_context.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module MCP
+  class ServerContext
+    def initialize(context, progress:, notification_target:)
+      @context = context
+      @progress = progress
+      @notification_target = notification_target
+    end
+
+    # Reports progress for the current tool operation.
+    # The notification is automatically scoped to the originating session.
+    #
+    # @param progress [Numeric] Current progress value.
+    # @param total [Numeric, nil] Total expected value.
+    # @param message [String, nil] Human-readable status message.
+    def report_progress(progress, total: nil, message: nil)
+      @progress.report(progress, total: total, message: message)
+    end
+
+    # Sends a log message notification scoped to the originating session.
+    #
+    # @param data [Object] The log data to send.
+    # @param level [String] Log level (e.g., `"debug"`, `"info"`, `"error"`).
+    # @param logger [String, nil] Logger name.
+    def notify_log_message(data:, level:, logger: nil)
+      return unless @notification_target
+
+      @notification_target.notify_log_message(data: data, level: level, logger: logger)
+    end
+
+    def method_missing(name, ...)
+      if @context.respond_to?(name)
+        @context.public_send(name, ...)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @context.respond_to?(name) || super
+    end
+  end
+end

data/lib/mcp/server_session.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "methods"
+
+module MCP
+  # Holds per-connection state for a single client session.
+  # Created by the transport layer; delegates request handling to the shared `Server`.
+  class ServerSession
+    attr_reader :session_id, :client, :logging_message_notification
+
+    def initialize(server:, transport:, session_id: nil)
+      @server = server
+      @transport = transport
+      @session_id = session_id
+      @client = nil
+      @client_capabilities = nil # TODO: Use for per-session capability validation.
+      @logging_message_notification = nil
+    end
+
+    def handle(request)
+      @server.handle(request, session: self)
+    end
+
+    def handle_json(request_json)
+      @server.handle_json(request_json, session: self)
+    end
+
+    # Called by `Server#init` during the initialization handshake.
+    def store_client_info(client:, capabilities: nil)
+      @client = client
+      @client_capabilities = capabilities
+    end
+
+    # Called by `Server#configure_logging_level`.
+    def configure_logging(logging_message_notification)
+      @logging_message_notification = logging_message_notification
+    end
+
+    # Sends a progress notification to this session only.
+    def notify_progress(progress_token:, progress:, total: nil, message: nil)
+      params = {
+        "progressToken" => progress_token,
+        "progress" => progress,
+        "total" => total,
+        "message" => message,
+      }.compact
+
+      send_to_transport(Methods::NOTIFICATIONS_PROGRESS, params)
+    rescue => e
+      @server.report_exception(e, notification: "progress")
+    end
+
+    # Sends a log message notification to this session only.
+    def notify_log_message(data:, level:, logger: nil)
+      effective_logging = @logging_message_notification || @server.logging_message_notification
+      return unless effective_logging&.should_notify?(level)
+
+      params = { "data" => data, "level" => level }
+      params["logger"] = logger if logger
+
+      send_to_transport(Methods::NOTIFICATIONS_MESSAGE, params)
+    rescue => e
+      @server.report_exception(e, { notification: "log_message" })
+    end
+
+    private
+
+    # TODO: When Ruby 2.7 support is dropped, replace with a direct call:
+    # `@transport.send_notification(method, params, session_id: @session_id)` and
+    # add `**` to `Transport#send_notification` and `StdioTransport#send_notification`.
+    def send_to_transport(method, params)
+      if @session_id
+        @transport.send_notification(method, params, session_id: @session_id)
+      else
+        @transport.send_notification(method, params)
+      end
+    end
+  end
+end

data/lib/mcp/tool.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+require_relative "tool/annotations"
+require_relative "tool/input_schema"
+require_relative "tool/output_schema"
+require_relative "tool/response"
+
 module MCP
   class Tool
     class << self