@contentful/mcp-tools 0.12.10 → 0.12.12

package/dist/index.d.ts

@@ -70,6 +70,8 @@ interface ContentfulConfig {
     deliveryToken?: string;
     /** Contentful Delivery API host (used with deliveryToken for custom CDA endpoints) */
     hostDelivery?: string;
+    /** Server-controlled root directory for space export output */
+    exportBaseDir?: 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. */
@@ -8909,7 +8911,7 @@ declare class ContentfulMcpTools {
             description: string;
             inputParams: {
                 organizationId: zod.ZodOptional<zod.ZodString>;
-                metricKey: zod.ZodEnum<["api_call_cma", "api_call_cpa", "api_call_cda", "api_call_graphql", "asset_bandwidth", "functions_invocations", "ai_action_invocation", "ai_action_word_count", "ai_consumption_unit"]>;
+                metricKey: zod.ZodEnum<["api_call_cma", "api_call_cpa", "api_call_cda", "api_call_graphql", "asset_bandwidth", "functions_invocations", "ai_action_invocation", "ai_action_word_count", "ai_consumption_unit", "monthly_active_profiles"]>;
                 dateGte: zod.ZodString;
                 dateLte: zod.ZodString;
                 granularity: zod.ZodOptional<zod.ZodEnum<["P1D", "P1M"]>>;
@@ -8925,7 +8927,7 @@ declare class ContentfulMcpTools {
                 openWorldHint: boolean;
             };
             tool: (params: {
-                metricKey: "api_call_cma" | "api_call_cpa" | "api_call_cda" | "api_call_graphql" | "asset_bandwidth" | "functions_invocations" | "ai_action_invocation" | "ai_action_word_count" | "ai_consumption_unit";
+                metricKey: "api_call_cma" | "api_call_cpa" | "api_call_cda" | "api_call_graphql" | "asset_bandwidth" | "functions_invocations" | "ai_action_invocation" | "ai_action_word_count" | "ai_consumption_unit" | "monthly_active_profiles";
                 dateGte: string;
                 dateLte: string;
                 filter?: Record<string, string | string[]> | undefined;
@@ -10532,9 +10534,7 @@ declare class ContentfulMcpTools {
                 export: zod.ZodOptional<zod.ZodObject<{
                     spaceId: zod.ZodOptional<zod.ZodString>;
                     environmentId: zod.ZodOptional<zod.ZodString>;
-                    exportDir: zod.ZodOptional<zod.ZodOptional<zod.ZodString>>;
                     saveFile: zod.ZodOptional<zod.ZodDefault<zod.ZodOptional<zod.ZodBoolean>>>;
-                    contentFile: zod.ZodOptional<zod.ZodOptional<zod.ZodString>>;
                     includeDrafts: zod.ZodOptional<zod.ZodDefault<zod.ZodOptional<zod.ZodBoolean>>>;
                     includeArchived: zod.ZodOptional<zod.ZodDefault<zod.ZodOptional<zod.ZodBoolean>>>;
                     skipContentModel: zod.ZodOptional<zod.ZodDefault<zod.ZodOptional<zod.ZodBoolean>>>;
@@ -10605,14 +10605,11 @@ declare class ContentfulMcpTools {
                     }, zod.ZodTypeAny, "passthrough">>>>;
                     downloadAssets: zod.ZodOptional<zod.ZodDefault<zod.ZodOptional<zod.ZodBoolean>>>;
                     maxAllowedLimit: zod.ZodOptional<zod.ZodDefault<zod.ZodOptional<zod.ZodNumber>>>;
-                    errorLogFile: zod.ZodOptional<zod.ZodOptional<zod.ZodString>>;
                     useVerboseRenderer: zod.ZodOptional<zod.ZodOptional<zod.ZodBoolean>>;
                 }, "strip", zod.ZodTypeAny, {
                     spaceId?: string | undefined;
                     environmentId?: string | undefined;
-                    exportDir?: string | undefined;
                     saveFile?: boolean | undefined;
-                    contentFile?: string | undefined;
                     includeDrafts?: boolean | undefined;
                     includeArchived?: boolean | undefined;
                     skipContentModel?: boolean | undefined;
@@ -10627,14 +10624,11 @@ declare class ContentfulMcpTools {
                     queryAssets?: unknown;
                     downloadAssets?: boolean | undefined;
                     maxAllowedLimit?: number | undefined;
-                    errorLogFile?: string | undefined;
                     useVerboseRenderer?: boolean | undefined;
                 }, {
                     spaceId?: string | undefined;
                     environmentId?: string | undefined;
-                    exportDir?: string | undefined;
                     saveFile?: boolean | undefined;
-                    contentFile?: string | undefined;
                     includeDrafts?: boolean | undefined;
                     includeArchived?: boolean | undefined;
                     skipContentModel?: boolean | undefined;
@@ -10663,7 +10657,6 @@ declare class ContentfulMcpTools {
                     }, zod.ZodTypeAny, "passthrough"> | undefined;
                     downloadAssets?: boolean | undefined;
                     maxAllowedLimit?: number | undefined;
-                    errorLogFile?: string | undefined;
                     useVerboseRenderer?: boolean | undefined;
                 }>>;
                 import: zod.ZodOptional<zod.ZodObject<{
@@ -10690,10 +10683,9 @@ declare class ContentfulMcpTools {
                     environmentId?: string | undefined;
                     retryLimit?: number | undefined;
                     timeout?: number | undefined;
-                    contentFile?: string | undefined;
                     skipContentModel?: boolean | undefined;
-                    errorLogFile?: string | undefined;
                     useVerboseRenderer?: boolean | undefined;
+                    contentFile?: string | undefined;
                     contentModelOnly?: boolean | undefined;
                     skipLocales?: boolean | undefined;
                     skipContentUpdates?: boolean | undefined;
@@ -10702,16 +10694,16 @@ declare class ContentfulMcpTools {
                     skipAssetUpdates?: boolean | undefined;
                     assetsDirectory?: string | undefined;
                     rateLimit?: number | undefined;
+                    errorLogFile?: string | undefined;
                 }, {
                     content?: Record<string, any> | undefined;
                     spaceId?: string | undefined;
                     environmentId?: string | undefined;
                     retryLimit?: number | undefined;
                     timeout?: number | undefined;
-                    contentFile?: string | undefined;
                     skipContentModel?: boolean | undefined;
-                    errorLogFile?: string | undefined;
                     useVerboseRenderer?: boolean | undefined;
+                    contentFile?: string | undefined;
                     contentModelOnly?: boolean | undefined;
                     skipLocales?: boolean | undefined;
                     skipContentUpdates?: boolean | undefined;
@@ -10720,6 +10712,7 @@ declare class ContentfulMcpTools {
                     skipAssetUpdates?: boolean | undefined;
                     assetsDirectory?: string | undefined;
                     rateLimit?: number | undefined;
+                    errorLogFile?: string | undefined;
                 }>>;
             };
             annotations: {
@@ -10734,9 +10727,7 @@ declare class ContentfulMcpTools {
                 export?: {
                     spaceId?: string | undefined;
                     environmentId?: string | undefined;
-                    exportDir?: string | undefined;
                     saveFile?: boolean | undefined;
-                    contentFile?: string | undefined;
                     includeDrafts?: boolean | undefined;
                     includeArchived?: boolean | undefined;
                     skipContentModel?: boolean | undefined;
@@ -10751,7 +10742,6 @@ declare class ContentfulMcpTools {
                     queryAssets?: unknown;
                     downloadAssets?: boolean | undefined;
                     maxAllowedLimit?: number | undefined;
-                    errorLogFile?: string | undefined;
                     useVerboseRenderer?: boolean | undefined;
                 } | undefined;
                 import?: {
@@ -10760,10 +10750,9 @@ declare class ContentfulMcpTools {
                     environmentId?: string | undefined;
                     retryLimit?: number | undefined;
                     timeout?: number | undefined;
-                    contentFile?: string | undefined;
                     skipContentModel?: boolean | undefined;
-                    errorLogFile?: string | undefined;
                     useVerboseRenderer?: boolean | undefined;
+                    contentFile?: string | undefined;
                     contentModelOnly?: boolean | undefined;
                     skipLocales?: boolean | undefined;
                     skipContentUpdates?: boolean | undefined;
@@ -10772,6 +10761,7 @@ declare class ContentfulMcpTools {
                     skipAssetUpdates?: boolean | undefined;
                     assetsDirectory?: string | undefined;
                     rateLimit?: number | undefined;
+                    errorLogFile?: string | undefined;
                 } | undefined;
             }, extra?: _modelcontextprotocol_sdk_shared_protocol_js.RequestHandlerExtra<_modelcontextprotocol_sdk_types_js.ServerRequest, _modelcontextprotocol_sdk_types_js.ServerNotification>) => Promise<ToolResponse>;
         };
@@ -10782,9 +10772,7 @@ declare class ContentfulMcpTools {
                 spaceId: zod.ZodString;
                 environmentId: zod.ZodString;
             } & {
-                exportDir: zod.ZodOptional<zod.ZodString>;
                 saveFile: zod.ZodDefault<zod.ZodOptional<zod.ZodBoolean>>;
-                contentFile: zod.ZodOptional<zod.ZodString>;
                 includeDrafts: zod.ZodDefault<zod.ZodOptional<zod.ZodBoolean>>;
                 includeArchived: zod.ZodDefault<zod.ZodOptional<zod.ZodBoolean>>;
                 skipContentModel: zod.ZodDefault<zod.ZodOptional<zod.ZodBoolean>>;
@@ -10855,7 +10843,6 @@ declare class ContentfulMcpTools {
                 }, zod.ZodTypeAny, "passthrough">>>;
                 downloadAssets: zod.ZodDefault<zod.ZodOptional<zod.ZodBoolean>>;
                 maxAllowedLimit: zod.ZodDefault<zod.ZodOptional<zod.ZodNumber>>;
-                errorLogFile: zod.ZodOptional<zod.ZodString>;
                 useVerboseRenderer: zod.ZodOptional<zod.ZodBoolean>;
             };
             annotations: {
@@ -10879,11 +10866,8 @@ declare class ContentfulMcpTools {
                 contentOnly: boolean;
                 downloadAssets: boolean;
                 maxAllowedLimit: number;
-                exportDir?: string | undefined;
-                contentFile?: string | undefined;
                 queryEntries?: unknown;
                 queryAssets?: unknown;
-                errorLogFile?: string | undefined;
                 useVerboseRenderer?: boolean | undefined;
             }, extra?: _modelcontextprotocol_sdk_shared_protocol_js.RequestHandlerExtra<_modelcontextprotocol_sdk_types_js.ServerRequest, _modelcontextprotocol_sdk_types_js.ServerNotification>) => Promise<ToolResponse>;
         };
@@ -10930,10 +10914,10 @@ declare class ContentfulMcpTools {
                 skipAssetUpdates: boolean;
                 rateLimit: number;
                 content?: Record<string, any> | undefined;
-                contentFile?: string | undefined;
-                errorLogFile?: string | undefined;
                 useVerboseRenderer?: boolean | undefined;
+                contentFile?: string | undefined;
                 assetsDirectory?: string | undefined;
+                errorLogFile?: string | undefined;
             }, extra?: _modelcontextprotocol_sdk_shared_protocol_js.RequestHandlerExtra<_modelcontextprotocol_sdk_types_js.ServerRequest, _modelcontextprotocol_sdk_types_js.ServerNotification>) => Promise<ToolResponse>;
         };
         spaceToSpaceMigrationHandler: {

package/dist/index.js

@@ -270,7 +270,7 @@ var InvokeAiActionToolParams = BaseToolSchema.extend({
 async function pollForCompletion(contentfulClient, params, aiActions, pollInterval = 3e4, maxAttempts = 10) {
   const completedActions = /* @__PURE__ */ new Map();
   for (let attempt = 0; attempt < maxAttempts && completedActions.size < aiActions.length; attempt++) {
-    await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
     await Promise.allSettled(
       aiActions.filter((action) => !completedActions.has(action.sys.id)).map(async (action) => {
         try {
@@ -1153,7 +1153,7 @@ async function waitForBulkActionCompletion(contentfulClient, baseParams, bulkAct
     bulkActionId
   });
   while (action.sys.status === "inProgress" || action.sys.status === "created") {
-    await new Promise((resolve) => setTimeout(resolve, 1e3));
+    await new Promise((resolve2) => setTimeout(resolve2, 1e3));
     action = await contentfulClient.bulkAction.get({
       ...baseParams,
       bulkActionId
@@ -5626,7 +5626,8 @@ var AGGREGATED_USAGE_METRIC_KEYS = [
   "functions_invocations",
   "ai_action_invocation",
   "ai_action_word_count",
-  "ai_consumption_unit"
+  "ai_consumption_unit",
+  "monthly_active_profiles"
 ];
 var FilterValueSchema = z80.union([
   z80.string().min(1),
@@ -5637,7 +5638,7 @@ var GetUsagesToolParams = z80.object({
     "Organization ID. If omitted, falls back to the ORGANIZATION_ID configured on the server."
   ),
   metricKey: z80.enum(AGGREGATED_USAGE_METRIC_KEYS).describe(
-    'Metric to aggregate. Availability depends on the products enabled for the organization. Allowed dimensions per metric (used by "group", "filter", and "order", all in the form sys.dimensions.<name>.sys.<suffix>): api_call_cma / api_call_cpa / api_call_cda / api_call_graphql \u2192 sys.dimensions.space.sys.id. asset_bandwidth \u2192 sys.dimensions.space.sys.id, sys.dimensions.asset.sys.id. functions_invocations \u2192 sys.dimensions.space.sys.id, sys.dimensions.app.sys.id, sys.dimensions.function.sys.id. ai_action_invocation / ai_action_word_count / ai_consumption_unit \u2192 sys.dimensions.space.sys.id, sys.dimensions.ai_action.sys.id, sys.dimensions.model.sys.provider, sys.dimensions.model.sys.id.'
+    'Metric to aggregate. Availability depends on the products enabled for the organization. Allowed dimensions per metric (used by "group", "filter", and "order", all in the form sys.dimensions.<name>.sys.<suffix>): api_call_cma / api_call_cpa / api_call_cda / api_call_graphql \u2192 sys.dimensions.space.sys.id. asset_bandwidth \u2192 sys.dimensions.space.sys.id, sys.dimensions.asset.sys.id. functions_invocations \u2192 sys.dimensions.space.sys.id, sys.dimensions.app.sys.id, sys.dimensions.function.sys.id. ai_action_invocation / ai_action_word_count / ai_consumption_unit \u2192 sys.dimensions.space.sys.id, sys.dimensions.ai_action.sys.id, sys.dimensions.model.sys.provider, sys.dimensions.model.sys.id. monthly_active_profiles (MAPs) has no dimensions \u2014 do not pass "group", "filter", or "order" with it. MAPs is calendar-month only: use granularity="P1M" ("P1D" is not meaningful for it).'
   ),
   dateGte: z80.string().describe(
     "Start date (inclusive) in ISO-8601 format (YYYY-MM-DD or full date-time). Sent as query param date[gte]. Max lookback: 12 months from now."
@@ -5704,7 +5705,8 @@ function getUsagesTool(config) {
       limit: collection.limit,
       skip: collection.skip,
       metricKey,
-      organizationId
+      organizationId,
+      dataLastUpdatedAt: collection.dataLastUpdatedAt
     });
   }
   return withErrorHandling(tool2, "Error retrieving usage");
@@ -5728,6 +5730,10 @@ function createUsageTools(config) {
   };
 }
 
+// src/tools/jobs/space-to-space-migration/exportSpace.ts
+import { mkdir, mkdtemp, realpath } from "fs/promises";
+import { join, resolve } from "path";
+
 // src/tools/jobs/space-to-space-migration/types.ts
 import { z as z82 } from "zod";
 
@@ -5766,11 +5772,7 @@ function stripUnsupportedQueryKeys(knownKeys) {
   };
 }
 var ExportParamsSchema = BaseToolSchema.extend({
-  exportDir: z82.string().optional().describe(
-    "Directory to save the exported space data (optional, defaults to current directory)"
-  ),
   saveFile: z82.boolean().optional().default(true).describe("Save the exported space data to a file"),
-  contentFile: z82.string().optional().describe("Custom filename for the exported space data (optional)"),
   includeDrafts: z82.boolean().optional().default(false).describe("Include draft entries in the export"),
   includeArchived: z82.boolean().optional().default(false).describe("Include archived entries in the export"),
   skipContentModel: z82.boolean().optional().default(false).describe("Skip exporting content types"),
@@ -5785,7 +5787,6 @@ var ExportParamsSchema = BaseToolSchema.extend({
   queryAssets: AssetQuerySchema.passthrough().transform(stripUnsupportedQueryKeys(Object.keys(AssetQuerySchema.shape))).optional().describe("Export only assets that match query parameters"),
   downloadAssets: z82.boolean().optional().default(false).describe("Download actual asset files"),
   maxAllowedLimit: z82.number().optional().default(1e3).describe("Maximum number of items per request"),
-  errorLogFile: z82.string().optional().describe("Path to error log output file"),
   useVerboseRenderer: z82.boolean().optional().describe("Line-by-line logging, useful for CI")
 });
 var ImportParamsSchema = BaseToolSchema.extend({
@@ -5809,6 +5810,14 @@ var ImportParamsSchema = BaseToolSchema.extend({
 });
 
 // src/tools/jobs/space-to-space-migration/exportSpace.ts
+var EXPORT_FILE_NAME = "contentful-export.json";
+var EXPORT_ERROR_LOG_FILE_NAME = "contentful-export-error.log";
+async function createExportDirectory(baseDir) {
+  const configuredBase = resolve(baseDir ?? process.cwd());
+  await mkdir(configuredBase, { recursive: true });
+  const canonicalBase = await realpath(configuredBase);
+  return mkdtemp(join(canonicalBase, "contentful-export-"));
+}
 function createExportSpaceTool(config) {
   async function tool2(args) {
     const clientConfig = createClientConfig(config);
@@ -5818,12 +5827,16 @@ function createExportSpaceTool(config) {
     }
     const safeOptions = ExportParamsSchema.parse({
       ...args,
-      environmentId: args.environmentId || "master",
-      exportDir: args.exportDir || process.cwd(),
-      contentFile: args.contentFile || `contentful-export-${args.spaceId}.json`
+      environmentId: args.environmentId || "master"
     });
+    const exportDir = await createExportDirectory(config.exportBaseDir);
     const exportOptions = {
       ...safeOptions,
+      exportDir,
+      contentFile: EXPORT_FILE_NAME,
+      // contentful-export resolves a caller-provided errorLogFile relative to
+      // process.cwd(). Pass an absolute, server-generated path instead.
+      errorLogFile: join(exportDir, EXPORT_ERROR_LOG_FILE_NAME),
       managementToken,
       host: config.host ?? "api.contentful.com",
       ...config.deliveryToken && { deliveryToken: config.deliveryToken },
@@ -5831,15 +5844,11 @@ function createExportSpaceTool(config) {
     };
     try {
       const contentfulExport = await import("contentful-export");
-      const path = await import("path");
       const result = await contentfulExport.default(exportOptions);
-      const exportPath = path.join(
-        exportOptions.exportDir,
-        exportOptions.contentFile
-      );
+      const exportPath = join(exportDir, EXPORT_FILE_NAME);
       return createSuccessResponse("Space exported successfully", {
-        spaceId: args.spaceId,
-        environmentId: args.environmentId || "master",
+        spaceId: safeOptions.spaceId,
+        environmentId: safeOptions.environmentId,
         exportPath,
         contentTypes: result.contentTypes?.length || 0,
         entries: result.entries?.length || 0,
@@ -5873,9 +5882,7 @@ spaceId                 // [string] [required] - ID of the space with source dat
     `,
     optionalParams: `
 environmentId           // [string] [default: 'master'] - ID of the environment in the source space
-exportDir               // [string] [default: process.cwd()] - Path to export JSON output
 saveFile                // [boolean] [default: true] - Save the export as a JSON file
-contentFile             // [string] - Filename for exported data
 
 includeDrafts           // [boolean] [default: false] - Include drafts in exported entries
 includeArchived         // [boolean] [default: false] - Include archived entries
@@ -5894,7 +5901,6 @@ downloadAssets          // [boolean] - Download asset files to disk
 
 maxAllowedLimit         // [number] [default: 1000] - Page size for requests
 
-errorLogFile            // [string] - Path to error log output file
 useVerboseRenderer      // [boolean] [default: false] - Line-by-line logging, useful for CI
     `
   },
@@ -6028,17 +6034,18 @@ Once the workflow is started, you will need to call the tools in the following o
 5. import_space
 6. space_to_space_migration_handler with enableWorkflow=false (to conclude the workflow)
 
-## Path Configuration Best Practices:
-- ALWAYS use consistent path formats throughout the workflow
+## Path Configuration:
+- Export output paths are managed by the server and are not user-configurable.
+- Use the exportPath returned by export_space as the source content file for the import step.
 
 ### Asset Handling Paths:
-- When downloadAssets=true, the export tool creates an assets directory structure like: exportDir/images.ctfassets.net/
+- When downloadAssets=true, the export tool creates an assets directory structure next to the returned export file, under: <export directory>/images.ctfassets.net/
 - The import tool expects assetsDirectory to point to the images.ctfassets.net directory, not the parent export directory
 
 Troubleshooting:
 - If the start_space_to_space_migration is not found, try to call it again on behalf of the user.
 - If space_to_space_param_collection or other tools are not found, ask the user to confirm they are ready to proceed, as the tools need to be enabled first.
-- If import fails with path errors, verify that exportDir and assetsDirectory paths are correctly aligned and accessible.
+- If import fails with path errors, verify that the returned exportPath and assetsDirectory paths are correctly aligned and accessible.
 `;
 
 // src/tools/jobs/space-to-space-migration/migrationHandler.ts

package/package.json

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