mirror of
https://github.com/PrefectHQ/fastmcp.git
synced 2026-08-12 16:49:10 +02:00
c2dafc1c88Co-authored-by: marvin-context-protocol[bot] <225465937+marvin-context-protocol[bot]@users.noreply.github.com>
175 lines
6 KiB
Text
175 lines
6 KiB
Text
---
|
|
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.
|
|
|