merge commit

Author: KKonstantinov

.npmrc

@@ -1 +1,2 @@
 registry = "https://registry.npmjs.org/"
+manage-package-manager-versions=false

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

@@ -0,0 +1,66 @@
+/**
+ * Example: Custom Protocol Version Support
+ *
+ * This demonstrates how to support protocol versions not yet in the SDK.
+ * First version in the list is used as fallback when client requests
+ * an unsupported version.
+ *
+ * Run with: pnpm tsx src/customProtocolVersion.ts
+ */
+
+import { randomUUID } from 'node:crypto';
+import { createServer } from 'node:http';
+
+import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
+import type { CallToolResult } from '@modelcontextprotocol/server';
+import { McpServer, SUPPORTED_PROTOCOL_VERSIONS } from '@modelcontextprotocol/server';
+
+// Add support for a newer protocol version (first in list is fallback)
+const CUSTOM_VERSIONS = ['2026-01-01', ...SUPPORTED_PROTOCOL_VERSIONS];
+
+const server = new McpServer(
+    { name: 'custom-protocol-server', version: '1.0.0' },
+    {
+        supportedProtocolVersions: CUSTOM_VERSIONS,
+        capabilities: { tools: {} }
+    }
+);
+
+// Register a tool that shows the protocol configuration
+server.registerTool(
+    'get-protocol-info',
+    {
+        title: 'Protocol Info',
+        description: 'Returns protocol version configuration',
+        inputSchema: {}
+    },
+    async (): Promise<CallToolResult> => ({
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({ supportedVersions: CUSTOM_VERSIONS }, null, 2)
+            }
+        ]
+    })
+);
+
+// Create transport - server passes versions automatically during connect()
+const transport = new NodeStreamableHTTPServerTransport({
+    sessionIdGenerator: () => randomUUID()
+});
+
+await server.connect(transport);
+
+// Simple HTTP server
+const PORT = process.env.MCP_PORT ? Number.parseInt(process.env.MCP_PORT, 10) : 3000;
+
+createServer(async (req, res) => {
+    if (req.url === '/mcp') {
+        await transport.handleRequest(req, res);
+    } else {
+        res.writeHead(404).end('Not Found');
+    }
+}).listen(PORT, () => {
+    console.log(`MCP server with custom protocol versions on port ${PORT}`);
+    console.log(`Supported versions: ${CUSTOM_VERSIONS.join(', ')}`);
+});

examples/client/src/simpleTaskInteractiveClient.ts

@@ -33,12 +33,12 @@
         "lint:fix:all": "pnpm -r lint:fix",
         "check:all": "pnpm -r typecheck && pnpm -r lint",
         "test:all": "pnpm -r test",
-        "test:conformance:client": "conformance client --command 'npx tsx src/conformance/everything-client.ts'",
-        "test:conformance:client:all": "conformance client --command 'npx tsx src/conformance/everything-client.ts' --suite all",
-        "test:conformance:client:run": "npx tsx src/conformance/everything-client.ts",
-        "test:conformance:server": "scripts/run-server-conformance.sh",
-        "test:conformance:server:all": "scripts/run-server-conformance.sh --suite all",
-        "test:conformance:server:run": "npx tsx src/conformance/everything-server.ts",
+        "test:conformance:client": "pnpm --filter @modelcontextprotocol/test-conformance run test:conformance:client",
+        "test:conformance:client:all": "pnpm --filter @modelcontextprotocol/test-conformance run test:conformance:client:all",
+        "test:conformance:client:run": "pnpm --filter @modelcontextprotocol/test-conformance run test:conformance:client:run",
+        "test:conformance:server": "pnpm --filter @modelcontextprotocol/test-conformance run test:conformance:server",
+        "test:conformance:server:all": "pnpm --filter @modelcontextprotocol/test-conformance run test:conformance:server:all",
+        "test:conformance:server:run": "pnpm --filter @modelcontextprotocol/test-conformance run test:conformance:server:run",
         "test:conformance:all": "pnpm run test:conformance:client:all && pnpm run test:conformance:server:all"
     },
     "devDependencies": {
@@ -47,7 +47,6 @@
         "@changesets/cli": "^2.29.8",
         "@eslint/js": "catalog:devTools",
         "@modelcontextprotocol/client": "workspace:^",
-        "@modelcontextprotocol/conformance": "0.1.10",
         "@modelcontextprotocol/server": "workspace:^",
         "@modelcontextprotocol/node": "workspace:^",
         "@types/content-type": "catalog:devTools",
@@ -60,12 +59,10 @@
         "@types/supertest": "catalog:devTools",
         "@types/ws": "catalog:devTools",
         "@typescript/native-preview": "catalog:devTools",
-        "cors": "catalog:runtimeServerOnly",
         "eslint": "catalog:devTools",
         "eslint-config-prettier": "catalog:devTools",
         "eslint-plugin-n": "catalog:devTools",
         "fast-glob": "^3.3.3",
-        "express": "catalog:runtimeServerOnly",
         "prettier": "catalog:devTools",
         "supertest": "catalog:devTools",
         "tsdown": "catalog:devTools",

examples/server/src/customProtocolVersion.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