@modelcontextprotocol/sdk 1.22.0 → 1.23.0-beta.0

package/dist/esm/types.js

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import * as z from 'zod/v4';
 export const LATEST_PROTOCOL_VERSION = '2025-06-18';
 export const DEFAULT_NEGOTIATED_PROTOCOL_VERSION = '2025-03-26';
 export const SUPPORTED_PROTOCOL_VERSIONS = [LATEST_PROTOCOL_VERSION, '2025-03-26', '2024-11-05', '2024-10-07'];
@@ -18,21 +18,16 @@ export const ProgressTokenSchema = z.union([z.string(), z.number().int()]);
  * An opaque token used to represent a cursor for pagination.
  */
 export const CursorSchema = z.string();
-const RequestMetaSchema = z
-    .object({
+const RequestMetaSchema = z.looseObject({
     /**
      * If specified, the caller is requesting out-of-band progress notifications for this request (as represented by notifications/progress). The value of this parameter is an opaque token that will be attached to any subsequent notifications. The receiver is not obligated to provide these notifications.
      */
     progressToken: ProgressTokenSchema.optional()
-})
-    /**
-     * Passthrough required here because we want to allow any additional fields to be added to the request meta.
-     */
-    .passthrough();
+});
 /**
  * Common params for any request.
  */
-const BaseRequestParamsSchema = z.object({
+const BaseRequestParamsSchema = z.looseObject({
     /**
      * See [General fields: `_meta`](/specification/draft/basic/index#meta) for notes on `_meta` usage.
      */
@@ -40,9 +35,9 @@ const BaseRequestParamsSchema = z.object({
 });
 export const RequestSchema = z.object({
     method: z.string(),
-    params: BaseRequestParamsSchema.passthrough().optional()
+    params: BaseRequestParamsSchema.optional()
 });
-const NotificationsParamsSchema = z.object({
+const NotificationsParamsSchema = z.looseObject({
     /**
      * See [MCP specification](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/47339c03c143bb4ec01a26e721a1b8fe66634ebe/docs/specification/draft/basic/index.mdx#general-fields)
      * for notes on _meta usage.
@@ -51,20 +46,15 @@ const NotificationsParamsSchema = z.object({
 });
 export const NotificationSchema = z.object({
     method: z.string(),
-    params: NotificationsParamsSchema.passthrough().optional()
+    params: NotificationsParamsSchema.optional()
 });
-export const ResultSchema = z
-    .object({
+export const ResultSchema = z.looseObject({
     /**
      * See [MCP specification](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/47339c03c143bb4ec01a26e721a1b8fe66634ebe/docs/specification/draft/basic/index.mdx#general-fields)
      * for notes on _meta usage.
      */
     _meta: z.record(z.string(), z.unknown()).optional()
-})
-    /**
-     * Passthrough required here because we want to allow any additional fields to be added to the result.
-     */
-    .passthrough();
+});
 /**
  * A uniquely identifying ID for a request in JSON-RPC.
  */
@@ -75,9 +65,9 @@ export const RequestIdSchema = z.union([z.string(), z.number().int()]);
 export const JSONRPCRequestSchema = z
     .object({
     jsonrpc: z.literal(JSONRPC_VERSION),
-    id: RequestIdSchema
+    id: RequestIdSchema,
+    ...RequestSchema.shape
 })
-    .merge(RequestSchema)
     .strict();
 export const isJSONRPCRequest = (value) => JSONRPCRequestSchema.safeParse(value).success;
 /**
@@ -85,9 +75,9 @@ export const isJSONRPCRequest = (value) => JSONRPCRequestSchema.safeParse(value)
  */
 export const JSONRPCNotificationSchema = z
     .object({
-    jsonrpc: z.literal(JSONRPC_VERSION)
+    jsonrpc: z.literal(JSONRPC_VERSION),
+    ...NotificationSchema.shape
 })
-    .merge(NotificationSchema)
     .strict();
 export const isJSONRPCNotification = (value) => JSONRPCNotificationSchema.safeParse(value).success;
 /**
@@ -115,6 +105,8 @@ export var ErrorCode;
     ErrorCode[ErrorCode["MethodNotFound"] = -32601] = "MethodNotFound";
     ErrorCode[ErrorCode["InvalidParams"] = -32602] = "InvalidParams";
     ErrorCode[ErrorCode["InternalError"] = -32603] = "InternalError";
+    // MCP-specific error codes
+    ErrorCode[ErrorCode["UrlElicitationRequired"] = -32042] = "UrlElicitationRequired";
 })(ErrorCode || (ErrorCode = {}));
 /**
  * A response to a request that indicates an error occurred.
@@ -232,12 +224,28 @@ export const BaseMetadataSchema = z.object({
  * Describes the name and version of an MCP implementation.
  */
 export const ImplementationSchema = BaseMetadataSchema.extend({
+    ...BaseMetadataSchema.shape,
+    ...IconsSchema.shape,
     version: z.string(),
     /**
      * An optional URL of the website for this implementation.
      */
     websiteUrl: z.string().optional()
-}).merge(IconsSchema);
+});
+const FormElicitationCapabilitySchema = z.intersection(z.object({
+    applyDefaults: z.boolean().optional()
+}), z.record(z.string(), z.unknown()));
+const ElicitationCapabilitySchema = z.preprocess(value => {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        if (Object.keys(value).length === 0) {
+            return { form: {} };
+        }
+    }
+    return value;
+}, z.intersection(z.object({
+    form: FormElicitationCapabilitySchema.optional(),
+    url: AssertObjectSchema.optional()
+}), z.record(z.string(), z.unknown()).optional()));
 /**
  * Capabilities a client may support. Known capabilities are defined here, in this schema, but this is not a closed set: any client can define its own, additional capabilities.
  */
@@ -249,18 +257,23 @@ export const ClientCapabilitiesSchema = z.object({
     /**
      * Present if the client supports sampling from an LLM.
      */
-    sampling: AssertObjectSchema.optional(),
-    /**
-     * Present if the client supports eliciting user input.
-     */
-    elicitation: z.intersection(z
+    sampling: z
         .object({
         /**
-         * Whether the client should apply defaults to the user input.
+         * Present if the client supports context inclusion via includeContext parameter.
+         * If not declared, servers SHOULD only use `includeContext: "none"` (or omit it).
+         */
+        context: AssertObjectSchema.optional(),
+        /**
+         * Present if the client supports tool use via tools and toolChoice parameters.
          */
-        applyDefaults: z.boolean().optional()
+        tools: AssertObjectSchema.optional()
     })
-        .optional(), z.record(z.string(), z.unknown()).optional()),
+        .optional(),
+    /**
+     * Present if the client supports eliciting user input.
+     */
+    elicitation: ElicitationCapabilitySchema.optional(),
     /**
      * Present if the client supports listing roots.
      */
@@ -387,7 +400,9 @@ export const ProgressSchema = z.object({
      */
     message: z.optional(z.string())
 });
-export const ProgressNotificationParamsSchema = NotificationsParamsSchema.merge(ProgressSchema).extend({
+export const ProgressNotificationParamsSchema = z.object({
+    ...NotificationsParamsSchema.shape,
+    ...ProgressSchema.shape,
     /**
      * The progress token which was given in the initial request, used to associate this notification with the request that is proceeding.
      */
@@ -470,7 +485,9 @@ export const BlobResourceContentsSchema = ResourceContentsSchema.extend({
 /**
  * A known resource that the server is capable of reading.
  */
-export const ResourceSchema = BaseMetadataSchema.extend({
+export const ResourceSchema = z.object({
+    ...BaseMetadataSchema.shape,
+    ...IconsSchema.shape,
     /**
      * The URI of this resource.
      */
@@ -489,12 +506,14 @@ export const ResourceSchema = BaseMetadataSchema.extend({
      * See [MCP specification](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/47339c03c143bb4ec01a26e721a1b8fe66634ebe/docs/specification/draft/basic/index.mdx#general-fields)
      * for notes on _meta usage.
      */
-    _meta: z.optional(z.object({}).passthrough())
-}).merge(IconsSchema);
+    _meta: z.optional(z.looseObject({}))
+});
 /**
  * A template description for resources available on the server.
  */
-export const ResourceTemplateSchema = BaseMetadataSchema.extend({
+export const ResourceTemplateSchema = z.object({
+    ...BaseMetadataSchema.shape,
+    ...IconsSchema.shape,
     /**
      * A URI template (according to RFC 6570) that can be used to construct resource URIs.
      */
@@ -513,8 +532,8 @@ export const ResourceTemplateSchema = BaseMetadataSchema.extend({
      * See [MCP specification](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/47339c03c143bb4ec01a26e721a1b8fe66634ebe/docs/specification/draft/basic/index.mdx#general-fields)
      * for notes on _meta usage.
      */
-    _meta: z.optional(z.object({}).passthrough())
-}).merge(IconsSchema);
+    _meta: z.optional(z.looseObject({}))
+});
 /**
  * Sent from the client to request a list of resources the server has.
  */
@@ -623,7 +642,9 @@ export const PromptArgumentSchema = z.object({
 /**
  * A prompt or prompt template that the server offers.
  */
-export const PromptSchema = BaseMetadataSchema.extend({
+export const PromptSchema = z.object({
+    ...BaseMetadataSchema.shape,
+    ...IconsSchema.shape,
     /**
      * An optional description of what this prompt provides
      */
@@ -636,8 +657,8 @@ export const PromptSchema = BaseMetadataSchema.extend({
      * See [MCP specification](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/47339c03c143bb4ec01a26e721a1b8fe66634ebe/docs/specification/draft/basic/index.mdx#general-fields)
      * for notes on _meta usage.
      */
-    _meta: z.optional(z.object({}).passthrough())
-}).merge(IconsSchema);
+    _meta: z.optional(z.looseObject({}))
+});
 /**
  * Sent from the client to request a list of prompts and prompt templates the server has.
  */
@@ -723,6 +744,35 @@ export const AudioContentSchema = z.object({
      */
     _meta: z.record(z.string(), z.unknown()).optional()
 });
+/**
+ * A tool call request from an assistant (LLM).
+ * Represents the assistant's request to use a tool.
+ */
+export const ToolUseContentSchema = z
+    .object({
+    type: z.literal('tool_use'),
+    /**
+     * The name of the tool to invoke.
+     * Must match a tool name from the request's tools array.
+     */
+    name: z.string(),
+    /**
+     * Unique identifier for this tool call.
+     * Used to correlate with ToolResultContent in subsequent messages.
+     */
+    id: z.string(),
+    /**
+     * Arguments to pass to the tool.
+     * Must conform to the tool's inputSchema.
+     */
+    input: z.object({}).passthrough(),
+    /**
+     * See [MCP specification](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/47339c03c143bb4ec01a26e721a1b8fe66634ebe/docs/specification/draft/basic/index.mdx#general-fields)
+     * for notes on _meta usage.
+     */
+    _meta: z.optional(z.object({}).passthrough())
+})
+    .passthrough();
 /**
  * The contents of a resource, embedded into a prompt or tool call result.
  */
@@ -829,7 +879,9 @@ export const ToolAnnotationsSchema = z.object({
 /**
  * Definition for a tool the client can call.
  */
-export const ToolSchema = BaseMetadataSchema.extend({
+export const ToolSchema = z.object({
+    ...BaseMetadataSchema.shape,
+    ...IconsSchema.shape,
     /**
      * A human-readable description of the tool.
      */
@@ -851,9 +903,6 @@ export const ToolSchema = BaseMetadataSchema.extend({
         type: z.literal('object'),
         properties: z.record(z.string(), AssertObjectSchema).optional(),
         required: z.optional(z.array(z.string())),
-        /**
-         * Not in the MCP specification, but added to support the Ajv validator while removing .passthrough() which previously allowed additionalProperties to be passed through.
-         */
         additionalProperties: z.optional(z.boolean())
     })
         .optional(),
@@ -866,7 +915,7 @@ export const ToolSchema = BaseMetadataSchema.extend({
      * for notes on _meta usage.
      */
     _meta: z.record(z.string(), z.unknown()).optional()
-}).merge(IconsSchema);
+});
 /**
  * Sent from the client to request a list of tools the server has.
  */
@@ -1020,13 +1069,61 @@ export const ModelPreferencesSchema = z.object({
      */
     intelligencePriority: z.optional(z.number().min(0).max(1))
 });
+/**
+ * Controls tool usage behavior in sampling requests.
+ */
+export const ToolChoiceSchema = z.object({
+    /**
+     * Controls when tools are used:
+     * - "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: z.optional(z.enum(['auto', 'required', 'none']))
+});
+/**
+ * The result of a tool execution, provided by the user (server).
+ * Represents the outcome of invoking a tool requested via ToolUseContent.
+ */
+export const ToolResultContentSchema = z
+    .object({
+    type: z.literal('tool_result'),
+    toolUseId: z.string().describe('The unique identifier for the corresponding tool call.'),
+    content: z.array(ContentBlockSchema).default([]),
+    structuredContent: z.object({}).passthrough().optional(),
+    isError: z.optional(z.boolean()),
+    /**
+     * See [MCP specification](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/47339c03c143bb4ec01a26e721a1b8fe66634ebe/docs/specification/draft/basic/index.mdx#general-fields)
+     * for notes on _meta usage.
+     */
+    _meta: z.optional(z.object({}).passthrough())
+})
+    .passthrough();
+/**
+ * Content block types allowed in sampling messages.
+ * This includes text, image, audio, tool use requests, and tool results.
+ */
+export const SamplingMessageContentBlockSchema = z.discriminatedUnion('type', [
+    TextContentSchema,
+    ImageContentSchema,
+    AudioContentSchema,
+    ToolUseContentSchema,
+    ToolResultContentSchema
+]);
 /**
  * Describes a message issued to or received from an LLM API.
  */
-export const SamplingMessageSchema = z.object({
+export const SamplingMessageSchema = z
+    .object({
     role: z.enum(['user', 'assistant']),
-    content: z.union([TextContentSchema, ImageContentSchema, AudioContentSchema])
-});
+    content: z.union([SamplingMessageContentBlockSchema, z.array(SamplingMessageContentBlockSchema)]),
+    /**
+     * See [MCP specification](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/47339c03c143bb4ec01a26e721a1b8fe66634ebe/docs/specification/draft/basic/index.mdx#general-fields)
+     * for notes on _meta usage.
+     */
+    _meta: z.optional(z.object({}).passthrough())
+})
+    .passthrough();
 /**
  * Parameters for a `sampling/createMessage` request.
  */
@@ -1041,7 +1138,11 @@ export const CreateMessageRequestParamsSchema = BaseRequestParamsSchema.extend({
      */
     systemPrompt: z.string().optional(),
     /**
-     * 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: z.enum(['none', 'thisServer', 'allServers']).optional(),
     temperature: z.number().optional(),
@@ -1055,7 +1156,18 @@ export const CreateMessageRequestParamsSchema = BaseRequestParamsSchema.extend({
     /**
      * Optional metadata to pass through to the LLM provider. The format of this metadata is provider-specific.
      */
-    metadata: AssertObjectSchema.optional()
+    metadata: AssertObjectSchema.optional(),
+    /**
+     * 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: z.optional(z.array(ToolSchema)),
+    /**
+     * 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: z.optional(ToolChoiceSchema)
 });
 /**
  * A request from the server to sample an LLM via the client. The client has full discretion over which model to select. The client should also inform the user before beginning sampling, to allow them to inspect the request (human in the loop) and decide whether to approve it.
@@ -1073,11 +1185,22 @@ export const CreateMessageResultSchema = ResultSchema.extend({
      */
     model: z.string(),
     /**
-     * The reason why sampling stopped.
+     * 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: z.optional(z.enum(['endTurn', 'stopSequence', 'maxTokens']).or(z.string())),
+    stopReason: z.optional(z.enum(['endTurn', 'stopSequence', 'maxTokens', 'toolUse']).or(z.string())),
     role: z.enum(['user', 'assistant']),
-    content: z.discriminatedUnion('type', [TextContentSchema, ImageContentSchema, AudioContentSchema])
+    /**
+     * Response content. May be ToolUseContent if stopReason is "toolUse".
+     */
+    content: z.union([SamplingMessageContentBlockSchema, z.array(SamplingMessageContentBlockSchema)])
 });
 /* Elicitation */
 /**
@@ -1194,11 +1317,15 @@ export const EnumSchemaSchema = z.union([LegacyTitledEnumSchemaSchema, SingleSel
  */
 export const PrimitiveSchemaDefinitionSchema = z.union([EnumSchemaSchema, BooleanSchemaSchema, StringSchemaSchema, NumberSchemaSchema]);
 /**
- * Parameters for an `elicitation/create` request.
+ * Parameters for an `elicitation/create` request for form-based elicitation.
  */
-export const ElicitRequestParamsSchema = BaseRequestParamsSchema.extend({
+export const ElicitRequestFormParamsSchema = BaseRequestParamsSchema.extend({
+    /**
+     * The elicitation mode.
+     */
+    mode: z.literal('form'),
     /**
-     * The message to present to the user.
+     * The message to present to the user describing what information is being requested.
      */
     message: z.string(),
     /**
@@ -1211,14 +1338,61 @@ export const ElicitRequestParamsSchema = BaseRequestParamsSchema.extend({
         required: z.array(z.string()).optional()
     })
 });
+/**
+ * Parameters for an `elicitation/create` request for URL-based elicitation.
+ */
+export const ElicitRequestURLParamsSchema = BaseRequestParamsSchema.extend({
+    /**
+     * The elicitation mode.
+     */
+    mode: z.literal('url'),
+    /**
+     * The message to present to the user explaining why the interaction is needed.
+     */
+    message: z.string(),
+    /**
+     * The ID of the elicitation, which must be unique within the context of the server.
+     * The client MUST treat this ID as an opaque value.
+     */
+    elicitationId: z.string(),
+    /**
+     * The URL that the user should navigate to.
+     */
+    url: z.string().url()
+});
+/**
+ * The parameters for a request to elicit additional information from the user via the client.
+ */
+export const ElicitRequestParamsSchema = z.union([ElicitRequestFormParamsSchema, ElicitRequestURLParamsSchema]);
 /**
  * A request from the server to elicit user input via the client.
- * The client should present the message and form fields to the user.
+ * The client should present the message and form fields to the user (form mode)
+ * or navigate to a URL (URL mode).
  */
 export const ElicitRequestSchema = RequestSchema.extend({
     method: z.literal('elicitation/create'),
     params: ElicitRequestParamsSchema
 });
+/**
+ * Parameters for a `notifications/elicitation/complete` notification.
+ *
+ * @category notifications/elicitation/complete
+ */
+export const ElicitationCompleteNotificationParamsSchema = NotificationsParamsSchema.extend({
+    /**
+     * The ID of the elicitation that completed.
+     */
+    elicitationId: z.string()
+});
+/**
+ * A notification from the server to the client, informing it of a completion of an out-of-band elicitation request.
+ *
+ * @category notifications/elicitation/complete
+ */
+export const ElicitationCompleteNotificationSchema = NotificationSchema.extend({
+    method: z.literal('notifications/elicitation/complete'),
+    params: ElicitationCompleteNotificationParamsSchema
+});
 /**
  * The client's response to an elicitation/create request from the server.
  */
@@ -1234,7 +1408,7 @@ export const ElicitResultSchema = ResultSchema.extend({
      * The submitted form data, only present when action is "accept".
      * Contains values matching the requested schema.
      */
-    content: z.record(z.union([z.string(), z.number(), z.boolean(), z.array(z.string())])).optional()
+    content: z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.array(z.string())])).optional()
 });
 /* Autocomplete */
 /**
@@ -1299,18 +1473,19 @@ export function assertCompleteRequestPrompt(request) {
     if (request.params.ref.type !== 'ref/prompt') {
         throw new TypeError(`Expected CompleteRequestPrompt, but got ${request.params.ref.type}`);
     }
+    void request;
 }
 export function assertCompleteRequestResourceTemplate(request) {
     if (request.params.ref.type !== 'ref/resource') {
         throw new TypeError(`Expected CompleteRequestResourceTemplate, but got ${request.params.ref.type}`);
     }
+    void request;
 }
 /**
  * The server's response to a completion/complete request
  */
 export const CompleteResultSchema = ResultSchema.extend({
-    completion: z
-        .object({
+    completion: z.looseObject({
         /**
          * An array of completion values. Must not exceed 100 items.
          */
@@ -1324,7 +1499,6 @@ export const CompleteResultSchema = ResultSchema.extend({
          */
         hasMore: z.optional(z.boolean())
     })
-        .passthrough()
 });
 /* Roots */
 /**
@@ -1395,7 +1569,8 @@ export const ServerNotificationSchema = z.union([
     ResourceUpdatedNotificationSchema,
     ResourceListChangedNotificationSchema,
     ToolListChangedNotificationSchema,
-    PromptListChangedNotificationSchema
+    PromptListChangedNotificationSchema,
+    ElicitationCompleteNotificationSchema
 ]);
 export const ServerResultSchema = z.union([
     EmptyResultSchema,
@@ -1416,5 +1591,34 @@ export class McpError extends Error {
         this.data = data;
         this.name = 'McpError';
     }
+    /**
+     * Factory method to create the appropriate error type based on the error code and data
+     */
+    static fromError(code, message, data) {
+        // Check for specific error types
+        if (code === ErrorCode.UrlElicitationRequired && data) {
+            const errorData = data;
+            if (errorData.elicitations) {
+                return new UrlElicitationRequiredError(errorData.elicitations, message);
+            }
+        }
+        // Default to generic McpError
+        return new McpError(code, message, data);
+    }
+}
+/**
+ * Specialized error type when a tool requires a URL mode elicitation.
+ * This makes it nicer for the client to handle since there is specific data to work with instead of just a code to check against.
+ */
+export class UrlElicitationRequiredError extends McpError {
+    constructor(elicitations, message = `URL elicitation${elicitations.length > 1 ? 's' : ''} required`) {
+        super(ErrorCode.UrlElicitationRequired, message, {
+            elicitations: elicitations
+        });
+    }
+    get elicitations() {
+        var _a, _b;
+        return (_b = (_a = this.data) === null || _a === void 0 ? void 0 : _a.elicitations) !== null && _b !== void 0 ? _b : [];
+    }
 }
 //# sourceMappingURL=types.js.map