cms_get_block

Instructions

Implementation Reference

• src/actions/cms.ts:211-222 (handler)

  The handler for the 'cms.get_block' tool. It validates params via CmsGetBlockSchema, then calls the Magento API GET /V1/cmsBlock/{block_id}. Returns CMS block data for the given block ID.

  {
    name: 'cms.get_block',
    description: 'Get a CMS block by ID.',
    riskTier: RiskTier.Safe,
    requiresAuth: true,
    handler: async (params: Record<string, unknown>, context: ActionContext) => {
      const validated = CmsGetBlockSchema.parse(params);
      const client = context.getClient();
      const storeCode = validated.scope?.store_view_code;
      return await client.get(`/V1/cmsBlock/${validated.block_id}`, undefined, storeCode);
    },
  },

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

  The Zod input schema for 'cms_get_block'. Expects: block_id (number, int) and optional scope (store_view_code).

  export const CmsGetBlockSchema = z.object({
    block_id: z.number().int(),
    scope: StoreScopeSchema.optional(),
  });

• src/index.ts:76-159 (registration)

  Registration of all actions as MCP tools. The 'cms.get_block' action is registered as 'cms_get_block' (dots replaced with underscores) via mcpServer.tool().

  for (const action of allActions) {
    // Convert dots to underscores for MCP tool names (e.g. "auth.login" -> "auth_login")
    const toolName = action.name.replace(/\./g, '_');
  
    mcpServer.tool(
      toolName,
      action.description,
      { params: z.record(z.unknown()).optional().describe('Action parameters as a JSON object') },
      async (args) => {
        const params = (args.params || {}) as Record<string, unknown>;
  
        // Check authentication
        if (action.requiresAuth) {
          const token = sessionStore.getToken(sessionId);
          if (!token) {
            return {
              content: [{ type: 'text' as const, text: JSON.stringify({ error: { code: 'NOT_AUTHENTICATED', message: 'Not authenticated. Call auth_login first.' } }, null, 2) }],
              isError: true,
            };
          }
        }
  
        // Build action context
        const context: ActionContext = {
          sessionId,
          getToken: () => sessionStore.getToken(sessionId),
          getBaseUrl: () => sessionStore.getBaseUrl(sessionId),
          getDefaultScope: () => sessionStore.getDefaultScope(sessionId),
          getOAuthCredentials: () => sessionStore.getOAuthCredentials(sessionId),
          getClient: () => {
            const baseUrl = sessionStore.getBaseUrl(sessionId);
            const token = sessionStore.getToken(sessionId);
            if (!baseUrl) throw new Error('No active session');
            const client = new MagentoRestClient(baseUrl, token);
            const oauth = sessionStore.getOAuthCredentials(sessionId);
            if (oauth) client.setOAuth(oauth);
            return client;
          },
          username: sessionStore.getUsername(sessionId),
        };
  
        try {
          const result = await action.handler(params, context);
  
          // Audit log
          const auditRecord: AuditRecord = {
            timestamp: new Date().toISOString(),
            username: context.username,
            action: action.name,
            scope: context.getDefaultScope(),
            params,
            result_summary: summarizeResult(result),
            plan_id: (params['plan_id'] as string) || null,
            reason: (params['reason'] as string) || null,
          };
          auditLogger.log(auditRecord);
  
          return {
            content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
          };
        } catch (err) {
          const errorMessage = err instanceof Error ? err.message : String(err);
  
          // Audit the error
          const auditRecord: AuditRecord = {
            timestamp: new Date().toISOString(),
            username: context.username,
            action: action.name,
            scope: null,
            params,
            result_summary: `ERROR: ${errorMessage}`,
            plan_id: null,
            reason: null,
          };
          auditLogger.log(auditRecord);
  
          return {
            content: [{ type: 'text' as const, text: JSON.stringify({ error: errorMessage }, null, 2) }],
            isError: true,
          };
        }
      },
    );
  }

• src/index.ts:57-58 (registration)

  The createCmsActions function is called to collect all CMS action definitions including 'cms.get_block'.

  ...createCmsActions(planStore, guardrails, config),
  ...createSeoActions(planStore, guardrails, config),

• src/actions/cms.ts:210-329 (registration)

  The action definition object for 'cms.get_block' within the createCmsActions function array.

    // ── Get Block ─────────────────────────────────────────────────────────
    {
      name: 'cms.get_block',
      description: 'Get a CMS block by ID.',
      riskTier: RiskTier.Safe,
      requiresAuth: true,
      handler: async (params: Record<string, unknown>, context: ActionContext) => {
        const validated = CmsGetBlockSchema.parse(params);
        const client = context.getClient();
        const storeCode = validated.scope?.store_view_code;
        return await client.get(`/V1/cmsBlock/${validated.block_id}`, undefined, storeCode);
      },
    },
  
    // ── Prepare Bulk Update Blocks ────────────────────────────────────────
    {
      name: 'cms.prepare_bulk_update_blocks',
      description: 'Prepare a bulk update for CMS blocks.',
      riskTier: RiskTier.Risk,
      requiresAuth: true,
      handler: async (params: Record<string, unknown>, context: ActionContext) => {
        const validated = CmsPrepareBulkUpdateBlocksSchema.parse(params);
  
        guardrails.enforceAllowedFields(
          Object.keys(validated.updates),
          config.allowedCmsBlockUpdateFields,
          'CMS block update',
        );
  
        const client = context.getClient();
        const blocks = await resolveMatchingBlocks(client, validated.match);
  
        const sampleDiffs = blocks.slice(0, 5).map((b: Record<string, unknown>) => {
          const diff: Record<string, { from: unknown; to: unknown }> = {};
          for (const [field, newValue] of Object.entries(validated.updates)) {
            diff[field] = { from: b[field], to: newValue };
          }
          return { block_id: b['id'], title: b['title'], changes: diff };
        });
  
        const blockIdentifiers: Record<number, string> = {};
        for (const b of blocks) {
          blockIdentifiers[b['id'] as number] = String(b['identifier'] || '');
        }
  
        const plan = planStore.create(
          'cms.commit_bulk_update_blocks',
          {
            block_ids: blocks.map((b: Record<string, unknown>) => b['id']),
            block_identifiers: blockIdentifiers,
            updates: validated.updates,
            scope: validated.scope,
          },
          blocks.length,
          config.planExpiryMinutes,
          sampleDiffs,
        );
  
        return {
          plan_id: plan.plan_id,
          expires_at: plan.expires_at,
          affected_count: blocks.length,
          sample_diffs: sampleDiffs,
          message: 'CMS block update plan created. Call cms.commit_bulk_update_blocks to execute.',
        };
      },
    },
  
    // ── Commit Bulk Update Blocks ─────────────────────────────────────────
    {
      name: 'cms.commit_bulk_update_blocks',
      description: 'Execute a previously prepared CMS block bulk update.',
      riskTier: RiskTier.Risk,
      requiresAuth: true,
      handler: async (params: Record<string, unknown>, context: ActionContext) => {
        const validated = CmsCommitBulkUpdateBlocksSchema.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 {
          block_ids: number[];
          block_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<{ block_id: number; error: string }> = [];
  
        for (const blockId of payload.block_ids) {
          try {
            const identifier = payload.block_identifiers?.[blockId];
            const blockPayload: Record<string, unknown> = { id: blockId, ...payload.updates };
            if (identifier) {
              blockPayload.identifier = identifier;
            }
            await client.put(`/V1/cmsBlock/${blockId}`, {
              block: blockPayload,
            }, storeCode);
            successCount++;
          } catch (err) {
            errors.push({ block_id: blockId, error: err instanceof Error ? err.message : String(err) });
          }
        }
  
        return {
          message: `Updated ${successCount}/${payload.block_ids.length} CMS blocks.`,
          success_count: successCount,
          error_count: errors.length,
          errors: errors.length > 0 ? errors : undefined,
        };
      },
    },
  ];