src/fastmcp/server/server.py (1)

42-45: SDK-prefixed MCP types and list_ handlers look consistent*

The new SDK* aliases and _list_{tools,resources,resource_templates,prompts}_mcp methods correctly map internal components to mcp.types SDK objects using the to_mcp_* helpers and the .key/uriTemplate conventions, which preserves prefixing and filtering semantics across mounted servers and middleware. The extra Context layer in both the *_mcp and *_middleware functions is slightly redundant but not harmful; you could later simplify by having only the middleware layer own the request context, mirroring _call_tool_middleware, if you want to reduce nesting.

Also applies to: 646-662, 730-746, 819-835, 913-928

docs/servers/sampling.mdx (1)

418-440: Clarify pseudo-code in the custom loop example

The custom_agent example uses placeholders like some_condition and different_tool that make the snippet non-runnable as-is. Consider adding a short comment (e.g., # pseudo-code: define some_condition/different_tool as needed) so users don’t mistake it for a copy‑paste runnable example, given the repo’s usual “runnable examples” convention.

examples/advanced_sampling/tool_use.py (1)

72-85: Ensure CallToolResult.data is populated for this example

The example prints result.data["summary"] / ["sources_used"] / ["confidence"]. This relies on Client.call_tool successfully parsing structured output into CallToolResult.data using the tool’s output_schema. Please double‑check that the research tool is registered with an appropriate output_schema (or auto‑derived one) so that data is not None; otherwise these subscripts will raise at runtime and you may need to read from result.structured_content instead.

examples/advanced_sampling/structured_output.py (1)

47-65: Confirm structured data reaches CallToolResult.data

As in the tool-use example, this script prints result.data["sentiment"], ["confidence"], and ["keywords"]. Please verify that the tool’s structured output is being exposed via CallToolResult.data (through a proper output_schema), otherwise data may be None and these lines will fail. If needed, you could fall back to result.structured_content or wrap the output schema explicitly on the server side.

src/fastmcp/client/client.py (1)

317-331: set_sampling_callback mirrors init behavior; watch for capability overrides

The updated set_sampling_callback correctly updates both the sampling callback and sampling_capabilities, defaulting to tools-enabled sampling when no explicit capabilities are provided, consistent with __init__. One thing to be aware of: calling set_sampling_callback without sampling_capabilities after constructing a client with custom capabilities will overwrite them with the default tools-capability. If you expect users to swap handlers while preserving custom capabilities, consider documenting this or accepting sampling_capabilities=... in those call sites.

src/fastmcp/experimental/sampling/handlers/openai.py (1)

324-338: Tool choice mapping currently supports mode-only semantics

_convert_tool_choice_to_openai maps MCP ToolChoice.mode values "auto", "required", and "none" directly to OpenAI’s accepted values, defaulting to "auto" for anything unknown. If MCP’s ToolChoice ever gains a “specific tool only” mode, this would need to be extended (e.g., to return {"type": "function", "function": {"name": ...}}). For now, with mode-only semantics, this is fine.

src/fastmcp/server/context.py (3)

634-642: Clarify type identity check with str.

The condition result_type is not str uses identity comparison, which works here because you're checking if the type itself is the str class. However, this won't catch subclasses or type aliases. If that's intentional, consider adding a comment for clarity; otherwise, you might want a more robust check.

---

1003-1018: Bare except Exception is acceptable here but consider logging.

The broad exception catches are justified since Pydantic validation and user-provided tool functions can raise various exception types. However, silently catching errors without logging may make debugging difficult.

Consider adding debug logging before returning error results:

             except Exception as e:
+                logger.debug(f"Tool '{tool_use.name}' failed: {e}")
                 tool_results.append(
                     ToolResultContent(

Also applies to: 1046-1054

---

1166-1184: Inconsistent type checks for response_type.

The checks at lines 1168-1184 use isinstance(response_type, dict) and isinstance(response_type, list), but response_type is declared as type[T] | list[str] | dict[str, dict[str, str]] | None. When it's a dict or list value (not a type), these runtime checks make sense—but the logic is hard to follow and could be simplified.

Consider extracting this into a helper or adding comments explaining the multi-select/single-select distinction.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: .cursor/rules/core-mcp-objects.mdc:0-0
Timestamp: 2025-11-26T21:51:44.174Z
Learning: Note that Resources and Resource Templates are distinct objects but both handled by ResourceManager, requiring coordinated updates when changes affect either object type

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: .cursor/rules/core-mcp-objects.mdc:0-0
Timestamp: 2025-11-26T21:51:44.174Z
Learning: When implementing changes that affect MCP object types (Tools, Resources, Resource Templates, or Prompts), such as adding tags or importing, ensure changes are adopted, applied, and tested on all four object types

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: .cursor/rules/core-mcp-objects.mdc:0-0
Timestamp: 2025-11-26T21:51:44.174Z
Learning: Review and update related Manager classes (ToolManager, ResourceManager, PromptManager) when modifying MCP object definitions

src/fastmcp/experimental/sampling/handlers/openai.py (4)

154-216: Consider simplifying the list content handling logic.

This block is quite complex with multiple nested conditionals and mixed responsibilities (collecting items, creating tool messages inline, then creating assistant messages). The logic:

1. Iterates to collect tool_calls and text_parts
2. Immediately creates tool messages for ToolResultContent during iteration
3. After iteration, conditionally creates assistant/user messages

This mixed approach makes the flow hard to follow and maintain. Consider refactoring to separate concerns—perhaps first categorize all content items, then construct messages in a second pass.

Additionally, Line 192 concatenates text parts with newlines ("\n".join(text_parts)). Verify this is the intended behavior, as it may relate to the past review comment about concatenation.

---

274-274: Make the error message more descriptive.

The current error message f"Unsupported content type: {type(content)}" is generic. Consider specifying which content types are supported (e.g., "Supported types: TextContent, ToolUseContent, ToolResultContent, or list").

Note: Static analysis flagged this as a long message outside the exception class (TRY003). If following strict style guidelines, consider defining a custom exception or moving to a constant.

---

376-379: Consider more explicit JSON parsing error handling.

When json.loads(tool_call.function.arguments) fails, the code silently falls back to an empty dict. This could mask issues with malformed tool call arguments from the LLM. Consider logging the error or raising a more specific exception with context about which tool call failed to parse.

Example:

 try:
     arguments = json.loads(tool_call.function.arguments)
-except json.JSONDecodeError:
-    arguments = {}
+except json.JSONDecodeError as e:
+    raise ValueError(
+        f"Failed to parse arguments for tool '{tool_call.function.name}': {e}"
+    ) from e

---

349-349: Optional: Address static analysis hints about error messages.

Static analysis (Ruff TRY003) suggests avoiding long messages directly in exception constructors. If following strict style guidelines, consider:

1. Defining custom exception classes, or
2. Moving messages to constants

This is a minor style concern and can be deferred.

Also applies to: 392-392

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

src/fastmcp/server/context.py (2)

821-827: Type contract violation when max_iterations exhausted (previously flagged).

Returning result=cast(ResultT, None) when iterations are exhausted without a final response violates the type contract. Callers expecting ResultT (e.g., a Pydantic model) will receive None, causing downstream AttributeErrors.

The previous review suggested raising an exception, which seems appropriate here:

             # Check if we've hit max iterations
             if iteration >= max_iterations:
-                # Return what we have with None text (tool use without completion)
-                return SamplingResult(
-                    text=None,
-                    result=cast(ResultT, None),
-                    history=current_messages,
-                )
+                raise RuntimeError(
+                    f"Sampling loop exhausted after {max_iterations} iterations "
+                    "without receiving a final response from the LLM."
+                )

---

916-923: Same None result issue in _sample_with_client (previously flagged).

This location has the identical type contract violation as _sample_with_fallback_handler. Apply the same fix for consistency.

examples/advanced_sampling/tool_use.py (1)

78-81: Minor output formatting inconsistency.

Line 81 formats confidence with a % suffix, but ResearchReport.confidence is defined as a plain float (line 48). If it's meant to be 0.0-1.0, consider multiplying by 100 or clarifying the expected range in the model's docstring.

-        print(f"  Confidence: {result.data['confidence']}%")
+        print(f"  Confidence: {result.data['confidence'] * 100:.1f}%")

docs/servers/sampling.mdx (2)

425-447: Placeholder some_condition in custom loop example.

The some_condition placeholder is undefined, which will cause a NameError if users copy-paste directly. Consider using a realistic condition or adding a comment clarifying it's illustrative.

         # Custom logic: check conditions, change tools, etc.
-        if some_condition:
+        if "weather" in str(result.history):  # Example condition
             tools = [different_tool]

Or add a clarifying comment:

        # Custom logic: check conditions, change tools, etc.
        # Replace `some_condition` with your actual termination logic
        if some_condition:

---

432-446: Missing termination condition in while True loop example.

The custom loop example lacks a break condition other than result.text, which could lead to an infinite loop if the LLM keeps calling tools. Consider adding a max iteration guard or documenting this caveat.

 async def custom_agent(question: str, ctx: Context) -> str:
     """Agent with custom loop logic."""
     history = []
     tools = [search, get_time]
+    max_loops = 20  # Prevent infinite loops

-    while True:
+    for _ in range(max_loops):
         result = await ctx.sample(
             messages=history or question,
             tools=tools,
             max_iterations=1,
         )
         history = result.history

         # Custom logic: check conditions, change tools, etc.
         if some_condition:
             tools = [different_tool]

         # When we get a text response, we're done
         if result.text:
             return result.text
+
+    return "Max iterations reached without final response"

src/fastmcp/server/sampling/sampling_tool.py (1)

52-67: Consider handling unexpected argument errors in run().

If the underlying function receives arguments that don't match its signature (e.g., extra keys from LLM hallucination), this will raise a TypeError. While the caller (_execute_tool_calls) catches exceptions, providing a more descriptive error here could aid debugging.

     async def run(self, arguments: dict[str, Any] | None = None) -> Any:
         """Execute the tool with the given arguments."""
         if arguments is None:
             arguments = {}

-        result = self.fn(**arguments)
+        try:
+            result = self.fn(**arguments)
+        except TypeError as e:
+            raise TypeError(
+                f"Failed to call tool '{self.name}' with arguments {arguments}: {e}"
+            ) from e
         if inspect.isawaitable(result):
             result = await result
         return result

src/fastmcp/server/context.py (1)

1345-1360: _extract_text_from_content uses duck typing.

Using hasattr(block, "text") works but is less type-safe than checking isinstance(block, TextContent). Consider the explicit check for clarity and IDE support.

 def _extract_text_from_content(
     content: SamplingMessageContentBlock | list[SamplingMessageContentBlock],
 ) -> str | None:
     if isinstance(content, list):
         for block in content:
-            if hasattr(block, "text"):
+            if isinstance(block, TextContent):
                 return block.text
         return None
-    elif hasattr(content, "text"):
+    elif isinstance(content, TextContent):
         return content.text
     return None

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

src/fastmcp/server/context.py (1)

836-842: Address the past review concern: Type-unsafe None return.

As flagged in the previous review, returning cast(ResultT, None) when max_iterations is exhausted violates the type contract when result_type is a non-optional structured type. This creates a runtime hazard where callers expect a valid object but receive None.

The previous review suggested raising an exception (e.g., RuntimeError or a dedicated MaxIterationsExceededError) instead of returning None. This would make the failure explicit and type-safe.

Apply a similar fix to both occurrences (here and at lines 931-938):

             # Check if we've hit max iterations
             if iteration >= max_iterations:
-                # Return what we have with None text (tool use without completion)
-                return SamplingResult(
-                    text=None,
-                    result=cast(ResultT, None),
-                    history=current_messages,
-                )
+                raise RuntimeError(
+                    f"Sampling exhausted {max_iterations} iterations without a final response. "
+                    "Consider increasing max_iterations or simplifying the task."
+                )

src/fastmcp/server/context.py (1)

647-649: Optional: Consider extracting error message to a constant.

The error message is clear and functional. For strict adherence to Ruff's TRY003 guideline, you could extract it to a module-level constant, but this is a low-priority style improvement.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Learnt from: jlowin
Repo: jlowin/fastmcp PR: 0
File: :0-0
Timestamp: 2025-12-01T15:48:05.095Z
Learning: PR #2505 in fastmcp adds NEW functionality to get_access_token(): it now first checks request.scope["user"] for the token (which never existed before), then falls back to _sdk_get_access_token() (the only thing the original code did). This is not a reversal of order but entirely new functionality to fix stale token issues.

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: .cursor/rules/core-mcp-objects.mdc:0-0
Timestamp: 2025-11-26T21:51:44.174Z
Learning: Review and update related Manager classes (ToolManager, ResourceManager, PromptManager) when modifying MCP object definitions

src/fastmcp/experimental/sampling/handlers/openai.py (1)

306-341: _convert_tool_choice_to_openai ignores ToolChoice.name and masks invalid modes.

This helper currently:

• Returns only string modes "auto" | "required" | "none", ignoring tool_choice.name.
• Silently falls back to "auto" on any unexpected mode.

Because Context.sample() uses ToolChoice(mode="required", name="final_response") to try to force a specific tool on the last iteration, dropping the name here means OpenAI is never explicitly constrained to that tool. The silent "auto" fallback also hides misconfigurations instead of surfacing them early. This is the same concern raised in an earlier review.

A more faithful conversion would:

• Return "auto", "none", or "required" for those explicit modes, when no name is set.
• When tool_choice.mode == "required" and tool_choice.name is provided, emit the object form expected by OpenAI to force a tool:

     @staticmethod
     def _convert_tool_choice_to_openai(
         tool_choice: ToolChoice,
     ) -> ChatCompletionToolChoiceOptionParam:
         """Convert MCP tool_choice to OpenAI format."""
-        if tool_choice.mode == "auto":
-            return "auto"
-        elif tool_choice.mode == "required":
-            return "required"
-        elif tool_choice.mode == "none":
-            return "none"
-        else:
-            # Unknown mode, default to auto
-            return "auto"
+        if tool_choice.mode == "auto":
+            return "auto"
+        if tool_choice.mode == "none":
+            return "none"
+        if tool_choice.mode == "required":
+            # If a specific tool name is provided, force that tool
+            if tool_choice.name:
+                return {
+                    "type": "function",
+                    "function": {"name": tool_choice.name},
+                }
+            return "required"
+        # Unknown mode: fail fast so configuration errors are visible
+        raise ValueError(f"Unsupported tool_choice mode: {tool_choice.mode!r}")

Please double‑check the latest OpenAI tool_choice docs and type stubs to ensure this object form and accepted string literals still match the current API:

OpenAI Chat Completions tool_choice parameter: valid string values and object shape for forcing a specific function/tool.

src/fastmcp/server/context.py (1)

780-909: Fix get_cached_typeadapter import and reconsider max_iterations + None results in sampling loops.

There are a few intertwined issues in the tool/structured-output sampling paths:

1. Missing get_cached_typeadapter import breaks structured outputs at runtime.
   _execute_tool_calls() and _create_final_response_tool() both call get_cached_typeadapter(...), but this symbol isn’t imported in this module. That yields a NameError the first time the final_response tool is used, which then gets misclassified as a “Validation error” and prevents structured results from ever succeeding.

   Apply an import fix near the other utilities:

    from fastmcp.server.sampling import SamplingTool
    from fastmcp.server.server import FastMCP
    from fastmcp.tools.tool import Tool as FastMCPTool
    from fastmcp.utilities.json_schema import compress_schema

• from fastmcp.utilities.logging import _clamp_logger, get_logger

• from fastmcp.utilities.logging import _clamp_logger, get_logger
• from fastmcp.utilities.types import get_cached_typeadapter

and keep the existing usages in `_execute_tool_calls()` and `_create_final_response_tool()`.

2. **`max_iterations` exhaustion returns `SamplingResult` with `result=None`.**  
In both `_sample_with_fallback_handler()` and `_sample_with_client()`, when `iteration >= max_iterations` and the LLM still returns `stopReason == "toolUse"`, you currently do:

```python
return SamplingResult(
    text=None,
    result=cast(ResultT, None),
    history=current_messages,
)

That violates the SamplingResult[ResultT] contract when ResultT is a non‑optional structured type, and was already called out in an earlier review. It also doesn’t match the PR description that the final iteration “forces the LLM to produce a result” and that max_iterations=1 should disable that forced‑final behavior rather than short‑circuit tool execution and return None.

A more robust approach would be to either:

• Raise a clear exception (e.g. RuntimeError or a dedicated MaxIterationsExceededError) when the loop is exhausted without a final response, or
• Change the API contract to return SamplingResult[ResultT | None] and document that result can be None in this edge case.

For example, raising makes the type contract honest while surfacing misbehaving models:

-            # Check if we've hit max iterations
-            if iteration >= max_iterations:
-                # Return what we have with None text (tool use without completion)
-                return SamplingResult(
-                    text=None,
-                    result=cast(ResultT, None),
-                    history=current_messages,
-                )
+            # Check if we've hit max iterations
+            if iteration >= max_iterations:
+                raise RuntimeError(
+                    f"Sampling loop exhausted after {max_iterations} iterations "
+                    "without receiving a final response from the LLM."
+                )

(and similarly in _sample_with_client).

This is the same concern previously flagged in this file.

3. Forced-final behavior also applies when max_iterations == 1.
   Both loops treat iteration == max_iterations - 1 as the “last iteration” and then unconditionally:

   • Force ToolChoice(mode="required", name="final_response") when a result_type is set, or
   • Force ToolChoice(mode="none") when tools are present but no structured output.

   When max_iterations == 1, that condition is true on the first call, so you still enforce a forced final response instead of returning the “raw response” for a one‑shot call. Combined with the early‑exit iteration >= max_iterations checks, this means max_iterations=1 can actually prevent any tool execution and just yield a SamplingResult with None fields.

   You may want to special‑case the “advanced loop control” behavior so that:

   • Forced finalization (final_response/none) only kicks in when max_iterations > 1, and
   • max_iterations=1 truly behaves as “single LLM call + optional tool execution, no forced final result”.

   That will bring the implementation in line with the behavior described in the PR summary.

4. _execute_tool_calls overall logic is sound once the adapter import is fixed.
   Aside from the adapter import and broad Exception catches, the flow—adding the assistant message, running tools via SamplingTool.run, appending ToolResultContent, and optionally short‑circuiting when final_response validates—is coherent. The dead should_continue == False branch in the callers could be simplified, but it’s harmless.

Would you like to (a) switch to raising on max‑iteration exhaustion, or (b) relax the SamplingResult type to allow Optional[ResultT] and document that behavior? In either case, aligning max_iterations=1 semantics with the documented “advanced loop control” behavior is worth clarifying in docs/tests.

Also applies to: 910-999, 1001-1119, 1313-1335

src/fastmcp/experimental/sampling/handlers/openai.py (1)

52-86: Message and tool/result conversion logic is reasonable, but be aware of text concatenation.

The mapping from SamplingMessage content (text/tool uses/results) into OpenAI chat params and back into CreateMessageResultWithTools looks coherent and should round‑trip tool calls correctly. Note that when a single message carries multiple TextContent blocks, they are concatenated with newlines into a single OpenAI content string; that’s fine for plain text, but it does lose original segmentation if callers relied on it.

Also applies to: 118-276, 344-399

src/fastmcp/server/context.py (2)

564-579: Context.sample() API shape and simple no-tools path look good.

The overloads, parameterization with ResultT, and basic non‑tool path (single create_message call, text extraction via _extract_text_from_content, and SamplingResult construction) are consistent and type‑annotated as required. Converting tools to SamplingTool from SamplingTool/FastMCPTool/callables and then to SDKTool is also a sensible layering.

Also applies to: 581-612, 656-779

---

1338-1353: _extract_text_from_content helper is a reasonable convenience.

The helper correctly pulls the first .text field from either a single content block or a list of blocks, and safely falls back to None when no text is present. It keeps the sampling code cleaner where only the primary text matters.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: .cursor/rules/core-mcp-objects.mdc:0-0
Timestamp: 2025-11-26T21:51:44.174Z
Learning: Review and update related Manager classes (ToolManager, ResourceManager, PromptManager) when modifying MCP object definitions

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: .cursor/rules/core-mcp-objects.mdc:0-0
Timestamp: 2025-11-26T21:51:44.174Z
Learning: When implementing changes that affect MCP object types (Tools, Resources, Resource Templates, or Prompts), such as adding tags or importing, ensure changes are adopted, applied, and tested on all four object types

src/fastmcp/server/context.py (1)

1059-1074: Type narrowing issue with hasattr checks.

As noted in a previous review, using hasattr(block, "text") doesn't provide sufficient type narrowing for the type checker. The # type: ignore[return-value] comments mask the issue.

Consider using isinstance with TextContent:

 def _extract_text_from_content(
     content: SamplingMessageContentBlock | list[SamplingMessageContentBlock],
 ) -> str | None:
     if isinstance(content, list):
         for block in content:
-            if hasattr(block, "text"):
-                return block.text  # type: ignore[return-value]
+            if isinstance(block, TextContent):
+                return block.text
         return None
-    elif hasattr(content, "text"):
-        return content.text  # type: ignore[return-value]
+    elif isinstance(content, TextContent):
+        return content.text
     return None

src/fastmcp/experimental/sampling/handlers/openai.py (1)

326-339: Handle specific tool selection when name is provided.

This method ignores the name field of ToolChoice. When a specific tool must be forced (e.g., ToolChoice(mode="required", name="my_tool")), OpenAI expects the object format {"type": "function", "function": {"name": "..."}}. The silent fallback to "auto" on line 339 also masks configuration errors.

     @staticmethod
     def _convert_tool_choice_to_openai(
         tool_choice: ToolChoice,
     ) -> ChatCompletionToolChoiceOptionParam:
         """Convert MCP tool_choice to OpenAI format."""
         if tool_choice.mode == "auto":
             return "auto"
         elif tool_choice.mode == "required":
+            # If a specific tool name is provided, force that tool
+            if tool_choice.name:
+                return {
+                    "type": "function",
+                    "function": {"name": tool_choice.name},
+                }
             return "required"
         elif tool_choice.mode == "none":
             return "none"
         else:
-            # Unknown mode, default to auto
-            return "auto"
+            raise ValueError(f"Unsupported tool_choice mode: {tool_choice.mode}")

examples/advanced_sampling/tool_use.py (1)

45-48: Consider adding field constraints to the Pydantic model.

The confidence field lacks constraints. For clarity and validation, consider adding bounds:

 class ResearchReport(BaseModel):
     summary: str
     sources_used: list[str]
-    confidence: float
+    confidence: float = Field(ge=0.0, le=1.0, description="Confidence score between 0 and 1")

This would require importing Field from pydantic.

docs/servers/sampling.mdx (1)

156-156: Inconsistent import location for SamplingMessage.

Line 156 imports SamplingMessage from fastmcp.client.sampling, but line 296 imports from mcp.types. For consistency and to use the canonical source, consider using mcp.types throughout:

-from fastmcp.client.sampling import SamplingMessage
+from mcp.types import SamplingMessage

src/fastmcp/server/context.py (1)

752-753: Hardcoded max_iterations limit.

The max_iterations = 50 is hardcoded inside the method. Consider exposing this as a parameter for users who need more or fewer iterations:

     async def sample(
         self,
         messages: str | Sequence[str | SamplingMessage],
         *,
         system_prompt: str | None = None,
         ...
+        max_iterations: int = 50,
     ) -> SamplingResult[ResultT] | SamplingResult[str]:

This would allow advanced users to tune the iteration limit without modifying the source.

src/fastmcp/server/sampling/run.py (1)

280-288: Consider catching a more specific exception type.

The bare except Exception is overly broad and may mask unexpected errors. If the intent is to catch tool execution failures, consider defining or using a more specific exception type, or at minimum logging the exception details for debugging.

-            except Exception as e:
+            except (TypeError, ValueError, RuntimeError) as e:
+                # Catch common tool execution errors; adjust based on actual tool behavior
                 tool_results.append(
                     ToolResultContent(
                         type="tool_result",
                         toolUseId=tool_use.id,
                         content=[TextContent(type="text", text=f"Error: {e}")],
                         isError=True,
                     )
                 )

Alternatively, if catching all exceptions is intentional for resilience, add a comment explaining the rationale.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

src/fastmcp/server/sampling/run.py (2)

45-48: Consider making SamplingResult.text non-optional (or enforce the invariant).

SamplingResult represents a completed sampling run; having text: str | None invites downstream None handling despite “run to completion” semantics. If None is truly possible, document when/why and consider a helper like require_text() that raises a clear error.

---

72-83: SampleStep.text should avoid hasattr/type: ignore and handle multi-block text predictably.

Right now you return the first block with .text, which can silently drop content and is structurally brittle. Prefer explicit isinstance(block, TextContent) and either concatenate text blocks or clearly define “first text block only”.

docs/servers/sampling.mdx (1)

410-426: OpenAI handler section: add minimal prerequisites / failure mode guidance.

Given the doc guidelines (“prerequisites” + “troubleshooting”), consider adding:

• required dependency install note for openai
• what happens if OPENAI_API_KEY is unset / invalid (expected error)
• whether tools require any extra OpenAI settings

Keeps the example closer to “runnable and verifiable.”

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

src/fastmcp/server/sampling/run.py (1)

149-172: Consider explicit validation for sampling_handler_behavior.

The function handles "always" and "fallback" explicitly, but other values (including typos like "fallbck") silently fall through. While None (unconfigured) correctly falls through, an explicit invalid string should fail fast:

     elif needs_tools and not has_tools_capability:
         raise ValueError(
             "Client does not support sampling with tools. "
             "The client must advertise the sampling.tools capability."
         )
+    elif fastmcp.sampling_handler_behavior is not None:
+        raise ValueError(
+            f"Invalid sampling_handler_behavior: {fastmcp.sampling_handler_behavior!r}. "
+            "Must be 'always', 'fallback', or None."
+        )
 
     return False

src/fastmcp/experimental/sampling/handlers/openai.py (1)

345-346: Silent fallback to "auto" for unknown modes masks configuration errors.

The else branch (line 346) silently returns "auto" for any unrecognized tool_choice.mode value. This could hide bugs where an invalid mode is passed.

         elif tool_choice.mode == "none":
             return "none"
-        else:
-            return "auto"
+        else:
+            raise ValueError(f"Unsupported tool_choice mode: {tool_choice.mode!r}")

docs/servers/sampling.mdx (3)

48-50: Documentation understates result_type capabilities.

The parameter is described as "A Pydantic model" but the implementation (via get_cached_typeadapter) also supports dataclasses and basic types. Consider updating to reflect the full capability:

-    <ResponseField name="result_type" type="type[T] | None" default="None">
-      A Pydantic model for validated structured output.
+    <ResponseField name="result_type" type="type[T] | None" default="None">
+      A type for validated structured output. Supports Pydantic models, dataclasses, and basic types.
     </ResponseField>

---

339-356: Add iteration limit to sample_step() loop example for safety.

The while True loop lacks a termination guard. Unlike sample() which has internal max_iterations=50, sample_step() is stateless and relies on user code for loop control. Adding a counter makes the example safer to copy:

     messages = [SamplingMessage(role="user", content=question)]
+    max_steps = 20

-    while True:
+    for _ in range(max_steps):
         step = await ctx.sample_step(
             messages=messages,
             tools=[search, get_time],
         )
         ...
         if step.is_text:
             return step.text

         messages = step.history
+
+    raise RuntimeError(f"Agent exceeded {max_steps} steps")

---

407-422: Manual tool execution example should handle unknown tools.

The example does a direct dict lookup (fn = tools[call.name]) which raises KeyError for unknown tools. Since the page documents isError=True, demonstrate it here:

         if step.is_tool_use:
             tool_results = []
             for call in step.tool_calls:
-                # Look up and execute the requested tool
-                fn = tools[call.name]
-                result = fn(**call.input)
-                tool_results.append(
-                    ToolResultContent(
-                        type="tool_result",
-                        toolUseId=call.id,
-                        content=[TextContent(type="text", text=result)],
+                fn = tools.get(call.name)
+                if fn is None:
+                    tool_results.append(
+                        ToolResultContent(
+                            type="tool_result",
+                            toolUseId=call.id,
+                            content=[TextContent(type="text", text=f"Unknown tool: {call.name}")],
+                            isError=True,
+                        )
                     )
-                )
+                else:
+                    result = fn(**call.input)
+                    tool_results.append(
+                        ToolResultContent(
+                            type="tool_result",
+                            toolUseId=call.id,
+                            content=[TextContent(type="text", text=result)],
+                        )
+                    )

src/fastmcp/server/context.py (1)

821-843: Consider catching a more specific exception for validation errors.

The bare Exception catch at line 821 is flagged by static analysis (BLE001). While Pydantic's ValidationError is the primary expected exception, catching all exceptions here could mask unexpected bugs.

+            from pydantic import ValidationError
             ...
-                        except Exception as e:
+                        except ValidationError as e:
                             # Validation failed - add error as tool result

If you need to handle other exceptions (e.g., TypeError from malformed input), consider catching them explicitly.

src/fastmcp/experimental/sampling/handlers/openai.py (2)

153-218: Complex list content handling looks correct but could benefit from comments.

The logic for handling mixed content (ToolUseContent, TextContent, ToolResultContent) is intricate. Consider adding a brief comment explaining the flow—especially that tool results are emitted immediately while tool_calls/text are accumulated for a single assistant message.

---

385-388: Consider logging a warning when tool arguments fail to parse.

Defaulting to an empty dict on JSONDecodeError is a reasonable fallback, but silently swallowing parse errors could hide issues with malformed LLM responses.

                 try:
                     arguments = json.loads(func.arguments)  # type: ignore[union-attr]
                 except json.JSONDecodeError:
+                    logger.warning(
+                        f"Failed to parse tool arguments for {func.name}: {func.arguments!r}"
+                    )
                     arguments = {}

This requires adding logger = get_logger(__name__) at module level.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro