Skip to content

Commit 32dd00e

Browse files
committed
[Doc] Restructure sampling section to lead with tool usage
Sampling is primarily used within tool execution via `server_context.create_sampling_message`, but the documentation led with the less common direct `Server#create_sampling_message` usage. This ordering could mislead readers into thinking direct usage is the recommended approach.
1 parent 40b048b commit 32dd00e

File tree

1 file changed

+49
-57
lines changed

1 file changed

+49
-57
lines changed

README.md

Lines changed: 49 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -112,67 +112,12 @@ This enables servers to leverage the client's LLM capabilities without needing d
112112

113113
**Key Concepts:**
114114

115-
- **Server-to-Client Request**: Unlike typical MCP methods (clientserver), sampling is initiated by the server
115+
- **Server-to-Client Request**: Unlike typical MCP methods (client to server), sampling is initiated by the server
116116
- **Client Capability**: Clients must declare `sampling` capability during initialization
117117
- **Tool Support**: When using tools in sampling requests, clients must declare `sampling.tools` capability
118118
- **Human-in-the-Loop**: Clients can implement user approval before forwarding requests to LLMs
119119

120-
**Usage Example (Stdio transport):**
121-
122-
`Server#create_sampling_message` is for single-client transports (e.g., `StdioTransport`).
123-
For multi-client transports (e.g., `StreamableHTTPTransport`), use `server_context.create_sampling_message` inside tools instead,
124-
which routes the request to the correct client session.
125-
126-
```ruby
127-
server = MCP::Server.new(name: "my_server")
128-
transport = MCP::Server::Transports::StdioTransport.new(server)
129-
server.transport = transport
130-
```
131-
132-
Client must declare sampling capability during initialization.
133-
This happens automatically when the client connects.
134-
135-
```ruby
136-
result = server.create_sampling_message(
137-
messages: [
138-
{ role: "user", content: { type: "text", text: "What is the capital of France?" } }
139-
],
140-
max_tokens: 100,
141-
system_prompt: "You are a helpful assistant.",
142-
temperature: 0.7
143-
)
144-
```
145-
146-
Result contains the LLM response:
147-
148-
```ruby
149-
{
150-
role: "assistant",
151-
content: { type: "text", text: "The capital of France is Paris." },
152-
model: "claude-3-sonnet-20240307",
153-
stopReason: "endTurn"
154-
}
155-
```
156-
157-
**Parameters:**
158-
159-
Required:
160-
161-
- `messages:` (Array) - Array of message objects with `role` and `content`
162-
- `max_tokens:` (Integer) - Maximum tokens in the response
163-
164-
Optional:
165-
166-
- `system_prompt:` (String) - System prompt for the LLM
167-
- `model_preferences:` (Hash) - Model selection preferences (e.g., `{ intelligencePriority: 0.8 }`)
168-
- `include_context:` (String) - Context inclusion: `"none"`, `"thisServer"`, or `"allServers"` (soft-deprecated)
169-
- `temperature:` (Float) - Sampling temperature
170-
- `stop_sequences:` (Array) - Sequences that stop generation
171-
- `metadata:` (Hash) - Additional metadata
172-
- `tools:` (Array) - Tools available to the LLM (requires `sampling.tools` capability)
173-
- `tool_choice:` (Hash) - Tool selection mode (e.g., `{ mode: "auto" }`)
174-
175-
**Using Sampling in Tools (works with both Stdio and HTTP transports):**
120+
**Using Sampling in Tools:**
176121

177122
Tools that accept a `server_context:` parameter can call `create_sampling_message` on it.
178123
The request is automatically routed to the correct client session.
@@ -207,6 +152,53 @@ server = MCP::Server.new(name: "my_server", tools: [SummarizeTool])
207152
server.server_context = server
208153
```
209154

155+
**Parameters:**
156+
157+
Required:
158+
159+
- `messages:` (Array) - Array of message objects with `role` and `content`
160+
- `max_tokens:` (Integer) - Maximum tokens in the response
161+
162+
Optional:
163+
164+
- `system_prompt:` (String) - System prompt for the LLM
165+
- `model_preferences:` (Hash) - Model selection preferences (e.g., `{ intelligencePriority: 0.8 }`)
166+
- `include_context:` (String) - Context inclusion: `"none"`, `"thisServer"`, or `"allServers"` (soft-deprecated)
167+
- `temperature:` (Float) - Sampling temperature
168+
- `stop_sequences:` (Array) - Sequences that stop generation
169+
- `metadata:` (Hash) - Additional metadata
170+
- `tools:` (Array) - Tools available to the LLM (requires `sampling.tools` capability)
171+
- `tool_choice:` (Hash) - Tool selection mode (e.g., `{ mode: "auto" }`)
172+
173+
**Direct Usage:**
174+
175+
`Server#create_sampling_message` can also be called directly outside of tools:
176+
177+
```ruby
178+
result = server.create_sampling_message(
179+
messages: [
180+
{ role: "user", content: { type: "text", text: "What is the capital of France?" } }
181+
],
182+
max_tokens: 100,
183+
system_prompt: "You are a helpful assistant.",
184+
temperature: 0.7
185+
)
186+
```
187+
188+
Result contains the LLM response:
189+
190+
```ruby
191+
{
192+
role: "assistant",
193+
content: { type: "text", text: "The capital of France is Paris." },
194+
model: "claude-3-sonnet-20240307",
195+
stopReason: "endTurn"
196+
}
197+
```
198+
199+
For multi-client transports (e.g., `StreamableHTTPTransport`), use `server_context.create_sampling_message` inside tools
200+
to route the request to the correct client session.
201+
210202
**Tool Use in Sampling:**
211203

212204
When tools are provided in a sampling request, the LLM can call them during generation.

0 commit comments

Comments
 (0)