LocalStack MCP Server

Instructions

Implementation Reference

• src/tools/localstack-cloud-pods.ts:39-134 (handler)

  The main asynchronous handler function for the 'localstack-cloud-pods' tool. It performs preflight checks, initializes CloudPodsApiClient, and dispatches to action-specific logic (save, load, delete, reset) with appropriate error handling and responses.

  export default async function localstackCloudPods({
    action,
    pod_name,
  }: InferSchema<typeof schema>) {
    const preflightError = await runPreflights([
      requireLocalStackCli(),
      requireProFeature(ProFeature.CLOUD_PODS),
    ]);
    if (preflightError) return preflightError;
  
    const client = new CloudPodsApiClient();
  
    switch (action) {
      case "save": {
        if (!pod_name || pod_name.trim() === "") {
          return ResponseBuilder.error(
            "Missing Required Parameter",
            "The `save` action requires the `pod_name` parameter to be specified."
          );
        }
  
        const result = await client.savePod(pod_name);
        if (!result.success) {
          if (result.statusCode === 409) {
            return ResponseBuilder.error(
              "Cloud Pods Error",
              `A Cloud Pod named '**${pod_name}**' already exists. Please choose a different name or delete the existing pod first.`
            );
          }
          return ResponseBuilder.error("Cloud Pods Error", result.message);
        }
  
        return ResponseBuilder.success(`Cloud Pod '**${pod_name}**' was saved successfully.`);
      }
  
      case "load": {
        if (!pod_name || pod_name.trim() === "") {
          return ResponseBuilder.error(
            "Missing Required Parameter",
            "The `load` action requires the `pod_name` parameter to be specified."
          );
        }
  
        const result = await client.loadPod(pod_name);
        if (!result.success) {
          if (result.statusCode === 404) {
            return ResponseBuilder.error(
              "Cloud Pods Error",
              `A Cloud Pod named '**${pod_name}**' could not be found.`
            );
          }
          return ResponseBuilder.error("Cloud Pods Error", result.message);
        }
  
        return ResponseBuilder.success(
          `Cloud Pod '**${pod_name}**' was loaded. Your LocalStack instance has been restored to this snapshot.`
        );
      }
  
      case "delete": {
        if (!pod_name || pod_name.trim() === "") {
          return ResponseBuilder.error(
            "Missing Required Parameter",
            "The `delete` action requires the `pod_name` parameter to be specified."
          );
        }
  
        const result = await client.deletePod(pod_name);
        if (!result.success) {
          if (result.statusCode === 404) {
            return ResponseBuilder.error(
              "Cloud Pods Error",
              `A Cloud Pod named '**${pod_name}**' could not be found.`
            );
          }
          return ResponseBuilder.error("Cloud Pods Error", result.message);
        }
  
        return ResponseBuilder.success(`Cloud Pod '**${pod_name}**' has been permanently deleted.`);
      }
  
      case "reset": {
        const result = await client.resetState();
        if (!result.success) {
          return ResponseBuilder.error("Cloud Pods Error", result.message);
        }
  
        return ResponseBuilder.markdown(
          "⚠️ LocalStack state has been reset successfully. **All unsaved state has been permanently lost.**"
        );
      }
  
      default:
        return ResponseBuilder.error("Unknown action", `Unsupported action: ${action}`);
    }
  }

• src/tools/localstack-cloud-pods.ts:9-25 (schema)

  Zod schema defining the input parameters for the tool: 'action' (required enum: save/load/delete/reset) and optional 'pod_name' (validated string).

  export const schema = {
    action: z.enum(["save", "load", "delete", "reset"]).describe("The Cloud Pods action to perform."),
  
    pod_name: z
      .string()
      .refine((v) => v.trim().length > 0, {
        message: "pod_name must not be empty or whitespace",
      })
      .refine((v) => /^[A-Za-z0-9._-]{1,128}$/.test(v), {
        message:
          "pod_name may only contain letters, numbers, '.', '_' or '-' and be at most 128 characters",
      })
      .optional()
      .describe(
        "The name of the Cloud Pod. This is required for 'save', 'load', and 'delete' actions."
      ),
  };

• src/tools/localstack-cloud-pods.ts:28-37 (registration)

  Tool metadata export defining the tool name 'localstack-cloud-pods', description, and annotations for registration in the MCP tools system.

  export const metadata: ToolMetadata = {
    name: "localstack-cloud-pods",
    description: "Manages LocalStack Cloud Pods with following actions: save, load, delete, reset",
    annotations: {
      title: "LocalStack Cloud Pods",
      readOnlyHint: false,
      destructiveHint: true,
      idempotentHint: false,
    },
  };

• src/lib/localstack/localstack.client.ts:1-25 (helper)

  Supporting CloudPodsApiClient class used by the handler for API calls to manage cloud pods. (Note: approximate lines; actual class definition within the file.)

  import { httpClient, HttpError } from "../../core/http-client";
  
  export type ApiResult<T> =
    | { success: true; data: T }
    | { success: false; message: string; statusCode?: number };
  
  // Chaos API Client
  export class ChaosApiClient {
    private async makeRequest(
      endpoint: string,
      method: "GET" | "POST" | "PATCH" | "DELETE",
      body?: any
    ): Promise<ApiResult<any>> {
      try {
        const data = await httpClient.request<any>(`/_localstack/chaos${endpoint}`, {
          method,
          headers: { "Content-Type": "application/json" },
          body: body ? JSON.stringify(body) : undefined,
        });
        return { success: true, data };
      } catch (error) {
        if (error instanceof HttpError) {
          return {
            success: false,
            message: `❌ **Error:** The LocalStack Chaos API returned an error (Status ${error.status}):\n\`\`\`\n${error.body}\n\`\`\``,