perf: resolve schema modules from @modelcontextprotocol/core instead of inlining them

.changeset/externalize-core-schemas.md

@@ -0,0 +1,12 @@
+---
+'@modelcontextprotocol/client': minor
+'@modelcontextprotocol/server': minor
+'@modelcontextprotocol/server-legacy': minor
+---
+
+Resolve the spec and OAuth schema modules from `@modelcontextprotocol/core` at
+runtime instead of inlining a copy into each package's bundle. `client`,
+`server`, and `server-legacy` gain a runtime dependency on
+`@modelcontextprotocol/core`, and their builds mark it external so the schema
+definitions ship once instead of once per package. Public import paths and the
+exported API are unchanged.

CLAUDE.md

@@ -70,7 +70,7 @@ The SDK separates internal code from the public API surface:
 - **`@modelcontextprotocol/core-internal`** (main entry, `packages/core-internal/src/index.ts`) — Internal barrel. Exports everything (including Zod schemas, Protocol class, stdio utils). Only consumed by sibling packages within the monorepo (`private: true`).
 - **`@modelcontextprotocol/core-internal/public`** (`packages/core-internal/src/exports/public/index.ts`) — Curated public API. Exports only TypeScript types, error classes, constants, and guards. Re-exported by client and server packages.
 - **`@modelcontextprotocol/client`** and **`@modelcontextprotocol/server`** (`packages/*/src/index.ts`) — Final public surface. Package-specific exports (named explicitly) plus re-exports from `core-internal/public`.
-- **`@modelcontextprotocol/core`** (`packages/core/src/index.ts`) — Public Zod-schema package. Re-exports **only** the `*Schema` Zod constants (MCP spec + OAuth/OpenID), bundled from `core-internal` at build time. The published home for raw runtime validation (`CallToolResultSchema.parse(...)`); runtime-neutral (`zod` is its only dependency). Not consumed by the sibling packages — `client`/`server` keep their own bundled schema copies and stay Zod-free in their public surface.
+- **`@modelcontextprotocol/core`** (`packages/core/src/index.ts`) — Public Zod-schema package. Re-exports **only** the `*Schema` Zod constants (MCP spec + OAuth/OpenID), bundled from `core-internal` at build time. The published home for raw runtime validation (`CallToolResultSchema.parse(...)`); runtime-neutral (`zod` is its only dependency). Consumed by the sibling packages at runtime: `client`/`server`/`server-legacy` bundles resolve the schema modules from this package (see the shared `externalize-core-schemas` plugin in `packages/core-internal/externalizeCoreSchemas.tsdown.mjs`, applied by their tsdown configs) so one evaluated schema-graph copy is shared per application; their public surfaces stay Zod-free.
 
 When modifying exports:
 - Use explicit named exports, not `export *`, in package `index.ts` files and `core-internal/public`.

packages/client/package.json

@@ -133,6 +133,7 @@
         "test:watch": "vitest"
     },
     "dependencies": {
+        "@modelcontextprotocol/core": "workspace:^",
         "cross-spawn": "catalog:runtimeClientOnly",
         "eventsource": "catalog:runtimeClientOnly",
         "eventsource-parser": "catalog:runtimeClientOnly",

packages/client/test/client/externalizedCoreBoundary.test.ts

@@ -0,0 +1,53 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { beforeAll, describe, expect, test } from 'vitest';
+
+const pkgDir = join(dirname(fileURLToPath(import.meta.url)), '../..');
+const distDir = join(pkgDir, 'dist');
+const coreDir = join(pkgDir, '..', 'core');
+const CORE_IMPORT = /\bfrom\s+["']@modelcontextprotocol\/core["']/;
+
+function chunksImportingCore(): string[] {
+    return (readdirSync(distDir, { recursive: true }) as string[])
+        .filter(file => file.endsWith('.mjs'))
+        .map(file => join(distDir, file))
+        .filter(chunk => CORE_IMPORT.test(readFileSync(chunk, 'utf8')));
+}
+
+// Consumer side of the externalize-core-schemas boundary (see
+// packages/core-internal/externalizeCoreSchemas.tsdown.mjs): the built package must resolve the
+// schema modules from @modelcontextprotocol/core at runtime, and everything it imports from there
+// must actually exist in core. The build-time assertions in the plugin guard the producer side;
+// this test pins the consumer side of the published contract.
+describe('@modelcontextprotocol/client dist resolves schemas from @modelcontextprotocol/core', () => {
+    beforeAll(() => {
+        if (!existsSync(join(distDir, 'index.mjs'))) {
+            execFileSync('pnpm', ['build'], { cwd: pkgDir, stdio: 'inherit' });
+        }
+        if (!existsSync(join(coreDir, 'dist', 'index.mjs'))) {
+            execFileSync('pnpm', ['build'], { cwd: coreDir, stdio: 'inherit' });
+        }
+    }, 240_000);
+
+    test('built ESM chunks import the schemas from @modelcontextprotocol/core instead of inlining them', () => {
+        expect(chunksImportingCore().length).toBeGreaterThan(0);
+    });
+
+    test('every name the built chunks import from @modelcontextprotocol/core exists in core, under real ESM linking', () => {
+        for (const chunk of chunksImportingCore()) {
+            // Plain-node import gives real ESM link semantics: it fails at instantiation if the chunk
+            // names an export core does not provide (e.g. an SDK-internal helper schema accidentally
+            // imported as a value) — exactly the error a published package would throw in consumers.
+            // Vitest's own module transform would report such a name as `undefined` instead of failing.
+            const result = spawnSync(
+                process.execPath,
+                ['--input-type=module', '-e', `await import(${JSON.stringify(pathToFileURL(chunk).href)});`],
+                { encoding: 'utf8', timeout: 30_000 }
+            );
+            expect(result.status, `importing ${chunk} failed:\n${result.error ?? result.stderr}`).toBe(0);
+        }
+    }, 60_000);
+});

packages/client/tsdown.config.ts

@@ -1,7 +1,13 @@
 import { defineConfig } from 'tsdown';
 
+import { externalizeCoreSchemas } from '../core-internal/externalizeCoreSchemas.tsdown.mjs';
+
 export default defineConfig({
     failOnWarn: 'ci-only',
+    // Resolve the published schema modules from @modelcontextprotocol/core at runtime instead of
+    // inlining them — see packages/core-internal/externalizeCoreSchemas.tsdown.mjs for the rationale
+    // and the build-time assertions that keep the rewrite honest.
+    plugins: [externalizeCoreSchemas()],
     entry: [
         'src/index.ts',
         'src/stdio.ts',

packages/core-internal/externalizeCoreSchemas.tsdown.d.mts

@@ -0,0 +1,16 @@
+import type { Rolldown } from 'tsdown';
+
+/**
+ * Absolute paths of the core-internal schema source modules that are published verbatim as
+ * @modelcontextprotocol/core (types/schemas.ts + shared/auth.ts). Single source of truth for
+ * {@link externalizeCoreSchemas}; keep in sync with the aliases in packages/core/tsdown.config.ts.
+ */
+export declare const CORE_SCHEMA_MODULES: readonly string[];
+
+/**
+ * tsdown/rolldown plugin that rewrites every import resolving to one of {@link CORE_SCHEMA_MODULES} into an external
+ * import of '@modelcontextprotocol/core', so built packages share ONE evaluated copy of the spec + OAuth Zod schema
+ * graph per application. Asserts at build time, in both directions, that the rewrite actually happened — see the
+ * implementation in externalizeCoreSchemas.tsdown.mjs for the full rationale.
+ */
+export declare function externalizeCoreSchemas(): Rolldown.Plugin;

packages/core-internal/externalizeCoreSchemas.tsdown.mjs

@@ -0,0 +1,108 @@
+// Shared tsdown build plugin. Plain .mjs (not .ts) because tsdown's config loader transpiles only
+// the entry tsdown.config.ts itself and native-imports everything else, and Node 20 cannot import
+// TypeScript sources. Types for consumers live in externalizeCoreSchemas.tsdown.d.mts.
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * core-internal's two schema source modules are published verbatim as @modelcontextprotocol/core (see
+ * packages/core/tsdown.config.ts). The externalizeCoreSchemas() tsdown plugin rewrites every import that RESOLVES to
+ * one of them — whatever the import specifier looked like — into an external import of '@modelcontextprotocol/core',
+ * so built packages resolve the schemas from that package at runtime instead of inlining yet another copy. That keeps
+ * ONE evaluated copy of the spec + OAuth Zod schema graph per application, however many SDK packages it uses.
+ *
+ * Safe because core exports every name that crosses this boundary at runtime: SDK-internal helper schemas live in
+ * separate core-internal modules (e.g. types/listChangedOptions.ts) and remain bundled, and the remaining
+ * internal-only exports of the two modules are imported type-only (client's externalizedCoreBoundary.test.ts checks
+ * the built output against core's real export surface). Type declarations still inline the types via each consumer's
+ * dts `paths` mapping — only runtime duplication costs.
+ *
+ * @type {readonly string[]}
+ */
+export const CORE_SCHEMA_MODULES = [
+    path.join(HERE, 'src', 'types', 'schemas.ts'), // MCP spec schemas
+    path.join(HERE, 'src', 'shared', 'auth.ts') // OAuth/OpenID schemas
+];
+
+const CORE_INTERNAL_SRC = path.join(HERE, 'src') + path.sep;
+
+/**
+ * Resolvers may decorate an id beyond the plain file path (`\0` virtual-module prefix, `?query` suffix).
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+function undecorate(id) {
+    return id.replace(/^\0/, '').replace(/\?.*$/, '');
+}
+
+/**
+ * Rewrites imports of {@link CORE_SCHEMA_MODULES} to external '@modelcontextprotocol/core' imports, and fails the
+ * build when the rewrite cannot have worked, in both directions:
+ *
+ * - a listed module that does not exist on disk, or is never rewritten by a build that emits runtime chunks bundling
+ *   core-internal sources, fails the build — otherwise renaming or moving a schema module would silently re-inline
+ *   the whole schema graph into every consumer;
+ * - a listed module that still ends up in an emitted runtime chunk fails the build — the rewrite was bypassed, e.g.
+ *   by a resolver id decoration the comparison does not recognize.
+ *
+ * The checks look at emitted runtime chunks (.mjs/.cjs), not the raw module graph, because the d.ts pass loads the
+ * schema .ts sources on purpose: type declarations inline the types via each consumer's dts `paths` mapping.
+ *
+ * @returns {import('tsdown').Rolldown.Plugin}
+ */
+export function externalizeCoreSchemas() {
+    const rewrites = new Map(CORE_SCHEMA_MODULES.map(module => [module, 0]));
+    return {
+        name: 'externalize-core-schemas',
+        buildStart() {
+            for (const module of CORE_SCHEMA_MODULES) {
+                if (!existsSync(module)) {
+                    this.error(
+                        `externalize-core-schemas: listed schema module ${module} does not exist. ` +
+                            `If it moved, update CORE_SCHEMA_MODULES in packages/core-internal/externalizeCoreSchemas.tsdown.mjs ` +
+                            `and the aliases in packages/core/tsdown.config.ts, which publish the same modules.`
+                    );
+                }
+            }
+        },
+        async resolveId(source, importer, options) {
+            if (importer === undefined) return null;
+            const resolved = await this.resolve(source, importer, options);
+            if (resolved === null) return null;
+            const id = path.normalize(undecorate(resolved.id));
+            const count = rewrites.get(id);
+            if (count === undefined) return null;
+            rewrites.set(id, count + 1);
+            return { id: '@modelcontextprotocol/core', external: true };
+        },
+        generateBundle(_outputOptions, bundle) {
+            const bundledIds = new Set(
+                Object.values(bundle)
+                    .filter(output => output.type === 'chunk' && !/\.d\.[cm]?ts$/.test(output.fileName))
+                    .flatMap(chunk => chunk.moduleIds.map(id => path.normalize(undecorate(id))))
+            );
+            // Outputs with no core-internal runtime code (e.g. the d.ts pass) prove nothing about the rewrite.
+            if (![...bundledIds].some(id => id.startsWith(CORE_INTERNAL_SRC))) return;
+            const missed = CORE_SCHEMA_MODULES.filter(module => rewrites.get(module) === 0);
+            if (missed.length > 0) {
+                this.error(
+                    `externalize-core-schemas: no import resolved to ${missed.join(' or ')}, ` +
+                        `so nothing was externalized from there and the schema graph would be inlined. ` +
+                        `If the module was renamed or split, update CORE_SCHEMA_MODULES in ` +
+                        `packages/core-internal/externalizeCoreSchemas.tsdown.mjs and packages/core/tsdown.config.ts.`
+                );
+            }
+            const inlined = CORE_SCHEMA_MODULES.filter(module => bundledIds.has(module));
+            if (inlined.length > 0) {
+                this.error(
+                    `externalize-core-schemas: ${inlined.join(' and ')} reached an emitted runtime chunk ` +
+                        `despite being listed for externalization — the resolveId rewrite was bypassed.`
+                );
+            }
+        }
+    };
+}

packages/core-internal/package.json

@@ -94,6 +94,7 @@
         "eslint-config-prettier": "catalog:devTools",
         "eslint-plugin-n": "catalog:devTools",
         "prettier": "catalog:devTools",
+        "tsdown": "catalog:devTools",
         "typescript": "catalog:devTools",
         "typescript-eslint": "catalog:devTools",
         "vitest": "catalog:devTools"

packages/core-internal/src/types/index.ts

@@ -4,6 +4,7 @@ export * from './constants';
 export * from './enums';
 export * from './errors';
 export * from './guards';
+export * from './listChangedOptions';
 export * from './schemas';
 export * from './specTypeSchema';
 export * from './types';

packages/core-internal/src/types/listChangedOptions.ts

@@ -0,0 +1,31 @@
+import * as z from 'zod/v4';
+
+/**
+ * Base schema for list changed subscription options (without callback).
+ * Used internally for Zod validation of `autoRefresh` and `debounceMs`.
+ *
+ * Lives outside `schemas.ts` deliberately: it is an SDK option schema, not a spec
+ * schema, so it is not part of `@modelcontextprotocol/core`'s public surface —
+ * and `schemas.ts` is resolved from that package at runtime by the client/server
+ * bundles, which can only see the names core actually exports.
+ */
+export const ListChangedOptionsBaseSchema = z.object({
+    /**
+     * If `true`, the list will be refreshed automatically when a list changed notification is received.
+     * The callback will be called with the updated list.
+     *
+     * If `false`, the callback will be called with `null` items, allowing manual refresh.
+     *
+     * @default true
+     */
+    autoRefresh: z.boolean().default(true),
+    /**
+     * Debounce time in milliseconds for list changed notification processing.
+     *
+     * Multiple notifications received within this timeframe will only trigger one refresh.
+     * Set to `0` to disable debouncing.
+     *
+     * @default 300
+     */
+    debounceMs: z.number().int().nonnegative().default(300)
+});

packages/core-internal/src/types/schemas.ts

@@ -1455,31 +1455,6 @@ export const ToolListChangedNotificationSchema = NotificationSchema.extend({
     params: NotificationsParamsSchema.optional()
 });
 
-/**
- * Base schema for list changed subscription options (without callback).
- * Used internally for Zod validation of `autoRefresh` and `debounceMs`.
- */
-export const ListChangedOptionsBaseSchema = z.object({
-    /**
-     * If `true`, the list will be refreshed automatically when a list changed notification is received.
-     * The callback will be called with the updated list.
-     *
-     * If `false`, the callback will be called with `null` items, allowing manual refresh.
-     *
-     * @default true
-     */
-    autoRefresh: z.boolean().default(true),
-    /**
-     * Debounce time in milliseconds for list changed notification processing.
-     *
-     * Multiple notifications received within this timeframe will only trigger one refresh.
-     * Set to `0` to disable debouncing.
-     *
-     * @default 300
-     */
-    debounceMs: z.number().int().nonnegative().default(300)
-});
-
 /* Logging */
 /**
  * The severity of a log message.

packages/core-internal/src/types/specTypeSchema.ts

@@ -21,7 +21,7 @@ import * as schemas from './schemas';
  * Explicit allowlist of protocol Zod schemas that correspond to a public spec type in `types.ts`.
  *
  * This intentionally excludes internal helper schemas exported from `schemas.ts` that have no
- * matching public type (e.g. `ListChangedOptionsBaseSchema`, `BaseRequestParamsSchema`,
+ * matching public type (e.g. `BaseRequestParamsSchema`,
  * `NotificationsParamsSchema`, `ClientTasksCapabilitySchema`, `ServerTasksCapabilitySchema`).
  * Keeping the list explicit means new public spec types must be added here deliberately, and
  * internals never leak into `SpecTypeName`.

packages/core/test/coreSchemas.test.ts

@@ -37,7 +37,6 @@ describe('@modelcontextprotocol/core', () => {
         const SPEC_INTERNAL_HELPERS = [
             'BaseRequestParamsSchema',
             'ClientTasksCapabilitySchema',
-            'ListChangedOptionsBaseSchema',
             'NotificationsParamsSchema',
             'ServerTasksCapabilitySchema'
         ];

packages/core/test/distEntry.test.ts

@@ -0,0 +1,38 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { beforeAll, describe, expect, test } from 'vitest';
+
+const pkgDir = join(dirname(fileURLToPath(import.meta.url)), '..');
+const distEntry = join(pkgDir, 'dist', 'index.mjs');
+
+// client, server, and server-legacy resolve their schema modules from this
+// package's dist entry at runtime, so a missing or incomplete build breaks
+// every consumer of a built package (the repo's CI test job never runs a
+// standalone build — dist only exists if a test builds it, the same way
+// client's barrelClean.test.ts builds client). Build on demand and pin the
+// runtime surface the boundary depends on.
+describe('@modelcontextprotocol/core dist entry', () => {
+    beforeAll(() => {
+        if (!existsSync(distEntry)) {
+            execFileSync('pnpm', ['build'], { cwd: pkgDir, stdio: 'inherit' });
+        }
+    }, 120_000);
+
+    test('root entry resolves and exposes the runtime schema surface', async () => {
+        const mod = await import(distEntry);
+        for (const name of [
+            'CallToolResultSchema',
+            'InitializeRequestSchema',
+            'JSONRPCMessageSchema',
+            'OAuthMetadataSchema',
+            'OAuthProtectedResourceMetadataSchema'
+        ]) {
+            expect(mod[name], `core dist entry must export ${name}`).toBeDefined();
+        }
+        // The externalized boundary re-exports the whole spec schema surface;
+        // a partial build would show up as a collapsed export count.
+        expect(Object.keys(mod).length).toBeGreaterThan(150);
+    });
+});

packages/server-legacy/package.json

@@ -83,6 +83,7 @@
         "test:watch": "vitest"
     },
     "dependencies": {
+        "@modelcontextprotocol/core": "workspace:^",
         "zod": "catalog:runtimeShared",
         "raw-body": "catalog:runtimeServerOnly",
         "content-type": "catalog:runtimeShared",

packages/server-legacy/tsdown.config.ts

@@ -1,7 +1,13 @@
 import { defineConfig } from 'tsdown';
 
+import { externalizeCoreSchemas } from '../core-internal/externalizeCoreSchemas.tsdown.mjs';
+
 export default defineConfig({
     failOnWarn: 'ci-only',
+    // Resolve the published schema modules from @modelcontextprotocol/core at runtime instead of
+    // inlining them — see packages/core-internal/externalizeCoreSchemas.tsdown.mjs for the rationale
+    // and the build-time assertions that keep the rewrite honest.
+    plugins: [externalizeCoreSchemas()],
     entry: ['src/index.ts', 'src/sse/index.ts', 'src/auth/index.ts'],
     format: ['esm', 'cjs'],
     fixedExtension: true,

packages/server/package.json

@@ -133,6 +133,7 @@
         "test:watch": "vitest"
     },
     "dependencies": {
+        "@modelcontextprotocol/core": "workspace:^",
         "zod": "catalog:runtimeShared"
     },
     "devDependencies": {