@cloudinary/asset-management-mcp 0.8.0 → 0.9.0-rc.0

package/src/mcp-server/server.extensions.ts

@@ -7,6 +7,19 @@ import { Register } from "./extensions.js";
 import { formatResult } from "./tools.js";
 import { assetsExplicitAsset } from "../funcs/assetsExplicitAsset.js";
 import { ResourceType$zodSchema } from "../models/resourcetype.js";
+import {
+  ASSET_GALLERY_RESOURCE_URI,
+  MCP_APP_MIME_TYPE,
+  getAssetGalleryHtml,
+} from "./widgets/asset-gallery-widget.js";
+import {
+  ASSET_DETAILS_RESOURCE_URI,
+  getAssetDetailsHtml,
+} from "./widgets/asset-details-widget.js";
+import {
+  ASSET_UPLOAD_RESOURCE_URI,
+  getAssetUploadHtml,
+} from "./widgets/asset-upload-widget.js";
 
 const TX_RULES_URL = "https://cloudinary.com/documentation/cloudinary_transformation_rules.md";
 
@@ -55,6 +68,90 @@ export function registerMCPExtensions(register: Register): void {
     }
   });
 
+  // Asset gallery MCP App — interactive UI for list-images results
+  register.resource({
+    name: "Asset Gallery Widget",
+    description: "Interactive asset gallery for browsing Cloudinary images",
+    metadata: {
+      mimeType: MCP_APP_MIME_TYPE,
+    },
+    resource: ASSET_GALLERY_RESOURCE_URI,
+    scopes: [],
+    read: async (_client, _uri, _extra) => ({
+      contents: [{
+        uri: ASSET_GALLERY_RESOURCE_URI,
+        mimeType: MCP_APP_MIME_TYPE,
+        text: getAssetGalleryHtml(),
+        _meta: {
+          ui: {
+            csp: {
+              resourceDomains: [
+                "https://res.cloudinary.com",
+                "https://*.cloudinary.com",
+              ],
+            },
+          },
+        },
+      } as any],
+    }),
+  });
+
+  // Asset details MCP App — interactive UI for get-asset-details results
+  register.resource({
+    name: "Asset Details Widget",
+    description: "Interactive single-asset detail view for Cloudinary assets",
+    metadata: {
+      mimeType: MCP_APP_MIME_TYPE,
+    },
+    resource: ASSET_DETAILS_RESOURCE_URI,
+    scopes: [],
+    read: async (_client, _uri, _extra) => ({
+      contents: [{
+        uri: ASSET_DETAILS_RESOURCE_URI,
+        mimeType: MCP_APP_MIME_TYPE,
+        text: getAssetDetailsHtml(),
+        _meta: {
+          ui: {
+            csp: {
+              resourceDomains: [
+                "https://res.cloudinary.com",
+                "https://*.cloudinary.com",
+              ],
+            },
+          },
+        },
+      } as any],
+    }),
+  });
+
+  // Asset upload MCP App — interactive upload UI for upload-asset tool
+  register.resource({
+    name: "Asset Upload Widget",
+    description: "Interactive upload interface for uploading assets to Cloudinary",
+    metadata: {
+      mimeType: MCP_APP_MIME_TYPE,
+    },
+    resource: ASSET_UPLOAD_RESOURCE_URI,
+    scopes: [],
+    read: async (_client, _uri, _extra) => ({
+      contents: [{
+        uri: ASSET_UPLOAD_RESOURCE_URI,
+        mimeType: MCP_APP_MIME_TYPE,
+        text: getAssetUploadHtml(),
+        _meta: {
+          ui: {
+            csp: {
+              resourceDomains: [
+                "https://res.cloudinary.com",
+                "https://*.cloudinary.com",
+              ],
+            },
+          },
+        },
+      } as any],
+    }),
+  });
+
   // Transform asset tool using explicit API with eager transformations
   register.tool({
     name: "transform-asset",

package/src/mcp-server/server.ts

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 2784dd48e82a
  */
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -14,7 +15,11 @@ import {
 } from "./resources.js";
 import { MCPScope } from "./scopes.js";
 import { registerMCPExtensions } from "./server.extensions.js";
-import { createRegisterTool, registerDynamicTools } from "./tools.js";
+import {
+  createRegisterTool,
+  MCPToolAnnotationFilter,
+  registerDynamicTools,
+} from "./tools.js";
 import { tool$assetRelationsCreateAssetRelationsByAssetId } from "./tools/assetRelationsCreateAssetRelationsByAssetId.js";
 import { tool$assetRelationsDeleteAssetRelationsByAssetId } from "./tools/assetRelationsDeleteAssetRelationsByAssetId.js";
 import { tool$assetsDerivedDestroy } from "./tools/assetsDerivedDestroy.js";
@@ -42,6 +47,7 @@ export function createMCPServer(deps: {
   allowedTools?: string[] | undefined;
   dynamic?: boolean | undefined;
   scopes?: MCPScope[] | undefined;
+  annotationFilter?: MCPToolAnnotationFilter | undefined;
   getSDK?: () => CloudinaryAssetMgmtCore;
   serverURL?: string | undefined;
   security?: SDKOptions["security"] | undefined;
@@ -52,7 +58,7 @@ export function createMCPServer(deps: {
 }) {
   const server = new McpServer({
     name: "CloudinaryAssetMgmt",
-    version: "0.8.0",
+    version: "0.9.0-rc.0",
   });
 
   const getClient = deps.getSDK || (() =>
@@ -82,6 +88,7 @@ export function createMCPServer(deps: {
     scopes,
     allowedTools,
     deps.dynamic,
+    deps.annotationFilter,
   );
   const resource = createRegisterResource(
     deps.logger,

package/src/mcp-server/shared.ts

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 074e80d4be1e
  */
 
 import * as z from "zod";

package/src/mcp-server/tools/assetRelationsCreateAssetRelationsByAssetId.ts

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: cb6c64076c69
  */
 
 import * as z from "zod";

package/src/mcp-server/tools/assetRelationsDeleteAssetRelationsByAssetId.ts

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 907bdae927cc
  */
 
 import * as z from "zod";

package/src/mcp-server/tools/assetsDerivedDestroy.ts

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 79a9a4f0c816
  */
 
 import { assetsDerivedDestroy } from "../../funcs/assetsDerivedDestroy.js";

package/src/mcp-server/tools/assetsDestroyByAssetId.ts

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 85f56534b2f4
  */
 
 import { assetsDestroyByAssetId } from "../../funcs/assetsDestroyByAssetId.js";

package/src/mcp-server/tools/assetsDownloadBackupAsset.ts

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 1a145ee6808c
  */
 
 import * as z from "zod";

package/src/mcp-server/tools/assetsGenerateArchive.ts

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 4410baf67905
  */
 
 import { assetsGenerateArchive } from "../../funcs/assetsGenerateArchive.js";
@@ -8,7 +9,9 @@ import { GenerateArchiveRequestBody$zodSchema } from "../../models/generatearchi
 import { formatResult, ToolDefinition } from "../tools.js";
 
 const args = {
-  resource_type: ArchiveResourceType$zodSchema,
+  resource_type: ArchiveResourceType$zodSchema.describe(
+    `The type of resources to include in the archive. "image" for images, "video" for videos, "raw" for non-media files, or "all" for mixed types.`,
+  ),
   RequestBody: GenerateArchiveRequestBody$zodSchema,
 };
 

package/src/mcp-server/tools/assetsGetResourceByAssetId.ts

@@ -1,10 +1,12 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: ed1937d792b3
  */
 
 import * as z from "zod";
 import { assetsGetResourceByAssetId } from "../../funcs/assetsGetResourceByAssetId.js";
 import { formatResult, ToolDefinition } from "../tools.js";
+import { ASSET_DETAILS_RESOURCE_URI } from "../widgets/asset-details-widget.js";
 
 const args = {
   asset_id: z.string().describe(
@@ -58,6 +60,9 @@ Returns the details of a single resource specified by its asset ID.`,
     "openWorldHint": false,
     "readOnlyHint": true,
   },
+  _meta: {
+    ui: { resourceUri: ASSET_DETAILS_RESOURCE_URI },
+  },
   args,
   tool: async (client, args, ctx) => {
     const [result] = await assetsGetResourceByAssetId(

package/src/mcp-server/tools/assetsListImages.ts

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: b471836a1d2e
  */
 
 import * as z from "zod";
@@ -7,10 +8,13 @@ import { assetsListImages } from "../../funcs/assetsListImages.js";
 import { Direction$zodSchema } from "../../models/direction.js";
 import { FieldsSpec$zodSchema } from "../../models/fieldsspec.js";
 import { ListStorageType$zodSchema } from "../../models/liststoragetype.js";
+import { ASSET_GALLERY_RESOURCE_URI } from "../widgets/asset-gallery-widget.js";
 import { formatResult, ToolDefinition } from "../tools.js";
 
 const args = {
-  type: ListStorageType$zodSchema.optional(),
+  type: ListStorageType$zodSchema.optional().describe(
+    `The storage type of the assets. Necessary for prefix filtering.`,
+  ),
   prefix: z.string().describe(
     "Find resources with a public ID prefix. Requires the `type` parameter.",
   ).optional(),
@@ -22,7 +26,7 @@ const args = {
   next_cursor: z.string().describe("Cursor for pagination.").optional(),
   max_results: z.int().describe("Maximum number of results to return (1-500).")
     .optional(),
-  direction: Direction$zodSchema.optional(),
+  direction: Direction$zodSchema.optional().describe(`Sort direction.`),
   start_at: z.iso.datetime({ offset: true }).describe(
     "Retrieve resources uploaded after this timestamp.",
   ).optional(),
@@ -43,6 +47,9 @@ Retrieves a list of image assets. Results can be filtered by various criteria li
     "openWorldHint": false,
     "readOnlyHint": true,
   },
+  _meta: {
+    ui: { resourceUri: ASSET_GALLERY_RESOURCE_URI },
+  },
   args,
   tool: async (client, args, ctx) => {
     const [result] = await assetsListImages(

package/src/mcp-server/tools/assetsListRawFiles.ts

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: ed13ba3617a1
  */
 
 import * as z from "zod";
@@ -8,9 +9,12 @@ import { Direction$zodSchema } from "../../models/direction.js";
 import { FieldsSpec$zodSchema } from "../../models/fieldsspec.js";
 import { ListStorageType$zodSchema } from "../../models/liststoragetype.js";
 import { formatResult, ToolDefinition } from "../tools.js";
+import { ASSET_GALLERY_RESOURCE_URI } from "../widgets/asset-gallery-widget.js";
 
 const args = {
-  type: ListStorageType$zodSchema.optional(),
+  type: ListStorageType$zodSchema.optional().describe(
+    `The delivery type. Necessary for prefix filtering.`,
+  ),
   prefix: z.string().describe(
     "A public_id prefix. When specified, all assets with that prefix are returned. When using this, the `type` parameter must also be specified.",
   ).optional(),
@@ -22,7 +26,7 @@ const args = {
   next_cursor: z.string().describe("Cursor for pagination.").optional(),
   max_results: z.int().describe("Maximum number of results to return (1-500).")
     .optional(),
-  direction: Direction$zodSchema.optional(),
+  direction: Direction$zodSchema.optional().describe(`Sort direction.`),
   start_at: z.iso.datetime({ offset: true }).describe(
     "An ISO-8601 formatted timestamp. When specified, assets created since that timestamp are returned.  Supported only if neither `prefix` nor `public_ids` were passed.",
   ).optional(),
@@ -43,6 +47,9 @@ Retrieves a list of raw assets. Results can be filtered by various criteria like
     "openWorldHint": false,
     "readOnlyHint": true,
   },
+  _meta: {
+    ui: { resourceUri: ASSET_GALLERY_RESOURCE_URI },
+  },
   args,
   tool: async (client, args, ctx) => {
     const [result] = await assetsListRawFiles(

package/src/mcp-server/tools/assetsListResourceTags.ts

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 317d658a1160
  */
 
 import * as z from "zod";
@@ -8,7 +9,7 @@ import { ResourceType$zodSchema } from "../../models/resourcetype.js";
 import { formatResult, ToolDefinition } from "../tools.js";
 
 const args = {
-  resource_type: ResourceType$zodSchema,
+  resource_type: ResourceType$zodSchema.describe(`The type of resource.`),
   prefix: z.string().describe(
     "The prefix to use if you want to limit the returned tags to those that start with the specified prefix.",
   ).optional(),

package/src/mcp-server/tools/assetsListVideos.ts

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 9127d9989ae2
  */
 
 import * as z from "zod";
@@ -8,9 +9,12 @@ import { Direction$zodSchema } from "../../models/direction.js";
 import { FieldsSpec$zodSchema } from "../../models/fieldsspec.js";
 import { ListStorageType$zodSchema } from "../../models/liststoragetype.js";
 import { formatResult, ToolDefinition } from "../tools.js";
+import { ASSET_GALLERY_RESOURCE_URI } from "../widgets/asset-gallery-widget.js";
 
 const args = {
-  type: ListStorageType$zodSchema.optional(),
+  type: ListStorageType$zodSchema.optional().describe(
+    `The delivery type. Necessary for prefix filtering.`,
+  ),
   prefix: z.string().describe(
     "A public_id prefix. When specified, all assets with that prefix are returned. When using this, the `type` parameter must also be specified.",
   ).optional(),
@@ -22,7 +26,7 @@ const args = {
   next_cursor: z.string().describe("Cursor for pagination.").optional(),
   max_results: z.int().describe("Maximum number of results to return (1-500).")
     .optional(),
-  direction: Direction$zodSchema.optional(),
+  direction: Direction$zodSchema.optional().describe(`Sort direction.`),
   start_at: z.iso.datetime({ offset: true }).describe(
     "An ISO-8601 formatted timestamp. When specified, assets created since that timestamp are returned.  Supported only if neither `prefix` nor `public_ids` were passed.",
   ).optional(),
@@ -43,6 +47,9 @@ Retrieves a list of video assets. Results can be filtered by various criteria li
     "openWorldHint": false,
     "readOnlyHint": true,
   },
+  _meta: {
+    ui: { resourceUri: ASSET_GALLERY_RESOURCE_URI },
+  },
   args,
   tool: async (client, args, ctx) => {
     const [result] = await assetsListVideos(

package/src/mcp-server/tools/assetsRenameAsset.ts

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 7820dd7568d4
  */
 
 import { assetsRenameAsset } from "../../funcs/assetsRenameAsset.js";
@@ -8,7 +9,7 @@ import { ResourceType$zodSchema } from "../../models/resourcetype.js";
 import { formatResult, ToolDefinition } from "../tools.js";
 
 const args = {
-  resource_type: ResourceType$zodSchema,
+  resource_type: ResourceType$zodSchema.describe(`The type of resource.`),
   RequestBody: RenameAssetRequestBody$zodSchema,
 };
 

package/src/mcp-server/tools/assetsUpdateResourceByAssetId.ts

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 2721ef2e5585
  */
 
 import * as z from "zod";

package/src/mcp-server/tools/foldersCreateFolder.ts

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: c8f166fa9b87
  */
 
 import * as z from "zod";

package/src/mcp-server/tools/foldersDestroyFolder.ts

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: b3c7817a482b
  */
 
 import * as z from "zod";

package/src/mcp-server/tools/foldersSearchFolders.ts

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 6081b2f765e6
  */
 
 import * as z from "zod";
@@ -8,7 +9,9 @@ import { ExpressionUnion$zodSchema } from "../../models/searchfoldersop.js";
 import { formatResult, ToolDefinition } from "../tools.js";
 
 const args = {
-  expression: ExpressionUnion$zodSchema.optional(),
+  expression: ExpressionUnion$zodSchema.optional().describe(
+    `The (Lucene-like) string expression specifying the search query, or an object for advanced queries. If not passed, returns all folders (up to max_results).`,
+  ),
   sort_by: z.array(z.string()).describe(
     "An array of key-value pairs for sorting. Each value is a key and direction (asc/desc).",
   ).optional(),

package/src/mcp-server/tools/foldersUpdateFolder.ts

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 10b30e9d4a77
  */
 
 import * as z from "zod";

package/src/mcp-server/tools/searchSearchAssets.ts

@@ -1,10 +1,12 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: af8d0e1dda1d
  */
 
 import { searchSearchAssets } from "../../funcs/searchSearchAssets.js";
 import { SearchParameters$zodSchema } from "../../models/searchparameters.js";
 import { formatResult, ToolDefinition } from "../tools.js";
+import { ASSET_GALLERY_RESOURCE_URI } from "../widgets/asset-gallery-widget.js";
 
 const args = {
   request: SearchParameters$zodSchema,
@@ -29,6 +31,9 @@ Examples: tags:shirt AND uploaded_at>1d, resource_type:image AND bytes>1mb, fold
     "openWorldHint": false,
     "readOnlyHint": true,
   },
+  _meta: {
+    ui: { resourceUri: ASSET_GALLERY_RESOURCE_URI },
+  },
   args,
   tool: async (client, args, ctx) => {
     const [result] = await searchSearchAssets(

package/src/mcp-server/tools/searchVisualSearchAssets.ts

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 0f7022b64923
  */
 
 import { searchVisualSearchAssets } from "../../funcs/searchVisualSearchAssets.js";

package/src/mcp-server/tools/uploadUpload.ts

@@ -1,14 +1,23 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 811aa635cedb
  */
 
 import { uploadUpload } from "../../funcs/uploadUpload.js";
 import { UploadRequest$zodSchema } from "../../models/uploadrequest.js";
 import { UploadResourceType$zodSchema } from "../../models/uploadresourcetype.js";
+import { ASSET_UPLOAD_RESOURCE_URI } from "../widgets/asset-upload-widget.js";
 import { formatResult, ToolDefinition } from "../tools.js";
 
 const args = {
-  resource_type: UploadResourceType$zodSchema.default("auto"),
+  resource_type: UploadResourceType$zodSchema.default("auto").describe(
+    `The type of resource to upload:
+- "image" for uploading strictly images
+- "video" for uploading strictly videos
+- "raw" for uploading non-media files
+- "auto" for allowing Cloudinary to automatically detect the type of the uploaded file
+`,
+  ),
   upload_request: UploadRequest$zodSchema,
 };
 
@@ -40,6 +49,9 @@ Transform media files using transformation syntax in delivery URLs, which create
     "openWorldHint": false,
     "readOnlyHint": false,
   },
+  _meta: {
+    ui: { resourceUri: ASSET_UPLOAD_RESOURCE_URI },
+  },
   args,
   tool: async (client, args, ctx) => {
     const [result] = await uploadUpload(

package/src/mcp-server/tools/usageGetUsage.ts

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 7e648dd5786c
  */
 
 import * as z from "zod";

package/src/mcp-server/tools.ts

@@ -1,5 +1,6 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 654d5d1f2062
  */
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -21,6 +22,50 @@ import { MCPServerFlags } from "./flags.js";
 import { MCPScope, mcpScopes } from "./scopes.js";
 import { valueToBase64 } from "./shared.js";
 
+export type MCPToolAnnotationFilter = {
+  readOnlyHint?: boolean;
+  destructiveHint?: boolean;
+  idempotentHint?: boolean;
+  openWorldHint?: boolean;
+};
+
+const VALID_ANNOTATIONS = [
+  "readOnly",
+  "destructive",
+  "idempotent",
+  "openWorld",
+] as const;
+type AnnotationName = typeof VALID_ANNOTATIONS[number];
+
+const annotationToKey: Record<AnnotationName, keyof MCPToolAnnotationFilter> = {
+  readOnly: "readOnlyHint",
+  destructive: "destructiveHint",
+  idempotent: "idempotentHint",
+  openWorld: "openWorldHint",
+};
+
+export function buildAnnotationFilter(
+  annotations: string[] | undefined,
+): MCPToolAnnotationFilter {
+  const filter: MCPToolAnnotationFilter = {};
+  if (!annotations || annotations.length === 0) {
+    return filter;
+  }
+  for (const a of annotations) {
+    if (!VALID_ANNOTATIONS.includes(a as AnnotationName)) {
+      throw new Error(
+        `Invalid annotation filter: "${a}". Valid values are: ${
+          VALID_ANNOTATIONS.join(", ")
+        }`,
+      );
+    }
+  }
+  for (const name of VALID_ANNOTATIONS) {
+    filter[annotationToKey[name]] = annotations.includes(name);
+  }
+  return filter;
+}
+
 export type ToolDefinition<
   Args extends undefined | ZodRawShapeCompat = undefined,
 > = Args extends ZodRawShapeCompat ? {
@@ -35,6 +80,7 @@ export type ToolDefinition<
       openWorldHint: boolean;
       readOnlyHint: boolean;
     };
+    _meta?: Record<string, unknown>;
     tool: (
       client: CloudinaryAssetMgmtCore,
       args: ShapeOutput<Args>,
@@ -53,6 +99,7 @@ export type ToolDefinition<
       openWorldHint: boolean;
       readOnlyHint: boolean;
     };
+    _meta?: Record<string, unknown>;
     tool: (
       client: CloudinaryAssetMgmtCore,
       extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
@@ -91,6 +138,7 @@ export function createRegisterTool(
   allowedScopes: Set<MCPScope>,
   allowedTools?: Set<string>,
   dynamic?: boolean,
+  annotationFilter?: MCPToolAnnotationFilter,
 ): [
   <A extends ZodRawShapeCompat | undefined>(tool: ToolDefinition<A>) => void,
   Array<{ name: string; description: string }>,
@@ -120,6 +168,34 @@ export function createRegisterTool(
       return;
     }
 
+    if (annotationFilter) {
+      const a = tool.annotations;
+      if (
+        annotationFilter.readOnlyHint !== undefined
+        && a.readOnlyHint !== annotationFilter.readOnlyHint
+      ) {
+        return;
+      }
+      if (
+        annotationFilter.destructiveHint !== undefined
+        && a.destructiveHint !== annotationFilter.destructiveHint
+      ) {
+        return;
+      }
+      if (
+        annotationFilter.idempotentHint !== undefined
+        && a.idempotentHint !== annotationFilter.idempotentHint
+      ) {
+        return;
+      }
+      if (
+        annotationFilter.openWorldHint !== undefined
+        && a.openWorldHint !== annotationFilter.openWorldHint
+      ) {
+        return;
+      }
+    }
+
     toolMap.set(
       tool.name,
       tool as ToolDefinition<ZodRawShapeCompat | undefined>,
@@ -138,6 +214,7 @@ export function createRegisterTool(
           description: tool.description,
           inputSchema: tool.args,
           annotations: tool.annotations,
+          ...(tool._meta ? { _meta: tool._meta } : {}),
         },
         async (args, ctx) => {
           return tool.tool(getSDK(), args, ctx);
@@ -149,6 +226,7 @@ export function createRegisterTool(
         {
           description: tool.description,
           annotations: tool.annotations,
+          ...(tool._meta ? { _meta: tool._meta } : {}),
         },
         async (ctx) => {
           return tool.tool(getSDK(), ctx);