cms_commit_bulk_update_pages

Instructions

Implementation Reference

• src/actions/cms.ts:128-180 (handler)

  The handler for the 'cms.commit_bulk_update_pages' tool. It validates input via CmsCommitBulkUpdatePagesSchema (which wraps CommitPlanSchema), consumes the plan from PlanStore, then iterates over page_ids making PUT requests to /V1/cmsPage/{pageId} for each page. Returns summary of successes and errors.

  // ── Commit Bulk Update Pages ──────────────────────────────────────────
  {
    name: 'cms.commit_bulk_update_pages',
    description: 'Execute a previously prepared CMS page bulk update.',
    riskTier: RiskTier.Risk,
    requiresAuth: true,
    handler: async (params: Record<string, unknown>, context: ActionContext) => {
      const validated = CmsCommitBulkUpdatePagesSchema.parse(params);
      guardrails.requireConfirmation(RiskTier.Risk, params);
  
      const plan = planStore.consume(validated.plan_id);
      if (!plan) {
        throw new Error('Plan not found or expired.');
      }
  
      const payload = plan.payload as {
        page_ids: number[];
        page_identifiers?: Record<number, string>;
        updates: Record<string, unknown>;
        scope?: { store_view_code?: string };
      };
      const client = context.getClient();
      const storeCode = payload.scope?.store_view_code;
  
      let successCount = 0;
      const errors: Array<{ page_id: number; error: string }> = [];
  
      for (const pageId of payload.page_ids) {
        try {
          // Include identifier in payload — required by Magento for pages whose
          // identifier is reserved in config (e.g. CMS Home Page "home")
          const identifier = payload.page_identifiers?.[pageId];
          const pagePayload: Record<string, unknown> = { id: pageId, ...payload.updates };
          if (identifier) {
            pagePayload.identifier = identifier;
          }
          await client.put(`/V1/cmsPage/${pageId}`, {
            page: pagePayload,
          }, storeCode);
          successCount++;
        } catch (err) {
          errors.push({ page_id: pageId, error: err instanceof Error ? err.message : String(err) });
        }
      }
  
      return {
        message: `Updated ${successCount}/${payload.page_ids.length} CMS pages.`,
        success_count: successCount,
        error_count: errors.length,
        errors: errors.length > 0 ? errors : undefined,
      };
    },
  },

• src/validation/schemas.ts:75-80 (schema)

  CommitPlanSchema is the underlying schema used by CmsCommitBulkUpdatePagesSchema. It validates plan_id (UUID), confirm (must be literal true), reason (non-empty string), and optional idempotency_key.

  export const CommitPlanSchema = z.object({
    plan_id: z.string().uuid(),
    confirm: z.literal(true),
    reason: z.string().min(1),
    idempotency_key: z.string().optional(),
  });

• src/validation/schemas.ts:190-190 (schema)

  CmsCommitBulkUpdatePagesSchema is simply an alias for CommitPlanSchema, meaning the tool expects plan_id, confirm (true), reason, and optional idempotency_key.

  export const CmsCommitBulkUpdatePagesSchema = CommitPlanSchema;

• src/actions/cms.ts:22-27 (registration)

  The createCmsActions function returns an array of ActionDefinitions, which includes the 'cms.commit_bulk_update_pages' tool registration at index covering lines 128-180.

  export function createCmsActions(
    planStore: PlanStore,
    guardrails: Guardrails,
    config: McpConfig,
  ): ActionDefinition[] {
    return [

• src/actions/cms.ts:334-358 (helper)

  Helper function that resolves matching pages by page_ids or identifier filter, used by the prepare step to gather pages for the bulk update plan.

  async function resolveMatchingPages(
    client: MagentoRestClient,
    match: { page_ids?: number[]; identifier?: string },
  ): Promise<Array<Record<string, unknown>>> {
    const filterGroups: Array<{ filters: Array<{ field: string; value: string; conditionType?: string }> }> = [];
  
    if (match.page_ids && match.page_ids.length > 0) {
      filterGroups.push({
        filters: [{ field: 'page_id', value: match.page_ids.join(','), conditionType: 'in' }],
      });
    }
    if (match.identifier) {
      filterGroups.push({
        filters: [{ field: 'identifier', value: `%${match.identifier}%`, conditionType: 'like' }],
      });
    }
  
    const searchParams = client.buildSearchParams({
      filterGroups: filterGroups.length > 0 ? filterGroups : undefined,
      pageSize: 200,
    });
  
    const result = await client.get<{ items: Array<Record<string, unknown>> }>('/V1/cmsPage/search', searchParams);
    return result.items || [];
  }