Skip to content

Commit 3f43b1f

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 2a1c9b7 commit 3f43b1f

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
@@ -810,67 +810,12 @@ This enables servers to leverage the client's LLM capabilities without needing d
810810

811811
**Key Concepts:**
812812

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

818-
**Usage Example (Stdio transport):**
819-
820-
`Server#create_sampling_message` is for single-client transports (e.g., `StdioTransport`).
821-
For multi-client transports (e.g., `StreamableHTTPTransport`), use `server_context.create_sampling_message` inside tools instead,
822-
which routes the request to the correct client session.
823-
824-
```ruby
825-
server = MCP::Server.new(name: "my_server")
826-
transport = MCP::Server::Transports::StdioTransport.new(server)
827-
server.transport = transport
828-
```
829-
830-
Client must declare sampling capability during initialization.
831-
This happens automatically when the client connects.
832-
833-
```ruby
834-
result = server.create_sampling_message(
835-
messages: [
836-
{ role: "user", content: { type: "text", text: "What is the capital of France?" } }
837-
],
838-
max_tokens: 100,
839-
system_prompt: "You are a helpful assistant.",
840-
temperature: 0.7
841-
)
842-
```
843-
844-
Result contains the LLM response:
845-
846-
```ruby
847-
{
848-
role: "assistant",
849-
content: { type: "text", text: "The capital of France is Paris." },
850-
model: "claude-3-sonnet-20240307",
851-
stopReason: "endTurn"
852-
}
853-
```
854-
855-
**Parameters:**
856-
857-
Required:
858-
859-
- `messages:` (Array) - Array of message objects with `role` and `content`
860-
- `max_tokens:` (Integer) - Maximum tokens in the response
861-
862-
Optional:
863-
864-
- `system_prompt:` (String) - System prompt for the LLM
865-
- `model_preferences:` (Hash) - Model selection preferences (e.g., `{ intelligencePriority: 0.8 }`)
866-
- `include_context:` (String) - Context inclusion: `"none"`, `"thisServer"`, or `"allServers"` (soft-deprecated)
867-
- `temperature:` (Float) - Sampling temperature
868-
- `stop_sequences:` (Array) - Sequences that stop generation
869-
- `metadata:` (Hash) - Additional metadata
870-
- `tools:` (Array) - Tools available to the LLM (requires `sampling.tools` capability)
871-
- `tool_choice:` (Hash) - Tool selection mode (e.g., `{ mode: "auto" }`)
872-
873-
**Using Sampling in Tools (works with both Stdio and HTTP transports):**
818+
**Using Sampling in Tools:**
874819

875820
Tools that accept a `server_context:` parameter can call `create_sampling_message` on it.
876821
The request is automatically routed to the correct client session.
@@ -905,6 +850,53 @@ server = MCP::Server.new(name: "my_server", tools: [SummarizeTool])
905850
server.server_context = server
906851
```
907852

853+
**Parameters:**
854+
855+
Required:
856+
857+
- `messages:` (Array) - Array of message objects with `role` and `content`
858+
- `max_tokens:` (Integer) - Maximum tokens in the response
859+
860+
Optional:
861+
862+
- `system_prompt:` (String) - System prompt for the LLM
863+
- `model_preferences:` (Hash) - Model selection preferences (e.g., `{ intelligencePriority: 0.8 }`)
864+
- `include_context:` (String) - Context inclusion: `"none"`, `"thisServer"`, or `"allServers"` (soft-deprecated)
865+
- `temperature:` (Float) - Sampling temperature
866+
- `stop_sequences:` (Array) - Sequences that stop generation
867+
- `metadata:` (Hash) - Additional metadata
868+
- `tools:` (Array) - Tools available to the LLM (requires `sampling.tools` capability)
869+
- `tool_choice:` (Hash) - Tool selection mode (e.g., `{ mode: "auto" }`)
870+
871+
**Direct Usage:**
872+
873+
`Server#create_sampling_message` can also be called directly outside of tools:
874+
875+
```ruby
876+
result = server.create_sampling_message(
877+
messages: [
878+
{ role: "user", content: { type: "text", text: "What is the capital of France?" } }
879+
],
880+
max_tokens: 100,
881+
system_prompt: "You are a helpful assistant.",
882+
temperature: 0.7
883+
)
884+
```
885+
886+
Result contains the LLM response:
887+
888+
```ruby
889+
{
890+
role: "assistant",
891+
content: { type: "text", text: "The capital of France is Paris." },
892+
model: "claude-3-sonnet-20240307",
893+
stopReason: "endTurn"
894+
}
895+
```
896+
897+
For multi-client transports (e.g., `StreamableHTTPTransport`), use `server_context.create_sampling_message` inside tools
898+
to route the request to the correct client session.
899+
908900
**Tool Use in Sampling:**
909901

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

0 commit comments

Comments
 (0)