From 2363a096733e5b43e0cadde995767dfca50b418f Mon Sep 17 00:00:00 2001
From: Felix Weinberger <fweinberger@anthropic.com>
Date: Wed, 15 Apr 2026 12:00:09 +0000
Subject: [PATCH] feat(compat): add deprecated v1 type aliases
 (ResourceTemplate, IsomorphicHeaders, RequestInfo)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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.
---
 .changeset/compat-v1-type-aliases.md          |  7 ++++++
 packages/core/src/exports/public/index.ts     | 23 +++++++++++++++++++
 .../core/test/exports/public.compat.test.ts   | 21 +++++++++++++++++
 3 files changed, 51 insertions(+)
 create mode 100644 .changeset/compat-v1-type-aliases.md
 create mode 100644 packages/core/test/exports/public.compat.test.ts

diff --git a/.changeset/compat-v1-type-aliases.md b/.changeset/compat-v1-type-aliases.md
new file mode 100644
index 000000000..9ff92dbed
--- /dev/null
+++ b/.changeset/compat-v1-type-aliases.md
@@ -0,0 +1,7 @@
+---
+'@modelcontextprotocol/core': patch
+'@modelcontextprotocol/client': patch
+'@modelcontextprotocol/server': patch
+---
+
+Add v1 type aliases to the public API surface for smoother migration: `IsomorphicHeaders` (→ `Headers`) and `RequestInfo` (→ `Request`). `FetchLike` retains its v1 name.
diff --git a/packages/core/src/exports/public/index.ts b/packages/core/src/exports/public/index.ts
index 2dc1e13a8..d7cd5d3b8 100644
--- a/packages/core/src/exports/public/index.ts
+++ b/packages/core/src/exports/public/index.ts
@@ -142,3 +142,26 @@ 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
+// ────────────────────────────────────────────────────────────────────────────
+
+// 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 `Headers` web type. v2 transports surface
+ * request headers via `Headers` on `ctx.http?.req`.
+ */
+export type IsomorphicHeaders = Headers;
+
+/**
+ * @deprecated Use the standard `Request` web type. v2's {@linkcode ServerContext}
+ * exposes the originating HTTP 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.
diff --git a/packages/core/test/exports/public.compat.test.ts b/packages/core/test/exports/public.compat.test.ts
new file mode 100644
index 000000000..c28e9ffb9
--- /dev/null
+++ b/packages/core/test/exports/public.compat.test.ts
@@ -0,0 +1,21 @@
+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');
+    });
+});