LocalStack MCP Server

import { z } from "zod"; import { type ToolMetadata, type InferSchema } from "xmcp"; import { spawn } from "child_process"; import { getLocalStackStatus } from "../lib/localstack/localstack.utils"; import { runCommand } from "../core/command-runner"; import { runPreflights, requireLocalStackCli } from "../core/preflight"; import { ResponseBuilder } from "../core/response-builder"; export const schema = { action: z .enum(["start", "stop", "restart", "status"]) .describe("The LocalStack management action to perform"), envVars: z .record(z.string()) .optional() .describe("Additional environment variables as key-value pairs (only for start action)"), }; export const metadata: ToolMetadata = { name: "localstack-management", description: "Manage LocalStack lifecycle: start, stop, restart, or check status", annotations: { title: "LocalStack Management", readOnlyHint: false, destructiveHint: false, idempotentHint: false, }, }; export default async function localstackManagement({ action, envVars, }: InferSchema<typeof schema>) { const preflightError = await runPreflights([requireLocalStackCli()]); if (preflightError) return preflightError; switch (action) { case "start": return await handleStart({ envVars }); case "stop": return await handleStop(); case "restart": return await handleRestart(); case "status": return await handleStatus(); default: return ResponseBuilder.error( "Unknown action", `❌ Unknown action: ${action}. Supported actions: start, stop, restart, status` ); } } // Handle start action async function handleStart({ envVars }: { envVars?: Record<string, string> }) { const statusCheck = await getLocalStackStatus(); if (statusCheck.isRunning) { return ResponseBuilder.markdown( "⚠️ LocalStack is already running. Use 'restart' if you want to apply new configuration." ); } const environment = { ...process.env, ...(envVars || {}) } as Record<string, string>; if (process.env.LOCALSTACK_AUTH_TOKEN) { environment.LOCALSTACK_AUTH_TOKEN = process.env.LOCALSTACK_AUTH_TOKEN; } return new Promise((resolve) => { const child = spawn("localstack", ["start"], { env: environment, stdio: ["ignore", "ignore", "pipe"], }); let stderr = ""; child.stderr.on("data", (data) => { stderr += data.toString(); }); let earlyExit = false; let poll: NodeJS.Timeout; child.on("error", (err) => { earlyExit = true; if (poll) clearInterval(poll); resolve(ResponseBuilder.markdown(`❌ Failed to start LocalStack process: ${err.message}`)); }); child.on("close", (code) => { if (earlyExit) return; if (poll) clearInterval(poll); if (code !== 0) { resolve( ResponseBuilder.markdown( `❌ LocalStack process exited unexpectedly with code ${code}.\n\nStderr:\n${stderr}` ) ); } }); const pollInterval = 5000; const maxWaitTime = 120000; let timeWaited = 0; poll = setInterval(async () => { timeWaited += pollInterval; const status = await getLocalStackStatus(); if (status.isReady || status.isRunning) { clearInterval(poll); let resultMessage = "🚀 LocalStack started successfully!\n\n"; if (envVars) resultMessage += `✅ Custom environment variables applied: ${Object.keys(envVars).join(", ")}\n`; resultMessage += `\n**Status:**\n${status.statusOutput}`; resolve(ResponseBuilder.markdown(resultMessage)); } else if (timeWaited >= maxWaitTime) { clearInterval(poll); resolve( ResponseBuilder.markdown( `❌ LocalStack start timed out after ${maxWaitTime / 1000} seconds. It may still be starting in the background.` ) ); } }, pollInterval); }); } // Handle stop action async function handleStop() { const cmd = await runCommand("localstack", ["stop"]); let result = "🛑 LocalStack stop command executed successfully!\n"; if (cmd.stdout.trim()) result += `\nOutput:\n${cmd.stdout}`; if (cmd.stderr.trim()) result += `\nMessages:\n${cmd.stderr}`; const statusResult = await getLocalStackStatus(); if (!statusResult.isRunning) { result += "\n\n✅ LocalStack has been stopped successfully."; } else if (statusResult.errorMessage) { result += "\n\n✅ LocalStack appears to be stopped."; } else { result += "\n\n⚠️ LocalStack may still be running. Check the status manually if needed."; } if (cmd.error) { result = `❌ Failed to stop LocalStack: ${cmd.error.message}\n\nThis could happen if:\n- LocalStack is not currently running\n- There was an error executing the stop command\n- Permission issues\n\nYou can try checking the LocalStack status first to see if it's running.`; } return ResponseBuilder.markdown(result); } // Handle restart action async function handleRestart() { const cmd = await runCommand("localstack", ["restart"], { timeout: 30000 }); let result = "🔄 LocalStack restart command executed!\n\n"; if (cmd.stdout.trim()) result += `Output:\n${cmd.stdout}\n`; if (cmd.stderr.trim()) result += `Messages:\n${cmd.stderr}\n`; await new Promise((resolve) => setTimeout(resolve, 2000)); const statusResult = await getLocalStackStatus(); if (statusResult.statusOutput) { result += `\nStatus after restart:\n${statusResult.statusOutput}`; if (statusResult.isRunning) { result += "\n\n✅ LocalStack has been restarted successfully and is now running with a fresh state."; } else { result += "\n\n⚠️ LocalStack restart completed but may still be starting up. Check status again in a few moments."; } } else { result += "\n\n⚠️ Restart completed but unable to verify status. LocalStack may still be starting up."; } if (cmd.error) { result = `❌ Failed to restart LocalStack: ${cmd.error.message}\n\nThis could happen if:\n- LocalStack is not currently installed properly\n- There was an error executing the restart command\n- The restart process timed out (LocalStack can take time to restart)\n- Permission issues\n\nYou can try stopping and starting LocalStack manually using separate actions if the restart action continues to fail.`; } return ResponseBuilder.markdown(result); } // Handle status action async function handleStatus() { const statusResult = await getLocalStackStatus(); if (statusResult.statusOutput) { let result = "📊 LocalStack Status:\n\n"; result += statusResult.statusOutput; // Add helpful information based on the status if (statusResult.isRunning) { result += "\n\n✅ LocalStack is currently running and ready to accept requests."; } else { result += "\n\n⚠️ LocalStack is not currently running. Use the start action to start it."; } return ResponseBuilder.markdown(result); } else { const result = `❌ ${statusResult.errorMessage} This could happen if: - LocalStack is not installed properly - There was an error executing the status command - LocalStack services are not accessible Try running the CLI check first to verify your LocalStack installation.`; return ResponseBuilder.markdown(result); } }