Bound FastMCP injection claims to the SDK's whole-signature and generic-type rules

[pengfei-threemoonslab]

Delivered — 2026-09-09

Completed in #603, merged 5c5a4b94118c93e2493812689d3920212451f1e4. The installed/shared idiom reader and zero-install port now make a bounded whole-signature injection decision, remove at most the first proven Context, and retain named signature/parameter limits where generic, annotation or class evidence is unresolved. Canonical/nullable Context, local proven subclasses and ordinary application models retain their supported behavior. No target server is imported or executed; medium confidence and tool discovery are preserved.

The published support note pins SDK 1.27.2 and standalone FastMCP 2.14.5 source behavior and explicitly does not claim full runtime fidelity. Framework-family/exact-export provenance is separately filed and deferred in #601.

Two independent GitHub coding-agent review/address rounds (reviews 5149304725 and 5149387533; addresses 5595251733 and 5595278042) completed. Round 1 found invalid typing arity/empty Union could hide Context; commit 9493d77545e8756e11daebd17d67d7dc67490967 fixed it with SDK-backed red/green probes and shared production/standalone coverage. Final full suite 9,203 passed, 5 skipped; round-2 reviewer independently passed 690 checks. All final CI including aggregate coverage and fresh current-base verifier authorization passed. An initial automated merge rejection cited pending checks; direct re-read evidence showed them complete and the same merge interface then succeeded. This does not establish v1.0 qualification.

v1.0 release disposition — 2026-09-08

v1.0 sequencing (#572): settle and verify the SDK profiles actually promised or consumed by qualification before contract freeze. A bounded support repair or explicit unsupported limit is the release slice; a general Python type evaluator is not required.

Found during review of #541 / #539; deferred from that implementation at the user's request.

Evidence

The supported MCP SDK's find_context_parameter inspects the whole function, returns the first matching parameter, and examines immediate generic arguments for a Context subclass. With the installed SDK, a synthetic def generic(holder: list[Context]) -> str returns holder as the injected parameter. The existing loader test instead says list[Context] is a caller input. The reader classifies each parameter independently and can therefore also disagree with first-match behavior or with the SDK's all-or-nothing get_type_hints failure.

This is a framework-semantic mismatch, not a claim that an unsafe release was reproduced. The two Context identity bugs and nullable evidence repair remain in #539.

Proposed follow-up

1. Pin the supported SDK/framework-family injection semantics using their primary source and small synthetic signature fixtures; standalone FastMCP and the SDK must not be assumed identical.
2. Cover generic Context arguments, two Context parameters, an unresolved annotation elsewhere in the signature, imported subclasses/re-exports, and normal application models.
3. Publish a named limitation where static evidence cannot establish the whole-signature result; retain tool discovery and the medium ceiling. Do not execute a target server or import its modules.
4. Reuse the shared idiom corpus and installed/standalone parity tests. Do not build a general Python type evaluator merely to close this edge case.

Acceptance

• Generic and first-match fixtures agree with the specified framework semantics, or explicitly retain a local coverage limit.
• Unresolved external class provenance is not described as established caller ownership solely because its import path lies outside framework packages.
• Canonical Context, ordinary context: str and application Context(BaseModel) preserve their established behavior.
• The documented support boundary names any remaining disagreement, without claiming full injection fidelity.

Primary source: https://github.com/modelcontextprotocol/python-sdk/blob/v1.x/src/mcp/server/fastmcp/utilities/context_injection.py . Main implementation audited at PR #541 commit 89f4967.

Priority and scope

P2 bounded correctness follow-up. Deferred because resolving all SDK/framework-family injection semantics expands the current #539 repair. No new verdict, adapter or runtime path.