mcp 0.9.2 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0f26c1a29af5a799a750d9ad00a224f39d24638a9ad267a540313f06da674ed
-  data.tar.gz: d340e2c1f6492f74a28c6dabc6a04575285269e13a2352e3f747195d4dac1527
+  metadata.gz: 29a39b8c5bb27a2fcdc8d084dce2cd79dfada5981a18d156bc1de78604035b2e
+  data.tar.gz: d969675cb0bb08b9ee3971a9bd90891767c7b28d68fe60579cf4857a06ff3680
 SHA512:
-  metadata.gz: 7f428407e35305f1cb5a087bd7abb708df12d17abe6cb66f335c8dc2d82d1020407942dd36ad3cb200377e7d60783d87a72bab765b202ae8426cb267f5d3f46a
-  data.tar.gz: 49d835de35b9c6c124d99ffe82561a5f7554901d43971afbb82adfb31fe13d0d6d1b6782d460d9b861b6924cc43705266cb09e5de3afd9249b7caa68634fff63
+  metadata.gz: 3ff992068b54cc35acd43bc9e93edb3959f270a19eedf52540748344f2a94488829cbfec65dedb2772d67dd883f7536523af25d6419ded2cc71944359ff2d016
+  data.tar.gz: 0f716e3f54ca10619f95787c65dfe01fecc2356474ddf2909dfb2918f544f3fc8aa2a1a798836b2c556a9178ad842472fd79820ad83e96e855e4ca1ded4f5d8b

data/README.md

@@ -113,9 +113,17 @@ The server provides the following notification methods:
 - `notify_tools_list_changed` - Send a notification when the tools list changes
 - `notify_prompts_list_changed` - Send a notification when the prompts list changes
 - `notify_resources_list_changed` - Send a notification when the resources list changes
-- `notify_progress` - Send a progress notification for long-running operations
 - `notify_log_message` - Send a structured logging notification message
 
+#### Session Scoping
+
+When using Streamable HTTP transport with multiple clients, each client connection gets its own session. Notifications are scoped as follows:
+
+- **`report_progress`** and **`notify_log_message`** called via `server_context` inside a tool handler are automatically sent only to the requesting client.
+No extra configuration is needed.
+- **`notify_tools_list_changed`**, **`notify_prompts_list_changed`**, and **`notify_resources_list_changed`** are always broadcast to all connected clients,
+as they represent server-wide state changes. These should be called on the `server` instance directly.
+
 #### Notification Format
 
 Notifications follow the JSON-RPC 2.0 specification and use these method names:
@@ -169,24 +177,10 @@ The `server_context.report_progress` method accepts:
 - `total:` (optional) — total expected value, so clients can display a percentage
 - `message:` (optional) — human-readable status message
 
-#### Server-Side: Direct `notify_progress` Usage
-
-You can also call `notify_progress` directly on the server instance:
-
-```ruby
-server.notify_progress(
-  progress_token: "token-123",
-  progress: 50,
-  total: 100,        # optional
-  message: "halfway" # optional
-)
-```
-
 **Key Features:**
 
 - Tools report progress via `server_context.report_progress`
 - `report_progress` is a no-op when no `progressToken` was provided by the client
-- `notify_progress` is a no-op when no transport is configured
 - Supports both numeric and string progress tokens
 
 ### Logging
@@ -293,6 +287,14 @@ Set `stateless: true` in `MCP::Server::Transports::StreamableHTTPTransport.new`
 transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, stateless: true)
 ```
 
+By default, sessions do not expire. To mitigate session hijacking risks, you can set a `session_idle_timeout` (in seconds).
+When configured, sessions that receive no HTTP requests for this duration are automatically expired and cleaned up:
+
+```ruby
+# Session timeout of 30 minutes
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, session_idle_timeout: 1800)
+```
+
 ### Unsupported Features (to be implemented in future versions)
 
 - Resource subscriptions

data/lib/mcp/progress.rb

@@ -2,15 +2,16 @@
 
 module MCP
   class Progress
-    def initialize(server:, progress_token:)
-      @server = server
+    def initialize(notification_target:, progress_token:)
+      @notification_target = notification_target
       @progress_token = progress_token
     end
 
     def report(progress, total: nil, message: nil)
       return unless @progress_token
+      return unless @notification_target
 
-      @server.notify_progress(
+      @notification_target.notify_progress(
         progress_token: @progress_token,
         progress: progress,
         total: total,

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

@@ -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

@@ -8,18 +8,30 @@ 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,9 @@ 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)
@@ -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,16 +327,27 @@ module MCP
         end
 
         def handle_regular_request(body_string, session_id)
+          server_session = nil
+          stream = nil
+
           unless @stateless
-            if session_id && !session_exists?(session_id)
-              return session_not_found_response
+            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)
@@ -273,6 +356,22 @@ module MCP
           end
         end
 
+        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)
           @mutex.synchronize { @sessions[session_id]&.fetch(:stream, nil) }
         end
@@ -378,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.rb

@@ -111,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
 
@@ -172,21 +186,6 @@ module MCP
       report_exception(e, { notification: "resources_list_changed" })
     end
 
-    def notify_progress(progress_token:, progress:, total: nil, message: nil)
-      return unless @transport
-
-      params = {
-        "progressToken" => progress_token,
-        "progress" => progress,
-        "total" => total,
-        "message" => message,
-      }.compact
-
-      @transport.send_notification(Methods::NOTIFICATIONS_PROGRESS, params)
-    rescue => e
-      report_exception(e, notification: "progress")
-    end
-
     def notify_log_message(data:, level:, logger: nil)
       return unless @transport
       return unless logging_message_notification&.should_notify?(level)
@@ -199,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!
@@ -297,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
@@ -311,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
@@ -321,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
@@ -360,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)
@@ -389,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
@@ -399,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
 
       {}
@@ -408,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]
@@ -440,7 +436,7 @@ module MCP
 
       progress_token = request.dig(:_meta, :progressToken)
 
-      call_tool_with_args(tool, arguments, server_context_with_meta(request), progress_token: progress_token)
+      call_tool_with_args(tool, arguments, server_context_with_meta(request), progress_token: progress_token, session: session)
     rescue RequestHandlerError
       raise
     rescue => e
@@ -509,12 +505,12 @@ module MCP
       parameters.any? { |type, name| type == :keyrest || name == :server_context }
     end
 
-    def call_tool_with_args(tool, arguments, context, progress_token: nil)
+    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(server: self, progress_token: progress_token)
-        server_context = ServerContext.new(context, progress: progress)
+        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

data/lib/mcp/server_context.rb

@@ -2,15 +2,33 @@
 
 module MCP
   class ServerContext
-    def initialize(context, progress:)
+    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, ...)

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/transport.rb

@@ -36,8 +36,8 @@ module MCP
       send_response(response) if response
     end
 
-    # Send a notification to the client
-    # Returns true if the notification was sent successfully
+    # Send a notification to the client.
+    # Returns true if the notification was sent successfully.
     def send_notification(method, params = nil)
       raise NotImplementedError, "Subclasses must implement send_notification"
     end

data/lib/mcp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MCP
-  VERSION = "0.9.2"
+  VERSION = "0.10.0"
 end

data/lib/mcp.rb

@@ -15,6 +15,7 @@ module MCP
   autoload :Resource, "mcp/resource"
   autoload :ResourceTemplate, "mcp/resource_template"
   autoload :Server, "mcp/server"
+  autoload :ServerSession, "mcp/server_session"
   autoload :Tool, "mcp/tool"
 
   class << self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.10.0
 platform: ruby
 authors:
 - Model Context Protocol
@@ -60,6 +60,7 @@ files:
 - lib/mcp/server/transports/stdio_transport.rb
 - lib/mcp/server/transports/streamable_http_transport.rb
 - lib/mcp/server_context.rb
+- lib/mcp/server_session.rb
 - lib/mcp/string_utils.rb
 - lib/mcp/tool.rb
 - lib/mcp/tool/annotations.rb
@@ -75,7 +76,7 @@ licenses:
 - Apache-2.0
 metadata:
   allowed_push_host: https://rubygems.org
-  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v0.9.2
+  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v0.10.0
   homepage_uri: https://github.com/modelcontextprotocol/ruby-sdk
   source_code_uri: https://github.com/modelcontextprotocol/ruby-sdk
   bug_tracker_uri: https://github.com/modelcontextprotocol/ruby-sdk/issues