ceos/fastmcp
1
0
Fork 0
mirror of https://github.com/PrefectHQ/fastmcp.git synced 2026-08-22 21:44:18 +02:00
Code Issues Projects Releases Packages Wiki Activity

chore: Update SDK documentation (#2604)

Browse source 
Co-authored-by: marvin-context-protocol[bot] <225465937+marvin-context-protocol[bot]@users.noreply.github.com>
This commit is contained in:
marvin-context-protocol[bot] 2025-12-24 16:21:31 -05:00 • committed by GitHub
commit 9d5ffa86b3
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
55 changed files with 3213 additions and 1480 deletions
Download patch file Download diff file Expand all files Collapse all files

116
docs/python-sdk/fastmcp-server-sampling-run.mdx Normal file
View file

@ -0,0 +1,116 @@
---
title: run
sidebarTitle: run
---
# `fastmcp.server.sampling.run`
Sampling types and helper functions for FastMCP servers.
## Functions
### `determine_handler_mode` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L118" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
determine_handler_mode(context: Context, needs_tools: bool) -> bool
```
Determine whether to use fallback handler or client for sampling.
**Args:**
- `context`: The MCP context.
- `needs_tools`: Whether the sampling request requires tool support.
**Returns:**
- True if fallback handler should be used, False to use client.
**Raises:**
- `ValueError`: If client lacks required capability and no fallback configured.
### `call_sampling_handler` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
call_sampling_handler(context: Context, messages: list[SamplingMessage]) -> CreateMessageResult | CreateMessageResultWithTools
```
Make LLM call using the fallback handler.
Note: This function expects the caller (sample_step) to have validated that
sampling_handler is set via determine_handler_mode(). The checks below are
safeguards against internal misuse.
### `execute_tools` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L228" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
execute_tools(tool_calls: list[ToolUseContent], tool_map: dict[str, SamplingTool], mask_error_details: bool = False) -> list[ToolResultContent]
```
Execute tool calls and return results.
**Args:**
- `tool_calls`: List of tool use requests from the LLM.
- `tool_map`: Mapping from tool name to SamplingTool.
- `mask_error_details`: If True, mask detailed error messages from tool execution.
When masked, only generic error messages are returned to the LLM.
Tools can explicitly raise ToolError to bypass masking when they want
to provide specific error messages to the LLM.
**Returns:**
- List of tool result content blocks.
## Classes
### `SamplingResult` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Result of a sampling operation.
**Attributes:**
- `text`: The text representation of the result (raw text or JSON for structured).
- `result`: The typed result (str for text, parsed object for structured output).
- `history`: All messages exchanged during sampling.
### `SampleStep` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
Result of a single sampling call.
Represents what the LLM returned in this step plus the message history.
**Methods:**
#### `is_tool_use` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
is_tool_use(self) -> bool
```
True if the LLM is requesting tool execution.
#### `text` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L72" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
text(self) -> str | None
```
Extract text from the response, if available.
#### `tool_calls` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/sampling/run.py#L85" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
```python
tool_calls(self) -> list[ToolUseContent]
```
Get the list of tool calls from the response.