mcp 0.7.0 → 0.10.0

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "../../transport"
 require "json"
+require_relative "../../transport"
 
 module MCP
   class Server
@@ -10,17 +10,19 @@ module MCP
         STATUS_INTERRUPTED = Signal.list["INT"] + 128
 
         def initialize(server)
-          @server = server
+          super(server)
           @open = false
+          @session = nil
           $stdin.set_encoding("UTF-8")
           $stdout.set_encoding("UTF-8")
-          super
         end
 
         def open
           @open = true
+          @session = ServerSession.new(server: @server, transport: self)
           while @open && (line = $stdin.gets)
-            handle_json_request(line.strip)
+            response = @session.handle_json(line.strip)
+            send_response(response) if response
           end
         rescue Interrupt
           warn("\nExiting...")

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

@@ -1,24 +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"]
@@ -34,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
@@ -55,10 +71,15 @@ 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
-              rescue IOError, Errno::EPIPE => e
+              rescue *STREAM_WRITE_ERRORS => e
                 MCP.configuration.exception_reporter.call(
                   e,
                   { session_id: session_id, error: "Failed to send notification" },
@@ -74,10 +95,15 @@ 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
-                rescue IOError, Errno::EPIPE => e
+                rescue *STREAM_WRITE_ERRORS => e
                   MCP.configuration.exception_reporter.call(
                     e,
                     { session_id: sid, error: "Failed to send notification" },
@@ -96,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")
@@ -119,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 })
@@ -140,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
@@ -153,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
 
@@ -192,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?
 
@@ -228,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",
@@ -255,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)
@@ -288,8 +379,8 @@ module MCP
         def send_response_to_stream(stream, response, session_id)
           message = JSON.parse(response)
           send_to_stream(stream, message)
-          [200, { "Content-Type" => "application/json" }, [{ accepted: true }.to_json]]
-        rescue IOError, Errno::EPIPE => e
+          handle_accepted
+        rescue *STREAM_WRITE_ERRORS => e
           MCP.configuration.exception_reporter.call(
             e,
             { session_id: session_id, error: "Stream closed during response" },
@@ -314,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)
 
@@ -328,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
@@ -366,13 +470,19 @@ module MCP
               send_ping_to_stream(@sessions[session_id][:stream])
             end
           end
-        rescue IOError, Errno::EPIPE => e
+        rescue *STREAM_WRITE_ERRORS => e
           MCP.configuration.exception_reporter.call(
             e,
             { session_id: session_id, error: "Stream closed" },
           )
           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,26 +99,41 @@ 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
-        Methods::RESOURCES_SUBSCRIBE => ->(_) {},
-        Methods::RESOURCES_UNSUBSCRIBE => ->(_) {},
-        Methods::COMPLETION_COMPLETE => ->(_) {},
+        Methods::RESOURCES_SUBSCRIBE => ->(_) { {} },
+        Methods::RESOURCES_UNSUBSCRIBE => ->(_) { {} },
+        Methods::COMPLETION_COMPLETE => ->(_) { { completion: { values: [], hasMore: false } } },
         Methods::ELICITATION_CREATE => ->(_) {},
       }
       @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!
@@ -219,6 +219,14 @@ module MCP
           message = "Error occurred in server_info. `description` is not supported in protocol version 2025-06-18 or earlier"
           raise ArgumentError, message
         end
+
+        tools_with_ref = @tools.each_with_object([]) do |(tool_name, tool), names|
+          names << tool_name if schema_contains_ref?(tool.input_schema_value.to_h)
+        end
+        unless tools_with_ref.empty?
+          message = "Error occurred in #{tools_with_ref.join(", ")}. `$ref` in input schemas is supported by protocol version 2025-11-25 or higher"
+          raise ArgumentError, message
+        end
       end
 
       if @configuration.protocol_version <= "2025-03-26"
@@ -259,11 +267,23 @@ module MCP
       raise ToolNotUnique, duplicated_tool_names unless duplicated_tool_names.empty?
     end
 
-    def handle_request(request, method)
+    def schema_contains_ref?(schema)
+      case schema
+      when Hash
+        schema.any? { |key, value| key.to_s == "$ref" || schema_contains_ref?(value) }
+      when Array
+        schema.any? { |element| schema_contains_ref?(element) }
+      else
+        false
+      end
+    end
+
+    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
@@ -273,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
@@ -283,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
@@ -322,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)
@@ -351,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
@@ -361,21 +394,24 @@ 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
+
+      {}
     end
 
     def list_tools(request)
       @tools.values.map(&:to_h)
     end
 
-    def call_tool(request)
+    def call_tool(request, session: nil)
       tool_name = request[:name]
 
       tool = tools[tool_name]
       unless tool
         add_instrumentation_data(tool_name: tool_name, error: :tool_not_found)
 
-        return error_tool_response("Tool not found: #{tool_name}")
+        raise RequestHandlerError.new("Tool not found: #{tool_name}", request, error_type: :invalid_params)
       end
 
       arguments = request[:arguments] || {}
@@ -398,7 +434,11 @@ 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
       report_exception(e, request: request)
 
@@ -422,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)
@@ -465,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