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

Remove Server#create_sampling_message direct call

Browse source 
## Motivation and Context

Sampling is a one-to-one request/response interaction between a server and a specific client.
`Server#create_sampling_message` does not scope requests to a specific session, which could
lead to unintended broadcasts on multi-client transports. `ServerSession#create_sampling_message`
should be used instead, as it routes the request to the correct client session.

This aligns with the Python SDK, which also exposes sampling only at the session level.

## How Has This Been Tested?

Existing tests updated to call `ServerSession#create_sampling_message` instead of
`Server#create_sampling_message`. All tests pass (`rake test`), RuboCop is clean,
and conformance tests pass.

## Breaking Changes

`Server#create_sampling_message` is removed without a deprecation warning.
The sampling feature was released recently and the method was not intended
to be the primary API for this feature.
This commit is contained in:
Koichi ITO 2026-04-12 16:46:40 +09:00
commit a235572777
3 changed files with 26 additions and 287 deletions
Download patch file Download diff file Expand all files Collapse all files

82
README.md
View file

@ -823,8 +823,7 @@ This enables servers to leverage the client's LLM capabilities without needing d
**Using Sampling in Tools:** **Using Sampling in Tools:**
Tools that accept a `server_context:` parameter can call `create_sampling_message` on it. Tools that accept a `server_context:` parameter can call `create_sampling_message` on it.
The request is automatically routed to the correct client session. The request is automatically routed to the correct client session:
Set `server.server_context = server` so that `server_context.create_sampling_message` delegates to the server:
```ruby ```ruby
class SummarizeTool < MCP::Tool class SummarizeTool < MCP::Tool
@ -852,7 +851,6 @@ class SummarizeTool < MCP::Tool
end end
server = MCP::Server.new(name: "my_server", tools: [SummarizeTool]) server = MCP::Server.new(name: "my_server", tools: [SummarizeTool])
server.server_context = server
``` ```
**Parameters:** **Parameters:**
@ -873,86 +871,8 @@ Optional:
- `tools:` (Array) - Tools available to the LLM (requires `sampling.tools` capability) - `tools:` (Array) - Tools available to the LLM (requires `sampling.tools` capability)
- `tool_choice:` (Hash) - Tool selection mode (e.g., `{ mode: "auto" }`) - `tool_choice:` (Hash) - Tool selection mode (e.g., `{ mode: "auto" }`)
**Direct Usage:**
`Server#create_sampling_message` can also be called directly outside of tools:
```ruby
result = server.create_sampling_message(
messages: [
{ role: "user", content: { type: "text", text: "What is the capital of France?" } }
],
max_tokens: 100,
system_prompt: "You are a helpful assistant.",
temperature: 0.7
)
```
Result contains the LLM response:
```ruby
{
role: "assistant",
content: { type: "text", text: "The capital of France is Paris." },
model: "claude-3-sonnet-20240307",
stopReason: "endTurn"
}
```
For multi-client transports (e.g., `StreamableHTTPTransport`), use `server_context.create_sampling_message` inside tools
to route the request to the correct client session.
**Tool Use in Sampling:**
When tools are provided in a sampling request, the LLM can call them during generation.
The server must handle tool calls and continue the conversation with tool results:
```ruby
result = server.create_sampling_message(
messages: [
{ role: "user", content: { type: "text", text: "What's the weather in Paris?" } }
],
max_tokens: 1000,
tools: [
{
name: "get_weather",
description: "Get weather for a city",
inputSchema: {
type: "object",
properties: { city: { type: "string" } },
required: ["city"]
}
}
],
tool_choice: { mode: "auto" }
)
if result[:stopReason] == "toolUse"
tool_results = result[:content].map do |tool_use|
weather_data = get_weather(tool_use[:input][:city])
{
type: "tool_result",
toolUseId: tool_use[:id],
content: [{ type: "text", text: weather_data.to_json }]
}
end
final_result = server.create_sampling_message(
messages: [
{ role: "user", content: { type: "text", text: "What's the weather in Paris?" } },
{ role: "assistant", content: result[:content] },
{ role: "user", content: tool_results }
],
max_tokens: 1000,
tools: [...]
)
end
```
**Error Handling:** **Error Handling:**
- Raises `RuntimeError` if transport is not set
- Raises `RuntimeError` if client does not support `sampling` capability - Raises `RuntimeError` if client does not support `sampling` capability
- Raises `RuntimeError` if `tools` are used but client lacks `sampling.tools` capability - Raises `RuntimeError` if `tools` are used but client lacks `sampling.tools` capability
- Raises `StandardError` if client returns an error response - Raises `StandardError` if client returns an error response

38
lib/mcp/server.rb
View file

@ -206,44 +206,6 @@ module MCP
report_exception(e, { notification: "log_message" }) report_exception(e, { notification: "log_message" })
end end
# Sends a `sampling/createMessage` request to the client.
# For single-client transports (e.g., `StdioTransport`). For multi-client transports
# (e.g., `StreamableHTTPTransport`), use `ServerSession#create_sampling_message` instead
# to ensure the request is routed to the correct client.
def create_sampling_message(
messages:,
max_tokens:,
system_prompt: nil,
model_preferences: nil,
include_context: nil,
temperature: nil,
stop_sequences: nil,
metadata: nil,
tools: nil,
tool_choice: nil,
related_request_id: nil
)
unless @transport
raise "Cannot send sampling request without a transport."
end
params = build_sampling_params(
@client_capabilities,
messages: messages,
max_tokens: max_tokens,
system_prompt: system_prompt,
model_preferences: model_preferences,
include_context: include_context,
temperature: temperature,
stop_sequences: stop_sequences,
metadata: metadata,
tools: tools,
tool_choice: tool_choice,
)
@transport.send_request(Methods::SAMPLING_CREATE_MESSAGE, params)
end
# Sets a custom handler for `resources/read` requests. # Sets a custom handler for `resources/read` requests.
# The block receives the parsed request params and should return resource # The block receives the parsed request params and should return resource
# contents. The return value is set as the `contents` field of the response. # contents. The return value is set as the `contents` field of the response.

193
test/mcp/server_sampling_test.rb
View file

@ -42,21 +42,12 @@ module MCP
@mock_transport = MockTransport.new(@server) @mock_transport = MockTransport.new(@server)
# Simulate client initialization with sampling capability. @session = ServerSession.new(server: @server, transport: @mock_transport)
@server.handle({ @session.store_client_info(client: { name: "test-client" }, capabilities: { sampling: {} })
jsonrpc: "2.0",
method: "initialize",
id: 1,
params: {
protocolVersion: "2025-11-25",
capabilities: { sampling: {} },
clientInfo: { name: "test-client", version: "1.0" },
},
})
end end
test "create_sampling_message sends request with required params" do test "create_sampling_message sends request with required params" do
result = @server.create_sampling_message( result = @session.create_sampling_message(
messages: [{ role: "user", content: { type: "text", text: "Hello" } }], messages: [{ role: "user", content: { type: "text", text: "Hello" } }],
max_tokens: 100, max_tokens: 100,
) )
@ -72,7 +63,7 @@ module MCP
end end
test "create_sampling_message sends all optional params" do test "create_sampling_message sends all optional params" do
@server.create_sampling_message( @session.create_sampling_message(
messages: [{ role: "user", content: { type: "text", text: "Hello" } }], messages: [{ role: "user", content: { type: "text", text: "Hello" } }],
max_tokens: 100, max_tokens: 100,
system_prompt: "You are helpful", system_prompt: "You are helpful",
@ -94,46 +85,11 @@ module MCP
assert_equal({ key: "value" }, params[:metadata]) assert_equal({ key: "value" }, params[:metadata])
end end
test "create_sampling_message raises error when transport is not set" do
server_without_transport = Server.new(name: "test", version: "1.0")
# Initialize with sampling capability but no transport.
server_without_transport.handle({
jsonrpc: "2.0",
method: "initialize",
id: 1,
params: {
protocolVersion: "2025-11-25",
capabilities: { sampling: {} },
clientInfo: { name: "test-client", version: "1.0" },
},
})
error = assert_raises(RuntimeError) do
server_without_transport.create_sampling_message(
messages: [{ role: "user", content: { type: "text", text: "Hello" } }],
max_tokens: 100,
)
end
assert_equal("Cannot send sampling request without a transport.", error.message)
end
test "create_sampling_message raises error when client does not support sampling" do test "create_sampling_message raises error when client does not support sampling" do
# Re-initialize without sampling capability. @session.store_client_info(client: { name: "test-client" }, capabilities: {})
@server.handle({
jsonrpc: "2.0",
method: "initialize",
id: 2,
params: {
protocolVersion: "2025-11-25",
capabilities: {},
clientInfo: { name: "test-client", version: "1.0" },
},
})
error = assert_raises(RuntimeError) do error = assert_raises(RuntimeError) do
@server.create_sampling_message( @session.create_sampling_message(
messages: [{ role: "user", content: { type: "text", text: "Hello" } }], messages: [{ role: "user", content: { type: "text", text: "Hello" } }],
max_tokens: 100, max_tokens: 100,
) )
@ -144,7 +100,7 @@ module MCP
test "create_sampling_message raises error when tools used but client lacks sampling.tools" do test "create_sampling_message raises error when tools used but client lacks sampling.tools" do
error = assert_raises(RuntimeError) do error = assert_raises(RuntimeError) do
@server.create_sampling_message( @session.create_sampling_message(
messages: [{ role: "user", content: { type: "text", text: "Hello" } }], messages: [{ role: "user", content: { type: "text", text: "Hello" } }],
max_tokens: 100, max_tokens: 100,
tools: [{ name: "test_tool", inputSchema: { type: "object" } }], tools: [{ name: "test_tool", inputSchema: { type: "object" } }],
@ -156,7 +112,7 @@ module MCP
test "create_sampling_message raises error when tool_choice used alone but client lacks sampling.tools" do test "create_sampling_message raises error when tool_choice used alone but client lacks sampling.tools" do
error = assert_raises(RuntimeError) do error = assert_raises(RuntimeError) do
@server.create_sampling_message( @session.create_sampling_message(
messages: [{ role: "user", content: { type: "text", text: "Hello" } }], messages: [{ role: "user", content: { type: "text", text: "Hello" } }],
max_tokens: 100, max_tokens: 100,
tool_choice: { mode: "auto" }, tool_choice: { mode: "auto" },
@ -167,19 +123,9 @@ module MCP
end end
test "create_sampling_message allows tools when client has sampling.tools capability" do test "create_sampling_message allows tools when client has sampling.tools capability" do
# Re-initialize with sampling.tools capability. @session.store_client_info(client: { name: "test-client" }, capabilities: { sampling: { tools: {} } })
@server.handle({
jsonrpc: "2.0",
method: "initialize",
id: 3,
params: {
protocolVersion: "2025-11-25",
capabilities: { sampling: { tools: {} } },
clientInfo: { name: "test-client", version: "1.0" },
},
})
result = @server.create_sampling_message( result = @session.create_sampling_message(
messages: [{ role: "user", content: { type: "text", text: "Hello" } }], messages: [{ role: "user", content: { type: "text", text: "Hello" } }],
max_tokens: 100, max_tokens: 100,
tools: [{ name: "test_tool", inputSchema: { type: "object" } }], tools: [{ name: "test_tool", inputSchema: { type: "object" } }],
@ -194,56 +140,6 @@ module MCP
assert_equal "Response from LLM", result[:content][:text] assert_equal "Response from LLM", result[:content][:text]
end end
test "init with sampling capability allows create_sampling_message" do
server = Server.new(name: "test", version: "1.0")
# Assigns server.transport via Transport#initialize, which create_sampling_message requires.
MockTransport.new(server)
server.handle({
jsonrpc: "2.0",
method: "initialize",
id: 1,
params: {
protocolVersion: "2025-11-25",
capabilities: { sampling: { tools: {} } },
clientInfo: { name: "test-client", version: "1.0" },
},
})
result = server.create_sampling_message(
messages: [{ role: "user", content: { type: "text", text: "Hello" } }],
max_tokens: 100,
tools: [{ name: "t", inputSchema: { type: "object" } }],
)
assert_equal "assistant", result[:role]
end
test "init without capabilities rejects create_sampling_message" do
server = Server.new(name: "test", version: "1.0")
# Assigns server.transport via Transport#initialize, which create_sampling_message requires.
MockTransport.new(server)
server.handle({
jsonrpc: "2.0",
method: "initialize",
id: 1,
params: {
protocolVersion: "2025-11-25",
clientInfo: { name: "test-client", version: "1.0" },
},
})
error = assert_raises(RuntimeError) do
server.create_sampling_message(
messages: [{ role: "user", content: { type: "text", text: "Hello" } }],
max_tokens: 100,
)
end
assert_equal("Client does not support sampling.", error.message)
end
test "create_sampling_message uses per-session capabilities via ServerSession" do test "create_sampling_message uses per-session capabilities via ServerSession" do
transport = MCP::Server::Transports::StreamableHTTPTransport.new(@server) transport = MCP::Server::Transports::StreamableHTTPTransport.new(@server)
@ -276,11 +172,23 @@ module MCP
test "ServerSession#client_capabilities falls back to server global capabilities" do test "ServerSession#client_capabilities falls back to server global capabilities" do
transport = MCP::Server::Transports::StreamableHTTPTransport.new(@server) transport = MCP::Server::Transports::StreamableHTTPTransport.new(@server)
# Initialize server with sampling capability.
@server.handle({
jsonrpc: "2.0",
method: "initialize",
id: 1,
params: {
protocolVersion: "2025-11-25",
capabilities: { sampling: {} },
clientInfo: { name: "test-client", version: "1.0" },
},
})
# Session without capabilities stored falls back to @server.client_capabilities. # Session without capabilities stored falls back to @server.client_capabilities.
session = ServerSession.new(server: @server, transport: transport, session_id: "s3") session = ServerSession.new(server: @server, transport: transport, session_id: "s3")
transport.instance_variable_get(:@sessions)["s3"] = { stream: nil, server_session: session } transport.instance_variable_get(:@sessions)["s3"] = { stream: nil, server_session: session }
# Server was initialized with sampling capability in setup, so fallback should pass validation. # Server was initialized with sampling capability, so fallback should pass validation.
error = assert_raises(RuntimeError) do error = assert_raises(RuntimeError) do
session.create_sampling_message( session.create_sampling_message(
messages: [{ role: "user", content: { type: "text", text: "Hello" } }], messages: [{ role: "user", content: { type: "text", text: "Hello" } }],
@ -292,7 +200,7 @@ module MCP
test "session init does not overwrite server global client_capabilities" do test "session init does not overwrite server global client_capabilities" do
server = Server.new(name: "test", version: "1.0") server = Server.new(name: "test", version: "1.0")
# Assigns server.transport via Transport#initialize, which create_sampling_message requires. # Assigns server.transport via Transport#initialize.
MockTransport.new(server) MockTransport.new(server)
# Non-session init sets global capabilities. # Non-session init sets global capabilities.
@ -333,59 +241,8 @@ module MCP
assert_equal({}, session.client_capabilities) assert_equal({}, session.client_capabilities)
end end
test "Server#create_sampling_message does not see session-scoped capabilities from HTTP init" do
server = Server.new(name: "test", version: "1.0")
transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
# HTTP init stores capabilities on the session, not on the server.
session = ServerSession.new(server: server, transport: transport, session_id: "s1")
server.handle(
{
jsonrpc: "2.0",
method: "initialize",
id: 1,
params: {
protocolVersion: "2025-11-25",
capabilities: { sampling: {} },
clientInfo: { name: "http-client", version: "1.0" },
},
},
session: session,
)
# Server-level API should not see session-scoped capabilities.
error = assert_raises(RuntimeError) do
server.create_sampling_message(
messages: [{ role: "user", content: { type: "text", text: "Hello" } }],
max_tokens: 100,
)
end
assert_equal("Client does not support sampling.", error.message)
# Session-scoped API should work (fails at transport level, not capability).
transport.instance_variable_get(:@sessions)["s1"] = { stream: nil, server_session: session }
error = assert_raises(RuntimeError) do
session.create_sampling_message(
messages: [{ role: "user", content: { type: "text", text: "Hello" } }],
max_tokens: 100,
)
end
assert_equal("No active stream for sampling/createMessage request.", error.message)
end
test "Server#create_sampling_message accepts related_request_id without error" do
@server.create_sampling_message(
messages: [{ role: "user", content: { type: "text", text: "Hello" } }],
max_tokens: 100,
related_request_id: "req-1",
)
request = @mock_transport.requests.first
assert_equal "sampling/createMessage", request[:method]
end
test "create_sampling_message omits nil optional params" do test "create_sampling_message omits nil optional params" do
@server.create_sampling_message( @session.create_sampling_message(
messages: [{ role: "user", content: { type: "text", text: "Hello" } }], messages: [{ role: "user", content: { type: "text", text: "Hello" } }],
max_tokens: 100, max_tokens: 100,
system_prompt: nil, system_prompt: nil,