Magento MCP Server

Instructions

Implementation Reference

• src/actions/cache.ts:139-169 (handler)

  The handler function for cache.purge_category tool. Validates input using CachePurgeCategorySchema, checks confirmation and rate limits, then uses Fastly client to purge cache by surrogate key (cat_c_${category_id}). Returns success status and purge ID.

  // ── Purge Category ────────────────────────────────────────────────────
  {
    name: 'cache.purge_category',
    description: 'Purge cache for a specific category.',
    riskTier: RiskTier.Risk,
    requiresAuth: true,
    handler: async (params: Record<string, unknown>, _context: ActionContext) => {
      const validated = CachePurgeCategorySchema.parse(params);
      guardrails.requireConfirmation(RiskTier.Risk, params);
      checkRateLimit(config);
  
      if (!config.fastlyServiceId || !config.fastlyApiToken) {
        return {
          message: 'Fastly not configured. Set FASTLY_SERVICE_ID and FASTLY_API_TOKEN environment variables.',
          purged: false,
        };
      }
  
      const fastly = new FastlyClient(config.fastlyServiceId, config.fastlyApiToken);
  
      // Purge by category surrogate key
      const surrogateKey = `cat_c_${validated.category_id}`;
      const result = await fastly.purgeSurrogateKey(surrogateKey);
  
      return {
        message: `Purged cache for category ${validated.category_id} (surrogate key: ${surrogateKey}).`,
        success: result.ok,
        purge_id: result.id,
      };
    },
  },

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

  Zod schema definition for CachePurgeCategory tool. Requires category_id (integer), optional store_view_code, confirm (must be true), and reason string for audit purposes.

  export const CachePurgeCategorySchema = z.object({
    category_id: z.number().int(),
    store_view_code: z.string().optional(),
    confirm: z.literal(true),
    reason: z.string().min(1),
  });

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

  MCP tool registration loop. Converts action name 'cache.purge_category' to 'cache_purge_category' (dots to underscores), registers each action as an MCP tool with the server, including authentication checks and context building.

  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>;