Skip to content

feat(core): BaseContext.ext / RequestEnv.ext plugin slot (SEP-2133 mechanism) #2061

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
felixweinberger wants to merge 3 commits into from
+12 −2
Closed

feat(core): BaseContext.ext / RequestEnv.ext plugin slot (SEP-2133 mechanism) #2061

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b2c7792
feat(core): BaseContext.ext / RequestEnv.ext plugin slot (SEP-2133 me…
felixweinberger May 12, 2026
6879b2f
chore(core): drop unused readExt helper and its public export
felixweinberger May 12, 2026
06673f2
docs(core): fix typedoc link to private Protocol.use in BaseContext.ext
felixweinberger May 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 12 additions & 2 deletions packages/core/src/shared/context.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -180,8 +180,18 @@ export type BaseContext = {
};

/**
* Extension slot. Adapters and middleware populate keys here; handlers cast to the
* extension's declared type to read them. Core never reads or writes this field.
* Extension slot (SEP-2133 mechanism). Dispatch middleware registered via
* `use()` populates keys here under the extension's reverse-DNS
* namespace; handlers read via the extension's typed accessor (e.g.
* `taskContext(ctx)` for `tasksPlugin`). Core never reads or writes this field.
*
* @example
* ```ts
* // In a DispatchMiddleware:
* env.ext = { ...env.ext, 'io.modelcontextprotocol/task': { id, store } };
* // In a handler:
* const task = taskContext(ctx); // typed read of ctx.ext['io.modelcontextprotocol/task']
* ```
Comment on lines +188 to +194
Copy link
Copy Markdown

@claude claude Bot May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 nit: per CLAUDE.md "JSDoc @example Code Snippets", @example blocks should use ```ts source="./file.examples.ts#region" fences so pnpm sync:snippets keeps them type-checked — every other @example in packages/core/src follows this, but this one is an inline fence referencing symbols (env, id, store, taskContext) that do not exist yet (tasksPlugin ships in F3). Consider either rewriting the example around readExt() (which this PR does export) in a context.examples.ts //#region, or dropping the @example tag until F3 lands so the snippet can be sourced and type-checked.

Extended reasoning...

What this is

CLAUDE.md:44-48 documents the repo's @example convention:

JSDoc @example tags should pull type-checked code from companion .examples.ts files … Use ```ts source="./file.examples.ts#regionName" fences referencing //#region regionName blocks … Run pnpm sync:snippets to sync example content into JSDoc comments and markdown files.

The new @example on BaseContext.ext (context.ts:188-194) uses a bare ```ts fence with no source= attribute and no companion packages/core/src/shared/context.examples.ts file, so sync:snippets can never validate it.

Why it matters here specifically

Grepping packages/core/src for @example shows this is the only un-sourced example in the core package — sdkErrors.ts, index.ts, protocol.ts, specTypeSchema.ts, and every validators/*.ts example all use source="./*.examples.ts#region" with a matching companion file (8 .examples.ts files exist under packages/core/src). So within core the convention is uniformly followed today, and this PR introduces the first divergence.

More substantively, the snippet references env, id, store, and taskContext(ctx). Per the PR description, tasksPlugin / taskContext ship in F3, not this PR — so the example is forward-referencing API that doesn't exist yet and cannot be type-checked today even if a .examples.ts were added. That is exactly the drift the sourced-example convention is meant to prevent: if F3's eventual API differs (different key, different accessor name), this doc comment silently rots.

Step-by-step

  1. CLAUDE.md:46 says @example fences should carry source="./file.examples.ts#regionName".
  2. ls packages/core/src/shared/*.examples.ts → only protocol.examples.ts; no context.examples.ts.
  3. grep -r "@example" packages/core/src → every hit (sdkErrors.ts:46, validators/types.ts:38, validators/cfWorkerProvider.ts:22/27, validators/fromJsonSchema.ts:18, validators/ajvProvider.ts:25/30/46+, index.ts:44/49, shared/protocol.ts) has source= on the next line. context.ts:188 does not.
  4. The snippet calls taskContext(ctx); grep -r "export function taskContext" packages/ → no matches (it's slated for F3).
  5. Therefore the example is un-type-checked pseudocode that pnpm sync:snippets ignores, and it references not-yet-existing API.

Addressing the "there are other inline examples" objection

It's true a handful of inline @example blocks exist elsewhere in the monorepo (packages/server/src/validators/cfWorker.ts:4, packages/middleware/express/src/auth/metadataRouter.ts:143, packages/server/src/experimental/tasks/server.ts:84/181). However: (a) none of those are in packages/core, where the convention is currently 100% consistent, and (b) those stragglers reference real, in-tree symbols, whereas this snippet references API from a future PR. The combination of "first inline example in core" + "references unshipped symbols" is what makes it worth a nit — not the bare style point on its own.

Suggested fix

Either:

  • Rewrite the example around what this PR actually ships, e.g. in packages/core/src/shared/context.examples.ts: 
    //#region BaseContext_ext_read
import { type BaseContext, readExt } from "@modelcontextprotocol/core";
declare const ctx: BaseContext;
type TaskExt = { id: string };
const task = readExt<TaskExt>(ctx, "io.modelcontextprotocol/task");
//#endregion
    and reference it with ```ts source="./context.examples.ts#BaseContext_ext_read"; or
  • Keep the prose description (which already explains the mechanism well) and drop the @example block until F3 lands taskContext, then add a sourced example.

Severity

nit — this is a documentation-convention issue, not a runtime or type-correctness bug. sync:snippets --check ignores fences without source=, so CI does not fail on it.

*/
ext?: Record<string, unknown>;
};
Expand Down
Loading