modelcontextprotocol/ruby-sdk
Watch
1
0
Fork
You've already forked ruby-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request #101 from 1debit/stateless

Browse source 
Add `stateless` feature to Streamable HTTP protocol
This commit is contained in:
Koichi ITO 2025-11-07 09:11:33 +09:00 • committed by GitHub
commit 400a56e83d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 179 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

7
README.md
View file

@ -126,12 +126,19 @@ Notifications follow the JSON-RPC 2.0 specification and use these method names:
- **stdio**: Notifications are sent as JSON-RPC 2.0 messages to stdout
- **Streamable HTTP**: Notifications are sent as JSON-RPC 2.0 messages over HTTP with streaming (chunked transfer or SSE)
- **Stateless Streamable HTTP**: Notifications are not supported and all calls are request/response interactions; allows for easy multi-node deployment.
#### Usage Example
```ruby
server = MCP::Server.new(name: "my_server")
# Default Streamable HTTP - session oriented
transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
# OR Stateless Streamable HTTP - session-less
transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, stateless: true)
server.transport = transport
# When tools change, notify clients

48
lib/mcp/server/transports/streamable_http_transport.rb
View file

@ -8,11 +8,13 @@ module MCP
class Server
module Transports
class StreamableHTTPTransport < Transport
def initialize(server)
super
def initialize(server, stateless: false)
super(server)
# { session_id => { stream: stream_object }
@sessions = {}
@mutex = Mutex.new
@stateless = stateless
end
def handle_request(request)
@ -24,7 +26,7 @@ module MCP
when "DELETE"
handle_delete(request)
else
[405, { "Content-Type" => "application/json" }, [{ error: "Method not allowed" }.to_json]]
method_not_allowed_response
end
end
@ -35,6 +37,9 @@ module MCP
end
def send_notification(method, params = nil, session_id: nil)
# Stateless mode doesn't support notifications
raise "Stateless mode does not support notifications" if @stateless
notification = {
jsonrpc: "2.0",
method:,
@ -119,6 +124,10 @@ module MCP
end
def handle_get(request)
if @stateless
return method_not_allowed_response
end
session_id = extract_session_id(request)
return missing_session_id_response unless session_id
@ -128,6 +137,13 @@ module MCP
end
def handle_delete(request)
success_response = [200, { "Content-Type" => "application/json" }, [{ success: true }.to_json]]
if @stateless
# Stateless mode doesn't support sessions, so we can just return a success response
return success_response
end
session_id = request.env["HTTP_MCP_SESSION_ID"]
return [
@ -137,7 +153,7 @@ module MCP
] unless session_id
cleanup_session(session_id)
[200, { "Content-Type" => "application/json" }, [{ success: true }.to_json]]
success_response
end
def cleanup_session(session_id)
@ -177,6 +193,9 @@ module MCP
end
def handle_initialization(body_string, body)
session_id = nil
unless @stateless
session_id = SecureRandom.uuid
@mutex.synchronize do
@ -184,14 +203,16 @@ module MCP
stream: nil,
}
end
end
response = @server.handle_json(body_string)
headers = {
"Content-Type" => "application/json",
"Mcp-Session-Id" => session_id,
}
headers["Mcp-Session-Id"] = session_id if session_id
[200, headers, [response]]
end
@ -200,21 +221,32 @@ module MCP
end
def handle_regular_request(body_string, session_id)
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]]
end
end
response = @server.handle_json(body_string)
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
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/")
end
def get_session_stream(session_id)
@mutex.synchronize { @sessions[session_id]&.fetch(:stream, nil) }
end
@ -236,6 +268,10 @@ module MCP
@mutex.synchronize { @sessions.key?(session_id) }
end
def method_not_allowed_response
[405, { "Content-Type" => "application/json" }, [{ error: "Method not allowed" }.to_json]]
end
def missing_session_id_response
[400, { "Content-Type" => "application/json" }, [{ error: "Missing session ID" }.to_json]]
end

122
test/mcp/server/transports/streamable_http_transport_test.rb
View file

@ -573,6 +573,128 @@ module MCP
assert_equal "Method not allowed", body["error"]
end
test "stateless mode allows requests without session IDs, responding with no session ID" do
stateless_transport = StreamableHTTPTransport.new(@server, stateless: true)
init_request = create_rack_request(
"POST",
"/",
{ "CONTENT_TYPE" => "application/json" },
{ jsonrpc: "2.0", method: "initialize", id: "init" }.to_json,
)
init_response = stateless_transport.handle_request(init_request)
assert_nil init_response[1]["Mcp-Session-Id"]
end
test "stateless mode responds without any session ID when session ID is present" do
stateless_transport = StreamableHTTPTransport.new(@server, stateless: true)
request = create_rack_request(
"POST",
"/",
{
"CONTENT_TYPE" => "application/json",
"HTTP_MCP_SESSION_ID" => "unseen_session_id",
},
{ jsonrpc: "2.0", method: "ping", id: "123" }.to_json,
)
response = stateless_transport.handle_request(request)
assert_equal 200, response[0]
assert_equal(
{
"Content-Type" => "application/json",
},
response[1],
)
body = JSON.parse(response[2][0])
assert_equal "2.0", body["jsonrpc"]
assert_equal "123", body["id"]
end
test "stateless mode responds with 405 when SSE is requested" do
stateless_transport = StreamableHTTPTransport.new(@server, stateless: true)
get_request = create_rack_request(
"GET",
"/",
{
"CONTENT_TYPE" => "application/json,text/event-stream",
},
)
response = stateless_transport.handle_request(get_request)
assert_equal 405, response[0]
assert_equal({ "Content-Type" => "application/json" }, response[1])
body = JSON.parse(response[2][0])
assert_equal "Method not allowed", body["error"]
end
test "stateless mode silently responds with success to session DELETE when session ID is not present" do
stateless_transport = StreamableHTTPTransport.new(@server, stateless: true)
delete_request = create_rack_request(
"DELETE",
"/",
{},
)
response = stateless_transport.handle_request(delete_request)
assert_equal 200, response[0]
assert_equal({ "Content-Type" => "application/json" }, response[1])
body = JSON.parse(response[2][0])
assert body["success"]
end
test "stateless mode silently responds with success to session DELETE when session ID is provided" do
stateless_transport = StreamableHTTPTransport.new(@server, stateless: true)
delete_request = create_rack_request(
"DELETE",
"/",
{ "HTTP_MCP_SESSION_ID" => "session_id" },
)
response = stateless_transport.handle_request(delete_request)
assert_equal 200, response[0]
assert_equal({ "Content-Type" => "application/json" }, response[1])
body = JSON.parse(response[2][0])
assert body["success"]
end
test "stateless mode does not support server-sent events" do
stateless_transport = StreamableHTTPTransport.new(@server, stateless: true)
e = assert_raises(RuntimeError) do
stateless_transport.send_notification(
"test_notification",
{ message: "Hello" },
session_id: "some_session_id",
)
end
assert_equal("Stateless mode does not support notifications", e.message)
end
test "stateless mode responds with 202 when client sends a notification/initialized request" do
stateless_transport = StreamableHTTPTransport.new(@server, stateless: true)
request = create_rack_request(
"POST",
"/",
{ "CONTENT_TYPE" => "application/json" },
{ jsonrpc: "2.0", method: "notifications/initialized" }.to_json,
)
response = stateless_transport.handle_request(request)
assert_equal 202, response[0]
assert_empty(response[1])
body = response[2][0]
assert_nil(body)
end
test "handle post request with a standard error" do
request = create_rack_request(
"POST",