LocalStack MCP Server

import { z } from "zod"; import { type ToolMetadata, type InferSchema } from "xmcp"; import { ensureLocalStackCli } from "../lib/localstack/localstack.utils"; import { LocalStackLogRetriever, type LogEntry } from "../lib/logs/log-retriever"; import { runPreflights, requireLocalStackCli } from "../core/preflight"; import { ResponseBuilder } from "../core/response-builder"; export const schema = { analysisType: z .enum(["summary", "errors", "requests", "logs"]) .default("summary") .describe( "The analysis to perform: 'summary' (default), 'errors', 'requests', or 'logs' for raw output." ), lines: z .number() .int() .positive() .default(2000) .describe("Number of recent log lines to fetch and analyze."), service: z .string() .optional() .describe( "Filter by AWS service (e.g., 's3', 'lambda'). Used with 'errors' and 'requests' modes." ), operation: z .string() .optional() .describe( "Filter by a specific API operation (e.g., 'CreateBucket'). Requires 'service'. Used with 'requests' mode." ), filter: z.string().optional().describe("Raw keyword filter. Only used with 'logs' mode."), }; export const metadata: ToolMetadata = { name: "localstack-logs-analysis", description: "LocalStack log analyzer that helps developers quickly diagnose issues and understand their LocalStack interactions", annotations: { title: "LocalStack Logs Analysis", readOnlyHint: true, destructiveHint: false, idempotentHint: true, }, }; export default async function localstackLogsAnalysis({ analysisType, lines, service, operation, filter, }: InferSchema<typeof schema>) { const preflightError = await runPreflights([requireLocalStackCli()]); if (preflightError) return preflightError; const retriever = new LocalStackLogRetriever(); const retrievalFilter = analysisType === "logs" ? filter : undefined; const logResult = await retriever.retrieveLogs(lines, retrievalFilter); if (!logResult.success) { return ResponseBuilder.error("Log Retrieval Failed", logResult.errorMessage || "Unknown error"); } switch (analysisType) { case "summary": return await handleSummaryAnalysis(logResult.logs, logResult.totalLines); case "errors": return await handleErrorAnalysis(retriever, logResult.logs, service); case "requests": return await handleRequestAnalysis(retriever, logResult.logs, service, operation); case "logs": return await handleRawLogsAnalysis( logResult.logs, logResult.totalLines, logResult.filteredLines, filter ); default: return ResponseBuilder.error( "Unknown analysis type", `❌ Unknown analysis type: ${analysisType}` ); } } /** * Handle summary analysis mode - high-level dashboard */ async function handleSummaryAnalysis(logs: LogEntry[], totalLines: number) { const errors = logs.filter((log) => log.isError); const warnings = logs.filter((log) => log.isWarning); const apiStats = new LocalStackLogRetriever().analyzeApiCalls(logs); let result = `# 📊 LocalStack Summary\n\n`; result += `**Lines Analyzed:** ${totalLines}\n`; result += `**API Calls:** ${apiStats.totalCalls}\n`; result += `**Errors:** ${errors.length} | **Warnings:** ${warnings.length}\n\n`; // Quick health check if (apiStats.failedCalls > 0) { result += `## ❌ Recent Failures (${apiStats.failedCalls})\n\n`; const recentFailures = apiStats.failedCallDetails.slice(-5).reverse(); for (const call of recentFailures) { const service = call.service || "unknown"; const operation = call.operation || "unknown"; const status = call.statusCode || "N/A"; result += `- **${service}.${operation}** → ${status} ${call.message}\n`; } result += `\n💡 Use \`errors\` mode for detailed analysis\n\n`; } // Service breakdown if there are API calls if (apiStats.callsByService.size > 0) { result += `## 🔧 Service Activity\n\n`; for (const [svc, count] of Array.from(apiStats.callsByService.entries()).sort( (a, b) => b[1] - a[1] )) { const serviceErrors = apiStats.failedCallDetails.filter( (call) => call.service === svc ).length; const status = serviceErrors === 0 ? "✅" : "❌"; result += `- **${svc}**: ${count} calls ${status}`; if (serviceErrors > 0) result += ` (${serviceErrors} failed)`; result += `\n`; } result += `\n`; } if (errors.length === 0 && apiStats.failedCalls === 0) { result += `## ✅ All Clear\n\nNo errors detected in recent LocalStack activity.\n\n`; } result += `**Drill down:** \`errors\` | \`requests\` | \`logs\`\n`; return ResponseBuilder.markdown(result); } /** * Handle error analysis mode - detailed error examination */ async function handleErrorAnalysis( retriever: LocalStackLogRetriever, logs: LogEntry[], serviceFilter?: string ) { let errorLogs = logs.filter((log) => log.isError || log.isWarning); // Apply service filter if provided if (serviceFilter) { errorLogs = errorLogs.filter( (log) => log.service?.toLowerCase() === serviceFilter.toLowerCase() ); } if (errorLogs.length === 0) { const filterMsg = serviceFilter ? ` for ${serviceFilter}` : ""; return ResponseBuilder.markdown(`✅ No errors found${filterMsg} in the analyzed logs.`); } const errorGroups = retriever.groupLogsByError(errorLogs); const serviceMsg = serviceFilter ? ` (${serviceFilter})` : ""; let result = `# 🚨 LocalStack Errors${serviceMsg}\n\n`; result += `**Found:** ${errorLogs.length} issues (${errorGroups.size} unique types)\n\n`; // Sort error groups by frequency (most common first) const sortedErrorGroups = Array.from(errorGroups.entries()).sort( (a, b) => b[1].length - a[1].length ); for (const [errorPattern, instances] of sortedErrorGroups) { const count = instances.length; const firstInstance = instances[0]; const isApiError = firstInstance.isApiCall && firstInstance.statusCode; result += `## ${isApiError ? "🔴" : "⚠️"} ${errorPattern}\n`; result += `**Occurrences:** ${count}\n\n`; // Show recent examples const recentInstances = instances.slice(-2); for (const instance of recentInstances) { if (instance.timestamp) result += `**${instance.timestamp}**\n`; result += `\`\`\`\n${instance.fullLine}\n\`\`\`\n\n`; } if (count > 2) { result += `*... and ${count - 2} more occurrences*\n\n`; } } // Quick suggestions const hasApiErrors = errorLogs.some((log) => log.isApiCall); if (hasApiErrors) { result += `💡 **Next:** Use \`requests\` mode to analyze API call patterns\n`; } return ResponseBuilder.markdown(result); } /** * Handle request analysis mode - API call examination */ async function handleRequestAnalysis( retriever: LocalStackLogRetriever, logs: LogEntry[], serviceFilter?: string, operationFilter?: string ) { const apiStats = retriever.analyzeApiCalls(logs); if (apiStats.totalCalls === 0) { return ResponseBuilder.markdown(`🔍 No API calls detected in the analyzed logs.`); } // Case 1: Both service and operation specified - show detailed call traces if (serviceFilter && operationFilter) { const matchingCalls = logs.filter( (log) => log.isApiCall && log.service?.toLowerCase() === serviceFilter.toLowerCase() && log.operation?.toLowerCase() === operationFilter.toLowerCase() ); if (matchingCalls.length === 0) { return ResponseBuilder.markdown(`🔍 No calls found for ${serviceFilter}.${operationFilter}`); } let result = `# 🔍 ${serviceFilter}.${operationFilter} Calls\n\n`; result += `**Total:** ${matchingCalls.length}\n\n`; for (let i = 0; i < Math.min(matchingCalls.length, 10); i++) { const call = matchingCalls[i]; const status = call.statusCode ? `${call.statusCode}` : "N/A"; const statusEmoji = call.statusCode && call.statusCode >= 400 ? "❌" : "✅"; result += `### ${statusEmoji} Call ${i + 1}\n`; if (call.timestamp) result += `**${call.timestamp}**\n`; result += `**Status:** ${status}\n`; result += `\`\`\`\n${call.fullLine}\n\`\`\`\n\n`; } if (matchingCalls.length > 10) { result += `*... and ${matchingCalls.length - 10} more calls*\n`; } return ResponseBuilder.markdown(result); } // Case 2: Only service specified - show operations for that service if (serviceFilter) { const serviceCalls = logs.filter( (log) => log.isApiCall && log.service?.toLowerCase() === serviceFilter.toLowerCase() ); if (serviceCalls.length === 0) { return ResponseBuilder.markdown(`🔍 No ${serviceFilter} API calls found.`); } const operationStats = new Map<string, { total: number; failed: number }>(); for (const call of serviceCalls) { const op = call.operation || "Unknown"; if (!operationStats.has(op)) { operationStats.set(op, { total: 0, failed: 0 }); } const stats = operationStats.get(op)!; stats.total++; if (call.statusCode && call.statusCode >= 400) { stats.failed++; } } let result = `# 🔧 ${serviceFilter.toUpperCase()} API Calls\n\n`; result += `**Total:** ${serviceCalls.length}\n\n`; const sortedOps = Array.from(operationStats.entries()).sort((a, b) => b[1].total - a[1].total); for (const [operation, stats] of sortedOps) { const status = stats.failed === 0 ? "✅" : "❌"; result += `- **${operation}** ${status} (${stats.total} calls`; if (stats.failed > 0) result += `, ${stats.failed} failed`; result += `)\n`; } result += `\n💡 Add \`operation\` parameter to see detailed traces\n`; return ResponseBuilder.markdown(result); } // Case 3: No filters - show service overview let result = `# 🌐 API Activity\n\n`; result += `**Total:** ${apiStats.totalCalls} calls\n`; result += `**Failed:** ${apiStats.failedCalls}\n`; result += `**Success Rate:** ${((apiStats.successfulCalls / apiStats.totalCalls) * 100).toFixed(1)}%\n\n`; if (apiStats.callsByService.size > 0) { result += `## Services\n\n`; const sortedServices = Array.from(apiStats.callsByService.entries()).sort( (a, b) => b[1] - a[1] ); for (const [service, totalCalls] of sortedServices) { const failedCalls = apiStats.failedCallDetails.filter( (call) => call.service === service ).length; const status = failedCalls === 0 ? "✅" : "❌"; result += `- **${service}** ${status} (${totalCalls} calls`; if (failedCalls > 0) result += `, ${failedCalls} failed`; result += `)\n`; } result += `\n💡 Add \`service\` parameter to focus on specific service\n`; } return ResponseBuilder.markdown(result); } /** * Handle raw logs analysis mode - direct log inspection */ async function handleRawLogsAnalysis( logs: LogEntry[], totalLines: number, filteredLines?: number, filter?: string ) { const displayLines = filteredLines || logs.length; let result = `# 📜 Raw Logs\n\n`; if (filter) { result += `**Filter:** "${filter}" → ${displayLines}/${totalLines} lines\n\n`; } else { result += `**Lines:** ${displayLines}\n\n`; } if (logs.length === 0) { result += `No matching logs found.\n`; return ResponseBuilder.markdown(result); } result += `\`\`\`\n`; for (const log of logs) { result += `${log.fullLine}\n`; } result += `\`\`\`\n\n`; // Quick stats const errors = logs.filter((log) => log.isError).length; const apiCalls = logs.filter((log) => log.isApiCall).length; if (errors > 0 || apiCalls > 0) { result += `**Quick stats:** ${errors} errors, ${apiCalls} API calls\n`; } return { content: [{ type: "text", text: result }], }; }