Make pydocket optional and unify DI systems by jlowin · Pull Request #2835 · PrefectHQ/fastmcp

jlowin · 2026-01-10T19:41:48Z

Moves pydocket from core dependencies to an optional fastmcp[tasks] extra. The base install no longer pulls in distributed task infrastructure—Redis clients, Lua environments, async job machinery—that's irrelevant for simple MCP servers.

What changed

pydocket is now optional. A vendored minimal DI engine provides Depends() functionality without docket. Task features (task=True, Progress(), CurrentDocket()) require the extra and give clear errors if it's missing.

Unified DI system. Legacy ctx: Context type annotations are now transformed to ctx: Context = CurrentContext() at registration time. One codepath instead of two, and the vendored DI engine only needs to understand Dependency.

# Both patterns now work identically:
@mcp.tool
def my_tool(ctx: Context) -> str: ...

@mcp.tool  
def my_tool(ctx: Context = CurrentContext()) -> str: ...

Graceful degradation. Task capabilities return empty {} when pydocket isn't installed, so clients won't see task support advertised. Attempting to use task=True without the extra raises:

ImportError: FastMCP background tasks require the `tasks` extra. 
Install with: pip install 'fastmcp[tasks]'.

Also adds a warning when combining task=True with Context parameters (Context isn't available in workers).

cc @chrisguidry — the vendored DI engine is a minimal subset of docket's dependency injection. Once the DI component is spun out as a standalone library, we'll replace the vendor with a proper dependency.

Move pydocket to fastmcp[tasks] optional extra. Vendor minimal DI engine for Depends() functionality without full docket. Transform ctx: Context annotations to CurrentContext() defaults at registration time, eliminating the legacy injection codepath.

coderabbitai · 2026-01-10T19:47:11Z

Warning

Rate limit exceeded

@jlowin has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 13 minutes and 4 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between c611515 and e934232.

⛔ Files ignored due to path filters (2)

tests/server/test_mount.py is excluded by none and included by none
tests/server/test_server_docket.py is excluded by none and included by none

📒 Files selected for processing (6)

docs/servers/tasks.mdx
src/fastmcp/server/dependencies.py
src/fastmcp/server/server.py
src/fastmcp/server/tasks/config.py
src/fastmcp/server/tasks/requests.py
src/fastmcp/server/tasks/subscriptions.py

Walkthrough

This PR introduces a vendored, minimal dependency injection engine in src/fastmcp/_vendor/docket_di/ as a fallback when the optional docket package is unavailable. It refactors the codebase to unify dependency injection by adding transform_context_annotations() to convert Context-typed parameters into Depends-style injections across resources, prompts, tools, and templates. The PR makes docket and task infrastructure conditional based on package availability, adds context utility functions and dependency accessors in src/fastmcp/server/dependencies.py, and updates src/fastmcp/server/server.py to conditionally initialize docket infrastructure. Task-related modules are updated to check for docket availability and consolidate state-mapping logic.

Possibly related PRs

[2.14] SEP-1686 tasks #2378: Directly enabled by this PR's vendored DI implementation, which provides the foundational dependency injection and task-related changes for the SEP-1686 tasks specification.
Add TaskConfig for SEP-1686 execution modes #2570: Both PRs modify the task execution surface and TaskConfig handling across resources, prompts, tools, and server routing.
Enable background task support for custom component subclasses #2657: Both PRs update the same component modules (prompt.py, resource.py, template.py, tool.py) to integrate task and docket-aware dependency handling.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main objective: making pydocket optional and unifying the DI (dependency injection) systems, which are the core themes throughout all file changes.
Description check	✅ Passed	The description comprehensively addresses what changed (pydocket as optional extra, vendored DI engine, unified DI system, graceful degradation), includes examples and error messages, and provides clear context for why these changes matter.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (2)

src/fastmcp/server/tasks/requests.py (1)
38-49: Consider making the state mapping a module-level constant instead of a function.

The _get_docket_to_mcp_state_map() function creates a new dictionary on every call (lines 159, 265, and also imported/used in subscriptions.py lines 105, 179). Since the mapping is static and never changes, recreating it repeatedly is inefficient.
♻️ Refactor to module-level constant
-def _get_docket_to_mcp_state_map() -> dict[ExecutionState, str]:
-    """Get the mapping from Docket execution states to MCP task status strings."""
-    # Map Docket execution states to MCP task status strings
-    # Per SEP-1686 final spec (line 381): tasks MUST begin in "working" status
-    return {
-        ExecutionState.SCHEDULED: "working",  # Initial state per spec
-        ExecutionState.QUEUED: "working",  # Initial state per spec
-        ExecutionState.RUNNING: "working",
-        ExecutionState.COMPLETED: "completed",
-        ExecutionState.FAILED: "failed",
-        ExecutionState.CANCELLED: "cancelled",
-    }
+# Map Docket execution states to MCP task status strings
+# Per SEP-1686 final spec (line 381): tasks MUST begin in "working" status
+_DOCKET_TO_MCP_STATE: dict[ExecutionState, str] = {
+    ExecutionState.SCHEDULED: "working",  # Initial state per spec
+    ExecutionState.QUEUED: "working",  # Initial state per spec
+    ExecutionState.RUNNING: "working",
+    ExecutionState.COMPLETED: "completed",
+    ExecutionState.FAILED: "failed",
+    ExecutionState.CANCELLED: "cancelled",
+}
Then replace state_map = _get_docket_to_mcp_state_map() with _DOCKET_TO_MCP_STATE at usage sites (lines 159, 265).
src/fastmcp/server/tasks/subscriptions.py (1)
18-19: Consider relocating shared state mapping to avoid cross-module private function import.

Importing the private function _get_docket_to_mcp_state_map() from requests.py creates tight coupling between these modules. When functionality is shared across multiple modules, it's better practice to either:

Move it to a shared utility module (e.g., tasks/common.py or tasks/state.py)

Make it a module-level constant (as suggested in the requests.py review)

If you adopt the module-level constant approach suggested for requests.py, this import would become:
from fastmcp.server.tasks.requests import _DOCKET_TO_MCP_STATE
And usage at lines 105-106 and 179-180 would simply reference _DOCKET_TO_MCP_STATE directly instead of calling a function.

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between daa2dac and c611515.

⛔ Files ignored due to path filters (3)

pyproject.toml is excluded by none and included by none
tests/server/test_dependencies.py is excluded by none and included by none
uv.lock is excluded by !**/*.lock and included by none

📒 Files selected for processing (14)

src/fastmcp/_vendor/__init__.py
src/fastmcp/_vendor/docket_di/README.md
src/fastmcp/_vendor/docket_di/__init__.py
src/fastmcp/dependencies.py
src/fastmcp/prompts/prompt.py
src/fastmcp/resources/resource.py
src/fastmcp/resources/template.py
src/fastmcp/server/dependencies.py
src/fastmcp/server/server.py
src/fastmcp/server/tasks/capabilities.py
src/fastmcp/server/tasks/config.py
src/fastmcp/server/tasks/requests.py
src/fastmcp/server/tasks/subscriptions.py
src/fastmcp/tools/tool.py

🧰 Additional context used

📓 Path-based instructions (1)

src/fastmcp/**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

src/fastmcp/**/*.py: Python ≥ 3.10 with full type annotations required
Prioritize readable, understandable code - clarity over cleverness. Avoid obfuscated or confusing patterns even if shorter
Follow existing patterns and maintain consistency in code implementation
Be intentional about re-exports - don't blindly re-export everything to parent namespaces. Core types defining a module's purpose should be exported. Specialized features can live in submodules. Only re-export to fastmcp.* for most fundamental types
Never use bare except - be specific with exception types

Files:

src/fastmcp/_vendor/__init__.py
src/fastmcp/server/tasks/config.py
src/fastmcp/prompts/prompt.py
src/fastmcp/server/tasks/subscriptions.py
src/fastmcp/_vendor/docket_di/__init__.py
src/fastmcp/server/server.py
src/fastmcp/dependencies.py
src/fastmcp/resources/resource.py
src/fastmcp/server/tasks/capabilities.py
src/fastmcp/tools/tool.py
src/fastmcp/resources/template.py
src/fastmcp/server/dependencies.py
src/fastmcp/server/tasks/requests.py

🧠 Learnings (5)