Magento MCP Server

Instructions

Implementation Reference

• src/actions/cache.ts:45-87 (handler)

  The handler for 'cache_purge_by_url' tool (named 'cache.purge_by_url' internally). Validates params with CachePurgeByUrlSchema, checks guardrails confirmation, enforces rate limiting, blocks wildcard purges, and uses FastlyClient to purge each URL individually.

  {
    name: 'cache.purge_by_url',
    description: 'Purge specific URLs from CDN cache.',
    riskTier: RiskTier.Risk,
    requiresAuth: true,
    handler: async (params: Record<string, unknown>, _context: ActionContext) => {
      const validated = CachePurgeByUrlSchema.parse(params);
      guardrails.requireConfirmation(RiskTier.Risk, params);
      checkRateLimit(config);
  
      // No wildcard purge allowed
      for (const url of validated.urls) {
        if (url.includes('*')) {
          throw new Error('Wildcard purge is not allowed. Specify exact URLs.');
        }
      }
  
      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);
      const results: Array<{ url: string; success: boolean; id?: string }> = [];
  
      for (const url of validated.urls) {
        try {
          const result = await fastly.purgeUrl(url);
          results.push({ url, success: result.ok, id: result.id });
        } catch (err) {
          results.push({ url, success: false });
        }
      }
  
      const successCount = results.filter((r) => r.success).length;
      return {
        message: `Purged ${successCount}/${validated.urls.length} URLs.`,
        results,
      };
    },
  },

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

  Input validation schema for cache_purge_by_url. Requires an array of 1-50 valid URLs, a confirm flag set to true, and a reason string.

  export const CachePurgeByUrlSchema = z.object({
    urls: z.array(z.string().url()).min(1).max(50),
    confirm: z.literal(true),
    reason: z.string().min(1),
  });

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

  Registration point where all actions (including cache actions) are converted to MCP tools. Tool names are transformed from dot notation (cache.purge_by_url) to underscore notation (cache_purge_by_url).

  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, '_');

• src/client/fastlyClient.ts:15-28 (helper)

  FastlyClient.purgeUrl method used by the handler. Sends a PURGE HTTP request to the target URL with Fastly API token authentication.

  async purgeUrl(url: string): Promise<FastlyPurgeResult> {
    const response = await fetch(url, {
      method: 'PURGE',
      headers: {
        'Fastly-Key': this.apiToken,
      },
    });
    const data = await response.json() as Record<string, unknown>;
    return {
      status: response.status,
      id: data['id'] as string | undefined,
      ok: response.ok,
    };
  }