From f36af623a1e250b49ed8b814e93d43ac8bb73464 Mon Sep 17 00:00:00 2001 From: Felix Weinberger Date: Wed, 24 Jun 2026 15:50:25 +0000 Subject: [PATCH 1/4] fix(packaging): inline the fast-uri URIComponent type; drop stale typesVersions The bundled client/server .d.mts left a dangling URIComponent reference: ajv@8.18's published types import it from fast-uri, which ships its types as an export-assigned namespace the dts bundler cannot destructure, so the import was dropped and the bare reference remained (TS2304 for consumers compiling with skipLibCheck: false). A dts-only path mapping now points fast-uri at a small declaration shim so the type is inlined. Runtime code is unaffected. Also drops @modelcontextprotocol/node's stale typesVersions entry for a subpath that no longer ships, and notes in the client/server READMEs that TypeScript >=6.0 needs "types": ["node"] because the published declarations reference Buffer. The json-schema-typed dts.resolve fix from the original branch is already on main; the validator-type subpath reorganization is superseded by the current root-barrel treatment. --- .changeset/validators-subpath-only.md | 7 ++++++ packages/client/README.md | 2 ++ packages/client/tsdown.config.ts | 3 ++- .../src/validators/fastUriShim.d.ts | 24 +++++++++++++++++++ packages/middleware/node/package.json | 7 ------ packages/server/README.md | 2 ++ packages/server/tsdown.config.ts | 3 ++- 7 files changed, 39 insertions(+), 9 deletions(-) create mode 100644 .changeset/validators-subpath-only.md create mode 100644 packages/core-internal/src/validators/fastUriShim.d.ts diff --git a/.changeset/validators-subpath-only.md b/.changeset/validators-subpath-only.md new file mode 100644 index 0000000000..809e64277d --- /dev/null +++ b/.changeset/validators-subpath-only.md @@ -0,0 +1,7 @@ +--- +'@modelcontextprotocol/server': patch +'@modelcontextprotocol/client': patch +'@modelcontextprotocol/node': patch +--- + +Fix two declaration-file issues for consumers compiling with `skipLibCheck: false`: the bundled `.d.mts` no longer leaves a dangling `URIComponent` reference (ajv's published types import it from `fast-uri`, whose `export =` namespace the dts bundler cannot destructure — the type is now inlined via a dts-only path mapping), and `@modelcontextprotocol/node` drops a stale `typesVersions` entry pointing at a subpath that no longer ships. Package READMEs note that TypeScript ≥6.0 requires `"types": ["node"]` since the published declarations reference `Buffer`. diff --git a/packages/client/README.md b/packages/client/README.md index e9ce66f511..3248ec9859 100644 --- a/packages/client/README.md +++ b/packages/client/README.md @@ -16,6 +16,8 @@ The MCP (Model Context Protocol) TypeScript client SDK. Build MCP clients that c npm install @modelcontextprotocol/client@alpha ``` +TypeScript ≥6.0 no longer auto-includes `@types/*` — add `"types": ["node"]` to your `tsconfig.json` `compilerOptions` (the published `.d.mts` references `Buffer`). + ## Documentation - **[Repository README](https://github.com/modelcontextprotocol/typescript-sdk#readme)** — overview, package layout, examples diff --git a/packages/client/tsdown.config.ts b/packages/client/tsdown.config.ts index 883fbf6f40..f0d1949e49 100644 --- a/packages/client/tsdown.config.ts +++ b/packages/client/tsdown.config.ts @@ -20,10 +20,11 @@ export default defineConfig({ shims: true, dts: { resolver: 'tsc', - resolve: ['ajv', 'ajv-formats'], + resolve: ['ajv', 'ajv-formats', 'json-schema-typed'], compilerOptions: { baseUrl: '.', paths: { + 'fast-uri': ['../core-internal/src/validators/fastUriShim.d.ts'], '@modelcontextprotocol/core-internal': ['../core-internal/src/index.ts'], '@modelcontextprotocol/core-internal/public': ['../core-internal/src/exports/public/index.ts'], '@modelcontextprotocol/core-internal/validators/ajv': ['../core-internal/src/validators/ajvProvider.ts'], diff --git a/packages/core-internal/src/validators/fastUriShim.d.ts b/packages/core-internal/src/validators/fastUriShim.d.ts new file mode 100644 index 0000000000..e2f5e21506 --- /dev/null +++ b/packages/core-internal/src/validators/fastUriShim.d.ts @@ -0,0 +1,24 @@ +/** + * dts-bundling shim for `fast-uri`. + * + * ajv@8.18.0's published .d.ts does `import { URIComponent } from "fast-uri"`, + * but fast-uri ships its types as `export = namespace`, which rolldown's dts + * bundler can't destructure into a named import — it drops the import and + * leaves a dangling `URIComponent` reference in the bundled .d.mts (TS2304 for + * downstream consumers with `skipLibCheck: false`). + * + * The server/client tsdown configs map `fast-uri` to this file via + * `dts.compilerOptions.paths` so the type is inlined as a plain named export. + * Runtime code is unaffected (this is a `.d.ts`; the path mapping is dts-only). + */ +export interface URIComponent { + scheme?: string; + userinfo?: string; + host?: string; + port?: number | string; + path?: string; + query?: string; + fragment?: string; + reference?: string; + error?: string; +} diff --git a/packages/middleware/node/package.json b/packages/middleware/node/package.json index 955f02eabe..3f5feb047e 100644 --- a/packages/middleware/node/package.json +++ b/packages/middleware/node/package.json @@ -27,13 +27,6 @@ } }, "types": "./dist/index.d.mts", - "typesVersions": { - "*": { - "sse": [ - "dist/sse.d.mts" - ] - } - }, "files": [ "dist" ], diff --git a/packages/server/README.md b/packages/server/README.md index 0dfe938209..7f46a411df 100644 --- a/packages/server/README.md +++ b/packages/server/README.md @@ -16,6 +16,8 @@ The MCP (Model Context Protocol) TypeScript server SDK. Build MCP servers that e npm install @modelcontextprotocol/server@alpha ``` +TypeScript ≥6.0 no longer auto-includes `@types/*` — add `"types": ["node"]` to your `tsconfig.json` `compilerOptions` (the published `.d.mts` references `Buffer`). + Optional framework adapters: [`@modelcontextprotocol/express`](https://www.npmjs.com/package/@modelcontextprotocol/express), [`@modelcontextprotocol/hono`](https://www.npmjs.com/package/@modelcontextprotocol/hono), [`@modelcontextprotocol/node`](https://www.npmjs.com/package/@modelcontextprotocol/node). diff --git a/packages/server/tsdown.config.ts b/packages/server/tsdown.config.ts index 9908a6e730..3ae3158242 100644 --- a/packages/server/tsdown.config.ts +++ b/packages/server/tsdown.config.ts @@ -19,10 +19,11 @@ export default defineConfig({ shims: true, dts: { resolver: 'tsc', - resolve: ['ajv', 'ajv-formats'], + resolve: ['ajv', 'ajv-formats', 'json-schema-typed'], compilerOptions: { baseUrl: '.', paths: { + 'fast-uri': ['../core-internal/src/validators/fastUriShim.d.ts'], '@modelcontextprotocol/core-internal': ['../core-internal/src/index.ts'], '@modelcontextprotocol/core-internal/public': ['../core-internal/src/exports/public/index.ts'], '@modelcontextprotocol/core-internal/validators/ajv': ['../core-internal/src/validators/ajvProvider.ts'], From b4beeffe6ae627aca8ed17cbd0ea490027e4c60a Mon Sep 17 00:00:00 2001 From: Felix Weinberger Date: Tue, 30 Jun 2026 13:52:37 +0000 Subject: [PATCH 2/4] fix(packaging): review follow-ups for the declaration-file fixes Complete the fast-uri URIComponent shim to a field-for-field copy of fast-uri@3.1.0 (the first cut carried 9 of 14 fields; consumers implementing a custom uriResolver would have seen property errors on the URN/WebSocket fields) and pin the source version in the comment. Add a dist-types smoke to CI: compiles a small consumer against the built .d.mts of client and server (root + validators/ajv subpath) with skipLibCheck: false. The dts bundler emits dangling-reference cases only as non-fatal warnings - its failOnWarn setting does not fail on them - so nothing else catches a dependency bump that reintroduces one. Rename and reword the changeset: the previous file name and text described an earlier approach; the entry now also covers the json-schema-typed inlining, which this branch relies on from dts.resolve. --- .changeset/dist-types-skiplibcheck.md | 7 +++ .changeset/validators-subpath-only.md | 7 --- .github/workflows/main.yml | 1 + .../src/validators/fastUriShim.d.ts | 7 +++ scripts/smoke-dist-types.mjs | 58 +++++++++++++++++++ 5 files changed, 73 insertions(+), 7 deletions(-) create mode 100644 .changeset/dist-types-skiplibcheck.md delete mode 100644 .changeset/validators-subpath-only.md create mode 100644 scripts/smoke-dist-types.mjs diff --git a/.changeset/dist-types-skiplibcheck.md b/.changeset/dist-types-skiplibcheck.md new file mode 100644 index 0000000000..a62a29db9d --- /dev/null +++ b/.changeset/dist-types-skiplibcheck.md @@ -0,0 +1,7 @@ +--- +'@modelcontextprotocol/server': patch +'@modelcontextprotocol/client': patch +'@modelcontextprotocol/node': patch +--- + +Fix the published declaration files for consumers compiling with `skipLibCheck: false`: the bundled `.d.mts` no longer leaves a dangling `URIComponent` reference (ajv's published types import it from `fast-uri`, whose export-assigned namespace the dts bundler cannot link — the type is now inlined via a dts-only path mapping), and no longer imports `json-schema-typed` from an undeclared dependency (it is inlined via `dts.resolve`). `@modelcontextprotocol/node` drops a stale `typesVersions` entry pointing at a subpath that never shipped. Package READMEs note that TypeScript >=6.0 requires `"types": ["node"]` since the published declarations reference `Buffer`. diff --git a/.changeset/validators-subpath-only.md b/.changeset/validators-subpath-only.md deleted file mode 100644 index 809e64277d..0000000000 --- a/.changeset/validators-subpath-only.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -'@modelcontextprotocol/server': patch -'@modelcontextprotocol/client': patch -'@modelcontextprotocol/node': patch ---- - -Fix two declaration-file issues for consumers compiling with `skipLibCheck: false`: the bundled `.d.mts` no longer leaves a dangling `URIComponent` reference (ajv's published types import it from `fast-uri`, whose `export =` namespace the dts bundler cannot destructure — the type is now inlined via a dts-only path mapping), and `@modelcontextprotocol/node` drops a stale `typesVersions` entry pointing at a subpath that no longer ships. Package READMEs note that TypeScript ≥6.0 requires `"types": ["node"]` since the published declarations reference `Buffer`. diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 5686454414..1b47f899c6 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -31,6 +31,7 @@ jobs: - run: pnpm install - run: pnpm run check:all - run: pnpm run build:all + - run: node scripts/smoke-dist-types.mjs test: runs-on: ubuntu-latest diff --git a/packages/core-internal/src/validators/fastUriShim.d.ts b/packages/core-internal/src/validators/fastUriShim.d.ts index e2f5e21506..d607d15c93 100644 --- a/packages/core-internal/src/validators/fastUriShim.d.ts +++ b/packages/core-internal/src/validators/fastUriShim.d.ts @@ -11,6 +11,8 @@ * `dts.compilerOptions.paths` so the type is inlined as a plain named export. * Runtime code is unaffected (this is a `.d.ts`; the path mapping is dts-only). */ +// Field-for-field copy of fast-uri@3.1.0's URIComponent (types/index.d.ts). +// Keep in sync when bumping fast-uri/ajv. export interface URIComponent { scheme?: string; userinfo?: string; @@ -20,5 +22,10 @@ export interface URIComponent { query?: string; fragment?: string; reference?: string; + nid?: string; + nss?: string; + resourceName?: string; + secure?: boolean; + uuid?: string; error?: string; } diff --git a/scripts/smoke-dist-types.mjs b/scripts/smoke-dist-types.mjs new file mode 100644 index 0000000000..ab56fb142f --- /dev/null +++ b/scripts/smoke-dist-types.mjs @@ -0,0 +1,58 @@ +// Compiles a small consumer against the BUILT declaration files with +// `skipLibCheck: false`, catching dangling type references that the dts +// bundler emits only as non-fatal warnings (its failOnWarn does not fail on +// MISSING_EXPORT). Run after `pnpm build:all`. +import { execFileSync } from 'node:child_process'; +import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import path from 'node:path'; + +const repo = path.resolve(import.meta.dirname, '..'); +const dir = mkdtempSync(path.join(tmpdir(), 'dist-types-smoke-')); +try { + writeFileSync( + path.join(dir, 'consumer.ts'), + [ + "import { Client } from '@modelcontextprotocol/client';", + "import type { AjvJsonSchemaValidator as ClientAjv } from '@modelcontextprotocol/client';", + "import { AjvJsonSchemaValidator } from '@modelcontextprotocol/client/validators/ajv';", + "import { McpServer } from '@modelcontextprotocol/server';", + "import { AjvJsonSchemaValidator as ServerAjv } from '@modelcontextprotocol/server/validators/ajv';", + "export const c = new Client({ name: 'smoke', version: '1.0.0' });", + "export const s = new McpServer({ name: 'smoke', version: '1.0.0' });", + 'export type T = ClientAjv;', + 'export { AjvJsonSchemaValidator, ServerAjv };', + '' + ].join('\n') + ); + writeFileSync( + path.join(dir, 'tsconfig.json'), + JSON.stringify( + { + compilerOptions: { + strict: true, + noEmit: true, + skipLibCheck: false, + module: 'esnext', + moduleResolution: 'bundler', + target: 'es2022', + types: ['node'], + typeRoots: [path.join(repo, 'node_modules', '@types')], + paths: { + '@modelcontextprotocol/client': [path.join(repo, 'packages/client/dist/index.d.mts')], + '@modelcontextprotocol/client/validators/ajv': [path.join(repo, 'packages/client/dist/validators/ajv.d.mts')], + '@modelcontextprotocol/server': [path.join(repo, 'packages/server/dist/index.d.mts')], + '@modelcontextprotocol/server/validators/ajv': [path.join(repo, 'packages/server/dist/validators/ajv.d.mts')] + } + }, + include: ['consumer.ts'] + }, + null, + 2 + ) + ); + execFileSync('pnpm', ['exec', 'tsc', '-p', dir], { cwd: repo, stdio: 'inherit' }); + console.log('dist-types smoke: clean (skipLibCheck: false)'); +} finally { + rmSync(dir, { recursive: true, force: true }); +} From b3a29325409807f1e8480a60d52b6a7179086c94 Mon Sep 17 00:00:00 2001 From: Felix Weinberger Date: Tue, 30 Jun 2026 14:24:47 +0000 Subject: [PATCH 3/4] test(packaging): cover every public declaration entry point in the dist-types smoke Review follow-up: the smoke is the only hard gate for dangling references in the built declarations, so it now also compiles validators/cf-worker and stdio for both packages, not just the root and the ajv subpath. --- scripts/smoke-dist-types.mjs | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/scripts/smoke-dist-types.mjs b/scripts/smoke-dist-types.mjs index ab56fb142f..16af6605f4 100644 --- a/scripts/smoke-dist-types.mjs +++ b/scripts/smoke-dist-types.mjs @@ -16,12 +16,16 @@ try { "import { Client } from '@modelcontextprotocol/client';", "import type { AjvJsonSchemaValidator as ClientAjv } from '@modelcontextprotocol/client';", "import { AjvJsonSchemaValidator } from '@modelcontextprotocol/client/validators/ajv';", + "import { CfWorkerJsonSchemaValidator as ClientCf } from '@modelcontextprotocol/client/validators/cf-worker';", + "import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';", "import { McpServer } from '@modelcontextprotocol/server';", "import { AjvJsonSchemaValidator as ServerAjv } from '@modelcontextprotocol/server/validators/ajv';", + "import { CfWorkerJsonSchemaValidator as ServerCf } from '@modelcontextprotocol/server/validators/cf-worker';", + "import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';", "export const c = new Client({ name: 'smoke', version: '1.0.0' });", "export const s = new McpServer({ name: 'smoke', version: '1.0.0' });", 'export type T = ClientAjv;', - 'export { AjvJsonSchemaValidator, ServerAjv };', + 'export { AjvJsonSchemaValidator, ServerAjv, ClientCf, ServerCf, StdioClientTransport, StdioServerTransport };', '' ].join('\n') ); @@ -41,8 +45,16 @@ try { paths: { '@modelcontextprotocol/client': [path.join(repo, 'packages/client/dist/index.d.mts')], '@modelcontextprotocol/client/validators/ajv': [path.join(repo, 'packages/client/dist/validators/ajv.d.mts')], + '@modelcontextprotocol/client/validators/cf-worker': [ + path.join(repo, 'packages/client/dist/validators/cfWorker.d.mts') + ], + '@modelcontextprotocol/client/stdio': [path.join(repo, 'packages/client/dist/stdio.d.mts')], '@modelcontextprotocol/server': [path.join(repo, 'packages/server/dist/index.d.mts')], - '@modelcontextprotocol/server/validators/ajv': [path.join(repo, 'packages/server/dist/validators/ajv.d.mts')] + '@modelcontextprotocol/server/validators/ajv': [path.join(repo, 'packages/server/dist/validators/ajv.d.mts')], + '@modelcontextprotocol/server/validators/cf-worker': [ + path.join(repo, 'packages/server/dist/validators/cfWorker.d.mts') + ], + '@modelcontextprotocol/server/stdio': [path.join(repo, 'packages/server/dist/stdio.d.mts')] } }, include: ['consumer.ts'] From f5ef187ff4a0a129f043de1151d316deb233c688 Mon Sep 17 00:00:00 2001 From: Felix Weinberger Date: Tue, 30 Jun 2026 14:29:56 +0000 Subject: [PATCH 4/4] fix(packaging): drop the stale zod-schemas typesVersions entry from server Review follow-up: same class as the node sse entry this PR removes - the mapping points at dist/zodSchemas.d.mts, which has no source, no build entry, and no exports subpath, so it never shipped. --- .changeset/dist-types-skiplibcheck.md | 2 +- packages/server/package.json | 3 --- 2 files changed, 1 insertion(+), 4 deletions(-) diff --git a/.changeset/dist-types-skiplibcheck.md b/.changeset/dist-types-skiplibcheck.md index a62a29db9d..65bdc0e653 100644 --- a/.changeset/dist-types-skiplibcheck.md +++ b/.changeset/dist-types-skiplibcheck.md @@ -4,4 +4,4 @@ '@modelcontextprotocol/node': patch --- -Fix the published declaration files for consumers compiling with `skipLibCheck: false`: the bundled `.d.mts` no longer leaves a dangling `URIComponent` reference (ajv's published types import it from `fast-uri`, whose export-assigned namespace the dts bundler cannot link — the type is now inlined via a dts-only path mapping), and no longer imports `json-schema-typed` from an undeclared dependency (it is inlined via `dts.resolve`). `@modelcontextprotocol/node` drops a stale `typesVersions` entry pointing at a subpath that never shipped. Package READMEs note that TypeScript >=6.0 requires `"types": ["node"]` since the published declarations reference `Buffer`. +Fix the published declaration files for consumers compiling with `skipLibCheck: false`: the bundled `.d.mts` no longer leaves a dangling `URIComponent` reference (ajv's published types import it from `fast-uri`, whose export-assigned namespace the dts bundler cannot link — the type is now inlined via a dts-only path mapping), and no longer imports `json-schema-typed` from an undeclared dependency (it is inlined via `dts.resolve`). `@modelcontextprotocol/node` and `@modelcontextprotocol/server` drop stale `typesVersions` entries pointing at subpaths that never shipped. Package READMEs note that TypeScript >=6.0 requires `"types": ["node"]` since the published declarations reference `Buffer`. diff --git a/packages/server/package.json b/packages/server/package.json index 76bbb7364e..b6a0b2337d 100644 --- a/packages/server/package.json +++ b/packages/server/package.json @@ -64,9 +64,6 @@ "validators/cf-worker": [ "dist/validators/cfWorker.d.mts" ], - "zod-schemas": [ - "dist/zodSchemas.d.mts" - ], "stdio": [ "dist/stdio.d.mts" ]