fix(packaging): inline the fast-uri URIComponent type; drop stale typesVersions (#2394)

Author: felixweinberger

.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` 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`.

.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

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

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'],

packages/core-internal/src/validators/fastUriShim.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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).
+ */
+// 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;
+    host?: string;
+    port?: number | string;
+    path?: string;
+    query?: string;
+    fragment?: string;
+    reference?: string;
+    nid?: string;
+    nss?: string;
+    resourceName?: string;
+    secure?: boolean;
+    uuid?: string;
+    error?: string;
+}

packages/middleware/node/package.json

@@ -27,13 +27,6 @@
         }
     },
     "types": "./dist/index.d.mts",
-    "typesVersions": {
-        "*": {
-            "sse": [
-                "dist/sse.d.mts"
-            ]
-        }
-    },
     "files": [
         "dist"
     ],

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).
 

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"
             ]

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'],

scripts/smoke-dist-types.mjs

@@ -0,0 +1,70 @@
+// 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 { 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, ClientCf, ServerCf, StdioClientTransport, StdioServerTransport };',
+            ''
+        ].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/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/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']
+            },
+            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 });
+}