feat(compat): add deprecated v1 type aliases (ResourceTemplate, IsomorphicHeaders, RequestInfo)

Adds @deprecated type aliases to core/public for smoother v1→v2 migration:
- ResourceTemplate → ResourceTemplateType (the spec-derived data type)
- IsomorphicHeaders → Headers (standard web type)
- RequestInfo → Request (standard web type)

FetchLike retains its v1 name and was already re-exported.

Server's ResourceTemplate helper class intentionally shadows the deprecated
type alias via named-export-wins-over-export-star ES module semantics; the
import/export lint rule is suppressed at those two sites with an explanatory
comment.

Author: felixweinberger

.changeset/compat-v1-type-aliases.md

@@ -0,0 +1,7 @@
+---
+'@modelcontextprotocol/core': patch
+'@modelcontextprotocol/client': patch
+'@modelcontextprotocol/server': patch
+---
+
+Add deprecated v1 type aliases to the public API surface for smoother migration: `ResourceTemplate` (→ `ResourceTemplateType`), `IsomorphicHeaders` (→ `Headers`), and `RequestInfo` (→ `Request`). `FetchLike` retains its v1 name. All aliases are `@deprecated` and will be removed in v3.

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

@@ -142,3 +142,32 @@ export type { CfWorkerSchemaDraft } from '../../validators/cfWorkerProvider.js';
 // fromJsonSchema is intentionally NOT exported here — the server and client packages
 // provide runtime-aware wrappers that default to the appropriate validator via _shims.
 export type { JsonSchemaType, JsonSchemaValidator, jsonSchemaValidator, JsonSchemaValidatorResult } from '../../validators/types.js';
+
+// ────────────────────────────────────────────────────────────────────────────
+// v1 backwards-compatibility type aliases (deprecated, removed in v3)
+// ────────────────────────────────────────────────────────────────────────────
+
+// Note: a `ResourceTemplate = ResourceTemplateType` alias is intentionally NOT
+// exported here — it conflicts with the server's `ResourceTemplate` class under
+// tsdown bundling. The alias lives only in the `/sdk` meta-package's `types.js`.
+
+/**
+ * @deprecated Use the standard {@linkcode Headers} web type. Removed in v3.
+ *
+ * v1's `IsomorphicHeaders` (`Record<string, string | string[] | undefined>`) is
+ * no longer used; v2 transports surface request headers via the standard
+ * `Headers` API on `ctx.http?.req`.
+ */
+export type IsomorphicHeaders = Headers;
+
+/**
+ * @deprecated Use the standard {@linkcode Request} web type. Removed in v3.
+ *
+ * v1's `RequestInfo` (`{ headers; url? }`) is no longer used; v2's
+ * {@linkcode ServerContext} exposes the originating HTTP request as a standard
+ * `Request` at `ctx.http?.req`.
+ */
+export type RequestInfo = Request;
+
+// `FetchLike` keeps its v1 name and is re-exported above from
+// '../../shared/transport.js' — no alias needed.

packages/core/test/exports/public.compat.test.ts

@@ -0,0 +1,22 @@
+/* eslint-disable @typescript-eslint/no-deprecated */
+import { describe, expect, expectTypeOf, test } from 'vitest';
+import type { FetchLike, IsomorphicHeaders, RequestInfo } from '../../src/exports/public/index.js';
+
+describe('v1 compat type aliases (core/public)', () => {
+    test('IsomorphicHeaders aliases the standard Headers type', () => {
+        expectTypeOf<IsomorphicHeaders>().toEqualTypeOf<Headers>();
+        const h: IsomorphicHeaders = new Headers({ 'content-type': 'application/json' });
+        expect(h.get('content-type')).toBe('application/json');
+    });
+
+    test('RequestInfo aliases the standard Request type', () => {
+        expectTypeOf<RequestInfo>().toEqualTypeOf<Request>();
+        const r: RequestInfo = new Request('http://localhost/mcp');
+        expect(r.url).toBe('http://localhost/mcp');
+    });
+
+    test('FetchLike is re-exported', () => {
+        const f: FetchLike = (url, init) => fetch(url, init);
+        expect(typeof f).toBe('function');
+    });
+});

packages/server/src/index.ts

@@ -23,6 +23,10 @@ export type {
     ResourceMetadata,
     ToolCallback
 } from './server/mcp.js';
+// The `ResourceTemplate` helper class intentionally shadows the deprecated
+// `ResourceTemplate` type alias re-exported from core/public below. ES module
+// semantics resolve this correctly (named export wins over `export *`).
+// eslint-disable-next-line import/export
 export { McpServer, ResourceTemplate } from './server/mcp.js';
 export type { HostHeaderValidationResult } from './server/middleware/hostHeaderValidation.js';
 export { hostHeaderValidationResponse, localhostAllowedHostnames, validateHostHeader } from './server/middleware/hostHeaderValidation.js';
@@ -47,4 +51,5 @@ export { ExperimentalServerTasks } from './experimental/tasks/server.js';
 export { fromJsonSchema } from './fromJsonSchema.js';
 
 // re-export curated public API from core
+// eslint-disable-next-line import/export -- see ResourceTemplate note above
 export * from '@modelcontextprotocol/core/public';