feat(compat): add deprecated flat ctx.* getters + RequestHandlerExtra alias

v1 handler signatures read context fields flat (extra.signal, extra.requestId,
extra._meta, extra.authInfo, extra.sendNotification, extra.sendRequest). v2
nests these under ctx.mcpReq / ctx.http.

This adds non-enumerable forwarding getters on the context object so v1 handlers
compile and run unchanged, with a one-time stderr deprecation warning per field.
Also adds the RequestHandlerExtra<R, N> type alias (= ServerContext) so v1 type
imports keep resolving.

All marked @deprecated; removed in v3.

Author: felixweinberger

.changeset/ctx-flat-compat-getters.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/core': patch
+---
+
+v1-compat: add deprecated flat-field getters (`signal`, `requestId`, `_meta`, `authInfo`, `sendNotification`, `sendRequest`) on the handler context that forward to the nested `ctx.mcpReq` / `ctx.http` fields, plus the `RequestHandlerExtra` type alias. Allows v1 handler signatures to compile and run unchanged. Removed in v3.

packages/core/src/exports/public/index.ts

@@ -45,6 +45,8 @@ export type {
     NotificationOptions,
     ProgressCallback,
     ProtocolOptions,
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    RequestHandlerExtra,
     RequestOptions,
     ServerContext
 } from '../../shared/protocol.js';

packages/core/src/shared/protocol.ts

@@ -44,6 +44,7 @@ import {
     ProtocolErrorCode,
     SUPPORTED_PROTOCOL_VERSIONS
 } from '../types/index.js';
+import { deprecate } from '../util/deprecate.js';
 import type { AnySchema, SchemaOutput } from '../util/schema.js';
 import { parseSchema } from '../util/schema.js';
 import type { TaskContext, TaskManagerHost, TaskManagerOptions, TaskRequestOptions } from './taskManager.js';
@@ -227,6 +228,25 @@ export type BaseContext = {
      * Task context, available when task storage is configured.
      */
     task?: TaskContext;
+
+    /** @deprecated Use `ctx.mcpReq.signal`. Removed in v3. */
+    signal: AbortSignal;
+    /** @deprecated Use `ctx.mcpReq.id`. Removed in v3. */
+    requestId: RequestId;
+    /** @deprecated Use `ctx.mcpReq._meta`. Removed in v3. */
+    _meta?: RequestMeta;
+    /** @deprecated Use `ctx.http?.authInfo`. Removed in v3. */
+    authInfo?: AuthInfo;
+    /** @deprecated Use `ctx.mcpReq.notify`. Removed in v3. */
+    sendNotification: (notification: Notification) => Promise<void>;
+    /** @deprecated Use `ctx.mcpReq.send`. Removed in v3. */
+    sendRequest: <T extends AnySchema>(request: Request, resultSchema: T, options?: RequestOptions) => Promise<SchemaOutput<T>>;
+    /** @deprecated Use `ctx.task?.store`. Removed in v3. */
+    taskStore?: TaskContext['store'];
+    /** @deprecated Use `ctx.task?.id`. Removed in v3. */
+    taskId?: TaskContext['id'];
+    /** @deprecated Use `ctx.task?.requestedTtl`. Removed in v3. */
+    taskRequestedTtl?: TaskContext['requestedTtl'];
 };
 
 /**
@@ -279,6 +299,54 @@ export type ServerContext = BaseContext & {
  */
 export type ClientContext = BaseContext;
 
+/**
+ * Flat-field shape of the v1 handler context. v2 nests these under
+ * {@linkcode BaseContext.mcpReq | ctx.mcpReq} / {@linkcode BaseContext.http | ctx.http}.
+ * Kept as deprecated forwarding properties on the context object so v1 handlers
+ * compile and run unchanged.
+ *
+ * @deprecated Use the nested fields on `ctx.mcpReq` / `ctx.http` instead. Will be removed in v3.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- phantom params kept for v1 source compatibility
+export type RequestHandlerExtra<_Req = unknown, _Notif = unknown> = ServerContext;
+
+// --- v1-compat: flat ctx.* getters (internal) ---
+
+function legacyFieldGetter(key: string, target: string, value: () => unknown): PropertyDescriptor {
+    return {
+        enumerable: false,
+        configurable: true,
+        get() {
+            deprecate(`ctx.${key}`, `ctx.${key} is deprecated. Use ${target} instead. Removed in v3.`);
+            return value();
+        }
+    };
+}
+
+/**
+ * Attaches v1's flat `extra.*` fields to the context object as deprecated
+ * forwarding getters. v2 nests these under `ctx.mcpReq` / `ctx.http`.
+ *
+ * @internal
+ */
+function attachLegacyContextFields(
+    ctx: BaseContext,
+    sendRequest: <T extends AnySchema>(r: Request, s: T, o?: RequestOptions) => Promise<SchemaOutput<T>>,
+    sendNotification: (n: Notification) => Promise<void>
+): void {
+    Object.defineProperties(ctx, {
+        signal: legacyFieldGetter('signal', 'ctx.mcpReq.signal', () => ctx.mcpReq.signal),
+        requestId: legacyFieldGetter('requestId', 'ctx.mcpReq.id', () => ctx.mcpReq.id),
+        _meta: legacyFieldGetter('_meta', 'ctx.mcpReq._meta', () => ctx.mcpReq._meta),
+        authInfo: legacyFieldGetter('authInfo', 'ctx.http?.authInfo', () => ctx.http?.authInfo),
+        sendNotification: legacyFieldGetter('sendNotification', 'ctx.mcpReq.notify', () => sendNotification),
+        sendRequest: legacyFieldGetter('sendRequest', 'ctx.mcpReq.send', () => sendRequest),
+        taskStore: legacyFieldGetter('taskStore', 'ctx.task?.store', () => ctx.task?.store),
+        taskId: legacyFieldGetter('taskId', 'ctx.task?.id', () => ctx.task?.id),
+        taskRequestedTtl: legacyFieldGetter('taskRequestedTtl', 'ctx.task?.requestedTtl', () => ctx.task?.requestedTtl)
+    });
+}
+
 /**
  * Information about a request's timeout state
  */
@@ -604,8 +672,11 @@ export abstract class Protocol<ContextT extends BaseContext> {
             },
             http: extra?.authInfo ? { authInfo: extra.authInfo } : undefined,
             task: taskContext
-        };
+            // Deprecated flat fields (signal, requestId, sendNotification, sendRequest, task*) are
+            // attached as getters by attachLegacyContextFields() below.
+        } as BaseContext;
         const ctx = this.buildContext(baseCtx, extra);
+        attachLegacyContextFields(ctx, sendRequest, sendNotification);
 
         // Starting with Promise.resolve() puts any synchronous errors into the monad as well.
         Promise.resolve()

packages/core/test/shared/protocol.compat.test.ts

@@ -0,0 +1,113 @@
+/* eslint-disable @typescript-eslint/no-deprecated */
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+
+import type { BaseContext, RequestHandlerExtra, ServerContext } from '../../src/shared/protocol.js';
+import { Protocol } from '../../src/shared/protocol.js';
+import type { Transport } from '../../src/shared/transport.js';
+import type { JSONRPCMessage } from '../../src/types/index.js';
+import { _resetDeprecationWarnings } from '../../src/util/deprecate.js';
+
+class TestProtocolImpl extends Protocol<BaseContext> {
+    protected assertCapabilityForMethod(): void {}
+    protected assertNotificationCapability(): void {}
+    protected assertRequestHandlerCapability(): void {}
+    protected assertTaskCapability(): void {}
+    protected assertTaskHandlerCapability(): void {}
+    protected buildContext(ctx: BaseContext): BaseContext {
+        return ctx;
+    }
+}
+
+class MockTransport implements Transport {
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: (message: unknown) => void;
+
+    async start(): Promise<void> {}
+    async close(): Promise<void> {
+        this.onclose?.();
+    }
+    async send(_message: JSONRPCMessage): Promise<void> {}
+}
+
+describe('v1-compat: flat ctx.* getters', () => {
+    let protocol: Protocol<BaseContext>;
+    let transport: MockTransport;
+    let warnSpy: ReturnType<typeof vi.spyOn>;
+
+    beforeEach(() => {
+        _resetDeprecationWarnings();
+        warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        protocol = new TestProtocolImpl();
+        transport = new MockTransport();
+    });
+
+    afterEach(() => {
+        warnSpy.mockRestore();
+    });
+
+    test('ctx.signal forwards to ctx.mcpReq.signal and warns once', async () => {
+        await protocol.connect(transport);
+
+        let captured: BaseContext | undefined;
+        const done = new Promise<void>(resolve => {
+            protocol.setRequestHandler('ping', (_request, ctx) => {
+                captured = ctx;
+                resolve();
+                return {};
+            });
+        });
+
+        transport.onmessage?.({ jsonrpc: '2.0', id: 1, method: 'ping', params: {} });
+        await done;
+
+        expect(captured).toBeDefined();
+        const ctx = captured as BaseContext;
+
+        // Flat getters forward to nested fields
+        expect(ctx.signal).toBe(ctx.mcpReq.signal);
+        expect(ctx.requestId).toBe(ctx.mcpReq.id);
+        expect(ctx._meta).toBe(ctx.mcpReq._meta);
+        expect(ctx.authInfo).toBe(ctx.http?.authInfo);
+        expect(ctx.sendNotification).toBeTypeOf('function');
+        expect(ctx.sendRequest).toBeTypeOf('function');
+
+        // Each key warns once; second access does not re-warn
+        const before = warnSpy.mock.calls.length;
+        expect(ctx.signal).toBe(ctx.mcpReq.signal);
+        expect(warnSpy.mock.calls.length).toBe(before);
+
+        // Exactly one warning per distinct key (6 keys touched above)
+        expect(warnSpy).toHaveBeenCalledTimes(6);
+        expect(warnSpy.mock.calls[0]?.[0]).toContain('ctx.signal is deprecated');
+    });
+
+    test('flat getters are non-enumerable (do not pollute spreads)', async () => {
+        await protocol.connect(transport);
+
+        let captured: BaseContext | undefined;
+        const done = new Promise<void>(resolve => {
+            protocol.setRequestHandler('ping', (_request, ctx) => {
+                captured = ctx;
+                resolve();
+                return {};
+            });
+        });
+
+        transport.onmessage?.({ jsonrpc: '2.0', id: 2, method: 'ping', params: {} });
+        await done;
+
+        const keys = Object.keys(captured as BaseContext);
+        expect(keys).not.toContain('signal');
+        expect(keys).not.toContain('requestId');
+        // Spreading should not trigger the deprecated getter
+        void { ...(captured as BaseContext) };
+        expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    test('RequestHandlerExtra<R, N> is a ServerContext alias (type-level)', () => {
+        // Compile-time assertion: RequestHandlerExtra is assignable to/from ServerContext.
+        const check = (ctx: ServerContext): RequestHandlerExtra<unknown, unknown> => ctx;
+        void check;
+    });
+});