Support sampling/createMessage per MCP specification

## Motivation and Context

The MCP specification defines `sampling/createMessage` to request LLM completions from the client.
The Ruby SDK did not yet support server-to-client requests,
so the server had no way to ask the client to sample an LLM.
This caused the `tools-call-sampling` conformance test to fail.

This adds `Server#create_sampling_message` to send a `sampling/createMessage` request
to the client via the transport layer. The method validates that the client declared
the `sampling` capability during initialization, and optionally checks the
`sampling.tools` capability when tools or tool_choice parameters are provided.

On the transport side, `Transport#send_request` is introduced as an abstract method,
with implementations in both `StdioTransport` and `StreamableHTTPTransport`.
Each transport assigns a unique request ID, sends the JSON-RPC request to the client,
and blocks until the client responds.

Client capabilities are stored per session via `ServerSession`, so validation is scoped
to the originating client. `ServerSession#create_sampling_message` uses
`build_sampling_params` for capability validation and sends the request directly through
the transport with the session ID, following the same pattern as `notify_progress`.

`Server#create_sampling_message` is the public API for single-client transports
(e.g., StdioTransport).

For multi-client transports (e.g., StreamableHTTPTransport),
`ServerSession#create_sampling_message` must be used to route requests to the correct client.
Tools using `server_context.create_sampling_message` automatically route to the correct session
regardless of transport.

`StreamableHTTPTransport#send_request` requires `session_id` to prevent broadcasting sampling requests
to all connected clients. Missing or invalid session IDs raise explicit errors instead of silently failing.

The `include_context` parameter is soft-deprecated in the MCP specification but is included
for compatibility with existing clients that declare the `sampling.context` capability.
Python and TypeScript SDKs also retain this parameter.

Ref: https://modelcontextprotocol.io/specification/latest/server/utilities/sampling

## How Has This Been Tested?

Added comprehensive tests in `test/mcp/server_sampling_test.rb` covering required and optional parameters,
capability validation, error handling, nil-param omission, per-session capability isolation,
and HTTP init capability scoping.

Added transport tests in `test/mcp/server/transports/stdio_transport_test.rb` and
`test/mcp/server/transports/streamable_http_transport_test.rb` for `send_request` round-trip behavior,
error responses, stateless mode rejection, missing session_id, invalid session_id, and no-active-stream error.

Conformance: `tools-call-sampling` is removed from expected failures. The conformance server's `TestSampling`
tool now calls `server_context.create_sampling_message` instead of returning a stub error.

This aligns the Ruby SDK with the MCP specification and other SDK implementations.

## Breaking Changes

None for end users.
`Transport#send_request` is a new abstract method. `ServerSession#create_sampling_message` is a new method.
This commit is contained in:
Koichi ITO 2026-03-29 16:05:10 +09:00
commit da5f9225ac
2 changed files with 1449 additions and 13 deletions

View file

@ -151,6 +151,247 @@ module MCP
$stdout = original_stdout
end
end
test "send_request sends request to stdout and waits for response" do
reader, writer = IO.pipe
output = StringIO.new
original_stdin = $stdin
original_stdout = $stdout
begin
$stdin = reader
$stdout = output
@transport.instance_variable_set(:@open, true)
# Send response from client in a thread.
Thread.new do
sleep(0.05) # Wait for request to be written to `StringIO`.
request = JSON.parse(output.string.lines.first, symbolize_names: true)
response = {
jsonrpc: "2.0",
id: request[:id],
result: { content: "test response" },
}
writer.puts(response.to_json)
writer.flush
end
result = @transport.send_request("test/method", { param: "value" })
assert_equal({ content: "test response" }, result)
# Verify request was sent.
request = JSON.parse(output.string.lines.first, symbolize_names: true)
assert_equal("2.0", request[:jsonrpc])
assert_equal("test/method", request[:method])
assert_equal({ param: "value" }, request[:params])
assert(request[:id])
ensure
$stdin = original_stdin
$stdout = original_stdout
begin
writer.close
rescue
nil
end
begin
reader.close
rescue
nil
end
end
end
test "send_request raises on error response from client" do
reader, writer = IO.pipe
output = StringIO.new
original_stdin = $stdin
original_stdout = $stdout
begin
$stdin = reader
$stdout = output
@transport.instance_variable_set(:@open, true)
Thread.new do
sleep(0.05) # Wait for request to be written to `StringIO`.
request = JSON.parse(output.string.lines.first, symbolize_names: true)
error_response = {
jsonrpc: "2.0",
id: request[:id],
error: { code: -1, message: "User rejected sampling request" },
}
writer.puts(error_response.to_json)
writer.flush
end
error = assert_raises(StandardError) do
@transport.send_request("sampling/createMessage", { messages: [] })
end
assert_equal("Client returned an error for sampling/createMessage request (code: -1): User rejected sampling request", error.message)
ensure
$stdin = original_stdin
$stdout = original_stdout
begin
writer.close
rescue
nil
end
begin
reader.close
rescue
nil
end
end
end
test "send_request does not double-report intentional raises via exception_reporter" do
reader, writer = IO.pipe
output = StringIO.new
original_stdin = $stdin
original_stdout = $stdout
reported_errors = []
original_reporter = MCP.configuration.exception_reporter
begin
MCP.configuration.exception_reporter = ->(e, ctx) { reported_errors << [e, ctx] }
$stdin = reader
$stdout = output
@transport.instance_variable_set(:@open, true)
Thread.new do
sleep(0.05) # Wait for request to be written to `StringIO`.
request = JSON.parse(output.string.lines.first, symbolize_names: true)
error_response = {
jsonrpc: "2.0",
id: request[:id],
error: { code: -1, message: "rejected" },
}
writer.puts(error_response.to_json)
writer.flush
end
assert_raises(StandardError) do
@transport.send_request("sampling/createMessage", { messages: [] })
end
assert_empty(reported_errors)
ensure
MCP.configuration.exception_reporter = original_reporter
$stdin = original_stdin
$stdout = original_stdout
begin
writer.close
rescue
nil
end
begin
reader.close
rescue
nil
end
end
end
test "send_request processes interleaved requests via session" do
reader, writer = IO.pipe
output = StringIO.new
original_stdin = $stdin
original_stdout = $stdout
begin
$stdin = reader
$stdout = output
@transport.instance_variable_set(:@open, true)
# Initialize a session so @session is set.
session = MCP::ServerSession.new(server: @server, transport: @transport)
@transport.instance_variable_set(:@session, session)
Thread.new do
sleep(0.05) # Wait for request to be written to `StringIO`.
request = JSON.parse(output.string.lines.first, symbolize_names: true)
# Send an interleaved ping request before the response.
ping = { jsonrpc: "2.0", method: "ping", id: "ping-1" }
writer.puts(ping.to_json)
writer.flush
sleep(0.05) # Wait for the ping to be processed.
# Then send the actual response.
response = {
jsonrpc: "2.0",
id: request[:id],
result: { content: "done" },
}
writer.puts(response.to_json)
writer.flush
end
result = @transport.send_request("test/method", { param: "value" })
assert_equal({ content: "done" }, result)
# Verify the interleaved ping was handled (response sent to output).
lines = output.string.lines
ping_response = lines.find { |l| l.include?("ping-1") }
assert(ping_response, "Interleaved ping request should have been handled")
ensure
$stdin = original_stdin
$stdout = original_stdout
begin
writer.close
rescue
nil
end
begin
reader.close
rescue
nil
end
end
end
test "send_request raises when transport is closed while waiting" do
reader, writer = IO.pipe
output = StringIO.new
original_stdin = $stdin
original_stdout = $stdout
begin
$stdin = reader
$stdout = output
@transport.instance_variable_set(:@open, true)
# Close transport while waiting for response.
Thread.new do
sleep(0.05) # Wait for request to be written to `StringIO`.
@transport.instance_variable_set(:@open, false)
writer.close
end
error = assert_raises(RuntimeError) do
@transport.send_request("sampling/createMessage", { messages: [] })
end
assert_equal("Transport closed while waiting for response to sampling/createMessage request.", error.message)
ensure
$stdin = original_stdin
$stdout = original_stdout
begin
writer.close
rescue IOError
nil
end
begin
reader.close
rescue IOError
nil
end
end
end
end
end
end

View file

@ -1395,6 +1395,294 @@ module MCP
assert_equal "Internal server error", body["error"]
end
test "send_request raises error in stateless mode" do
stateless_transport = StreamableHTTPTransport.new(@server, stateless: true)
error = assert_raises(RuntimeError) do
stateless_transport.send_request("sampling/createMessage", { "messages" => [] })
end
assert_equal("Stateless mode does not support server-to-client requests.", error.message)
end
test "send_request raises error when session_id is not provided" do
error = assert_raises(RuntimeError) do
@transport.send_request("sampling/createMessage", { "messages" => [] })
end
assert_equal("session_id is required for server-to-client requests.", error.message)
end
test "send_request raises error when session is not found" do
error = assert_raises(RuntimeError) do
@transport.send_request("sampling/createMessage", { "messages" => [] }, session_id: "nonexistent")
end
assert_equal("Session not found: nonexistent.", error.message)
end
test "send_request raises error when no active SSE streams" do
# Create session but do NOT connect SSE.
init_request = create_rack_request(
"POST",
"/",
{ "CONTENT_TYPE" => "application/json" },
{ jsonrpc: "2.0", method: "initialize", id: "init" }.to_json,
)
init_response = @transport.handle_request(init_request)
session_id = init_response[1]["Mcp-Session-Id"]
error = assert_raises(RuntimeError) do
@transport.send_request("sampling/createMessage", { "messages" => [] }, session_id: session_id)
end
assert_equal("No active SSE stream for sampling/createMessage request.", error.message)
end
test "send_request sends via SSE and waits for response" do
# Create session.
init_request = create_rack_request(
"POST",
"/",
{ "CONTENT_TYPE" => "application/json" },
{ jsonrpc: "2.0", method: "initialize", id: "init" }.to_json,
)
init_response = @transport.handle_request(init_request)
session_id = init_response[1]["Mcp-Session-Id"]
# Connect SSE.
io = StringIO.new
get_request = create_rack_request(
"GET",
"/",
{ "HTTP_MCP_SESSION_ID" => session_id },
)
response = @transport.handle_request(get_request)
response[2].call(io) if response[2].is_a?(Proc)
sleep(0.1) # Give the stream time to set up.
# Send request in background.
result_queue = Queue.new
Thread.new do
result = @transport.send_request(
"sampling/createMessage",
{ messages: [{ role: "user", content: { type: "text", text: "Hello" } }], maxTokens: 100 },
session_id: session_id,
)
result_queue.push(result)
end
sleep(0.1) # Wait for the request to be sent.
# Verify request was sent to stream.
io.rewind
output = io.read
assert_includes output, "sampling/createMessage"
# Parse the sent request to get its ID.
data_lines = output.lines.select { |line| line.start_with?("data: ") }
request_data = JSON.parse(data_lines.first.sub("data: ", ""))
request_id = request_data["id"]
# Simulate client response.
client_response = create_rack_request(
"POST",
"/",
{
"CONTENT_TYPE" => "application/json",
"HTTP_MCP_SESSION_ID" => session_id,
},
{
jsonrpc: "2.0",
id: request_id,
result: { role: "assistant", content: { type: "text", text: "Hi there" } },
}.to_json,
)
@transport.handle_request(client_response)
# Get result.
result = result_queue.pop
assert_equal "assistant", result[:role]
assert_equal "Hi there", result[:content][:text]
end
test "send_request ignores response from wrong session" do
# Create two sessions.
init_a = create_rack_request(
"POST",
"/",
{ "CONTENT_TYPE" => "application/json" },
{ jsonrpc: "2.0", method: "initialize", id: "init-a" }.to_json,
)
resp_a = @transport.handle_request(init_a)
session_a = resp_a[1]["Mcp-Session-Id"]
init_b = create_rack_request(
"POST",
"/",
{ "CONTENT_TYPE" => "application/json" },
{ jsonrpc: "2.0", method: "initialize", id: "init-b" }.to_json,
)
resp_b = @transport.handle_request(init_b)
session_b = resp_b[1]["Mcp-Session-Id"]
# Connect SSE for session A.
io_a = StringIO.new
get_a = create_rack_request("GET", "/", { "HTTP_MCP_SESSION_ID" => session_a })
response_a = @transport.handle_request(get_a)
response_a[2].call(io_a) if response_a[2].is_a?(Proc)
sleep(0.1) # Give the stream time to set up.
# Send sampling request targeting session A.
result_queue = Queue.new
Thread.new do
result = @transport.send_request(
"sampling/createMessage",
{ messages: [{ role: "user", content: { type: "text", text: "Hello" } }], maxTokens: 100 },
session_id: session_a,
)
result_queue.push(result)
end
sleep(0.1) # Wait for the request to be sent.
# Get the request ID from session A's stream.
io_a.rewind
data_lines = io_a.read.lines.select { |line| line.start_with?("data: ") }
request_data = JSON.parse(data_lines.first.sub("data: ", ""))
request_id = request_data["id"]
# Session B tries to respond (cross-session injection attempt).
cross_session_response = create_rack_request(
"POST",
"/",
{ "CONTENT_TYPE" => "application/json", "HTTP_MCP_SESSION_ID" => session_b },
{ jsonrpc: "2.0", id: request_id, result: { role: "assistant", content: { type: "text", text: "injected" } } }.to_json,
)
@transport.handle_request(cross_session_response)
# The request should still be pending (not resolved by wrong session).
assert_empty(result_queue, "Response from wrong session should be ignored")
# Now send the correct response from session A.
correct_response = create_rack_request(
"POST",
"/",
{ "CONTENT_TYPE" => "application/json", "HTTP_MCP_SESSION_ID" => session_a },
{ jsonrpc: "2.0", id: request_id, result: { role: "assistant", content: { type: "text", text: "correct" } } }.to_json,
)
@transport.handle_request(correct_response)
result = result_queue.pop
assert_equal "correct", result[:content][:text]
end
test "send_request raises on error response from client" do
# Create session.
init_request = create_rack_request(
"POST",
"/",
{ "CONTENT_TYPE" => "application/json" },
{ jsonrpc: "2.0", method: "initialize", id: "init" }.to_json,
)
init_response = @transport.handle_request(init_request)
session_id = init_response[1]["Mcp-Session-Id"]
# Connect SSE.
io = StringIO.new
get_request = create_rack_request(
"GET",
"/",
{ "HTTP_MCP_SESSION_ID" => session_id },
)
response = @transport.handle_request(get_request)
response[2].call(io) if response[2].is_a?(Proc)
sleep(0.1) # Give the stream time to set up.
error_queue = Queue.new
Thread.new do
@transport.send_request("sampling/createMessage", { messages: [] }, session_id: session_id)
rescue => e
error_queue.push(e)
end
sleep(0.1) # Wait for the request to be sent.
# Get request ID from stream.
io.rewind
data_lines = io.read.lines.select { |line| line.start_with?("data: ") }
request_data = JSON.parse(data_lines.first.sub("data: ", ""))
request_id = request_data["id"]
# Send error response.
error_response = create_rack_request(
"POST",
"/",
{
"CONTENT_TYPE" => "application/json",
"HTTP_MCP_SESSION_ID" => session_id,
},
{
jsonrpc: "2.0",
id: request_id,
error: { code: -1, message: "User rejected" },
}.to_json,
)
@transport.handle_request(error_response)
error = error_queue.pop
assert_kind_of StandardError, error
assert_equal("Client returned an error for sampling/createMessage request (code: -1): User rejected", error.message)
end
test "send_request unblocks when session is cleaned up" do
# Create session.
init_request = create_rack_request(
"POST",
"/",
{ "CONTENT_TYPE" => "application/json" },
{ jsonrpc: "2.0", method: "initialize", id: "init" }.to_json,
)
init_response = @transport.handle_request(init_request)
session_id = init_response[1]["Mcp-Session-Id"]
# Connect SSE.
io = StringIO.new
get_request = create_rack_request(
"GET",
"/",
{ "HTTP_MCP_SESSION_ID" => session_id },
)
response = @transport.handle_request(get_request)
response[2].call(io) if response[2].is_a?(Proc)
sleep(0.1) # Give the stream time to set up.
error_queue = Queue.new
Thread.new do
@transport.send_request("sampling/createMessage", { messages: [] }, session_id: session_id)
rescue => e
error_queue.push(e)
end
sleep(0.1) # Wait for the request to be sent.
# Delete the session to trigger cleanup (simulates client disconnect).
delete_request = create_rack_request(
"DELETE",
"/",
{ "HTTP_MCP_SESSION_ID" => session_id },
)
@transport.handle_request(delete_request)
error = error_queue.pop
assert_kind_of RuntimeError, error
assert_equal("SSE session closed while waiting for sampling/createMessage response.", error.message)
end
test "POST notifications/initialized returns 202 with no body" do
# Create a session first (optional for notification, but keep consistent with flow)
init_request = create_rack_request(
@ -1821,6 +2109,45 @@ module MCP
assert_equal([], response[2])
end
test "POST response without session ID returns 400" do
request = create_rack_request(
"POST",
"/",
{ "CONTENT_TYPE" => "application/json" },
{ jsonrpc: "2.0", result: "success", id: "123" }.to_json,
)
response = @transport.handle_request(request)
assert_equal 400, response[0]
body = JSON.parse(response[2][0])
assert_equal "Missing session ID", body["error"]
end
test "POST response with invalid session ID returns 404" do
init_request = create_rack_request(
"POST",
"/",
{ "CONTENT_TYPE" => "application/json" },
{ jsonrpc: "2.0", method: "initialize", id: "init" }.to_json,
)
@transport.handle_request(init_request)
request = create_rack_request(
"POST",
"/",
{
"CONTENT_TYPE" => "application/json",
"HTTP_MCP_SESSION_ID" => "invalid-session-id",
},
{ jsonrpc: "2.0", result: "success", id: "123" }.to_json,
)
response = @transport.handle_request(request)
assert_equal 404, response[0]
body = JSON.parse(response[2][0])
assert_equal "Session not found", body["error"]
end
test "handle_regular_request returns 404 for unknown session_id" do
request = create_rack_request(
"POST",