mirror of
https://github.com/PrefectHQ/fastmcp.git
synced 2026-08-23 22:14:18 +02:00
chore: Update SDK documentation (#3901)
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]
GitHub
parent
e66cce2538
commit
c2dafc1c88
21 changed files with 476 additions and 343 deletions
175
docs/python-sdk/fastmcp-server-tasks-context.mdx
Normal file
175
docs/python-sdk/fastmcp-server-tasks-context.mdx
Normal file
|
|
@ -0,0 +1,175 @@
|
|||
---
|
||||
title: context
|
||||
sidebarTitle: context
|
||||
---
|
||||
|
||||
# `fastmcp.server.tasks.context`
|
||||
|
||||
|
||||
Task context and scoping for background task execution.
|
||||
|
||||
Determines authorization scope (``get_task_scope``), manages the context
|
||||
snapshot that is captured at task submission and restored in workers
|
||||
(``TaskContextSnapshot``), and maintains in-process registries for live
|
||||
sessions and servers.
|
||||
|
||||
|
||||
## Functions
|
||||
|
||||
### `get_task_scope` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L30" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
||||
|
||||
```python
|
||||
get_task_scope() -> str | None
|
||||
```
|
||||
|
||||
|
||||
Get the authorization scope for task isolation.
|
||||
|
||||
Returns the raw scope identifier for the current access token, or
|
||||
``None`` when no auth context is present (anonymous tasks).
|
||||
|
||||
The scope is composed as ``client_id|sub`` when the token carries a
|
||||
``sub`` claim — necessary for fixed-OAuth servers where ``client_id`` is
|
||||
shared across all users — and falls back to ``client_id`` alone for
|
||||
DCR/CIMD flows where the client identity is already per-user.
|
||||
|
||||
Encoding for Redis/Docket keys happens at the boundary in ``keys.py``;
|
||||
this function returns the raw value.
|
||||
|
||||
|
||||
### `get_task_context` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L70" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
||||
|
||||
```python
|
||||
get_task_context() -> TaskContextInfo | None
|
||||
```
|
||||
|
||||
|
||||
Get the current task context if running inside a background task worker.
|
||||
|
||||
This function extracts task information from the Docket execution context.
|
||||
Returns None if not running in a task context (e.g., foreground execution).
|
||||
|
||||
**Returns:**
|
||||
- TaskContextInfo with task_id and task_scope, or None if not in a task.
|
||||
|
||||
|
||||
### `get_task_session_id` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L245" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
||||
|
||||
```python
|
||||
get_task_session_id() -> str | None
|
||||
```
|
||||
|
||||
|
||||
Get the session_id for the current background task, if available.
|
||||
|
||||
Loads the task snapshot (from cache or Redis) and returns the session_id
|
||||
that was captured at task submission time. Returns None if not in a task
|
||||
context or if the snapshot isn't available.
|
||||
|
||||
|
||||
### `register_task_session` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L341" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
||||
|
||||
```python
|
||||
register_task_session(session_id: str, session: ServerSession) -> None
|
||||
```
|
||||
|
||||
|
||||
Register a session for in-process background task access.
|
||||
|
||||
Called automatically when a task is submitted to Docket. The session is
|
||||
stored as a weakref so it doesn't prevent garbage collection when the
|
||||
client disconnects.
|
||||
|
||||
|
||||
### `get_task_session` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L351" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
||||
|
||||
```python
|
||||
get_task_session(session_id: str) -> ServerSession | None
|
||||
```
|
||||
|
||||
|
||||
Get a registered session by ID if still alive.
|
||||
|
||||
Returns None in distributed workers where the session lives in another
|
||||
process — callers must handle this gracefully.
|
||||
|
||||
|
||||
### `register_task_server` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L370" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
||||
|
||||
```python
|
||||
register_task_server(task_id: str, server: FastMCP) -> None
|
||||
```
|
||||
|
||||
|
||||
Register the server for a background task.
|
||||
|
||||
Called at task-submission time so that background workers can resolve
|
||||
the correct (child) server for mounted tasks.
|
||||
|
||||
|
||||
### `get_task_server` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L381" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
||||
|
||||
```python
|
||||
get_task_server(task_id: str) -> FastMCP | None
|
||||
```
|
||||
|
||||
|
||||
Get the registered server for a background task, if still alive.
|
||||
|
||||
|
||||
## Classes
|
||||
|
||||
### `TaskContextInfo` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
||||
|
||||
|
||||
Information about the current background task context.
|
||||
|
||||
Returned by ``get_task_context()`` when running inside a Docket worker.
|
||||
Contains identifiers needed to communicate with the MCP session.
|
||||
|
||||
|
||||
### `TaskContextSnapshot` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
||||
|
||||
|
||||
All context data snapshotted at task-submission time.
|
||||
|
||||
Stored as a single Redis key per task, restored once in the worker.
|
||||
|
||||
|
||||
**Methods:**
|
||||
|
||||
#### `capture` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
||||
|
||||
```python
|
||||
capture(cls) -> TaskContextSnapshot
|
||||
```
|
||||
|
||||
Capture current context for background task execution.
|
||||
|
||||
|
||||
#### `from_json` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L139" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
||||
|
||||
```python
|
||||
from_json(cls, raw: str | bytes) -> TaskContextSnapshot
|
||||
```
|
||||
|
||||
Deserialize from JSON stored in Redis.
|
||||
|
||||
|
||||
#### `to_json` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L154" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
||||
|
||||
```python
|
||||
to_json(self) -> str
|
||||
```
|
||||
|
||||
Serialize to JSON for Redis storage.
|
||||
|
||||
|
||||
#### `save` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L165" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
||||
|
||||
```python
|
||||
save(self, docket: Docket, task_scope: str | None, task_id: str, ttl_seconds: int) -> None
|
||||
```
|
||||
|
||||
Store this snapshot as a single Redis key.
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue