Introduce ServerSession for per-connection state

## Motivation and Context

The Ruby SDK uses a 1-Server-to-many-sessions model where session-specific state
(`@client`, `@logging_message_notification`) is stored on the shared `Server` instance.
This causes the last client to connect to overwrite state for all sessions,
and requires `session_id` to be threaded through method signatures for session-scoped notifications.

The Python SDK avoids this by creating a `ServerSession` per connection that wraps a shared `Server`.
Each session holds its own state and naturally scopes notifications through its own stream.

### Changes

- Added `MCP::ServerSession` class holding per-session state: client info,
  logging configuration, and a `transport` reference for session-scoped
  notification delivery.
- `StreamableHTTPTransport#handle_initialization` creates a `ServerSession`
  per `initialize` request and stores it in the session hash.
- `handle_regular_request` routes requests through the session's
  `ServerSession` instead of the shared `Server` directly.
- `Server#handle` and `Server#handle_json` accept an optional `session:`
  keyword (`ServerSession` instance).
- `Server#init` stores client info on the session when available.
- `Server#configure_logging_level` stores logging config on the session.
- `ServerContext` and `Progress` accept a `notification_target:` which
  can be either a `ServerSession` (session-scoped) or a `Server` (broadcast).
  No `session_id:` parameter needed.
- `ServerContext#notify_progress` and `#notify_log_message` delegate to
  the `notification_target` without `session_id` threading.
- `StdioTransport` creates a single `ServerSession` on `open`,
  making the session model transparent across both transports.

### Design Decision

This follows the Python SDK's "shared `Server` + per-connection `Session`" pattern.
The `Server` holds configuration (tools, prompts, resources, handlers).
Each `ServerSession` holds per-connection state (client info, logging level, stream writer).
Notifications from `ServerSession` go only to that session's stream.

## How Has This Been Tested?

All existing tests pass. All conformance tests pass. Added tests verifying:

- Session-scoped log notification is sent only to the originating session.
- Session-scoped progress notification is sent only to the originating session.
- Each session stores its own client info independently.
- Each session stores its own logging level independently.
- `StdioTransport#open` creates a `ServerSession` and stores client info on it.

## Breaking Change

None for end users.

The public API (`Server.new`, `define_tool`,`server_context.report_progress`,
`server_context.notify_log_message`, etc.) is unchanged. The following internal API
changes affect only SDK internals:

- `ServerContext.new` now requires `notification_target:` instead of just`progress:`.
- `Progress.new` now takes `notification_target:` instead of `server:`.
- `Server#handle` and `Server#handle_json` accept an optional `session:` keyword.
This commit is contained in:
Koichi ITO 2026-03-26 00:15:30 +09:00
commit 719e5e7fee
2 changed files with 563 additions and 63 deletions

View file

@ -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...")

View file

@ -10,7 +10,7 @@ module MCP
class StreamableHTTPTransport < Transport
def initialize(server, stateless: false)
super(server)
# { session_id => { stream: stream_object }
# Maps `session_id` to `{ stream: stream_object, server_session: ServerSession }`.
@sessions = {}
@mutex = Mutex.new
@ -228,18 +228,25 @@ 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,
}
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 +262,24 @@ module MCP
end
def handle_regular_request(body_string, session_id)
unless @stateless
if session_id && !session_exists?(session_id)
return session_not_found_response
server_session = nil
stream = nil
if session_id && !@stateless
@mutex.synchronize do
session = @sessions[session_id]
return session_not_found_response unless session
server_session = session[:server_session]
stream = session[:stream]
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)