When a prompt function returned `mcp.types.PromptMessage` objects directly
and was executed as a task, the result serialization failed with
"'PromptMessage' object has no attribute 'to_mcp'".
The task result converter was calling `.to_mcp()` on what it thought was a
FastMCP wrapper type, but the import actually pulls in `mcp.types.PromptMessage`
directly, which is already the final MCP type. Removed the unnecessary
conversion.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* feat: handle error from the initialize middleware
In some situation, the initialize middleware can check the status of the
server and decide to raise an error.
Example use case: in a FastMCPProxy, an initialization middleware
overrides the on_initialize method and connect to the underlying proxied
client. When client respond with error, I want to pass this error to the
client.
* docs update
* test: use McpError assertions now that exception propagation is fixed
- Update tests to catch McpError specifically instead of generic Exception
- Remove commented-out code in low_level.py
---------
Co-authored-by: Jeremiah Lowin <153965+jlowin@users.noreply.github.com>
anyio task groups suppress exceptions when cancel_scope.cancel() is
called during cleanup. Capture exceptions before cleanup and re-raise
after task group exits cleanly.
Also preserve McpError type in client _connect() so callers can catch
protocol-level errors specifically.
When upstream OAuth providers don't return expires_in (like GitHub OAuth
Apps), use smart defaults: 1 hour if refresh token available, 1 year if
not. Adds fallback_access_token_expiry_seconds parameter to override.
Tools, resources, and prompts from servers mounted more than 2 levels
deep failed to invoke even though they were correctly listed.
The bug was in the routing methods which used manager methods that only
search locally, not through nested mounted servers. Changed to use
server-level methods that search recursively.
Fixes#2583
Proxied tool results now properly forward the meta attribute from upstream servers through ProxyToolManager and ProxyTool.
Co-authored-by: Jeremiah Lowin <153965+jlowin@users.noreply.github.com>
* Add comprehensive documentation for read-only tool patterns
Created new patterns guide explaining readOnlyHint annotation usage,
including practical examples, client-specific behavior, and best
practices for marking tools as read-only.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: William Easton <strawgate@users.noreply.github.com>
* Reorganize read-only tools docs into tools section
Moved read-only tools documentation from standalone patterns page into the tools.mdx file as a "Using Annotation Hints" subsection. Condensed from 218 lines to ~50 lines focusing on practical usage while maintaining essential information about readOnlyHint and other annotations.
Changes:
- Added "Using Annotation Hints" subsection in tools.mdx after MCP Annotations
- Removed docs/patterns/read-only-tools.mdx
- Updated docs.json navigation to remove patterns entry
- Content now positioned as core tool feature rather than advanced pattern
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Bill Easton <strawgate@users.noreply.github.com>
---------
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: William Easton <strawgate@users.noreply.github.com>
* [feat] expose get_session_id callback
* [test] add test for session id callback
* [fix] add test for uninitialized case and default to None
* [fix] add in changes based on reviewers
* SEP-1330 enum schema support for elicitation
* Add version badges for 2.14.0 elicitation features
* Fix Context.elicit() to handle SEP-1330 enum syntaxes
* Guard against empty list in elicit response_type
* Add guards for empty dict/list edge cases in elicit
* Refactor elicit: extract parsing and response handling to elicitation.py
Addresses code review feedback:
- Extract `get_task_capabilities()` to avoid duplicating the SEP-1686
capability structure across transports
- Add `_should_enable_component()` check before task routing for tools,
resources, and prompts to respect enable/tag filtering
- Simplify tasks/__init__.py to avoid circular import issues
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Add EventStore and SSE polling support (SEP-1699)
* Add close_sse_stream() method to Context
* Add SSE polling documentation
* Fix missing Context import in docs example
* Remove EventStore from root __init__.py, update docs imports
- Removed EventStore import and export from src/fastmcp/__init__.py
- Updated docs to import EventStore from fastmcp.server.event_store
- Resolves merge conflict by not exporting EventStore from root package
The task protocol (SEP-1686) is now always enabled - server always
registers task handlers and advertises task capabilities. Users still
opt into background execution at the server level (tasks=True) or
component level (task=True on tools, prompts, resources).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The base Tool class now has an optional `execution` field for storing
task execution metadata (SEP-1686). This lets gateways/proxies preserve
execution info when forwarding tools from backends - previously this
metadata was lost because Tool had no way to store it.
FunctionTool continues to derive execution from task_config as before.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
When multiple servers with task-enabled tools are mounted into a parent,
their functions were all registered with Docket using `fn.__name__`. This
meant two mounted servers each having a function named `add` would both
register under `"add"`, with the second overwriting the first.
Now mounted functions use prefixed names matching their client-facing tool
names (e.g., `c1_add`, `c2_add`). Root server functions still use their
original names with no prefix.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
When a server is mounted on another, both were creating their own
Docket and Worker instances. With memory:// URLs they share the same
FakeServer queue but have separate result_storage instances. This
caused a race condition where results could be stored in one Docket's
storage but looked up in another's, returning None.
The fix marks mounted servers with `_is_mounted=True` flag so they
skip creating their own Docket/Worker. The parent's Docket handles
all task execution for mounted servers.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Simplifies the task support story for proxies and mounts:
- Mounts get full SEP-1686 task support (unchanged)
- Proxies explicitly forbid task execution
The cross-session task forwarding for proxies turned out to be complex
since each client connection creates a new server lifespan with a new
Docket context, and task keys include session_id. Rather than introduce
that complexity, proxies now explicitly refuse task-augmented execution.
Key changes:
- All proxy components (ProxyTool, ProxyPrompt, ProxyResource,
ProxyTemplate) now have task_config.mode="forbidden"
- Proxy tests verify forbidden behavior (sync execution works,
task=True returns error/raises McpError)
- Fixed prompt task handler to check hasattr(prompt, "task_config")
instead of isinstance(prompt, FunctionPrompt) so it applies to
ProxyPrompt too
- Added test suites for both proxy and mount task behavior
Also includes minor fixes:
- Fixed result.meta_ -> result.meta in ProxyTool.run()
- Fixed client handling of returned_immediately without taskId
- Bumped pydocket>=0.15.2
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Replace custom VersionBadge implementation with Mintlify's native Badge component while preserving custom color and border styling via CSS. This leverages Mintlify's built-in sizing, typography, and icon support while maintaining the original visual design.
- Lead with concepts instead of code
- Explain MCP background tasks vs general Python concurrency
- Document Docket's Prefect origins and battle-tested infrastructure
- Add sections on graceful degradation and embedded workers
- Fix version badge to 2.14.0
- Link to SEP-1686 spec
Follow-up to PR #2563 which fixed the signature handling in
create_function_without_params. These tests ensure the fix
works end-to-end for all object types that support Context injection.
* Fix: Include signature modification in create_function_without_params
When excluding parameters via create_function_without_params(), only
__annotations__ was being updated but not __signature__. This caused
Pydantic's _arguments_schema() to fail when it iterated over signature
parameters that didn't exist in the type hints dictionary.
The fix adds proper signature reconstruction matching the pattern used
in without_injected_parameters().
Fixes KeyError: 'ctx' when using @mcp.tool() with Context parameters.
* fix: add regression tests for create_function_without_params
The test_pydantic_typeadapter_compatibility test specifically reproduces the issue from #2562 and verifies the fix.
* fix: linter for test function
---------
Co-authored-by: Jeremiah Lowin <153965+jlowin@users.noreply.github.com>
* Fix type errors for ty 0.0.1-alpha.31 upgrade
Add type ignores and fixes for ty's stricter checking:
- Path(None) guards in cli.py
- isinstance checks for ElicitRequestFormParams (URL elicitation support)
- TODO(ty) comments for match/isinstance narrowing bugs
- Method override type ignores for generic covariance
- Starlette Middleware typing workarounds
- Dynamic type construction ignores in json_schema_type.py
* Fix remaining type errors for ty 0.0.1-alpha.31
- Add asserts for optional attribute access in tests
- Add type ignores for dynamic httpx transport internals
- Add TODO(ty) comments for `in` operator on str|bytes
- Add TODO(ty) comments for Starlette Middleware typing
- Use cast for prompt.fn async validation in server.py
* Upgrade ty to 0.0.1-alpha.31
Fixes additional test file type errors discovered after upgrade.
