modelcontextprotocol / modelcontextprotocol/python-sdk

Refactor handler context to be transport- and handler-type-aware

Open
#2,021 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

P1 v2
Dominant language
Python
Stars
24.3k
Forks
4k
Avg merge
1d 1h
Merged PRs (30d)
31

Description

The current RequestContext / ServerRequestContext design has a few rough edges that warrant a dedicated refactor:

  1. Request vs notification context — Request handlers have request_id and meta, notification handlers do not. Currently request_id is optional (RequestId | None) on a single shared type, which loses type safety. Ideally these would be distinct types so request handlers get a context where request_id is always present, and notification handlers get one where it does not exist.

  2. Transport-specific context — The request_context field on ServerMessageMetadata is typed as Any because the server layer is transport-agnostic (e.g. it is a Starlette Request for HTTP transports, None for stdio). A better design would let transports provide their own typed context that handlers can access without casting.

These two concerns are related — both point toward making the context type more precise depending on how and where a handler is invoked.

AI Disclaimer

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing RequestContext and ServerRequestContext through handler entry points, then inspect ServerMessageMetadata.request_context and the transport cases mentioned for Starlette Request and stdio. Compare how request and notification handlers receive context and how transport-specific values are accessed. Done means the intended type boundaries and transport behavior are defined without relying on Any or optional request IDs.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
backend-api-design
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.