Implement SEP-1577 - Sampling With Tools (#1101)

Author: ochafik

src/examples/server/toolWithSampleServer.ts

@@ -33,13 +33,12 @@ mcpServer.registerTool(
             maxTokens: 500
         });
 
+        const contents = Array.isArray(response.content) ? response.content : [response.content];
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: response.content.type === 'text' ? response.content.text : 'Unable to generate summary'
-                }
-            ]
+            content: contents.map(content => ({
+                type: 'text',
+                text: content.type === 'text' ? content.text : 'Unable to generate summary'
+            }))
         };
     }
 );

src/spec.types.test.ts

@@ -360,11 +360,11 @@ const sdkTypeChecks = {
         sdk = spec;
         spec = sdk;
     },
-    SamplingMessage: (sdk: SDKTypes.SamplingMessage, spec: SpecTypes.SamplingMessage) => {
+    SamplingMessage: (sdk: RemovePassthrough<SDKTypes.SamplingMessage>, spec: SpecTypes.SamplingMessage) => {
         sdk = spec;
         spec = sdk;
     },
-    CreateMessageResult: (sdk: SDKTypes.CreateMessageResult, spec: SpecTypes.CreateMessageResult) => {
+    CreateMessageResult: (sdk: RemovePassthrough<SDKTypes.CreateMessageResult>, spec: SpecTypes.CreateMessageResult) => {
         sdk = spec;
         spec = sdk;
     },
@@ -614,6 +614,25 @@ const sdkTypeChecks = {
     ModelPreferences: (sdk: SDKTypes.ModelPreferences, spec: SpecTypes.ModelPreferences) => {
         sdk = spec;
         spec = sdk;
+    },
+    ToolChoice: (sdk: SDKTypes.ToolChoice, spec: SpecTypes.ToolChoice) => {
+        sdk = spec;
+        spec = sdk;
+    },
+    ToolUseContent: (sdk: RemovePassthrough<SDKTypes.ToolUseContent>, spec: SpecTypes.ToolUseContent) => {
+        sdk = spec;
+        spec = sdk;
+    },
+    ToolResultContent: (sdk: RemovePassthrough<SDKTypes.ToolResultContent>, spec: SpecTypes.ToolResultContent) => {
+        sdk = spec;
+        spec = sdk;
+    },
+    SamplingMessageContentBlock: (
+        sdk: RemovePassthrough<SDKTypes.SamplingMessageContentBlock>,
+        spec: SpecTypes.SamplingMessageContentBlock
+    ) => {
+        sdk = spec;
+        spec = sdk;
     }
 };
 
@@ -643,7 +662,7 @@ describe('Spec Types', () => {
     it('should define some expected types', () => {
         expect(specTypes).toContain('JSONRPCNotification');
         expect(specTypes).toContain('ElicitResult');
-        expect(specTypes).toHaveLength(123);
+        expect(specTypes).toHaveLength(127);
     });
 
     it('should have up to date list of missing sdk types', () => {

src/spec.types.ts

@@ -307,7 +307,17 @@ export interface ClientCapabilities {
   /**
    * Present if the client supports sampling from an LLM.
    */
-  sampling?: object;
+  sampling?: {
+    /**
+     * Whether the client supports context inclusion via includeContext parameter.
+     * If not declared, servers SHOULD only use `includeContext: "none"` (or omit it).
+     */
+    context?: object;
+    /**
+     * Whether the client supports tool use via tools and toolChoice parameters.
+     */
+    tools?: object;
+  };
   /**
    * Present if the client supports elicitation from the server.
    */
@@ -1255,7 +1265,11 @@ export interface CreateMessageRequestParams extends RequestParams {
    */
   systemPrompt?: string;
   /**
-   * A request to include context from one or more MCP servers (including the caller), to be attached to the prompt. The client MAY ignore this request.
+   * A request to include context from one or more MCP servers (including the caller), to be attached to the prompt.
+   * The client MAY ignore this request.
+   *
+   * Default is "none". Values "thisServer" and "allServers" are soft-deprecated. Servers SHOULD only use these values if the client
+   * declares ClientCapabilities.sampling.context. These values may be removed in future spec releases.
    */
   includeContext?: "none" | "thisServer" | "allServers";
   /**
@@ -1273,6 +1287,32 @@ export interface CreateMessageRequestParams extends RequestParams {
    * Optional metadata to pass through to the LLM provider. The format of this metadata is provider-specific.
    */
   metadata?: object;
+  /**
+   * Tools that the model may use during generation.
+   * The client MUST return an error if this field is provided but ClientCapabilities.sampling.tools is not declared.
+   */
+  tools?: Tool[];
+  /**
+   * Controls how the model uses tools.
+   * The client MUST return an error if this field is provided but ClientCapabilities.sampling.tools is not declared.
+   * Default is `{ mode: "auto" }`.
+   */
+  toolChoice?: ToolChoice;
+}
+
+/**
+ * Controls tool selection behavior for sampling requests.
+ *
+ * @category `sampling/createMessage`
+ */
+export interface ToolChoice {
+  /**
+   * Controls the tool use ability of the model:
+   * - "auto": Model decides whether to use tools (default)
+   * - "required": Model MUST use at least one tool before completing
+   * - "none": Model MUST NOT use any tools
+   */
+  mode?: "auto" | "required" | "none";
 }
 
 /**
@@ -1295,10 +1335,19 @@ export interface CreateMessageResult extends Result, SamplingMessage {
    * The name of the model that generated the message.
    */
   model: 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
+   * - "toolUse": The model wants to use one or more tools
+   *
+   * This field is an open string to allow for provider-specific stop reasons.
    */
-  stopReason?: "endTurn" | "stopSequence" | "maxTokens" | string;
+  stopReason?: "endTurn" | "stopSequence" | "maxTokens" | "toolUse" | string;
 }
 
 /**
@@ -1308,8 +1357,18 @@ export interface CreateMessageResult extends Result, SamplingMessage {
  */
 export interface SamplingMessage {
   role: Role;
-  content: TextContent | ImageContent | AudioContent;
+  content: SamplingMessageContentBlock | SamplingMessageContentBlock[];
+  /**
+   * See [General fields: `_meta`](/specification/draft/basic/index#meta) for notes on `_meta` usage.
+   */
+  _meta?: { [key: string]: unknown };
 }
+export type SamplingMessageContentBlock =
+  | TextContent
+  | ImageContent
+  | AudioContent
+  | ToolUseContent
+  | ToolResultContent;
 
 /**
  * Optional annotations for the client. The client can use annotations to inform how objects are used or displayed
@@ -1444,6 +1503,87 @@ export interface AudioContent {
   _meta?: { [key: string]: unknown };
 }
 
+/**
+ * A request from the assistant to call a tool.
+ *
+ * @category `sampling/createMessage`
+ */
+export interface ToolUseContent {
+  type: "tool_use";
+
+  /**
+   * A unique identifier for this tool use.
+   *
+   * This ID is used to match tool results to their corresponding tool uses.
+   */
+  id: string;
+
+  /**
+   * The name of the tool to call.
+   */
+  name: string;
+
+  /**
+   * The arguments to pass to the tool, conforming to the tool's input schema.
+   */
+  input: { [key: string]: unknown };
+
+  /**
+   * Optional metadata about the tool use. Clients SHOULD preserve this field when
+   * including tool uses in subsequent sampling requests to enable caching optimizations.
+   *
+   * See [General fields: `_meta`](/specification/draft/basic/index#meta) for notes on `_meta` usage.
+   */
+  _meta?: { [key: string]: unknown };
+}
+
+/**
+ * The result of a tool use, provided by the user back to the assistant.
+ *
+ * @category `sampling/createMessage`
+ */
+export interface ToolResultContent {
+  type: "tool_result";
+
+  /**
+   * The ID of the tool use this result corresponds to.
+   *
+   * This MUST match the ID from a previous ToolUseContent.
+   */
+  toolUseId: string;
+
+  /**
+   * The unstructured result content of the tool use.
+   *
+   * This has the same format as CallToolResult.content and can include text, images,
+   * audio, resource links, and embedded resources.
+   */
+  content: ContentBlock[];
+
+  /**
+   * An optional structured result object.
+   *
+   * If the tool defined an outputSchema, this SHOULD conform to that schema.
+   */
+  structuredContent?: { [key: string]: unknown };
+
+  /**
+   * Whether the tool use resulted in an error.
+   *
+   * If true, the content typically describes the error that occurred.
+   * Default: false
+   */
+  isError?: boolean;
+
+  /**
+   * Optional metadata about the tool result. Clients SHOULD preserve this field when
+   * including tool results in subsequent sampling requests to enable caching optimizations.
+   *
+   * See [General fields: `_meta`](/specification/draft/basic/index#meta) for notes on `_meta` usage.
+   */
+  _meta?: { [key: string]: unknown };
+}
+
 /**
  * The server's preferences for model selection, requested of the client during sampling.
  *
@@ -1762,7 +1902,6 @@ export interface ElicitRequest extends JSONRPCRequest {
   params: ElicitRequestParams;
 }
 
-/**
 /**
  * Restricted schema definitions that only allow primitive types
  * without nested objects or arrays.