feat: backwards-compatible createMessage overloads for SEP-1577

Introduce method overloading for createMessage to preserve backwards
compatibility while supporting the new tools feature from SEP-1577.

When called without tools, createMessage returns CreateMessageResult
with single content (backwards compatible). When called with tools,
it returns CreateMessageResultWithTools which allows array content.

This allows existing code that doesn't use tools to continue working
without any changes, while new code using tools gets the appropriate
type that handles array content.

Changes:
- Add SamplingContentSchema for basic content types (no tool use)
- Add CreateMessageResultWithToolsSchema for tool-enabled responses
- Add CreateMessageRequestParamsBase/WithTools types for overloads
- Add method overloads to Server.createMessage()
- Update tests to use appropriate schemas
- Simplify example that doesn't use tools

Author: felixweinberger

src/examples/server/toolWithSampleServer.ts

@@ -33,12 +33,14 @@ mcpServer.registerTool(
             maxTokens: 500
         });
 
-        const contents = Array.isArray(response.content) ? response.content : [response.content];
+        // Since we're not using tools, response.content is guaranteed to be single content
         return {
-            content: contents.map(content => ({
-                type: 'text',
-                text: content.type === 'text' ? content.text : 'Unable to generate summary'
-            }))
+            content: [
+                {
+                    type: 'text',
+                    text: response.content.type === 'text' ? response.content.text : 'Unable to generate summary'
+                }
+            ]
         };
     }
 );

src/server/index.ts

@@ -2,7 +2,12 @@ import { mergeCapabilities, Protocol, type NotificationOptions, type ProtocolOpt
 import {
     type ClientCapabilities,
     type CreateMessageRequest,
+    type CreateMessageResult,
     CreateMessageResultSchema,
+    type CreateMessageResultWithTools,
+    CreateMessageResultWithToolsSchema,
+    type CreateMessageRequestParamsBase,
+    type CreateMessageRequestParamsWithTools,
     type ElicitRequestFormParams,
     type ElicitRequestURLParams,
     type ElicitResult,
@@ -467,7 +472,32 @@ export class Server<
         return this.request({ method: 'ping' }, EmptyResultSchema);
     }
 
-    async createMessage(params: CreateMessageRequest['params'], options?: RequestOptions) {
+    /**
+     * Request LLM sampling from the client (without tools).
+     * Returns single content block for backwards compatibility.
+     */
+    async createMessage(params: CreateMessageRequestParamsBase, options?: RequestOptions): Promise<CreateMessageResult>;
+
+    /**
+     * Request LLM sampling from the client with tool support.
+     * Returns content that may be a single block or array (for parallel tool calls).
+     */
+    async createMessage(params: CreateMessageRequestParamsWithTools, options?: RequestOptions): Promise<CreateMessageResultWithTools>;
+
+    /**
+     * Request LLM sampling from the client.
+     * When tools may or may not be present, returns the union type.
+     */
+    async createMessage(
+        params: CreateMessageRequest['params'],
+        options?: RequestOptions
+    ): Promise<CreateMessageResult | CreateMessageResultWithTools>;
+
+    // Implementation
+    async createMessage(
+        params: CreateMessageRequest['params'],
+        options?: RequestOptions
+    ): Promise<CreateMessageResult | CreateMessageResultWithTools> {
         // Capability check - only required when tools/toolChoice are provided
         if (params.tools || params.toolChoice) {
             if (!this._clientCapabilities?.sampling?.tools) {
@@ -510,6 +540,10 @@ export class Server<
             }
         }
 
+        // Use different schemas based on whether tools are provided
+        if (params.tools) {
+            return this.request({ method: 'sampling/createMessage', params }, CreateMessageResultWithToolsSchema, options);
+        }
         return this.request({ method: 'sampling/createMessage', params }, CreateMessageResultSchema, options);
     }
 

src/types.test.ts

@@ -13,6 +13,7 @@ import {
     SamplingMessageSchema,
     CreateMessageRequestSchema,
     CreateMessageResultSchema,
+    CreateMessageResultWithToolsSchema,
     ClientCapabilitiesSchema
 } from './types.js';
 
@@ -787,7 +788,7 @@ describe('Types', () => {
             }
         });
 
-        test('should validate result with tool call', () => {
+        test('should validate result with tool call (using WithTools schema)', () => {
             const result = {
                 model: 'claude-3-5-sonnet-20241022',
                 role: 'assistant',
@@ -800,7 +801,8 @@ describe('Types', () => {
                 stopReason: 'toolUse'
             };
 
-            const parseResult = CreateMessageResultSchema.safeParse(result);
+            // Tool call results use CreateMessageResultWithToolsSchema
+            const parseResult = CreateMessageResultWithToolsSchema.safeParse(result);
             expect(parseResult.success).toBe(true);
             if (parseResult.success) {
                 expect(parseResult.data.stopReason).toBe('toolUse');
@@ -810,9 +812,13 @@ describe('Types', () => {
                     expect(content.type).toBe('tool_use');
                 }
             }
+
+            // Basic CreateMessageResultSchema should NOT accept tool_use content
+            const basicResult = CreateMessageResultSchema.safeParse(result);
+            expect(basicResult.success).toBe(false);
         });
 
-        test('should validate result with array content', () => {
+        test('should validate result with array content (using WithTools schema)', () => {
             const result = {
                 model: 'claude-3-5-sonnet-20241022',
                 role: 'assistant',
@@ -828,7 +834,8 @@ describe('Types', () => {
                 stopReason: 'toolUse'
             };
 
-            const parseResult = CreateMessageResultSchema.safeParse(result);
+            // Array content uses CreateMessageResultWithToolsSchema
+            const parseResult = CreateMessageResultWithToolsSchema.safeParse(result);
             expect(parseResult.success).toBe(true);
             if (parseResult.success) {
                 expect(parseResult.data.stopReason).toBe('toolUse');
@@ -840,6 +847,10 @@ describe('Types', () => {
                     expect(content[1].type).toBe('tool_use');
                 }
             }
+
+            // Basic CreateMessageResultSchema should NOT accept array content
+            const basicResult = CreateMessageResultSchema.safeParse(result);
+            expect(basicResult.success).toBe(false);
         });
 
         test('should validate all new stop reasons', () => {

src/types.ts

@@ -1495,6 +1495,12 @@ export const ToolResultContentSchema = z
     })
     .passthrough();
 
+/**
+ * Basic content types for sampling responses (without tool use).
+ * Used for backwards-compatible CreateMessageResult when tools are not used.
+ */
+export const SamplingContentSchema = z.discriminatedUnion('type', [TextContentSchema, ImageContentSchema, AudioContentSchema]);
+
 /**
  * Content block types allowed in sampling messages.
  * This includes text, image, audio, tool use requests, and tool results.
@@ -1576,9 +1582,38 @@ export const CreateMessageRequestSchema = RequestSchema.extend({
 });
 
 /**
- * The client's response to a sampling/create_message request from the server. The client should inform the user before returning the sampled message, to allow them to inspect the response (human in the loop) and decide whether to allow the server to see it.
+ * The client's response to a sampling/create_message request from the server.
+ * This is the backwards-compatible version that returns single content (no arrays).
+ * Used when the request does not include tools.
  */
 export const CreateMessageResultSchema = ResultSchema.extend({
+    /**
+     * The name of the model that generated the message.
+     */
+    model: z.string(),
+    /**
+     * The reason why sampling stopped, if known.
+     *
+     * Standard values:
+     * - "endTurn": Natural end of the assistant's turn
+     * - "stopSequence": A stop sequence was encountered
+     * - "maxTokens": Maximum token limit was reached
+     *
+     * This field is an open string to allow for provider-specific stop reasons.
+     */
+    stopReason: z.optional(z.enum(['endTurn', 'stopSequence', 'maxTokens']).or(z.string())),
+    role: z.enum(['user', 'assistant']),
+    /**
+     * Response content. Single content block (text, image, or audio).
+     */
+    content: SamplingContentSchema
+});
+
+/**
+ * The client's response to a sampling/create_message request when tools were provided.
+ * This version supports array content for tool use flows.
+ */
+export const CreateMessageResultWithToolsSchema = ResultSchema.extend({
     /**
      * The name of the model that generated the message.
      */
@@ -1597,7 +1632,7 @@ export const CreateMessageResultSchema = ResultSchema.extend({
     stopReason: z.optional(z.enum(['endTurn', 'stopSequence', 'maxTokens', 'toolUse']).or(z.string())),
     role: z.enum(['user', 'assistant']),
     /**
-     * Response content. May be ToolUseContent if stopReason is "toolUse".
+     * Response content. May be a single block or array. May include ToolUseContent if stopReason is "toolUse".
      */
     content: z.union([SamplingMessageContentBlockSchema, z.array(SamplingMessageContentBlockSchema)])
 });
@@ -2005,6 +2040,7 @@ export const ClientNotificationSchema = z.union([
 export const ClientResultSchema = z.union([
     EmptyResultSchema,
     CreateMessageResultSchema,
+    CreateMessageResultWithToolsSchema,
     ElicitResultSchema,
     ListRootsResultSchema,
     GetTaskResultSchema,
@@ -2274,11 +2310,26 @@ export type LoggingMessageNotification = Infer<typeof LoggingMessageNotification
 export type ToolChoice = Infer<typeof ToolChoiceSchema>;
 export type ModelHint = Infer<typeof ModelHintSchema>;
 export type ModelPreferences = Infer<typeof ModelPreferencesSchema>;
+export type SamplingContent = Infer<typeof SamplingContentSchema>;
 export type SamplingMessageContentBlock = Infer<typeof SamplingMessageContentBlockSchema>;
 export type SamplingMessage = Infer<typeof SamplingMessageSchema>;
 export type CreateMessageRequestParams = Infer<typeof CreateMessageRequestParamsSchema>;
 export type CreateMessageRequest = Infer<typeof CreateMessageRequestSchema>;
 export type CreateMessageResult = Infer<typeof CreateMessageResultSchema>;
+export type CreateMessageResultWithTools = Infer<typeof CreateMessageResultWithToolsSchema>;
+
+/**
+ * CreateMessageRequestParams without tools - for backwards-compatible overload.
+ * Excludes tools/toolChoice to indicate they should not be provided.
+ */
+export type CreateMessageRequestParamsBase = Omit<CreateMessageRequestParams, 'tools' | 'toolChoice'>;
+
+/**
+ * CreateMessageRequestParams with required tools - for tool-enabled overload.
+ */
+export interface CreateMessageRequestParamsWithTools extends CreateMessageRequestParams {
+    tools: Tool[];
+}
 
 /* Elicitation */
 export type BooleanSchema = Infer<typeof BooleanSchemaSchema>;