feat: auto-select JSON Schema validator based on runtime #1456

mattzcarey · 2026-02-03T10:22:21Z

Summary

Add runtime shims that automatically select the appropriate implementations based on execution environment, enabling seamless cross-platform support for:

Node.js: Full functionality with native modules
Cloudflare Workers (workerd): Web API-based implementations (no nodejs_compat required)
Deno: Works via npm compatibility with Node.js shims
Bun: Works with Node.js shims

Key Features

Auto-selected JSON Schema Validator

Node.js/Deno/Bun: Uses AjvJsonSchemaValidator (unchanged behavior)
Cloudflare Workers: Uses CfWorkerJsonSchemaValidator (previously required explicit configuration)

This eliminates the need for Cloudflare Workers users to explicitly configure the validator - it now "just works".

Runtime-aware `process` shim for StdioServerTransport

Node.js/Deno/Bun: Uses native process.stdin/process.stdout
Cloudflare Workers: Throws helpful error directing users to use StreamableHTTPServerTransport

Web Crypto API for cross-platform compatibility

InMemoryTaskStore now uses crypto.randomUUID() (Web Crypto API) instead of Node.js crypto.randomBytes()
Works in all environments without runtime-specific code

Implementation

Uses package.json export conditions to resolve the correct implementations at runtime:

"./_shims": {
  "workerd": { "import": "./dist/shimsWorkerd.mjs" },
  "browser": { "import": "./dist/shimsWorkerd.mjs" },
  "node": { "import": "./dist/shimsNode.mjs" },
  "default": { "import": "./dist/shimsNode.mjs" }
}

Server and Client import from their own _shims export using self-referencing imports, which are kept external during bundling so the runtime resolver picks the correct variant.

Shim exports

Node.js shims (shimsNode.ts):

DefaultJsonSchemaValidator → AjvJsonSchemaValidator
randomBytes → node:crypto
process → node:process

Workerd/Browser shims (shimsWorkerd.ts):

DefaultJsonSchemaValidator → CfWorkerJsonSchemaValidator
randomBytes → Web Crypto API implementation
process → Stub that throws "not supported" error

Changes

Add _shims export to @modelcontextprotocol/server
Update Server and Client to use DefaultJsonSchemaValidator from shims as default
Update StdioServerTransport to import process from shims
Add randomBytes shim using Web Crypto API for Cloudflare Workers
Add process stub for non-Node environments with helpful error messages
Update tsdown configs to build shim entry points and keep self-references external
Add integration tests for Cloudflare Workers, Deno, and Bun runtimes
Update InMemoryTaskStore to use crypto.randomUUID() (Web Crypto API)

Test plan

All existing tests pass (pnpm check:all)
Verified Node.js correctly resolves to AjvJsonSchemaValidator
Verified Cloudflare Workers (wrangler) correctly resolves to CfWorkerJsonSchemaValidator
Added integration test for Cloudflare Workers (no nodejs_compat)
Added integration test for Deno runtime
Added integration test for Bun runtime
Build succeeds with correct output files

Migration

No breaking changes. This is backwards compatible:

Node.js users: No change needed
Cloudflare Workers users: Can remove explicit jsonSchemaValidator configuration (optional)
Deno/Bun users: Should work out of the box

🤖 Generated with Claude Code

changeset-bot · 2026-02-03T10:22:29Z

⚠️ No Changeset found

Latest commit: 530f8a5

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

pkg-pr-new · 2026-02-03T10:45:25Z

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/client@1456

@modelcontextprotocol/server

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/server@1456

@modelcontextprotocol/express

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/express@1456

@modelcontextprotocol/hono

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/hono@1456

@modelcontextprotocol/node

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/node@1456

commit: 530f8a5

Add runtime shims that automatically select the appropriate JSON Schema validator based on the execution environment: - Node.js: Uses AjvJsonSchemaValidator (unchanged from before) - Cloudflare Workers (workerd): Uses CfWorkerJsonSchemaValidator This eliminates the need for Cloudflare Workers users to explicitly configure the validator. The SDK now uses package.json export conditions to resolve the correct validator at runtime. Changes: - Add `_shims` export to core, server, and client packages - Update Server and Client to import DefaultJsonSchemaValidator from shims - Use self-referencing package imports for runtime resolution - Document the enhancement in migration guide

Move runtime shims from server and client packages to just core: - Server and client now import from @modelcontextprotocol/core/_shims - Removed redundant shim files from server and client packages - Updated migration docs to reference core/_shims import path This simplifies the shim structure - there's now only one place to define the runtime-specific validators.

Since @modelcontextprotocol/core is a private package and not published, we cannot keep core/_shims as an external import in server/client bundles. Instead, bundle the shims directly so the packages work standalone.

Since core is a private package, shims must be in server/client for runtime selection to work. Core still exports the validators as barrel exports for direct use. - Add shimsNode.ts and shimsWorkerd.ts to server and client - Remove shims directory from core - Update package.json exports with runtime conditions - Server/client import DefaultJsonSchemaValidator from their own _shims

- Add randomBytes shim to shimsNode.ts (re-exports from node:crypto) and shimsWorkerd.ts (Web Crypto API implementation) - Update inMemory.ts to import randomBytes from server shims - Separate Node.js-specific transports into barrel exports: - @modelcontextprotocol/server/stdio for StdioServerTransport - @modelcontextprotocol/server/streamableHttp for StreamableHTTPServerTransport - Remove node:util TextEncoder import (globally available) - Add Cloudflare Workers integration test (no nodejs_compat required) - Update examples and tests to use new import paths

- StdioServerTransport is now at @modelcontextprotocol/server/stdio - StreamableHTTPServerTransport (web standard) at @modelcontextprotocol/server/streamableHttp - Add browser export condition to client package.json - Add integration tests for Cloudflare Workers, Bun, and Deno runtimes

@default

The @default tag sufficiently documents the behavior.

- Remove @modelcontextprotocol/server/stdio and /streamableHttp entry points - Export StdioServerTransport and WebStandardStreamableHTTPServerTransport from main entry - Add process shim that throws in non-Node environments (stdio not supported) - Fix TextEncoder type issue (use InstanceType<typeof TextEncoder>) - Update migration docs to reflect simplified imports

- Move tests to test/integration/test/server/ - Test MCP server creation and tool registration - Remove complex MCP protocol session handling - Tests verify runtime compatibility without stateful sessions

- Move InMemoryTaskStore to use Web Crypto API (crypto.randomUUID()) instead of Node.js crypto.randomBytes() - Keep InMemoryTaskStore in core package as a test fixture/demo - Server re-exports from core via main index.ts - Rename runtime test files to camelCase per lint rules - Fix lint issues in runtime tests

- Use /mcp endpoint with WebStandardStreamableHTTPServerTransport - Remove /health and /test endpoints - Test actual MCP client-server communication - Minimal server code: just register tool and handle requests

- Create runtimeTest.ts helper with common setup/teardown logic - Standardize server source generation with MCP_SERVER_SETUP template - Add testMcpConnection helper for actual MCP protocol testing - Simplify bunRuntime, denoRuntime, and cloudflareWorkers tests - Add wrangler to pnpm-workspace.yaml devTools catalog

Tests that spawn child processes (processCleanup, runtime tests) were failing intermittently due to parallel execution causing resource conflicts. Running test files sequentially ensures stable results.

- Remove unnecessary exports from core package.json (private package) - Fix prettierignore path in middleware packages (../../ -> ../../../)

Required for runtime compatibility tests (bunRuntime, denoRuntime).

mattzcarey requested a review from a team as a code owner February 3, 2026 10:22

mattzcarey force-pushed the feat/runtime-shims branch 2 times, most recently from bc4373f to 7c5b80d Compare February 3, 2026 11:18

mattzcarey added 7 commits February 3, 2026 19:03

fix: bundle core/_shims into server/client instead of external

9b6f08d

Since @modelcontextprotocol/core is a private package and not published, we cannot keep core/_shims as an external import in server/client bundles. Instead, bundle the shims directly so the packages work standalone.

chore: remove verbose JSDoc examples for jsonSchemaValidator

6a9d570

The @default tag sufficiently documents the behavior.

KKonstantinov previously approved these changes Feb 3, 2026

View reviewed changes

mattzcarey added 15 commits February 3, 2026 19:04

fix: update imports to use main @modelcontextprotocol/server entry

0035955

chore: remove TODO for Deno/Bun tests (now implemented)

262f46a

refactor: simplify runtime integration tests

ecd4a33

- Move tests to test/integration/test/server/ - Test MCP server creation and tool registration - Remove complex MCP protocol session handling - Tests verify runtime compatibility without stateful sessions

chore: clean up unnecessary comments

b3d9155

chore: remove unused randomBytes shim

bd779bf

refactor: simplify runtime integration tests to use real MCP protocol

f710036

- Use /mcp endpoint with WebStandardStreamableHTTPServerTransport - Remove /health and /test endpoints - Test actual MCP client-server communication - Minimal server code: just register tool and handle requests

fix: run integration tests sequentially to avoid race conditions

9dcbf40

Tests that spawn child processes (processCleanup, runtime tests) were failing intermittently due to parallel execution causing resource conflicts. Running test files sequentially ensures stable results.

fix: correct prettierignore path in middleware packages

19f7868

- Remove unnecessary exports from core package.json (private package) - Fix prettierignore path in middleware packages (../../ -> ../../../)

ci: install Bun and Deno in test runner

d7a8d31

Required for runtime compatibility tests (bunRuntime, denoRuntime).

fix: map server shims for middleware typecheck

85a10d1

fix: add _shims path mappings to tsconfigs

128c999

refactor: remove Bun/Deno tests, simplify cloudflare test

87d0181

mattzcarey dismissed KKonstantinov’s stale review via 87d0181 February 3, 2026 19:05

mattzcarey force-pushed the feat/runtime-shims branch from e3c7cd4 to 87d0181 Compare February 3, 2026 19:05

mattzcarey added 4 commits February 3, 2026 19:08

fix: restore error hierarchy and OAuth sections in migration docs

f8d9a9a

chore: use wrangler from catalog, remove vitest.config.js

1fd4fc0

chore: update pnpm-lock.yaml

7b40b7e

fix: restore vitest.config.js for integration tests

530f8a5

KKonstantinov approved these changes Feb 3, 2026

View reviewed changes

mattzcarey merged commit bc883af into main Feb 3, 2026
14 checks passed

mattzcarey deleted the feat/runtime-shims branch February 3, 2026 19:22

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: auto-select JSON Schema validator based on runtime #1456

feat: auto-select JSON Schema validator based on runtime #1456

Uh oh!

mattzcarey commented Feb 3, 2026 •

edited

Loading

Uh oh!

changeset-bot bot commented Feb 3, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Feb 3, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat: auto-select JSON Schema validator based on runtime #1456

feat: auto-select JSON Schema validator based on runtime #1456

Uh oh!

Conversation

mattzcarey commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key Features

Auto-selected JSON Schema Validator

Runtime-aware process shim for StdioServerTransport

Web Crypto API for cross-platform compatibility

Implementation

Shim exports

Changes

Test plan

Migration

Uh oh!

changeset-bot bot commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

pkg-pr-new bot commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mattzcarey commented Feb 3, 2026 •

edited

Loading

Runtime-aware `process` shim for StdioServerTransport

changeset-bot bot commented Feb 3, 2026 •

edited

Loading

pkg-pr-new bot commented Feb 3, 2026 •

edited

Loading