René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Refactor global contextvars request context into explicit parameters","articleBody":"### Description\n\n## Summary\n\nThe Python SDK currently uses a global `contextvars.ContextVar` (e.g. `request_ctx`) to hold per-request state for the server. This enables convenience helpers like `get_request_context()`, but it also introduces implicit dependencies and makes testing, debugging, and refactoring harder.\n\nThis proposal suggests moving towards **explicit context passing** in handlers and eventually **deprecating global request context access**, with a migration path.\n\n## Background\n\nToday, the low-level server and FastMCP rely on a global `ContextVar` that holds a `RequestContext`. Handler code can implicitly call `get_request_context()` without any indication in the function signature that it depends on request-local state.\n\nThis has several drawbacks:\n\n- **Hidden dependencies:** Functions depend on ambient state, not their parameters.\n- **Debugging complexity:** Stack traces do not show where the context came from.\n- **Testability:** Unit tests must set up `ContextVar` state or fall back to full integration tests.\n- **Refactoring risk:** Moving code between modules can silently break if context assumptions change.\n\n## Proposal\n\n### Phase 1 – Explicit context in handler signatures\n\n1. Make `RequestContext` (or a higher-level `Context`) an **explicit parameter** for all tool/resource handlers at the low-level server boundary.\n2. At the FastMCP layer, inject the context explicitly into handler callsites instead of relying on global `ContextVar` lookups.\n3. Keep `get_request_context()` for now, but document it as **deprecated** and implemented in terms of the explicit parameter passing.\n\n### Phase 2 – Internal-only use (or removal) of `ContextVar`\n\n4. Refactor internal call chains so that the `RequestContext` is always passed as an argument rather than read from a global.\n5. Limit any remaining `ContextVar` usage to:\n   - bridging with external frameworks (if needed), or\n   - cross-cutting concerns like tracing where explicit parameter threading is impossible.\n6. Remove `get_request_context()` (or keep only as a thin, clearly discouraged compatibility helper).\n\n### Migration and compatibility\n\n- Provide an explicit, documented pattern for handlers that need context:\n  - e.g. `async def tool(ctx: Context, ...) -\u003e ...`\n- Keep the current behavior working for at least one minor release, with deprecation warnings where appropriate.\n- Update examples and docs to promote explicit context usage.\n\n## Why this matters\n\n- **Testability:** Handlers become pure-ish functions with explicit dependencies.\n- **Debugging:** It’s easier to follow how context flows through the system.\n- **Robustness:** Less risk of accidental context leakage across concurrent requests.\n- **API clarity:** Users see, in signatures, that a handler depends on request context.\n\n## Acceptance criteria\n\n- [ ] All public handler registration paths can accept an explicit context parameter.\n- [ ] Core server internals pass `RequestContext` explicitly rather than relying on `ContextVar`.\n- [ ] `get_request_context()` is either deprecated or clearly documented as a compatibility shim.\n- [ ] Tests no longer need to directly manipulate global request `ContextVar` state.\n- [ ] Documentation updated to show explicit context patterns as the recommended approach.\n\n\n### References\n\n_No response_","author":{"url":"https://github.com/dgenio","@type":"Person","name":"dgenio"},"datePublished":"2025-11-28T11:52:12.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":4},"url":"https://github.com/1684/python-sdk/issues/1684"}