What agents should know before contributing
modelcontextprotocol/typescript-sdk
The official TypeScript SDK for Model Context Protocol servers and clients
Read by Bluet from 7 files written for agents and 300 merged pull requests on 2026-09-24. Not reviewed by the maintainers.
Rules its files tell agents (9)
- docs/troubleshooting.md
mustWhen an era, package, or supported Node.js version is removed, delete its entries in the same change — this pa…
produces it. When an era, package, or supported Node.js version is removed, delete its entries in the same change — this page never accretes. -->
- docs/troubleshooting.md
mustvia server/discover (no fallback in pin mode) — the pin names a revision the server does not offer, and pinnin…
the server did not offer pinned protocol version ... via server/discover (no fallback in pin mode) — the pin names a revision the server does not offer, and pinning never falls back: drop the pin or use 'auto'.
- docs/protocol-versions.md
mustOn stdio, a legacy server that never answers unknown pre-initialize requests stalls connect() for the full pro…
::: warning Do not default a spawn-per-invocation CLI tool to 'auto'. On stdio, a legacy server that never answers unknown pre-initialize requests stalls connect() for the full probe timeout before falling back, and the probe spawns an extra short-lived server process per connect. Keep the default and expose 'auto' (or a pin) as a flag. :::
- docs/behavior-surface-pins.md
mustNever weaken a pin (loosen an exact match, delete an assertion) just to make CI pass — that reopens the silent…
Never weaken a pin (loosen an exact match, delete an assertion) just to make CI pass — that reopens the silent-drift hole the pin exists to close.
- docs/behavior-surface-pins.md
mustThe expectation side must be a literal frozen in the test, never a value imported from src.
The expectation side must be a literal frozen in the test, never a value imported from src. Comparing a source constant against itself pins nothing.
- docs/behavior-surface-pins.md
shouldDon't pin a known bug to make it load-bearing — file an issue instead.
- docs/behavior-surface-pins.md
shouldInternal details that are invisible across the wire and the public API don't need pins.
Pin behavior a deployed peer or consumer can observe. Internal details that are invisible across the wire and the public API don't need pins.
- CONTRIBUTING.md
shouldWe'll close PRs for undiscussed features—not because we don't appreciate the effort, but because every merged…
We'll close PRs for undiscussed features—not because we don't appreciate the effort, but because every merged feature becomes an ongoing maintenance burden for our small team of maintainers. Talking first helps us figure out together whether something belongs in the SDK.
- CLAUDE.md
shouldMechanical renames go in packages/codemod/src/migrations/v1-to-v2/mappings/ and the codemod handles them — do…
When making breaking changes, add to the relevant subsystem section in docs/migration/upgrade-to-v2.md (or docs/migration/support-2026-07-28.md if the change is 2026-07-28-only). Mechanical renames go in packages/codemod/src/migrations/v1-to-v2/mappings/ and the codemod handles them — do not reproduce mapping tables in the guide; link to the mapping file instead.
Decisions its pull requests settled (34)
- #1611[v1.x backport] Default to client_secret_basic when server omits token_endpoint_auth_methods_supported
- #1624add request-time OAuth scope challenges
- #1738RFC 8252 loopback port relaxation
- #1673`v2` - RFC Extract Tasks out of protocol.ts into TaskManager
- #1790consolidate per-request cleanup in _requestWithSchema
- #1972preserve resource URI without trailing slash
- #1974custom-method support (3-arg setRequestHandler + request schema overload)
- #2280bound resumability version gates to supported versions, pin the unsupported-version rejection format
- #2276stop leaking the conformance server and hanging on stale ports
- #2294per-era wire codec interface
- #2315serveStdio — connection-pinned era serving for stdio; remove ServerOptions.eraSupport
- #2305opt-in stdio dual-era serving via ServerOptions.eraSupport; dual-era examples
- #2343name AuthOptions; add iss/skipIssuerMetadataValidation and OAuthClientInformationContext
- #2344SEP-2468 RFC 9207 iss + RFC 8414 §3.3 issuer-echo validation
- #2348SEP-2352 per-authorization-server credential isolation
- #2346SEP-2350 scope step-up — union, retry cap, superset-gated refresh bypass
- #2356SEP-2350 scope step-up — union, retry cap, superset-gated refresh bypass
- #2358SEP-2352 per-authorization-server credential isolation
- #2384make instanceof on SDK error classes work across bundled copies
- #2399bump referee to 0.2.0-alpha.9; arm SEP-2575 diagnostic fixtures; fix post-dispatch -32021 HTTP status
- #2420runtime-neutral requireBearerAuth for web-standard hosts
- #2422runtime-neutral OAuth discovery serving for web-standard hosts
- #2441validate Content-Type by parsed media type instead of substring match
- #2444Validate Content-Type by parsed media type instead of substring match (v1.x)
- #2453trim OWS from standard MCP headers
- #2511accept a cached era verdict on ConnectOptions.prior
- #2455preserve pre-set transport handlers across the version-negotiation probe window
- #2501Export Protocol and mergeCapabilities from client/server package roots
- #2564treat HTTP 401/403 on the negotiation probe as auth failures, not legacy evidence
- #2597treat *.localhost as loopback for OAuth token endpoints
- #2613mirror params.taskId into Mcp-Name for tasks requests (SEP-2663)
- #2668never send notifications/cancelled for the initialize hand…
- #2629add DPoP (RFC 9449) sender-constrained token support
- #2698read HTTP request bodies with a size limit and bound JSON-RPC batch length