cache_purge_by_url

Instructions

Implementation Reference

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

  The handler function for the cache_purge_by_url tool. Validates input using CachePurgeByUrlSchema, enforces rate limiting, rejects wildcard URLs, and iterates over each URL calling fastly.purgeUrl() via FastlyClient.

    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:262-266 (schema)

  Zod validation schema for the cache_purge_by_url tool. Expects an array of 1-50 valid URLs, a confirm field set to true, and a non-empty 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:77-79 (registration)

  Registration loop in index.ts that converts action names (dots to underscores) and registers them as MCP tools. The action name 'cache.purge_by_url' becomes the MCP tool name 'cache_purge_by_url'.

  // Convert dots to underscores for MCP tool names (e.g. "auth.login" -> "auth_login")
  const toolName = action.name.replace(/\./g, '_');

• src/actions/cache.ts:45-49 (registration)

  The ActionDefinition object where the tool is defined with its metadata (name 'cache.purge_by_url', description, risk tier, auth requirement, and handler).

  {
    name: 'cache.purge_by_url',
    description: 'Purge specific URLs from CDN cache.',
    riskTier: RiskTier.Risk,
    requiresAuth: true,

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

  FastlyClient.purgeUrl helper method that sends a PURGE HTTP request to the target URL with the Fastly API token, returning the purge result status and ID.

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