@ai-sdk/mcp 1.0.77 → 1.0.78

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @ai-sdk/mcp
 
+## 1.0.78
+
+### Patch Changes
+
+- 172d3c0: feat(mcp): surface server-provided tool annotations in tool metadata
+
 ## 1.0.77
 
 ### Patch Changes

package/dist/index.d.mts

@@ -308,6 +308,27 @@ type MCPTransportConfig = {
     fetch?: FetchFunction;
 };
 
+/**
+ * Metadata attached to tools created by the MCP client.
+ */
+type McpProviderMetadata = {
+    clientName?: string;
+    annotations?: McpToolAnnotations;
+};
+/**
+ * Behavioral hints reported by an MCP server for a tool.
+ *
+ * These annotations are untrusted unless the server itself is trusted.
+ *
+ * @see https://modelcontextprotocol.io/specification/2025-11-25/server/tools#annotations
+ */
+type McpToolAnnotations = {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+};
 /** MCP tool metadata - keys should follow MCP _meta key format specification */
 declare const ToolMetaSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 type ToolMeta = z.infer<typeof ToolMetaSchema>;
@@ -377,6 +398,10 @@ declare const ListToolsResultSchema: z.ZodObject<{
         outputSchema: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
         annotations: z.ZodOptional<z.ZodObject<{
             title: z.ZodOptional<z.ZodString>;
+            readOnlyHint: z.ZodOptional<z.ZodBoolean>;
+            destructiveHint: z.ZodOptional<z.ZodBoolean>;
+            idempotentHint: z.ZodOptional<z.ZodBoolean>;
+            openWorldHint: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$loose>>;
         _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$loose>>;
@@ -650,4 +675,4 @@ interface MCPClient {
     close: () => Promise<void>;
 }
 
-export { type CallToolResult, type CompleteRequestParams, type CompleteResult, type Configuration, type ElicitResult, ElicitResultSchema, type ElicitationRequest, ElicitationRequestSchema, type JSONRPCError, type JSONRPCMessage, type JSONRPCNotification, type JSONRPCRequest, type JSONRPCResponse, type ListToolsResult, type MCPClient, type ClientCapabilities as MCPClientCapabilities, type MCPClientConfig, type MCPTransport, type MCPTransportCloseOptions, type MCPTransportSendOptions, type OAuthAuthorizationServerInformation, type OAuthClientInformation, type OAuthClientMetadata, type OAuthClientProvider, type OAuthTokens, UnauthorizedError, auth, createMCPClient, type MCPClient as experimental_MCPClient, type ClientCapabilities as experimental_MCPClientCapabilities, type MCPClientConfig as experimental_MCPClientConfig, createMCPClient as experimental_createMCPClient, validateJSONRPCMessage };
+export { type CallToolResult, type CompleteRequestParams, type CompleteResult, type Configuration, type ElicitResult, ElicitResultSchema, type ElicitationRequest, ElicitationRequestSchema, type JSONRPCError, type JSONRPCMessage, type JSONRPCNotification, type JSONRPCRequest, type JSONRPCResponse, type ListToolsResult, type MCPClient, type ClientCapabilities as MCPClientCapabilities, type MCPClientConfig, type MCPTransport, type MCPTransportCloseOptions, type MCPTransportSendOptions, type McpProviderMetadata, type McpToolAnnotations, type OAuthAuthorizationServerInformation, type OAuthClientInformation, type OAuthClientMetadata, type OAuthClientProvider, type OAuthTokens, UnauthorizedError, auth, createMCPClient, type MCPClient as experimental_MCPClient, type ClientCapabilities as experimental_MCPClientCapabilities, type MCPClientConfig as experimental_MCPClientConfig, createMCPClient as experimental_createMCPClient, validateJSONRPCMessage };

package/dist/index.d.ts

@@ -308,6 +308,27 @@ type MCPTransportConfig = {
     fetch?: FetchFunction;
 };
 
+/**
+ * Metadata attached to tools created by the MCP client.
+ */
+type McpProviderMetadata = {
+    clientName?: string;
+    annotations?: McpToolAnnotations;
+};
+/**
+ * Behavioral hints reported by an MCP server for a tool.
+ *
+ * These annotations are untrusted unless the server itself is trusted.
+ *
+ * @see https://modelcontextprotocol.io/specification/2025-11-25/server/tools#annotations
+ */
+type McpToolAnnotations = {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+};
 /** MCP tool metadata - keys should follow MCP _meta key format specification */
 declare const ToolMetaSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 type ToolMeta = z.infer<typeof ToolMetaSchema>;
@@ -377,6 +398,10 @@ declare const ListToolsResultSchema: z.ZodObject<{
         outputSchema: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
         annotations: z.ZodOptional<z.ZodObject<{
             title: z.ZodOptional<z.ZodString>;
+            readOnlyHint: z.ZodOptional<z.ZodBoolean>;
+            destructiveHint: z.ZodOptional<z.ZodBoolean>;
+            idempotentHint: z.ZodOptional<z.ZodBoolean>;
+            openWorldHint: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$loose>>;
         _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$loose>>;
@@ -650,4 +675,4 @@ interface MCPClient {
     close: () => Promise<void>;
 }
 
-export { type CallToolResult, type CompleteRequestParams, type CompleteResult, type Configuration, type ElicitResult, ElicitResultSchema, type ElicitationRequest, ElicitationRequestSchema, type JSONRPCError, type JSONRPCMessage, type JSONRPCNotification, type JSONRPCRequest, type JSONRPCResponse, type ListToolsResult, type MCPClient, type ClientCapabilities as MCPClientCapabilities, type MCPClientConfig, type MCPTransport, type MCPTransportCloseOptions, type MCPTransportSendOptions, type OAuthAuthorizationServerInformation, type OAuthClientInformation, type OAuthClientMetadata, type OAuthClientProvider, type OAuthTokens, UnauthorizedError, auth, createMCPClient, type MCPClient as experimental_MCPClient, type ClientCapabilities as experimental_MCPClientCapabilities, type MCPClientConfig as experimental_MCPClientConfig, createMCPClient as experimental_createMCPClient, validateJSONRPCMessage };
+export { type CallToolResult, type CompleteRequestParams, type CompleteResult, type Configuration, type ElicitResult, ElicitResultSchema, type ElicitationRequest, ElicitationRequestSchema, type JSONRPCError, type JSONRPCMessage, type JSONRPCNotification, type JSONRPCRequest, type JSONRPCResponse, type ListToolsResult, type MCPClient, type ClientCapabilities as MCPClientCapabilities, type MCPClientConfig, type MCPTransport, type MCPTransportCloseOptions, type MCPTransportSendOptions, type McpProviderMetadata, type McpToolAnnotations, type OAuthAuthorizationServerInformation, type OAuthClientInformation, type OAuthClientMetadata, type OAuthClientProvider, type OAuthTokens, UnauthorizedError, auth, createMCPClient, type MCPClient as experimental_MCPClient, type ClientCapabilities as experimental_MCPClientCapabilities, type MCPClientConfig as experimental_MCPClientConfig, createMCPClient as experimental_createMCPClient, validateJSONRPCMessage };

package/dist/index.js

@@ -121,7 +121,11 @@ var ToolSchema = import_v4.z.object({
   outputSchema: import_v4.z.optional(import_v4.z.object({}).loose()),
   annotations: import_v4.z.optional(
     import_v4.z.object({
-      title: import_v4.z.optional(import_v4.z.string())
+      title: import_v4.z.optional(import_v4.z.string()),
+      readOnlyHint: import_v4.z.optional(import_v4.z.boolean()),
+      destructiveHint: import_v4.z.optional(import_v4.z.boolean()),
+      idempotentHint: import_v4.z.optional(import_v4.z.boolean()),
+      openWorldHint: import_v4.z.optional(import_v4.z.boolean())
     }).loose()
   ),
   _meta: ToolMetaSchema
@@ -2591,6 +2595,18 @@ var DefaultMCPClient = class {
       }
       const self = this;
       const outputSchema = schemas !== "automatic" ? (_a3 = schemas[name3]) == null ? void 0 : _a3.outputSchema : void 0;
+      const metadata = {
+        clientName: this.clientInfo.name,
+        ...annotations != null ? {
+          annotations: {
+            ...annotations.title != null ? { title: annotations.title } : {},
+            ...annotations.readOnlyHint != null ? { readOnlyHint: annotations.readOnlyHint } : {},
+            ...annotations.destructiveHint != null ? { destructiveHint: annotations.destructiveHint } : {},
+            ...annotations.idempotentHint != null ? { idempotentHint: annotations.idempotentHint } : {},
+            ...annotations.openWorldHint != null ? { openWorldHint: annotations.openWorldHint } : {}
+          }
+        } : {}
+      };
       const execute = async (args, options) => {
         var _a4;
         (_a4 = options == null ? void 0 : options.abortSignal) == null ? void 0 : _a4.throwIfAborted();
@@ -2606,9 +2622,7 @@ var DefaultMCPClient = class {
       const toolWithExecute = schemas === "automatic" ? (0, import_provider_utils5.dynamicTool)({
         description,
         title: resolvedTitle,
-        metadata: {
-          clientName: this.clientInfo.name
-        },
+        metadata,
         inputSchema: (0, import_provider_utils5.jsonSchema)({
           ...inputSchema,
           properties: (_b3 = inputSchema.properties) != null ? _b3 : {},
@@ -2619,9 +2633,7 @@ var DefaultMCPClient = class {
       }) : (0, import_provider_utils5.tool)({
         description,
         title: resolvedTitle,
-        metadata: {
-          clientName: this.clientInfo.name
-        },
+        metadata,
         inputSchema: schemas[name3].inputSchema,
         ...outputSchema != null ? { outputSchema } : {},
         execute,