Skip to content

feat(compat): McpError/ErrorCode/JSONRPCError/StreamableHTTPError + OAuth subclass aliases#1903

Draft
felixweinberger wants to merge 2 commits intomainfrom
fweinberger/v2-bc-error-aliases
Draft

feat(compat): McpError/ErrorCode/JSONRPCError/StreamableHTTPError + OAuth subclass aliases#1903
felixweinberger wants to merge 2 commits intomainfrom
fweinberger/v2-bc-error-aliases

Conversation

@felixweinberger
Copy link
Copy Markdown
Contributor

Part of the v2 backwards-compatibility series — see reviewer guide.

v2 split McpError into ProtocolError/SdkError and consolidated 17 OAuth error classes into OAuthError+OAuthErrorCode. This restores the v1 names as @deprecated aliases/subclasses.

Motivation and Context

v2 split McpError into ProtocolError/SdkError and consolidated 17 OAuth error classes into OAuthError+OAuthErrorCode. This restores the v1 names as @deprecated aliases/subclasses.

v1 vs v2 pattern & evidence

v1 pattern:

`if (err instanceof McpError && err.code === ErrorCode.InvalidParams)`; `throw new InvalidTokenError('...')`

v2-native:

`if (err instanceof ProtocolError && err.code === ProtocolErrorCode.InvalidParams)`; `throw new OAuthError(OAuthErrorCode.InvalidToken, '...')`

Evidence: GitHub code search: ~1,540 files reference McpError/ErrorCode. ErrorCode.ConnectionClosed/RequestTimeout shimmed to SdkErrorCode values so comparisons work (string-vs-number assignment to error.code: number is irreducible — 1-line consumer fix).

How Has This Been Tested?

  • packages/core/test/errors/compat.test.ts — instanceof + code equivalence
  • Integration: validated bump-only against 5 OSS repos via the v2-bc-integration validation branch
  • pnpm typecheck:all && pnpm lint:all && pnpm test:all green

Breaking Changes

None — additive @deprecated shim. Removed in v3.

Types of changes

  • New feature (non-breaking change which adds functionality)

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added or updated documentation as needed

Additional context

Stacks on: C1

…tter, and legacy OAuth error subclasses

v1-compat shims (all @deprecated, removed in v3):
- McpError -> ProtocolError, ErrorCode -> ProtocolErrorCode (re-export aliases)
- OAuthError.errorCode getter -> .code (warns once)
- 17 OAuth error subclasses (InvalidTokenError etc.) + CustomOAuthError as
  thin wrappers around OAuthError(OAuthErrorCode.X, ...), preserving v1
  constructor signature, static errorCode, and instanceof OAuthError

InvalidRequestError is defined in oauthErrorsCompat.ts but intentionally not
re-exported from core/public to avoid colliding with the JSON-RPC
InvalidRequestError interface from types.ts; the sdk meta-package
server/auth/errors.js subpath will surface it.
@felixweinberger felixweinberger added the v2-bc v2 backwards-compatibility series label Apr 15, 2026
@changeset-bot
Copy link
Copy Markdown

changeset-bot bot commented Apr 15, 2026

🦋 Changeset detected

Latest commit: 68afee0

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
@modelcontextprotocol/core Patch

Not sure what this means? Click here to learn what changesets are.

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

@felixweinberger felixweinberger added this to the v2.0.0-bc milestone Apr 15, 2026
@pkg-pr-new
Copy link
Copy Markdown

pkg-pr-new bot commented Apr 15, 2026

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/@modelcontextprotocol/client@1903

@modelcontextprotocol/server

npm i https://pkg.pr.new/@modelcontextprotocol/server@1903

@modelcontextprotocol/express

npm i https://pkg.pr.new/@modelcontextprotocol/express@1903

@modelcontextprotocol/fastify

npm i https://pkg.pr.new/@modelcontextprotocol/fastify@1903

@modelcontextprotocol/hono

npm i https://pkg.pr.new/@modelcontextprotocol/hono@1903

@modelcontextprotocol/node

npm i https://pkg.pr.new/@modelcontextprotocol/node@1903

commit: 68afee0

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

v2-bc v2 backwards-compatibility series

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant