René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Revisit FastMCP context injection to reduce “magic” and improve type-safety","articleBody":"### Description\n\n## Summary\n\nFastMCP currently uses introspection to automatically inject a `Context` parameter into tools/resources when it detects a parameter with the right name/type. This is convenient but “magic”:\n\n- it relies on parameter naming/type hints,\n- it’s invisible in function signatures (from a caller’s perspective),\n- it can break silently after refactors.\n\nThis issue proposes making context injection **more explicit and type-safe**, while preserving ergonomics.\n\n## Problems\n\n- **Brittle conventions:** Renaming the parameter or changing the import path of `Context` can silently break injection.\n- **Type checker mismatch:** Type hints show a required parameter, but at runtime the SDK auto-populates it, which can confuse static analysis and IDEs.\n- **New user confusion:** It’s not obvious from examples why a parameter is populated or how to opt into/opt out of it.\n\n## Proposal\n\n1. **Introduce explicit opt-in for context injection**\n\n   For example:\n\n   - Via decorator argument:\n\n     ```python\n     @mcp.tool(inject_context=True)\n     async def my_tool(ctx: Context, ...) -\u003e ...:\n         ...\n     ```\n\n   - Or via a dedicated “injected” marker type, e.g. `ctx: Injected[Context]`.\n\n2. **Document a single, clear convention**\n\n   - If conventions are used (e.g., `_mcp_context` parameter name), make them explicit and heavily documented:\n     - “If you define a parameter named `_mcp_context` with type `Context`, FastMCP will inject it.”\n\n3. **Migration path**\n\n   - Support both the old introspection behavior and the new explicit pattern for at least one minor release.\n   - Add warnings or docs guiding users towards the explicit pattern.\n\n## Why this matters\n\n- **Predictability:** Less “magic” makes it easier to reason about what the SDK is doing.\n- **Tooling:** IDEs and static analyzers can more accurately represent what parameters are expected.\n- **Refactoring safety:** Users are less likely to accidentally break context injection when renaming parameters or types.\n\n## Acceptance criteria\n\n- [ ] There is an explicit, documented way to opt into context injection (decorator flag or marker type).\n- [ ] The existing introspection mechanism is either deprecated or clearly described as legacy.\n- [ ] Examples and docs use the explicit pattern as the recommended approach.\n- [ ] Type checkers can understand the pattern without special configuration.\n\n\n### References\n\n_No response_","author":{"url":"https://github.com/dgenio","@type":"Person","name":"dgenio"},"datePublished":"2025-11-28T14:52:45.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":1},"url":"https://github.com/1695/python-sdk/issues/1695"}