@contentful/mcp-tools 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -63,6 +63,8 @@ interface ContentfulConfig {
     hostDelivery?: string;
     /** Environment IDs that are protected from write/delete operations */
     protectedEnvironments?: string[];
+    /** Maximum number of IDs allowed in a single bulk-operation tool call. Defaults to 10 when unset. */
+    maxBulkSize?: number;
 }
 
 /**
@@ -994,6 +996,7 @@ declare class ContentfulMcpTools {
                 environmentId: zod.ZodString;
             } & {
                 assetId: zod.ZodUnion<[zod.ZodString, zod.ZodArray<zod.ZodString, "many">]>;
+                dryRun: zod.ZodOptional<zod.ZodBoolean>;
             };
             annotations: {
                 readOnlyHint: boolean;
@@ -1005,6 +1008,7 @@ declare class ContentfulMcpTools {
                 spaceId: string;
                 environmentId: string;
                 assetId: string | string[];
+                dryRun?: boolean | undefined;
             }, extra?: _modelcontextprotocol_sdk_shared_protocol_js.RequestHandlerExtra<_modelcontextprotocol_sdk_types_js.ServerRequest, _modelcontextprotocol_sdk_types_js.ServerNotification>) => Promise<ToolResponse>;
         };
         unpublishAsset: {
@@ -1015,6 +1019,7 @@ declare class ContentfulMcpTools {
                 environmentId: zod.ZodString;
             } & {
                 assetId: zod.ZodUnion<[zod.ZodString, zod.ZodArray<zod.ZodString, "many">]>;
+                dryRun: zod.ZodOptional<zod.ZodBoolean>;
             };
             annotations: {
                 readOnlyHint: boolean;
@@ -1026,6 +1031,7 @@ declare class ContentfulMcpTools {
                 spaceId: string;
                 environmentId: string;
                 assetId: string | string[];
+                dryRun?: boolean | undefined;
             }, extra?: _modelcontextprotocol_sdk_shared_protocol_js.RequestHandlerExtra<_modelcontextprotocol_sdk_types_js.ServerRequest, _modelcontextprotocol_sdk_types_js.ServerNotification>) => Promise<ToolResponse>;
         };
         archiveAsset: {
@@ -1036,6 +1042,7 @@ declare class ContentfulMcpTools {
                 environmentId: zod.ZodString;
             } & {
                 assetId: zod.ZodUnion<[zod.ZodString, zod.ZodArray<zod.ZodString, "many">]>;
+                dryRun: zod.ZodOptional<zod.ZodBoolean>;
             };
             annotations: {
                 readOnlyHint: boolean;
@@ -1047,6 +1054,7 @@ declare class ContentfulMcpTools {
                 spaceId: string;
                 environmentId: string;
                 assetId: string | string[];
+                dryRun?: boolean | undefined;
             }, extra?: _modelcontextprotocol_sdk_shared_protocol_js.RequestHandlerExtra<_modelcontextprotocol_sdk_types_js.ServerRequest, _modelcontextprotocol_sdk_types_js.ServerNotification>) => Promise<ToolResponse>;
         };
         unarchiveAsset: {
@@ -1057,6 +1065,7 @@ declare class ContentfulMcpTools {
                 environmentId: zod.ZodString;
             } & {
                 assetId: zod.ZodUnion<[zod.ZodString, zod.ZodArray<zod.ZodString, "many">]>;
+                dryRun: zod.ZodOptional<zod.ZodBoolean>;
             };
             annotations: {
                 readOnlyHint: boolean;
@@ -1068,6 +1077,7 @@ declare class ContentfulMcpTools {
                 spaceId: string;
                 environmentId: string;
                 assetId: string | string[];
+                dryRun?: boolean | undefined;
             }, extra?: _modelcontextprotocol_sdk_shared_protocol_js.RequestHandlerExtra<_modelcontextprotocol_sdk_types_js.ServerRequest, _modelcontextprotocol_sdk_types_js.ServerNotification>) => Promise<ToolResponse>;
         };
     };
@@ -5003,6 +5013,7 @@ declare class ContentfulMcpTools {
                 environmentId: zod.ZodString;
             } & {
                 entryId: zod.ZodArray<zod.ZodString, "many">;
+                dryRun: zod.ZodOptional<zod.ZodBoolean>;
             };
             annotations: {
                 readOnlyHint: boolean;
@@ -5014,6 +5025,7 @@ declare class ContentfulMcpTools {
                 spaceId: string;
                 environmentId: string;
                 entryId: string[];
+                dryRun?: boolean | undefined;
             }, extra?: _modelcontextprotocol_sdk_shared_protocol_js.RequestHandlerExtra<_modelcontextprotocol_sdk_types_js.ServerRequest, _modelcontextprotocol_sdk_types_js.ServerNotification>) => Promise<ToolResponse>;
         };
         unpublishEntry: {
@@ -5024,6 +5036,7 @@ declare class ContentfulMcpTools {
                 environmentId: zod.ZodString;
             } & {
                 entryId: zod.ZodArray<zod.ZodString, "many">;
+                dryRun: zod.ZodOptional<zod.ZodBoolean>;
             };
             annotations: {
                 readOnlyHint: boolean;
@@ -5035,6 +5048,7 @@ declare class ContentfulMcpTools {
                 spaceId: string;
                 environmentId: string;
                 entryId: string[];
+                dryRun?: boolean | undefined;
             }, extra?: _modelcontextprotocol_sdk_shared_protocol_js.RequestHandlerExtra<_modelcontextprotocol_sdk_types_js.ServerRequest, _modelcontextprotocol_sdk_types_js.ServerNotification>) => Promise<ToolResponse>;
         };
         archiveEntry: {
@@ -5045,6 +5059,7 @@ declare class ContentfulMcpTools {
                 environmentId: zod.ZodString;
             } & {
                 entryId: zod.ZodArray<zod.ZodString, "many">;
+                dryRun: zod.ZodOptional<zod.ZodBoolean>;
             };
             annotations: {
                 readOnlyHint: boolean;
@@ -5056,6 +5071,7 @@ declare class ContentfulMcpTools {
                 spaceId: string;
                 environmentId: string;
                 entryId: string[];
+                dryRun?: boolean | undefined;
             }, extra?: _modelcontextprotocol_sdk_shared_protocol_js.RequestHandlerExtra<_modelcontextprotocol_sdk_types_js.ServerRequest, _modelcontextprotocol_sdk_types_js.ServerNotification>) => Promise<ToolResponse>;
         };
         unarchiveEntry: {
@@ -5066,6 +5082,7 @@ declare class ContentfulMcpTools {
                 environmentId: zod.ZodString;
             } & {
                 entryId: zod.ZodArray<zod.ZodString, "many">;
+                dryRun: zod.ZodOptional<zod.ZodBoolean>;
             };
             annotations: {
                 readOnlyHint: boolean;
@@ -5077,6 +5094,7 @@ declare class ContentfulMcpTools {
                 spaceId: string;
                 environmentId: string;
                 entryId: string[];
+                dryRun?: boolean | undefined;
             }, extra?: _modelcontextprotocol_sdk_shared_protocol_js.RequestHandlerExtra<_modelcontextprotocol_sdk_types_js.ServerRequest, _modelcontextprotocol_sdk_types_js.ServerNotification>) => Promise<ToolResponse>;
         };
     };

package/dist/index.js

@@ -1180,10 +1180,47 @@ function createEntitiesCollection(entities) {
   };
 }
 
+// src/utils/bulkLimits.ts
+var DEFAULT_MAX_BULK_SIZE = 10;
+function resolveMaxBulkSize(configured) {
+  if (configured === void 0 || !Number.isInteger(configured) || configured <= 0) {
+    return DEFAULT_MAX_BULK_SIZE;
+  }
+  return configured;
+}
+function assertBulkSizeAllowed(count, configured) {
+  const limit = resolveMaxBulkSize(configured);
+  if (count > limit) {
+    throw new Error(
+      `Bulk operation rejected: ${count} IDs exceeds MAX_BULK_SIZE of ${limit}. Reduce batch size or increase the limit.`
+    );
+  }
+}
+var PLURAL_BY_ENTITY = {
+  entry: "entries",
+  asset: "assets"
+};
+function buildDryRunPreview(input) {
+  const { operation, entityType, ids, spaceId, environmentId } = input;
+  const noun = ids.length === 1 ? entityType : PLURAL_BY_ENTITY[entityType];
+  return {
+    dryRun: true,
+    operation,
+    entityType,
+    count: ids.length,
+    ids,
+    target: { spaceId, environmentId },
+    message: `Dry run: would ${operation} ${ids.length} ${noun} in ${spaceId}/${environmentId}. No changes were made. Re-run without dryRun to execute.`
+  };
+}
+
 // src/tools/assets/publishAsset.ts
 var PublishAssetToolParams = BaseToolSchema.extend({
   assetId: z19.union([z19.string(), z19.array(z19.string()).max(100)]).describe(
-    "The ID of the asset to publish (string) or an array of asset IDs (up to 100 assets)"
+    "A single asset ID (string) or an array of asset IDs to publish (up to MAX_BULK_SIZE per call; default 10, max 100 \u2014 configurable via MAX_BULK_SIZE env var)."
+  ),
+  dryRun: z19.boolean().optional().describe(
+    "When true, returns a preview of the operation without executing it. Still subject to MAX_BULK_SIZE \u2014 use this to confirm intent for within-limit calls."
   )
 });
 function publishAssetTool(config) {
@@ -1192,12 +1229,25 @@ function publishAssetTool(config) {
       args.environmentId,
       config.protectedEnvironments
     );
+    const assetIds = Array.isArray(args.assetId) ? args.assetId : [args.assetId];
+    assertBulkSizeAllowed(assetIds.length, config.maxBulkSize);
+    if (args.dryRun) {
+      return createSuccessResponse(
+        "Dry run: no changes were made",
+        buildDryRunPreview({
+          operation: "publish",
+          entityType: "asset",
+          ids: assetIds,
+          spaceId: args.spaceId,
+          environmentId: args.environmentId
+        })
+      );
+    }
     const baseParams = {
       spaceId: args.spaceId,
       environmentId: args.environmentId
     };
     const contentfulClient = createToolClient(config, args);
-    const assetIds = Array.isArray(args.assetId) ? args.assetId : [args.assetId];
     if (assetIds.length === 1) {
       try {
         const assetId = assetIds[0];
@@ -1247,7 +1297,10 @@ function publishAssetTool(config) {
 import { z as z20 } from "zod";
 var UnpublishAssetToolParams = BaseToolSchema.extend({
   assetId: z20.union([z20.string(), z20.array(z20.string()).max(100)]).describe(
-    "The ID of the asset to unpublish (string) or an array of asset IDs (up to 100 assets)"
+    "A single asset ID (string) or an array of asset IDs to unpublish (up to MAX_BULK_SIZE per call; default 10, max 100 \u2014 configurable via MAX_BULK_SIZE env var)."
+  ),
+  dryRun: z20.boolean().optional().describe(
+    "When true, returns a preview of the operation without executing it. Still subject to MAX_BULK_SIZE \u2014 use this to confirm intent for within-limit calls."
   )
 });
 function unpublishAssetTool(config) {
@@ -1256,12 +1309,25 @@ function unpublishAssetTool(config) {
       args.environmentId,
       config.protectedEnvironments
     );
+    const assetIds = Array.isArray(args.assetId) ? args.assetId : [args.assetId];
+    assertBulkSizeAllowed(assetIds.length, config.maxBulkSize);
+    if (args.dryRun) {
+      return createSuccessResponse(
+        "Dry run: no changes were made",
+        buildDryRunPreview({
+          operation: "unpublish",
+          entityType: "asset",
+          ids: assetIds,
+          spaceId: args.spaceId,
+          environmentId: args.environmentId
+        })
+      );
+    }
     const baseParams = {
       spaceId: args.spaceId,
       environmentId: args.environmentId
     };
     const contentfulClient = createToolClient(config, args);
-    const assetIds = Array.isArray(args.assetId) ? args.assetId : [args.assetId];
     if (assetIds.length === 1) {
       try {
         const assetId = assetIds[0];
@@ -1311,7 +1377,10 @@ function unpublishAssetTool(config) {
 import { z as z21 } from "zod";
 var ArchiveAssetToolParams = BaseToolSchema.extend({
   assetId: z21.union([z21.string(), z21.array(z21.string()).max(100)]).describe(
-    "The ID of the asset to archive (string) or an array of asset IDs (up to 100 assets)"
+    "A single asset ID (string) or an array of asset IDs to archive (up to MAX_BULK_SIZE per call; default 10, max 100 \u2014 configurable via MAX_BULK_SIZE env var)."
+  ),
+  dryRun: z21.boolean().optional().describe(
+    "When true, returns a preview of the operation without executing it. Still subject to MAX_BULK_SIZE \u2014 use this to confirm intent for within-limit calls."
   )
 });
 function archiveAssetTool(config) {
@@ -1320,12 +1389,25 @@ function archiveAssetTool(config) {
       args.environmentId,
       config.protectedEnvironments
     );
+    const assetIds = Array.isArray(args.assetId) ? args.assetId : [args.assetId];
+    assertBulkSizeAllowed(assetIds.length, config.maxBulkSize);
+    if (args.dryRun) {
+      return createSuccessResponse(
+        "Dry run: no changes were made",
+        buildDryRunPreview({
+          operation: "archive",
+          entityType: "asset",
+          ids: assetIds,
+          spaceId: args.spaceId,
+          environmentId: args.environmentId
+        })
+      );
+    }
     const baseParams = {
       spaceId: args.spaceId,
       environmentId: args.environmentId
     };
     const contentfulClient = createToolClient(config, args);
-    const assetIds = Array.isArray(args.assetId) ? args.assetId : [args.assetId];
     const successfullyArchived = [];
     for (const assetId of assetIds) {
       try {
@@ -1361,7 +1443,10 @@ function archiveAssetTool(config) {
 import { z as z22 } from "zod";
 var UnarchiveAssetToolParams = BaseToolSchema.extend({
   assetId: z22.union([z22.string(), z22.array(z22.string()).max(100)]).describe(
-    "The ID of the asset to unarchive (string) or an array of asset IDs (up to 100 assets)"
+    "A single asset ID (string) or an array of asset IDs to unarchive (up to MAX_BULK_SIZE per call; default 10, max 100 \u2014 configurable via MAX_BULK_SIZE env var)."
+  ),
+  dryRun: z22.boolean().optional().describe(
+    "When true, returns a preview of the operation without executing it. Still subject to MAX_BULK_SIZE \u2014 use this to confirm intent for within-limit calls."
   )
 });
 function unarchiveAssetTool(config) {
@@ -1370,12 +1455,25 @@ function unarchiveAssetTool(config) {
       args.environmentId,
       config.protectedEnvironments
     );
+    const assetIds = Array.isArray(args.assetId) ? args.assetId : [args.assetId];
+    assertBulkSizeAllowed(assetIds.length, config.maxBulkSize);
+    if (args.dryRun) {
+      return createSuccessResponse(
+        "Dry run: no changes were made",
+        buildDryRunPreview({
+          operation: "unarchive",
+          entityType: "asset",
+          ids: assetIds,
+          spaceId: args.spaceId,
+          environmentId: args.environmentId
+        })
+      );
+    }
     const baseParams = {
       spaceId: args.spaceId,
       environmentId: args.environmentId
     };
     const contentfulClient = createToolClient(config, args);
-    const assetIds = Array.isArray(args.assetId) ? args.assetId : [args.assetId];
     const successfullyUnarchived = [];
     for (const assetId of assetIds) {
       try {
@@ -3033,7 +3131,10 @@ function getEntryTool(config) {
 import { z as z45 } from "zod";
 var PublishEntryToolParams = BaseToolSchema.extend({
   entryId: z45.array(z45.string()).min(1).max(100).describe(
-    "Array of entry IDs to publish. Pass a single-element array for one entry, or up to 100 IDs for bulk operations."
+    "Array of entry IDs to publish. Single-element array for one entry, or up to MAX_BULK_SIZE per call (default 10, max 100 \u2014 configurable via MAX_BULK_SIZE env var)."
+  ),
+  dryRun: z45.boolean().optional().describe(
+    "When true, returns a preview of the operation without executing it. Still subject to MAX_BULK_SIZE \u2014 use this to confirm intent for within-limit calls."
   )
 });
 function publishEntryTool(config) {
@@ -3042,12 +3143,25 @@ function publishEntryTool(config) {
       args.environmentId,
       config.protectedEnvironments
     );
+    const entryIds = args.entryId;
+    assertBulkSizeAllowed(entryIds.length, config.maxBulkSize);
+    if (args.dryRun) {
+      return createSuccessResponse(
+        "Dry run: no changes were made",
+        buildDryRunPreview({
+          operation: "publish",
+          entityType: "entry",
+          ids: entryIds,
+          spaceId: args.spaceId,
+          environmentId: args.environmentId
+        })
+      );
+    }
     const baseParams = {
       spaceId: args.spaceId,
       environmentId: args.environmentId
     };
     const contentfulClient = createToolClient(config, args);
-    const entryIds = args.entryId;
     if (entryIds.length === 1) {
       const entryId = entryIds[0];
       const params = {
@@ -3090,7 +3204,10 @@ function publishEntryTool(config) {
 import { z as z46 } from "zod";
 var UnpublishEntryToolParams = BaseToolSchema.extend({
   entryId: z46.array(z46.string()).min(1).max(100).describe(
-    "Array of entry IDs to unpublish. Pass a single-element array for one entry, or up to 100 IDs for bulk operations."
+    "Array of entry IDs to unpublish. Single-element array for one entry, or up to MAX_BULK_SIZE per call (default 10, max 100 \u2014 configurable via MAX_BULK_SIZE env var)."
+  ),
+  dryRun: z46.boolean().optional().describe(
+    "When true, returns a preview of the operation without executing it. Still subject to MAX_BULK_SIZE \u2014 use this to confirm intent for within-limit calls."
   )
 });
 function unpublishEntryTool(config) {
@@ -3099,12 +3216,25 @@ function unpublishEntryTool(config) {
       args.environmentId,
       config.protectedEnvironments
     );
+    const entryIds = args.entryId;
+    assertBulkSizeAllowed(entryIds.length, config.maxBulkSize);
+    if (args.dryRun) {
+      return createSuccessResponse(
+        "Dry run: no changes were made",
+        buildDryRunPreview({
+          operation: "unpublish",
+          entityType: "entry",
+          ids: entryIds,
+          spaceId: args.spaceId,
+          environmentId: args.environmentId
+        })
+      );
+    }
     const baseParams = {
       spaceId: args.spaceId,
       environmentId: args.environmentId
     };
     const contentfulClient = createToolClient(config, args);
-    const entryIds = args.entryId;
     if (entryIds.length === 1) {
       const entryId = entryIds[0];
       const params = {
@@ -3147,7 +3277,10 @@ function unpublishEntryTool(config) {
 import { z as z47 } from "zod";
 var ArchiveEntryToolParams = BaseToolSchema.extend({
   entryId: z47.array(z47.string()).min(1).max(100).describe(
-    "Array of entry IDs to archive. Pass a single-element array for one entry, or up to 100 IDs for batch operations."
+    "Array of entry IDs to archive. Single-element array for one entry, or up to MAX_BULK_SIZE per call (default 10, max 100 \u2014 configurable via MAX_BULK_SIZE env var)."
+  ),
+  dryRun: z47.boolean().optional().describe(
+    "When true, returns a preview of the operation without executing it. Still subject to MAX_BULK_SIZE \u2014 use this to confirm intent for within-limit calls."
   )
 });
 function archiveEntryTool(config) {
@@ -3156,12 +3289,25 @@ function archiveEntryTool(config) {
       args.environmentId,
       config.protectedEnvironments
     );
+    const entryIds = args.entryId;
+    assertBulkSizeAllowed(entryIds.length, config.maxBulkSize);
+    if (args.dryRun) {
+      return createSuccessResponse(
+        "Dry run: no changes were made",
+        buildDryRunPreview({
+          operation: "archive",
+          entityType: "entry",
+          ids: entryIds,
+          spaceId: args.spaceId,
+          environmentId: args.environmentId
+        })
+      );
+    }
     const baseParams = {
       spaceId: args.spaceId,
       environmentId: args.environmentId
     };
     const contentfulClient = createToolClient(config, args);
-    const entryIds = args.entryId;
     const successfullyArchived = [];
     for (const entryId of entryIds) {
       try {
@@ -3197,7 +3343,10 @@ function archiveEntryTool(config) {
 import { z as z48 } from "zod";
 var UnarchiveEntryToolParams = BaseToolSchema.extend({
   entryId: z48.array(z48.string()).min(1).max(100).describe(
-    "Array of entry IDs to unarchive. Pass a single-element array for one entry, or up to 100 IDs for batch operations."
+    "Array of entry IDs to unarchive. Single-element array for one entry, or up to MAX_BULK_SIZE per call (default 10, max 100 \u2014 configurable via MAX_BULK_SIZE env var)."
+  ),
+  dryRun: z48.boolean().optional().describe(
+    "When true, returns a preview of the operation without executing it. Still subject to MAX_BULK_SIZE \u2014 use this to confirm intent for within-limit calls."
   )
 });
 function unarchiveEntryTool(config) {
@@ -3206,12 +3355,25 @@ function unarchiveEntryTool(config) {
       args.environmentId,
       config.protectedEnvironments
     );
+    const entryIds = args.entryId;
+    assertBulkSizeAllowed(entryIds.length, config.maxBulkSize);
+    if (args.dryRun) {
+      return createSuccessResponse(
+        "Dry run: no changes were made",
+        buildDryRunPreview({
+          operation: "unarchive",
+          entityType: "entry",
+          ids: entryIds,
+          spaceId: args.spaceId,
+          environmentId: args.environmentId
+        })
+      );
+    }
     const baseParams = {
       spaceId: args.spaceId,
       environmentId: args.environmentId
     };
     const contentfulClient = createToolClient(config, args);
-    const entryIds = args.entryId;
     const successfullyUnarchived = [];
     for (const entryId of entryIds) {
       try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/mcp-tools",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",