@modelcontextprotocol/client 2.0.0-alpha.2 is missing peer dependency declaration for @cfworker/json-schema

[slowtick]

Describe the bug
Application using @modelcontextprotocol/client dependency fails to import the Client at runtime due to missing @cfworker/json-schema. Works with 1.x @modelcontextprotocol/sdk

> node --version
v24.13.0

> npm run start

> my-service@1.0.0 start
> node dist/index.js

node:internal/modules/package_json_reader:316
  throw new ERR_MODULE_NOT_FOUND(packageName, fileURLToPath(base), null);
        ^

Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@cfworker/json-schema' imported from C:\repos\my-service\node_modules\@modelcontextprotocol\client\dist\src-RIHfgPRm.mjs
    at Object.getPackageJSONURL (node:internal/modules/package_json_reader:316:9)
    at packageResolve (node:internal/modules/esm/resolve:768:81)
    at moduleResolve (node:internal/modules/esm/resolve:858:18)
    at defaultResolve (node:internal/modules/esm/resolve:990:11)
    at #cachedDefaultResolve (node:internal/modules/esm/loader:718:20)
    at #resolveAndMaybeBlockOnLoaderThread (node:internal/modules/esm/loader:735:38)
    at ModuleLoader.resolveSync (node:internal/modules/esm/loader:764:52)
    at #resolve (node:internal/modules/esm/loader:700:17)
    at ModuleLoader.getOrCreateModuleJob (node:internal/modules/esm/loader:620:35)
    at ModuleJob.syncLink (node:internal/modules/esm/module_job:143:33) {
  code: 'ERR_MODULE_NOT_FOUND'
}

Node.js v24.13.0

Manually installing @cfworker/json-schema as dependency solves this issue.

To Reproduce
Steps to reproduce the behavior:

1. npm install --save @modelcontextprotocol/client
2. node -e "import { Client } from '@modelcontextprotocol/client';"

Expected behavior
All peer dependencies for library should be installed automatically.

Logs

> node -e "import { Client } from '@modelcontextprotocol/client';"
node:internal/modules/package_json_reader:316
  throw new ERR_MODULE_NOT_FOUND(packageName, fileURLToPath(base), null);
        ^

Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@cfworker/json-schema' imported from C:\repos\my-service\node_modules\@modelcontextprotocol\client\dist\src-RIHfgPRm.mjs
    at Object.getPackageJSONURL (node:internal/modules/package_json_reader:316:9)
    at packageResolve (node:internal/modules/esm/resolve:768:81)
    at moduleResolve (node:internal/modules/esm/resolve:858:18)
    at defaultResolve (node:internal/modules/esm/resolve:990:11)
    at #cachedDefaultResolve (node:internal/modules/esm/loader:718:20)
    at #resolveAndMaybeBlockOnLoaderThread (node:internal/modules/esm/loader:735:38)
    at ModuleLoader.resolveSync (node:internal/modules/esm/loader:764:52)
    at #resolve (node:internal/modules/esm/loader:700:17)
    at ModuleLoader.getOrCreateModuleJob (node:internal/modules/esm/loader:620:35)
    at ModuleJob.syncLink (node:internal/modules/esm/module_job:143:33) {
  code: 'ERR_MODULE_NOT_FOUND'
}

[he-yufeng]

I checked this against the published alpha.2 package and current main. The published package still reproduces the failure because dist/index.mjs imports a shared chunk that statically imports @cfworker/json-schema. Current main appears to have already fixed the root import path: after rebuilding packages/client, importing ./packages/client/dist/index.mjs succeeds and the root bundle no longer has a static @cfworker/json-schema import.

So this looks like it may be fixed by the current source and needs the next alpha publish rather than another code change. I did not open a duplicate PR.

[kagura-agent]

I'd like to take this one.

The root cause: tsdown bundles @modelcontextprotocol/core into the client (noExternal: ['@modelcontextprotocol/core']). The validators/cfWorker entry point imports @cfworker/json-schema through core, and tsdown creates a shared chunk (src-RIHfgPRm.mjs) that mixes both the main barrel code and the cfWorker validator. Since index.mjs loads from this shared chunk, the @cfworker/json-schema import fires eagerly — even when users only import the base client.

Proposed fix: add @cfworker/json-schema as an optional peer dependency in packages/client/package.json, matching core's existing pattern (peerDependenciesMeta: { optional: true }). This surfaces the dependency requirement correctly in npm's install resolution rather than failing with a cryptic ERR_MODULE_NOT_FOUND.

🤖 Disclosure: This PR will be authored by Kagura, an AI agent. You can see my work history here. If you'd prefer not to receive AI-authored PRs, just let me know and I'll stop.

[mcp-claude]

fixed on main and in the published 2.0.0-beta.2 — upgrade to @modelcontextprotocol/client@2.0.0-beta.2 (or any beta.*) and this goes away. fix is PR #1897 / 434b2f1, first shipped in 2.0.0-beta.1: CfWorkerJsonSchemaValidator moved out of the core-internal barrel so tsdown no longer pulls @cfworker/json-schema into the root chunk. reopen if still reproducing on beta.1 or later.

verification

repro (repro.mjs):

// Repro for #2143: importing @modelcontextprotocol/client base entry
// must not eagerly load @cfworker/json-schema (which is only a devDep).
import { Client } from '@modelcontextprotocol/client';
console.log('OK: imported Client =', typeof Client);

against the reported version — reproduces:

$ npm install @modelcontextprotocol/client@2.0.0-alpha.2
$ node repro.mjs
FAIL ERR_MODULE_NOT_FOUND Cannot find package '@cfworker/json-schema' imported from .../node_modules/@modelcontextprotocol/client/dist/src-RIHfgPRm.mjs

against current 2.0.0-beta.2 — works:

$ npm install @modelcontextprotocol/client@2.0.0-beta.2
$ node repro.mjs
OK: imported Client = function

on main (HEAD 3834921), grep '@cfworker' packages/client/dist/index.mjs packages/client/dist/src-*.mjs packages/client/dist/chunk-*.mjs returns 0 matches — the reference now only lives in dist/cfWorkerProvider-*.mjs, loaded via the ./validators/cf-worker subpath.

[mattzcarey]

Closed as already fixed: this is the client-side face of #2093, resolved by PR #1897, which moved CfWorkerJsonSchemaValidator to the opt-in ./validators/cf-worker subpath so the root entry no longer pulls @cfworker/json-schema into its shared chunk. Guarded by the barrel test. Verified on the published @modelcontextprotocol/client@2.0.0 with the package absent.