feat: add union types for type narrowing (McpRequest, McpNotification, McpResult)

- Generate discriminated union types from base interfaces for type narrowing
- Naming scheme: base types keep original names (Request, Notification, Result),
  union types get Mcp prefix (McpRequest, McpNotification, McpResult)
- Client and Server classes now default to union types for better DX
- Add deprecated aliases (RequestBase, NotificationBase, ResultBase) for migration
- Fix type errors in tests and examples by adding proper type casts

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: ochafik

scripts/generate-schemas.ts

@@ -276,11 +276,12 @@ const BASE_TO_UNION_CONFIG: Record<string, string[]> = {
  *   interface InitializeResult extends Result { ... }
  *
  * Into:
- *   interface ResultBase { _meta?: {...} }
- *   interface InitializeResult extends ResultBase { ... }
- *   type Result = InitializeResult | CompleteResult | ...
+ *   interface Result { _meta?: {...} }  // Base stays as-is
+ *   interface InitializeResult extends Result { ... }
+ *   type McpResult = InitializeResult | CompleteResult | ...  // Union with Mcp prefix
  *
- * This enables TypeScript union narrowing while preserving the extends hierarchy.
+ * This enables TypeScript union narrowing while preserving backwards compatibility.
+ * The base type keeps its original name, and the union gets an "Mcp" prefix.
  */
 function convertBaseTypesToUnions(content: string): string {
     const project = new Project({ useInMemoryFileSystem: true });
@@ -295,37 +296,16 @@ function convertBaseTypesToUnions(content: string): string {
             continue;
         }
 
-        const baseRename = `${baseName}Base`;
-
-        // 1. Rename the base interface to ResultBase
-        baseInterface.rename(baseRename);
-
-        // 2. Update all extends clauses that reference the old name
-        for (const iface of sourceFile.getInterfaces()) {
-            for (const ext of iface.getExtends()) {
-                if (ext.getText() === baseName) {
-                    ext.replaceWithText(baseRename);
-                }
-            }
-        }
-
-        // 3. Update type aliases that use intersection with the base
-        for (const typeAlias of sourceFile.getTypeAliases()) {
-            const typeNode = typeAlias.getTypeNode();
-            if (typeNode) {
-                const text = typeNode.getText();
-                if (text.includes(baseName) && !text.includes(baseRename)) {
-                    typeAlias.setType(text.replace(new RegExp(`\\b${baseName}\\b`, 'g'), baseRename));
-                }
-            }
-        }
+        // Base interface keeps its original name (Request, Notification, Result)
+        // Union type gets Mcp prefix (McpRequest, McpNotification, McpResult)
+        const unionName = `Mcp${baseName}`;
 
-        // 4. Add the union type alias after the base interface
+        // Add the union type alias after the base interface
         const unionType = unionMembers.join(' | ');
         const insertPos = baseInterface.getEnd();
-        sourceFile.insertText(insertPos, `\n\n/** Union of all ${baseName.toLowerCase()} types for type narrowing. */\nexport type ${baseName} = ${unionType};`);
+        sourceFile.insertText(insertPos, `\n\n/** Union of all MCP ${baseName.toLowerCase()} types for type narrowing. */\nexport type ${unionName} = ${unionType};`);
 
-        console.log(`    ✓ Converted ${baseName} to union of ${unionMembers.length} types`);
+        console.log(`    ✓ Created ${unionName} as union of ${unionMembers.length} types`);
     }
 
     return sourceFile.getFullText();

src/client/index.ts

@@ -48,7 +48,10 @@ import {
     type ListChangedHandlers,
     type Request,
     type Notification,
-    type Result
+    type Result,
+    type McpRequest,
+    type McpNotification,
+    type McpResult
 } from '../types.js';
 import { AjvJsonSchemaValidator } from '../validation/ajv-provider.js';
 import type { JsonSchemaType, JsonSchemaValidator, jsonSchemaValidator } from '../validation/types.js';
@@ -231,9 +234,9 @@ export type ClientOptions = ProtocolOptions & {
  * ```
  */
 export class Client<
-    RequestT extends Request = Request,
-    NotificationT extends Notification = Notification,
-    ResultT extends Result = Result
+    RequestT extends Request = McpRequest,
+    NotificationT extends Notification = McpNotification,
+    ResultT extends Result = McpResult
 > extends Protocol<ClientRequest | RequestT, ClientNotification | NotificationT, ClientResult | ResultT> {
     private _serverCapabilities?: ServerCapabilities;
     private _serverVersion?: Implementation;

src/examples/server/simpleStreamableHttp.ts

@@ -488,7 +488,7 @@ const getServer = () => {
                                 text: `Completed ${duration}ms delay`
                             }
                         ]
-                    });
+                    } as CallToolResult);
                 })();
 
                 // Return CreateTaskResult with the created task

src/examples/server/simpleTaskInteractive.ts

@@ -561,7 +561,7 @@ const createServer = (): Server => {
                     console.log(`[Server] Completing task with result: ${text}`);
                     await taskStore.storeTaskResult(task.taskId, 'completed', {
                         content: [{ type: 'text', text }]
-                    });
+                    } as CallToolResult);
                 } else if (name === 'write_haiku') {
                     const topic = args?.topic ?? 'nature';
                     console.log(`[Server] write_haiku: topic '${topic}'`);
@@ -586,14 +586,14 @@ const createServer = (): Server => {
                     console.log('[Server] Completing task with haiku');
                     await taskStore.storeTaskResult(task.taskId, 'completed', {
                         content: [{ type: 'text', text: `Haiku:\n${haiku}` }]
-                    });
+                    } as CallToolResult);
                 }
             } catch (error) {
                 console.error(`[Server] Task ${task.taskId} failed:`, error);
                 await taskStore.storeTaskResult(task.taskId, 'failed', {
                     content: [{ type: 'text', text: `Error: ${error}` }],
                     isError: true
-                });
+                } as CallToolResult);
             } finally {
                 activeTaskExecutions.delete(task.taskId);
             }