v2: Errors refactor (ProtocolError, SdkError, OAuthError) (#1454)

Author: KKonstantinov

CLAUDE.md

@@ -29,8 +29,7 @@ When making breaking changes, document them in **both**:
 - `docs/migration.md` — human-readable guide with before/after code examples
 - `docs/migration-SKILL.md` — LLM-optimized mapping tables for mechanical migration
 
-Include what changed, why, and how to migrate. Search for related sections and group
-related changes together rather than adding new standalone sections.
+Include what changed, why, and how to migrate. Search for related sections and group related changes together rather than adding new standalone sections.
 
 ## Code Style Guidelines
 

docs/migration-SKILL.md

@@ -21,10 +21,10 @@ import type {
 import {
     CallToolResultSchema,
     Client,
-    ErrorCode,
     getDisplayName,
     ListToolsResultSchema,
-    McpError,
+    ProtocolError,
+    ProtocolErrorCode,
     StreamableHTTPClientTransport,
     UnauthorizedError,
     UrlElicitationRequiredError
@@ -337,7 +337,7 @@ async function handleElicitationRequest(request: ElicitRequest): Promise<ElicitR
     } else {
         // Should not happen because the client declares its capabilities to the server,
         // but being defensive is a good practice:
-        throw new McpError(ErrorCode.InvalidParams, `Unsupported elicitation mode: ${mode}`);
+        throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Unsupported elicitation mode: ${mode}`);
     }
 }
 

docs/migration.md

@@ -12,13 +12,13 @@ import type {
 import {
     CallToolResultSchema,
     Client,
-    ErrorCode,
     getDisplayName,
     GetPromptResultSchema,
     ListPromptsResultSchema,
     ListResourcesResultSchema,
     ListToolsResultSchema,
-    McpError,
+    ProtocolError,
+    ProtocolErrorCode,
     ReadResourceResultSchema,
     RELATED_TASK_META_KEY,
     StreamableHTTPClientTransport
@@ -270,7 +270,7 @@ async function connect(url?: string): Promise<void> {
         // Set up elicitation request handler with proper validation
         client.setRequestHandler('elicitation/create', async request => {
             if (request.params.mode !== 'form') {
-                throw new McpError(ErrorCode.InvalidParams, `Unsupported elicitation mode: ${request.params.mode}`);
+                throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Unsupported elicitation mode: ${request.params.mode}`);
             }
             console.log('\n🔔 Elicitation (form) Request Received:');
             console.log(`Message: ${request.params.message}`);

examples/client/src/elicitationUrlExample.ts

@@ -10,7 +10,13 @@
 import { createInterface } from 'node:readline';
 
 import type { CreateMessageRequest, CreateMessageResult, TextContent } from '@modelcontextprotocol/client';
-import { CallToolResultSchema, Client, ErrorCode, McpError, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
+import {
+    CallToolResultSchema,
+    Client,
+    ProtocolError,
+    ProtocolErrorCode,
+    StreamableHTTPClientTransport
+} from '@modelcontextprotocol/client';
 
 // Create readline interface for user input
 const readline = createInterface({
@@ -96,7 +102,7 @@ async function run(url: string): Promise<void> {
     // Set up elicitation request handler
     client.setRequestHandler('elicitation/create', async request => {
         if (request.params.mode && request.params.mode !== 'form') {
-            throw new McpError(ErrorCode.InvalidParams, `Unsupported elicitation mode: ${request.params.mode}`);
+            throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Unsupported elicitation mode: ${request.params.mode}`);
         }
         return elicitationCallback(request.params);
     });

examples/client/src/simpleStreamableHttp.ts

@@ -11,21 +11,16 @@ import type {
 } from '@modelcontextprotocol/core';
 import {
     checkResourceAllowed,
-    InvalidClientError,
-    InvalidClientMetadataError,
-    InvalidGrantError,
     LATEST_PROTOCOL_VERSION,
-    OAUTH_ERRORS,
     OAuthClientInformationFullSchema,
     OAuthError,
+    OAuthErrorCode,
     OAuthErrorResponseSchema,
     OAuthMetadataSchema,
     OAuthProtectedResourceMetadataSchema,
     OAuthTokensSchema,
     OpenIdProviderDiscoveryMetadataSchema,
-    resourceUrlFromServerUrl,
-    ServerError,
-    UnauthorizedClientError
+    resourceUrlFromServerUrl
 } from '@modelcontextprotocol/core';
 import pkceChallenge from 'pkce-challenge';
 
@@ -328,7 +323,7 @@ function applyPublicAuth(clientId: string, params: URLSearchParams): void {
  * Parses an OAuth error response from a string or Response object.
  *
  * If the input is a standard OAuth2.0 error response, it will be parsed according to the spec
- * and an instance of the appropriate OAuthError subclass will be returned.
+ * and an OAuthError will be returned with the appropriate error code.
  * If parsing fails, it falls back to a generic ServerError that includes
  * the response status (if available) and original content.
  *
@@ -341,13 +336,11 @@ export async function parseErrorResponse(input: Response | string): Promise<OAut
 
     try {
         const result = OAuthErrorResponseSchema.parse(JSON.parse(body));
-        const { error, error_description, error_uri } = result;
-        const errorClass = OAUTH_ERRORS[error] || ServerError;
-        return new errorClass(error_description || '', error_uri);
+        return OAuthError.fromResponse(result);
     } catch (error) {
         // Not a valid OAuth error response, but try to inform the user of the raw data anyway
         const errorMessage = `${statusCode ? `HTTP ${statusCode}: ` : ''}Invalid OAuth error response: ${error}. Raw body: ${body}`;
-        return new ServerError(errorMessage);
+        return new OAuthError(OAuthErrorCode.ServerError, errorMessage);
     }
 }
 
@@ -371,12 +364,14 @@ export async function auth(
         return await authInternal(provider, options);
     } catch (error) {
         // Handle recoverable error types by invalidating credentials and retrying
-        if (error instanceof InvalidClientError || error instanceof UnauthorizedClientError) {
-            await provider.invalidateCredentials?.('all');
-            return await authInternal(provider, options);
-        } else if (error instanceof InvalidGrantError) {
-            await provider.invalidateCredentials?.('tokens');
-            return await authInternal(provider, options);
+        if (error instanceof OAuthError) {
+            if (error.code === OAuthErrorCode.InvalidClient || error.code === OAuthErrorCode.UnauthorizedClient) {
+                await provider.invalidateCredentials?.('all');
+                return await authInternal(provider, options);
+            } else if (error.code === OAuthErrorCode.InvalidGrant) {
+                await provider.invalidateCredentials?.('tokens');
+                return await authInternal(provider, options);
+            }
         }
 
         // Throw otherwise
@@ -437,7 +432,8 @@ async function authInternal(
         const clientMetadataUrl = provider.clientMetadataUrl;
 
         if (clientMetadataUrl && !isHttpsUrl(clientMetadataUrl)) {
-            throw new InvalidClientMetadataError(
+            throw new OAuthError(
+                OAuthErrorCode.InvalidClientMetadata,
                 `clientMetadataUrl must be a valid HTTPS URL with a non-root pathname, got: ${clientMetadataUrl}`
             );
         }
@@ -502,7 +498,7 @@ async function authInternal(
             return 'AUTHORIZED';
         } catch (error) {
             // If this is a ServerError, or an unknown type, log it out and try to continue. Otherwise, escalate so we can fix things and retry.
-            if (!(error instanceof OAuthError) || error instanceof ServerError) {
+            if (!(error instanceof OAuthError) || error.code === OAuthErrorCode.ServerError) {
                 // Could not refresh OAuth tokens
             } else {
                 // Refresh failed for another reason, re-throw