mcp-aws-manager 0.3.4 → 0.3.6

package/bin/mcp-aws-manager-mcp.js

@@ -1,736 +1,1184 @@
-#!/usr/bin/env node
-"use strict";
-
-const path = require("node:path");
-const { spawn } = require("node:child_process");
-
-const { McpServer } = require("@modelcontextprotocol/sdk/server/mcp.js");
-const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
-const z4 = require("zod/v4");
-
-const z = z4.z || z4;
-const pkg = require("../package.json");
-
-const CLI_SCRIPT_PATH = path.join(__dirname, "mcp-aws-manager.js");
-const DEFAULT_TIMEOUT_SEC = 300;
-const DEFAULT_STDIO_TEXT_LIMIT = 16000;
-const DEFAULT_JSON_TEXT_LIMIT = 120000;
-
-function usageText() {
-  return [
-    "mcp-aws-manager-mcp",
-    "",
-    "MCP stdio wrapper for the mcp-aws-manager CLI.",
-    "",
-    "Usage:",
-    "  mcp-aws-manager-mcp",
-    "  mcp-aws-manager-mcp --help",
-    "",
-    "Notes:",
-    "  - This process is an MCP stdio server.",
-    "  - Exposes multi-service AWS inventory and optional runtime tools.",
-    ""
-  ].join("\n");
-}
+#!/usr/bin/env node
+"use strict";
+
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+
+const { McpServer } = require("@modelcontextprotocol/sdk/server/mcp.js");
+const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
+const z4 = require("zod/v4");
+
+const z = z4.z || z4;
+const pkg = require("../package.json");
+
+const CLI_SCRIPT_PATH = path.join(__dirname, "mcp-aws-manager.js");
+const DEFAULT_TIMEOUT_SEC = 300;
+const DEFAULT_STDIO_TEXT_LIMIT = 16000;
+const DEFAULT_JSON_TEXT_LIMIT = 120000;
+
+function usageText() {
+  return [
+    "mcp-aws-manager-mcp",
+    "",
+    "MCP stdio wrapper for the mcp-aws-manager CLI.",
+    "",
+    "Usage:",
+    "  mcp-aws-manager-mcp",
+    "  mcp-aws-manager-mcp --help",
+    "",
+    "Notes:",
+    "  - This process is an MCP stdio server.",
+    "  - Exposes multi-service AWS inventory and optional runtime tools.",
+    ""
+  ].join("\n");
+}
+
+function shouldShowHelp(argv) {
+  return argv.includes("-h") || argv.includes("--help");
+}
+
+function toCsvArg(values) {
+  if (!Array.isArray(values) || !values.length) return null;
+  return values.map((v) => String(v).trim()).filter(Boolean).join(",");
+}
+
+function truncateText(value, maxLength = DEFAULT_STDIO_TEXT_LIMIT) {
+  const text = String(value || "");
+  if (text.length <= maxLength) return text;
+  const suffix = `\n... [truncated ${text.length - maxLength} chars]`;
+  return text.slice(0, maxLength) + suffix;
+}
+
+function parseStderr(stderrText) {
+  const lines = String(stderrText || "")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  const warnings = [];
+  const requiredActions = [];
+  let summaryLine = null;
+
+  for (const line of lines) {
+    if (line.startsWith("WARNING: ")) {
+      warnings.push(line.slice("WARNING: ".length));
+      continue;
+    }
+    if (line.startsWith("Summary: ")) {
+      summaryLine = line;
+      continue;
+    }
+    if (line.startsWith("ACTION_REQUIRED: ")) {
+      const payload = line.slice("ACTION_REQUIRED: ".length).trim();
+      const m = /^\[(.+?)\]\s*(.*)$/.exec(payload);
+      requiredActions.push({
+        code: m ? m[1] : "UNKNOWN",
+        message: m ? m[2] : payload,
+        hint: null
+      });
+      continue;
+    }
+    if (line.startsWith("ACTION_HINT: ")) {
+      if (requiredActions.length) {
+        requiredActions[requiredActions.length - 1].hint = line.slice("ACTION_HINT: ".length);
+      }
+    }
+  }
+
+  return { lines, warnings, requiredActions, summaryLine };
+}
+
+function buildCliArgs(input) {
+  const args = [CLI_SCRIPT_PATH, "--format", "json"];
+
+  const profiles = toCsvArg(input.profiles);
+  if (profiles) args.push("--profiles", profiles);
+
+  const regions = toCsvArg(input.regions);
+  if (regions) args.push("--regions", regions);
+
+  const instanceIds = toCsvArg(input.instanceIds);
+  if (instanceIds) args.push("--instance-ids", instanceIds);
+
+  if (input.includeLambda === true) args.push("--include-lambda");
+  if (input.includeLambda === false) args.push("--no-include-lambda");
+  if (input.includeEc2 === true) args.push("--include-ec2");
+  if (input.includeEc2 === false) args.push("--no-ec2");
+  if (input.includeAlb === true) args.push("--include-alb");
+  if (input.includeAlb === false) args.push("--no-include-alb");
+  if (input.includeAsg === true) args.push("--include-asg");
+  if (input.includeAsg === false) args.push("--no-include-asg");
+  if (input.includeRds === true) args.push("--include-rds");
+  if (input.includeRds === false) args.push("--no-include-rds");
+  if (input.includeElastiCache === true) args.push("--include-elasticache");
+  if (input.includeElastiCache === false) args.push("--no-include-elasticache");
+  if (input.includeRoute53 === true) args.push("--include-route53");
+  if (input.includeRoute53 === false) args.push("--no-include-route53");
+
+  if (input.publicOnly) args.push("--public-only");
+  if (input.managedOnly) args.push("--managed-only");
+
+  if (input.autoRemediateSsm) args.push("--auto-remediate-ssm");
+  if (input.ssmInstanceProfileName) args.push("--ssm-instance-profile-name", input.ssmInstanceProfileName);
+  if (input.ssmInstanceProfileArn) args.push("--ssm-instance-profile-arn", input.ssmInstanceProfileArn);
+  if (input.allowReplaceProfile) args.push("--allow-replace-profile");
+  if (input.remediationWaitSec != null) args.push("--remediation-wait", String(input.remediationWaitSec));
+
+  if (input.runtimeSnapshot === false) args.push("--no-runtime-snapshot");
+  if (input.runtimeSnapshot === true) args.push("--runtime-snapshot");
+  if (input.snapshotTimeoutSec != null) args.push("--snapshot-timeout", String(input.snapshotTimeoutSec));
+  if (input.snapshotConcurrency != null) args.push("--snapshot-concurrency", String(input.snapshotConcurrency));
+  if (input.snapshotMaxKb != null) args.push("--snapshot-max-kb", String(input.snapshotMaxKb));
+
+  if (input.manualServerListPath) args.push("--manual-server-list", input.manualServerListPath);
+  const pemPaths = toCsvArg(input.pemPaths);
+  if (pemPaths) args.push("--pem-paths", pemPaths);
+  if (input.sshUser) args.push("--ssh-user", input.sshUser);
+  if (input.sshPort != null) args.push("--ssh-port", String(input.sshPort));
+  if (input.sshConnectTimeoutSec != null) args.push("--ssh-connect-timeout", String(input.sshConnectTimeoutSec));
+  if (input.htmlOutPath) args.push("--html-out", input.htmlOutPath);
+  if (input.openHtml) args.push("--open-html");
 
-function shouldShowHelp(argv) {
-  return argv.includes("-h") || argv.includes("--help");
+  if (input.autoSsoLogin === false) args.push("--no-auto-sso-login");
+  if (input.autoSsoLogin === true) args.push("--auto-sso-login");
+
+  if (input.noProgress !== false) args.push("--no-progress");
+
+  return args;
+}
+
+function runDiscoverCli(input) {
+  const timeoutSec =
+    typeof input.timeoutSec === "number" && Number.isFinite(input.timeoutSec)
+      ? input.timeoutSec
+      : DEFAULT_TIMEOUT_SEC;
+  const timeoutMs = Math.max(1, Math.round(timeoutSec * 1000));
+
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, buildCliArgs(input), {
+      cwd: input.workingDirectory || process.cwd(),
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let exited = false;
+
+    if (child.stdout) {
+      child.stdout.setEncoding("utf8");
+      child.stdout.on("data", (chunk) => {
+        stdout += chunk;
+      });
+    }
+    if (child.stderr) {
+      child.stderr.setEncoding("utf8");
+      child.stderr.on("data", (chunk) => {
+        stderr += chunk;
+      });
+    }
+
+    const timer = setTimeout(() => {
+      if (exited) return;
+      timedOut = true;
+      try { child.kill("SIGTERM"); } catch {}
+      setTimeout(() => {
+        if (!exited) {
+          try { child.kill("SIGKILL"); } catch {}
+        }
+      }, 3000).unref();
+    }, timeoutMs);
+    timer.unref();
+
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      exited = true;
+      resolve({
+        ok: false,
+        exitCode: null,
+        signal: null,
+        stdout,
+        stderr,
+        timedOut,
+        spawnError: error && error.message ? error.message : String(error)
+      });
+    });
+
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      exited = true;
+      resolve({
+        ok: true,
+        exitCode: typeof code === "number" ? code : null,
+        signal: signal || null,
+        stdout,
+        stderr,
+        timedOut,
+        spawnError: null
+      });
+    });
+  });
 }
 
-function toCsvArg(values) {
-  if (!Array.isArray(values) || !values.length) return null;
-  return values.map((v) => String(v).trim()).filter(Boolean).join(",");
+let mutationAwsModules = null;
+function loadMutationAwsModules() {
+  if (mutationAwsModules) return mutationAwsModules;
+  try {
+    const ec2 = require("@aws-sdk/client-ec2");
+    const creds = require("@aws-sdk/credential-providers");
+    mutationAwsModules = { ec2, creds };
+    return mutationAwsModules;
+  } catch {
+    throw new Error("Missing AWS SDK dependencies. Run: npm install");
+  }
 }
 
-function truncateText(value, maxLength = DEFAULT_STDIO_TEXT_LIMIT) {
-  const text = String(value || "");
-  if (text.length <= maxLength) return text;
-  const suffix = `\n... [truncated ${text.length - maxLength} chars]`;
-  return text.slice(0, maxLength) + suffix;
+function mutationAwsConfig(profile, region) {
+  const { creds } = loadMutationAwsModules();
+  const config = { region };
+  if (profile) {
+    config.credentials = creds.fromIni({ profile });
+  }
+  return config;
 }
 
-function parseStderr(stderrText) {
-  const lines = String(stderrText || "")
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .filter(Boolean);
-
-  const warnings = [];
-  const requiredActions = [];
-  let summaryLine = null;
-
-  for (const line of lines) {
-    if (line.startsWith("WARNING: ")) {
-      warnings.push(line.slice("WARNING: ".length));
-      continue;
-    }
-    if (line.startsWith("Summary: ")) {
-      summaryLine = line;
-      continue;
-    }
-    if (line.startsWith("ACTION_REQUIRED: ")) {
-      const payload = line.slice("ACTION_REQUIRED: ".length).trim();
-      const m = /^\[(.+?)\]\s*(.*)$/.exec(payload);
-      requiredActions.push({
-        code: m ? m[1] : "UNKNOWN",
-        message: m ? m[2] : payload,
-        hint: null
-      });
-      continue;
-    }
-    if (line.startsWith("ACTION_HINT: ")) {
-      if (requiredActions.length) {
-        requiredActions[requiredActions.length - 1].hint = line.slice("ACTION_HINT: ".length);
-      }
-    }
+function mutationErrorMeta(error, profile, region) {
+  const detail = `${error && error.name ? error.name : "Error"}: ${error && error.message ? error.message : String(error)}`;
+  const text = detail.toLowerCase();
+  if (
+    text.includes("credential") ||
+    text.includes("sso") ||
+    text.includes("token") ||
+    text.includes("unable to locate credentials")
+  ) {
+    return {
+      code: "AWS_CREDENTIALS_REQUIRED",
+      message: `AWS authentication failed for profile=${profile || "default"} region=${region}.`,
+      hint: profile
+        ? `Run 'aws sso login --profile ${profile}' or configure access key; then retry.`
+        : "Configure AWS credentials (SSO or access key) and retry."
+    };
   }
-
-  return { lines, warnings, requiredActions, summaryLine };
+  if (text.includes("accessdenied") || text.includes("not authorized")) {
+    return {
+      code: "IAM_PERMISSION_REQUIRED",
+      message: `Missing AWS IAM permission for profile=${profile || "default"} region=${region}.`,
+      hint: detail
+    };
+  }
+  return {
+    code: "AWS_OPERATION_FAILED",
+    message: `AWS operation failed for profile=${profile || "default"} region=${region}.`,
+    hint: detail
+  };
 }
 
-function buildCliArgs(input) {
-  const args = [CLI_SCRIPT_PATH, "--format", "json"];
-
-  const profiles = toCsvArg(input.profiles);
-  if (profiles) args.push("--profiles", profiles);
-
-  const regions = toCsvArg(input.regions);
-  if (regions) args.push("--regions", regions);
-
-  const instanceIds = toCsvArg(input.instanceIds);
-  if (instanceIds) args.push("--instance-ids", instanceIds);
-
-  if (input.includeLambda === true) args.push("--include-lambda");
-  if (input.includeLambda === false) args.push("--no-include-lambda");
-  if (input.includeEc2 === true) args.push("--include-ec2");
-  if (input.includeEc2 === false) args.push("--no-ec2");
-  if (input.includeAlb === true) args.push("--include-alb");
-  if (input.includeAlb === false) args.push("--no-include-alb");
-  if (input.includeAsg === true) args.push("--include-asg");
-  if (input.includeAsg === false) args.push("--no-include-asg");
-  if (input.includeRds === true) args.push("--include-rds");
-  if (input.includeRds === false) args.push("--no-include-rds");
-  if (input.includeElastiCache === true) args.push("--include-elasticache");
-  if (input.includeElastiCache === false) args.push("--no-include-elasticache");
-  if (input.includeRoute53 === true) args.push("--include-route53");
-  if (input.includeRoute53 === false) args.push("--no-include-route53");
-
-  if (input.publicOnly) args.push("--public-only");
-  if (input.managedOnly) args.push("--managed-only");
-
-  if (input.autoRemediateSsm) args.push("--auto-remediate-ssm");
-  if (input.ssmInstanceProfileName) args.push("--ssm-instance-profile-name", input.ssmInstanceProfileName);
-  if (input.ssmInstanceProfileArn) args.push("--ssm-instance-profile-arn", input.ssmInstanceProfileArn);
-  if (input.allowReplaceProfile) args.push("--allow-replace-profile");
-  if (input.remediationWaitSec != null) args.push("--remediation-wait", String(input.remediationWaitSec));
-
-  if (input.runtimeSnapshot === false) args.push("--no-runtime-snapshot");
-  if (input.runtimeSnapshot === true) args.push("--runtime-snapshot");
-  if (input.snapshotTimeoutSec != null) args.push("--snapshot-timeout", String(input.snapshotTimeoutSec));
-  if (input.snapshotConcurrency != null) args.push("--snapshot-concurrency", String(input.snapshotConcurrency));
-  if (input.snapshotMaxKb != null) args.push("--snapshot-max-kb", String(input.snapshotMaxKb));
-
-  if (input.autoSsoLogin === false) args.push("--no-auto-sso-login");
-  if (input.autoSsoLogin === true) args.push("--auto-sso-login");
-
-  if (input.noProgress !== false) args.push("--no-progress");
-
-  return args;
+function normalizeProfile(profile) {
+  const value = String(profile == null ? "" : profile).trim();
+  return value || "default";
 }
 
-function runDiscoverCli(input) {
-  const timeoutSec =
-    typeof input.timeoutSec === "number" && Number.isFinite(input.timeoutSec)
-      ? input.timeoutSec
-      : DEFAULT_TIMEOUT_SEC;
-  const timeoutMs = Math.max(1, Math.round(timeoutSec * 1000));
-
-  return new Promise((resolve) => {
-    const child = spawn(process.execPath, buildCliArgs(input), {
-      cwd: input.workingDirectory || process.cwd(),
-      env: process.env,
-      stdio: ["ignore", "pipe", "pipe"]
-    });
-
-    let stdout = "";
-    let stderr = "";
-    let timedOut = false;
-    let exited = false;
+async function runEc2InstanceAction(input, action) {
+  const { ec2 } = loadMutationAwsModules();
+  const profile = normalizeProfile(input.profile);
+  const region = String(input.region || "").trim();
+  const instanceIds = Array.isArray(input.instanceIds) ? input.instanceIds.map((v) => String(v).trim()).filter(Boolean) : [];
+  if (!region) {
+    return { ok: false, error: "region is required", requiredAction: null };
+  }
+  if (!instanceIds.length) {
+    return { ok: false, error: "instanceIds is required", requiredAction: null };
+  }
 
-    if (child.stdout) {
-      child.stdout.setEncoding("utf8");
-      child.stdout.on("data", (chunk) => {
-        stdout += chunk;
-      });
-    }
-    if (child.stderr) {
-      child.stderr.setEncoding("utf8");
-      child.stderr.on("data", (chunk) => {
-        stderr += chunk;
-      });
+  const client = new ec2.EC2Client(mutationAwsConfig(profile, region));
+  try {
+    if (action === "start") {
+      const output = await client.send(new ec2.StartInstancesCommand({
+        InstanceIds: instanceIds,
+        DryRun: input.dryRun === true
+      }));
+      return {
+        ok: true,
+        action,
+        profile,
+        region,
+        instanceIds,
+        response: {
+          startingInstances: output && output.StartingInstances ? output.StartingInstances : []
+        }
+      };
     }
 
-    const timer = setTimeout(() => {
-      if (exited) return;
-      timedOut = true;
-      try { child.kill("SIGTERM"); } catch {}
-      setTimeout(() => {
-        if (!exited) {
-          try { child.kill("SIGKILL"); } catch {}
+    if (action === "stop") {
+      const output = await client.send(new ec2.StopInstancesCommand({
+        InstanceIds: instanceIds,
+        Force: input.force === true,
+        DryRun: input.dryRun === true
+      }));
+      return {
+        ok: true,
+        action,
+        profile,
+        region,
+        instanceIds,
+        response: {
+          stoppingInstances: output && output.StoppingInstances ? output.StoppingInstances : []
         }
-      }, 3000).unref();
-    }, timeoutMs);
-    timer.unref();
-
-    child.on("error", (error) => {
-      clearTimeout(timer);
-      exited = true;
-      resolve({
-        ok: false,
-        exitCode: null,
-        signal: null,
-        stdout,
-        stderr,
-        timedOut,
-        spawnError: error && error.message ? error.message : String(error)
-      });
-    });
+      };
+    }
 
-    child.on("close", (code, signal) => {
-      clearTimeout(timer);
-      exited = true;
-      resolve({
+    if (action === "reboot") {
+      await client.send(new ec2.RebootInstancesCommand({
+        InstanceIds: instanceIds,
+        DryRun: input.dryRun === true
+      }));
+      return {
         ok: true,
-        exitCode: typeof code === "number" ? code : null,
-        signal: signal || null,
-        stdout,
-        stderr,
-        timedOut,
-        spawnError: null
-      });
-    });
-  });
-}
-
-function tryParseJsonArray(text) {
-  const trimmed = String(text || "").trim();
-  if (!trimmed) {
-    return { ok: false, error: "Empty stdout" };
-  }
-  try {
-    const parsed = JSON.parse(trimmed);
-    if (!Array.isArray(parsed)) {
-      return { ok: false, error: "CLI JSON output was not an array" };
+        action,
+        profile,
+        region,
+        instanceIds,
+        response: { rebootRequested: true }
+      };
     }
-    return { ok: true, value: parsed };
+
+    return { ok: false, error: `unsupported action: ${action}`, requiredAction: null };
   } catch (error) {
-    return { ok: false, error: error && error.message ? error.message : String(error) };
+    return {
+      ok: false,
+      error: error && error.message ? error.message : String(error),
+      requiredAction: mutationErrorMeta(error, profile, region)
+    };
+  } finally {
+    client.destroy();
   }
 }
 
-function summarizeRecords(records) {
-  const summary = {
-    totalRecords: 0,
-    ec2Records: 0,
-    lambdaRecords: 0,
-    albRecords: 0,
-    targetGroupRecords: 0,
-    asgRecords: 0,
-    rdsRecords: 0,
-    elasticacheRecords: 0,
-    route53ZoneRecords: 0,
-    publicIpRecords: 0,
-    ssmManagedCount: 0,
-    ssmOnlineCount: 0,
-    runtimeSnapshotCount: 0,
-    runtimeSnapshotSuccessCount: 0,
-    profiles: [],
-    regions: []
-  };
-
-  const profileSet = new Set();
-  const regionSet = new Set();
-
-  for (const item of Array.isArray(records) ? records : []) {
-    summary.totalRecords += 1;
-    const resourceType = item && item.resourceType ? String(item.resourceType).toLowerCase() : null;
-    if (resourceType === "ec2") summary.ec2Records += 1;
-    if (resourceType === "lambda") summary.lambdaRecords += 1;
-    if (resourceType === "alb") summary.albRecords += 1;
-    if (resourceType === "target_group") summary.targetGroupRecords += 1;
-    if (resourceType === "asg") summary.asgRecords += 1;
-    if (resourceType === "rds") summary.rdsRecords += 1;
-    if (resourceType === "elasticache") summary.elasticacheRecords += 1;
-    if (resourceType === "route53_zone") summary.route53ZoneRecords += 1;
-    if (item && item.publicIp) summary.publicIpRecords += 1;
-    if (item && item.ssmManaged === true) summary.ssmManagedCount += 1;
-    if (item && item.ssmOnline === true) summary.ssmOnlineCount += 1;
-    if (item && item.runtimeSnapshot) {
-      summary.runtimeSnapshotCount += 1;
-      if (item.runtimeSnapshot.status === "Success") {
-        summary.runtimeSnapshotSuccessCount += 1;
-      }
-    }
-    if (item && item.profile) profileSet.add(String(item.profile));
-    if (item && item.region) regionSet.add(String(item.region));
+async function applyInstanceProfile(input) {
+  const { ec2 } = loadMutationAwsModules();
+  const profile = normalizeProfile(input.profile);
+  const region = String(input.region || "").trim();
+  const instanceId = String(input.instanceId || "").trim();
+  if (!region) {
+    return { ok: false, error: "region is required", requiredAction: null };
   }
-
-  summary.profiles = Array.from(profileSet).sort();
-  summary.regions = Array.from(regionSet).sort();
-  return summary;
-}
-
-function firstProfileArg(args) {
-  if (args && Array.isArray(args.profiles) && args.profiles.length > 0) {
-    return String(args.profiles[0]);
+  if (!instanceId) {
+    return { ok: false, error: "instanceId is required", requiredAction: null };
   }
-  return "default";
-}
 
-function inferSsoLoginCommand(action, args) {
-  const hint = action && action.hint ? String(action.hint) : "";
-  const matched = /aws sso login --profile\s+[^\s'"]+/i.exec(hint);
-  if (matched) {
-    return matched[0];
+  const name = input.instanceProfileName ? String(input.instanceProfileName).trim() : "";
+  const arn = input.instanceProfileArn ? String(input.instanceProfileArn).trim() : "";
+  if (!name && !arn) {
+    return { ok: false, error: "instanceProfileName or instanceProfileArn is required", requiredAction: null };
   }
-  return `aws sso login --profile ${firstProfileArg(args)}`;
-}
+  const target = arn ? { Arn: arn } : { Name: name };
 
-function guidanceForAction(action, args) {
-  const code = action && action.code ? String(action.code) : "UNKNOWN";
-  const defaultItem = {
-    code,
-    title: "Manual action required",
-    steps: [
-      action && action.message ? action.message : "A manual action is required.",
-      action && action.hint ? action.hint : "After completing the action, reply '?熬곣뫁?? to continue."
-    ],
-    confirmText: "?브퀗??洹쏆쾸? ?熬곣뫁???濡?듆 '?熬곣뫁?????┑€?????면썒??닔??? ?띠룇?? ??븐슙???怨쀬Ŧ ???吏?????熬곥굥由?뇦猿뗭쪠????덈펲."
-  };
+  const client = new ec2.EC2Client(mutationAwsConfig(profile, region));
+  try {
+    const associations = await client.send(new ec2.DescribeIamInstanceProfileAssociationsCommand({
+      Filters: [{ Name: "instance-id", Values: [instanceId] }]
+    }));
+    const list = Array.isArray(associations && associations.IamInstanceProfileAssociations)
+      ? associations.IamInstanceProfileAssociations
+      : [];
+    const active = list.find((item) => {
+      const state = item && item.State ? String(item.State).toLowerCase() : "";
+      return state === "associated" || state === "associating";
+    });
 
-  switch (code) {
-    case "SSO_LOGIN_NEEDED":
-    case "SSO_REAUTH_REQUIRED": {
-      const cmd = inferSsoLoginCommand(action, args);
+    if (!active) {
+      const out = await client.send(new ec2.AssociateIamInstanceProfileCommand({
+        InstanceId: instanceId,
+        IamInstanceProfile: target
+      }));
       return {
-        code,
-        title: "AWS SSO login required",
-        steps: [
-          `????????????깅쾳 嶺뚮ㅏ援앲??????덈뺄??琉얠돪?? ${cmd}`,
-          "??곗뒧???? ?筌뤾쑴理?MFA???熬곣뫁???琉얠돪??",
-          "?熬곣뫁????'?熬곣뫁?????┑€?????면썒??닔???"
-        ],
-        confirmText: "SSO ?β돦裕??筌뤾쑴逾???硫명뀬???좊듆 '?熬곣뫁?????┑€?????면썒??닔???"
+        ok: true,
+        action: "associate",
+        profile,
+        region,
+        instanceId,
+        response: {
+          associationId: out && out.IamInstanceProfileAssociation ? out.IamInstanceProfileAssociation.AssociationId : null
+        }
       };
     }
-    case "AWS_CREDENTIALS_REQUIRED":
-      return {
-        code,
-        title: "AWS credentials required",
-        steps: [
-          "??????熬곣뫁夷?熬곣뫗踰????遊꾤춯?밸퉾筌?????깆젧??琉얠돪??(SSO ???裕?access key).",
-          "SSO??寃밸듆 'aws configure sso --profile <profile>' ???β돦裕??筌뤿굝由?筌뤾쑴??",
-          "?熬곣뫁????'?熬곣뫁?????┑€?????면썒??닔???"
-        ],
-        confirmText: "???遊꾤춯?밸퉾筌????깆젧/?β돦裕??筌뤾쑴逾???硫명뀬???좊듆 '?熬곣뫁?????┑€?????면썒??닔???"
-      };
-    case "SET_SSM_INSTANCE_PROFILE":
-      return {
-        code,
-        title: "SSM remediation target missing",
-        steps: [
-          "???吏??곌랜踰€?袁ㅻご??????濡?졎嶺?instance profile ???藥????裕?ARN??嶺뚯솘??筌먐삵돵????紐껊퉵??",
-          "???깅쾳 ?????繞???濡る룎????節띾쐾 ?熬곣뫀堉??琉얠돪?? --ssm-instance-profile-name ???裕?--ssm-instance-profile-arn",
-          "?熬곣뫁????'?熬곣뫁?????┑€?????면썒??닔???"
-        ],
-        confirmText: "?熬곣뫁夷???逾?????⑤챷諭?嶺뚯솘??筌먐삳빳???좊듆 '?熬곣뫁?????┑€?????면썒??닔???"
-      };
-    case "SSM_ROLE_OR_AGENT_REQUIRED":
-      return {
-        code,
-        title: "Instance is not SSM managed",
-        steps: [
-          "?筌뤾쑬裕??怨룸츩 ?????AmazonSSMManagedInstanceCore???????琉얠돪??",
-          "SSM Agent?? ???덈콦??怨뚯씩(SSM endpoint/?筌뤿굛????롪퍔?δ빳??띠럾? ?筌먦끆留?筌? ?筌먦끉逾??琉얠돪??",
-          "?熬곣뫁????'?熬곣뫁?????┑€?????면썒??닔???"
-        ],
-        confirmText: "SSM ??㉱€????⑤객臾???브퀗?????덈펲嶺?'?熬곣뫁?????┑€?????면썒??닔???"
-      };
-    case "INSTANCE_HAS_PROFILE":
-      return {
-        code,
-        title: "Existing instance profile detected",
-        steps: [
-          "?リ옇????筌뤾쑬裕??怨룸츩 ?熬곣뫁夷???逾?????곕????덈펲.",
-          "??ルㅎ臾?1: ?リ옇????????筌먦끉???SSM 雅?굝??뇡???怨뺣뼺???紐껊퉵??",
-          "??ルㅎ臾?2: ???吏???€흮?우뮁紐???믨퀡由?춯?allowReplaceProfile=true ??????熬곥굥????덈펲."
-        ],
-        confirmText: "??⑤챷????꾩렮維뽬떋???筌먐삳빳???좊듆 '?熬곣뫁?????┑€?????면썒??닔???"
-      };
-    case "IAM_PROFILE_ASSOCIATION_FAILED":
-    case "IAM_PROFILE_REPLACE_FAILED":
-      return {
-        code,
-        title: "Missing IAM permission for remediation",
-        steps: [
-          "???덈뺄 ?낅슣?섊뙼??EC2 ?筌뤾쑬裕??怨룸츩 ?熬곣뫁夷???逾???⑤슡????€흮??雅?굝??뇡???遊붋€????筌뤾쑴??",
-          "?熬곣뫗??雅?굝??뇡? ec2:AssociateIamInstanceProfile, ec2:ReplaceIamInstanceProfileAssociation(??€흮????, iam:PassRole",
-          "?熬곣뫁????'?熬곣뫁?????┑€?????면썒??닔???"
-        ],
-        confirmText: "IAM 雅?굝??뇡??꾩룇瑗?????硫명뀬???좊듆 '?熬곣뫁?????┑€?????면썒??닔???"
-      };
-    case "SSM_RUNCOMMAND_PERMISSION_REQUIRED":
-      return {
-        code,
-        title: "Missing SSM RunCommand permission",
-        steps: [
-          "???덈뺄 ?낅슣?섊뙼??SSM 嶺뚮ㅏ援앲??雅?굝??뇡???遊붋€????筌뤾쑴??",
-          "?熬곣뫗??雅?굝??뇡? ssm:SendCommand, ssm:GetCommandInvocation",
-          "?熬곣뫁????'?熬곣뫁?????┑€?????면썒??닔???"
-        ],
-        confirmText: "SSM 雅?굝??뇡??꾩룇瑗?????硫명뀬???좊듆 '?熬곣뫁?????┑€?????면썒??닔???"
-      };
-    case "LAMBDA_LIST_PERMISSION_REQUIRED":
-      return {
-        code,
-        title: "Missing Lambda list permission",
-        steps: [
-          "??쎈뻬 雅뚯눘猿??Lambda 鈺곌퀬??亦낅슦釉???봔€鈺곌퉲鍮€??덈뼄.",
-          "?袁⑹뒄 亦낅슦釉? lambda:ListFunctions",
-          "亦낅슦釉?獄쏆꼷????'??袁⑥┷'??⑦€????젻雅뚯눘苑??"
-        ],
-        confirmText: "Lambda 亦낅슦釉?獄쏆꼷?????멸돌筌?'??袁⑥┷'??⑦€????젻雅뚯눘苑??"
-      };
-    case "ELBV2_LIST_PERMISSION_REQUIRED":
-      return {
-        code,
-        title: "Missing ELBv2 list permission",
-        steps: [
-          "Grant permissions to list load balancers and target groups.",
-          "Required: elasticloadbalancing:DescribeLoadBalancers and elasticloadbalancing:DescribeTargetGroups.",
-          "Retry after permission update."
-        ],
-        confirmText: "After ELBv2 permission update, reply 'completed' and retry."
-      };
-    case "ASG_LIST_PERMISSION_REQUIRED":
-      return {
-        code,
-        title: "Missing Auto Scaling list permission",
-        steps: [
-          "Grant permission to read Auto Scaling Groups.",
-          "Required: autoscaling:DescribeAutoScalingGroups.",
-          "Retry after permission update."
-        ],
-        confirmText: "After Auto Scaling permission update, reply 'completed' and retry."
-      };
-    case "RDS_LIST_PERMISSION_REQUIRED":
-      return {
-        code,
-        title: "Missing RDS list permission",
-        steps: [
-          "Grant permission to list RDS DB instances.",
-          "Required: rds:DescribeDBInstances.",
-          "Retry after permission update."
-        ],
-        confirmText: "After RDS permission update, reply 'completed' and retry."
-      };
-    case "ELASTICACHE_LIST_PERMISSION_REQUIRED":
-      return {
-        code,
-        title: "Missing ElastiCache list permission",
-        steps: [
-          "Grant permission to list ElastiCache clusters.",
-          "Required: elasticache:DescribeCacheClusters.",
-          "Retry after permission update."
-        ],
-        confirmText: "After ElastiCache permission update, reply 'completed' and retry."
-      };
-    case "ROUTE53_LIST_PERMISSION_REQUIRED":
+
+    if (!input.allowReplaceProfile) {
       return {
-        code,
-        title: "Missing Route53 list permission",
-        steps: [
-          "Grant permission to list Route53 hosted zones.",
-          "Required: route53:ListHostedZones (and route53:ListResourceRecordSets for record counts).",
-          "Retry after permission update."
-        ],
-        confirmText: "After Route53 permission update, reply 'completed' and retry."
+        ok: true,
+        requiresUserAction: true,
+        requiredAction: {
+          code: "INSTANCE_HAS_PROFILE",
+          message: `Instance ${instanceId} already has an instance profile.`,
+          hint: "Set allowReplaceProfile=true to replace existing association."
+        },
+        action: "skipped-existing-profile",
+        profile,
+        region,
+        instanceId
       };
-    default:
-      return defaultItem;
-  }
-}
-
-function buildAgentGuidance(requiredActions, toolName, args) {
-  const items = Array.isArray(requiredActions)
-    ? requiredActions.map((action) => guidanceForAction(action, args))
-    : [];
+    }
 
-  if (!items.length) {
+    const out = await client.send(new ec2.ReplaceIamInstanceProfileAssociationCommand({
+      AssociationId: active.AssociationId,
+      IamInstanceProfile: target
+    }));
     return {
-      mode: "none",
-      autoRetryRecommended: false,
-      retryTool: toolName,
-      retryArgs: args,
-      userChecklist: [],
-      assistantMessageTemplate: "상태 조회가 완료되었습니다."
+      ok: true,
+      action: "replace",
+      profile,
+      region,
+      instanceId,
+      response: {
+        associationId: out && out.IamInstanceProfileAssociation ? out.IamInstanceProfileAssociation.AssociationId : active.AssociationId
+      }
     };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error && error.message ? error.message : String(error),
+      requiredAction: mutationErrorMeta(error, profile, region)
+    };
+  } finally {
+    client.destroy();
   }
-
-  const firstItem = items[0];
-  const lines = [];
-  lines.push("AWS 상태 조회를 계속하려면 아래 조치가 필요합니다.");
-  lines.push(`1. [${firstItem.code}] ${firstItem.title}`);
-  for (let i = 0; i < firstItem.steps.length; i += 1) {
-    lines.push(`${i + 1}. ${firstItem.steps[i]}`);
-  }
-  lines.push(firstItem.confirmText);
-
-  return {
-    mode: "human_in_the_loop",
-    autoRetryRecommended: true,
-    retryTool: toolName,
-    retryArgs: args,
-    completionTrigger: "사용자가 '완료' 또는 조치 완료 의사를 전달하면 같은 입력으로 재시도",
-    userChecklist: items,
-    assistantMessageTemplate: lines.join("\n")
-  };
 }
 
-function buildToolTextResponse(payload) {
-  return truncateText(JSON.stringify(payload, null, 2), DEFAULT_JSON_TEXT_LIMIT);
+function tryParseJsonArray(text) {
+  const trimmed = String(text || "").trim();
+  if (!trimmed) {
+    return { ok: false, error: "Empty stdout" };
+  }
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (!Array.isArray(parsed)) {
+      return { ok: false, error: "CLI JSON output was not an array" };
+    }
+    return { ok: true, value: parsed };
+  } catch (error) {
+    return { ok: false, error: error && error.message ? error.message : String(error) };
+  }
+}
+
+function summarizeRecords(records) {
+  const summary = {
+    totalRecords: 0,
+    ec2Records: 0,
+    lambdaRecords: 0,
+    albRecords: 0,
+    targetGroupRecords: 0,
+    asgRecords: 0,
+    rdsRecords: 0,
+    elasticacheRecords: 0,
+    route53ZoneRecords: 0,
+    publicIpRecords: 0,
+    ssmManagedCount: 0,
+    ssmOnlineCount: 0,
+    runtimeSnapshotCount: 0,
+    runtimeSnapshotSuccessCount: 0,
+    profiles: [],
+    regions: []
+  };
+
+  const profileSet = new Set();
+  const regionSet = new Set();
+
+  for (const item of Array.isArray(records) ? records : []) {
+    summary.totalRecords += 1;
+    const resourceType = item && item.resourceType ? String(item.resourceType).toLowerCase() : null;
+    if (resourceType === "ec2") summary.ec2Records += 1;
+    if (resourceType === "lambda") summary.lambdaRecords += 1;
+    if (resourceType === "alb") summary.albRecords += 1;
+    if (resourceType === "target_group") summary.targetGroupRecords += 1;
+    if (resourceType === "asg") summary.asgRecords += 1;
+    if (resourceType === "rds") summary.rdsRecords += 1;
+    if (resourceType === "elasticache") summary.elasticacheRecords += 1;
+    if (resourceType === "route53_zone") summary.route53ZoneRecords += 1;
+    if (item && item.publicIp) summary.publicIpRecords += 1;
+    if (item && item.ssmManaged === true) summary.ssmManagedCount += 1;
+    if (item && item.ssmOnline === true) summary.ssmOnlineCount += 1;
+    if (item && item.runtimeSnapshot) {
+      summary.runtimeSnapshotCount += 1;
+      if (item.runtimeSnapshot.status === "Success") {
+        summary.runtimeSnapshotSuccessCount += 1;
+      }
+    }
+    if (item && item.profile) profileSet.add(String(item.profile));
+    if (item && item.region) regionSet.add(String(item.region));
+  }
+
+  summary.profiles = Array.from(profileSet).sort();
+  summary.regions = Array.from(regionSet).sort();
+  return summary;
+}
+
+function firstProfileArg(args) {
+  if (args && Array.isArray(args.profiles) && args.profiles.length > 0) {
+    return String(args.profiles[0]);
+  }
+  return "default";
+}
+
+function inferSsoLoginCommand(action, args) {
+  const hint = action && action.hint ? String(action.hint) : "";
+  const matched = /aws sso login --profile\s+[^\s'"]+/i.exec(hint);
+  if (matched) {
+    return matched[0];
+  }
+  return `aws sso login --profile ${firstProfileArg(args)}`;
+}
+
+function guidanceForAction(action, args) {
+  const code = action && action.code ? String(action.code) : "UNKNOWN";
+  const defaultItem = {
+    code,
+    title: "Manual action required",
+    steps: [
+      action && action.message ? action.message : "A manual action is required.",
+      action && action.hint ? action.hint : "After completing the action, reply '????썹땟?? to continue."
+    ],
+    confirmText: "??됰슦????잙?猷뉓떋? ????썹땟???????'????썹땟??????維◈€?????筌롫똻??????? ??醫딆┻?? ???됰Ŋ??????Β€?????嶺????????꾣뤃管逾??????泥??????딅젩."
+  };
+
+  switch (code) {
+    case "SSO_LOGIN_NEEDED":
+    case "SSO_REAUTH_REQUIRED": {
+      const cmd = inferSsoLoginCommand(action, args);
+      return {
+        code,
+        title: "AWS SSO login required",
+        steps: [
+          `Run: ${cmd}`,
+          "Complete browser SSO login and MFA.",
+          "Alternative: if SSO/access key cannot be used, switch to manual fallback with manualServerListPath (JSON/CSV server list + PEM)."
+        ],
+        confirmText: "After completing one path (SSO/access key or manual fallback), reply 'completed' and retry."
+      };
+    }
+    case "AWS_CREDENTIALS_REQUIRED":
+      return {
+        code,
+        title: "AWS credentials required",
+        steps: [
+          "Configure AWS auth first (SSO recommended, or access key).",
+          "SSO example: aws configure sso --profile <profile> then aws sso login --profile <profile>.",
+          "Alternative: if auth cannot be issued in this environment, switch to manual fallback with manualServerListPath (JSON/CSV server list + PEM)."
+        ],
+        confirmText: "After completing one path (auth setup or manual fallback), reply 'completed' and retry."
+      };
+    case "SET_SSM_INSTANCE_PROFILE":
+      return {
+        code,
+        title: "SSM remediation target missing",
+        steps: [
+          "???嶺???⑤슢?뽫뵓嫄붋€??ш낄??????????鈺곕〕??instance profile ??????????ARN???꿔꺂????癲ル슢怡??щ쨫????嶺뚮ㅎ????",
+          "???繹먮굞???????嚥????β뼯援η뙴????壤굿€??좊㎧ ????썹땟????嶺뚮슣堉??? --ssm-instance-profile-name ?????--ssm-instance-profile-arn",
+          "????썹땟????'????썹땟??????維◈€?????筌롫똻???????"
+        ],
+        confirmText: "????썹땟怨⒲뀋???????????쇨덫???꿔꺂????癲ル슢怡??몃춣????ル봾諭?'????썹땟??????維◈€?????筌롫똻???????"
+      };
+    case "SSM_ROLE_OR_AGENT_REQUIRED":
+      return {
+        code,
+        title: "Instance is not SSM managed",
+        steps: [
+          "?癲ル슢???吏????ㅿ폍筌??????AmazonSSMManagedInstanceCore???????嶺뚮슣堉???",
+          "SSM Agent?? ?????됱뎽????ㅼ뒩??SSM endpoint/?癲ル슢?뤸뤃????嚥▲굧???뚪뜮???醫딆쓧? ?癲ル슢캉??낆춹?癲? ?癲ル슢캉???€??嶺뚮슣堉???",
+          "????썹땟????'????썹땟??????維◈€?????筌롫똻???????"
+        ],
+        confirmText: "SSM ???援온€??????븐뻤?????됰슦????????딅젩??'????썹땟??????維◈€?????筌롫똻???????"
+      };
+    case "INSTANCE_HAS_PROFILE":
+      return {
+        code,
+        title: "Existing instance profile detected",
+        steps: [
+          "???뚯?????癲ル슢???吏????ㅿ폍筌?????썹땟怨⒲뀋????????????????딅젩.",
+          "????ｋ€??1: ???뚯?????????癲ル슢캉????SSM ???????????ㅻ쿋????嶺뚮ㅎ????",
+          "????ｋ€??2: ???嶺???????怨뺤툋嶺???沃섃뫂??먮뎨???allowReplaceProfile=true ?????????꾣뤃??????딅젩."
+        ],
+        confirmText: "????쇨덫????熬곣뫖?삥납??????癲ル슢怡??몃춣????ル봾諭?'????썹땟??????維◈€?????筌롫똻???????"
+      };
+    case "IAM_PROFILE_ASSOCIATION_FAILED":
+    case "IAM_PROFILE_REPLACE_FAILED":
+      return {
+        code,
+        title: "Missing IAM permission for remediation",
+        steps: [
+          "?????덊떀 ???녿뮝???낆뇢??EC2 ?癲ル슢???吏????ㅿ폍筌?????썹땟怨⒲뀋?????????쇰뮚???????????????????낇뀘?????癲ル슢????",
+          "????썹땟????????? ec2:AssociateIamInstanceProfile, ec2:ReplaceIamInstanceProfileAssociation(????????, iam:PassRole",
+          "????썹땟????'????썹땟??????維◈€?????筌롫똻???????"
+        ],
+        confirmText: "IAM ????????熬곣뫖利??????嶺뚮∥梨?????ル봾諭?'????썹땟??????維◈€?????筌롫똻???????"
+      };
+    case "SSM_RUNCOMMAND_PERMISSION_REQUIRED":
+      return {
+        code,
+        title: "Missing SSM RunCommand permission",
+        steps: [
+          "?????덊떀 ???녿뮝???낆뇢??SSM ?꿔꺂??琉몃쨨??????????????낇뀘?????癲ル슢????",
+          "????썹땟????????? ssm:SendCommand, ssm:GetCommandInvocation",
+          "????썹땟????'????썹땟??????維◈€?????筌롫똻???????"
+        ],
+        confirmText: "SSM ????????熬곣뫖利??????嶺뚮∥梨?????ル봾諭?'????썹땟??????維◈€?????筌롫똻???????"
+      };
+    case "LAMBDA_LIST_PERMISSION_REQUIRED":
+      return {
+        code,
+        title: "Missing Lambda list permission",
+        steps: [
+          "????덈틖 ??낆뒩??딅쇊??Lambda ?釉뚰€?????援???????딅텑??釉뚰€?轅대쑏?????덊렡.",
+          "??ш끽維????援???? lambda:ListFunctions",
+          "??援?????袁⑸즵?????'???ш끽維??????뫢€???????뜏??????"
+        ],
+        confirmText: "Lambda ??援?????袁⑸즵??????筌롫챶猷롳┼?'???ш끽維??????뫢€???????뜏??????"
+      };
+    case "ELBV2_LIST_PERMISSION_REQUIRED":
+      return {
+        code,
+        title: "Missing ELBv2 list permission",
+        steps: [
+          "Grant permissions to list load balancers and target groups.",
+          "Required: elasticloadbalancing:DescribeLoadBalancers and elasticloadbalancing:DescribeTargetGroups.",
+          "Retry after permission update."
+        ],
+        confirmText: "After ELBv2 permission update, reply 'completed' and retry."
+      };
+    case "ASG_LIST_PERMISSION_REQUIRED":
+      return {
+        code,
+        title: "Missing Auto Scaling list permission",
+        steps: [
+          "Grant permission to read Auto Scaling Groups.",
+          "Required: autoscaling:DescribeAutoScalingGroups.",
+          "Retry after permission update."
+        ],
+        confirmText: "After Auto Scaling permission update, reply 'completed' and retry."
+      };
+    case "RDS_LIST_PERMISSION_REQUIRED":
+      return {
+        code,
+        title: "Missing RDS list permission",
+        steps: [
+          "Grant permission to list RDS DB instances.",
+          "Required: rds:DescribeDBInstances.",
+          "Retry after permission update."
+        ],
+        confirmText: "After RDS permission update, reply 'completed' and retry."
+      };
+    case "ELASTICACHE_LIST_PERMISSION_REQUIRED":
+      return {
+        code,
+        title: "Missing ElastiCache list permission",
+        steps: [
+          "Grant permission to list ElastiCache clusters.",
+          "Required: elasticache:DescribeCacheClusters.",
+          "Retry after permission update."
+        ],
+        confirmText: "After ElastiCache permission update, reply 'completed' and retry."
+      };
+    case "ROUTE53_LIST_PERMISSION_REQUIRED":
+      return {
+        code,
+        title: "Missing Route53 list permission",
+        steps: [
+          "Grant permission to list Route53 hosted zones.",
+          "Required: route53:ListHostedZones (and route53:ListResourceRecordSets for record counts).",
+          "Retry after permission update."
+        ],
+        confirmText: "After Route53 permission update, reply 'completed' and retry."
+      };
+    case "MANUAL_SERVER_LIST_EMPTY":
+      return {
+        code,
+        title: "Manual server list is empty",
+        steps: [
+          "Provide at least one server row in JSON or CSV format.",
+          "Minimum fields: host/publicIp/privateIp, optional pemPath/keyName.",
+          "Retry after updating the file."
+        ],
+        confirmText: "After updating the server list file, reply 'completed' and retry."
+      };
+    case "MANUAL_SERVER_HOST_REQUIRED":
+      return {
+        code,
+        title: "Server host is required",
+        steps: [
+          "At least one of host/publicIp/privateIp/publicDns is required per server row.",
+          "Update the manual server list row(s) that are missing host info.",
+          "Retry with the same manual list path."
+        ],
+        confirmText: "After fixing host fields, reply 'completed' and retry."
+      };
+    case "PEM_KEY_NOT_FOUND":
+      return {
+        code,
+        title: "PEM key file not found",
+        steps: [
+          "Check pemPath in server rows or --pem-paths input.",
+          "Use absolute paths or valid relative paths from the working directory.",
+          "Retry after fixing key paths."
+        ],
+        confirmText: "After fixing PEM paths, reply 'completed' and retry."
+      };
+    case "PEM_MAPPING_REQUIRED":
+      return {
+        code,
+        title: "PEM mapping required",
+        steps: [
+          "Set pemPath per server row, or pass --pem-paths.",
+          "If multiple PEM files are used, include keyName per server for deterministic mapping.",
+          "Retry after mapping PEM keys."
+        ],
+        confirmText: "After PEM mapping is configured, reply 'completed' and retry."
+      };
+    case "SSH_CLIENT_NOT_FOUND":
+      return {
+        code,
+        title: "SSH client missing",
+        steps: [
+          "Install OpenSSH client on this machine.",
+          "Verify with: ssh -V",
+          "Retry after SSH is available."
+        ],
+        confirmText: "After OpenSSH is installed, reply 'completed' and retry."
+      };
+    case "SSH_AUTH_OR_CONNECT_FAILED":
+      return {
+        code,
+        title: "SSH authentication or connectivity failed",
+        steps: [
+          "Verify security group/NACL, host reachability, and target SSH port.",
+          "Check SSH user and PEM key permissions.",
+          "Retry after connectivity/auth fix."
+        ],
+        confirmText: "After fixing SSH access, reply 'completed' and retry."
+      };
+    default:
+      return defaultItem;
+  }
+}
+
+function buildAgentGuidance(requiredActions, toolName, args) {
+  const items = Array.isArray(requiredActions)
+    ? requiredActions.map((action) => guidanceForAction(action, args))
+    : [];
+
+  if (!items.length) {
+    return {
+      mode: "none",
+      autoRetryRecommended: false,
+      retryTool: toolName,
+      retryArgs: args,
+      userChecklist: [],
+      assistantMessageTemplate: "?怨밴묶 鈺곌퀬?뜹첎? ?袁⑥┷??뤿???щ빍??"
+    };
+  }
+
+  const firstItem = items[0];
+  const lines = [];
+  lines.push("AWS ?怨밴묶 鈺곌퀬?띄몴??④쑴???롮젻筌??袁⑥삋 鈺곌퀣?귛첎? ?袁⑹뒄??몃빍??");
+  lines.push(`1. [${firstItem.code}] ${firstItem.title}`);
+  for (let i = 0; i < firstItem.steps.length; i += 1) {
+    lines.push(`${i + 1}. ${firstItem.steps[i]}`);
+  }
+  lines.push(firstItem.confirmText);
+
+  return {
+    mode: "human_in_the_loop",
+    autoRetryRecommended: true,
+    retryTool: toolName,
+    retryArgs: args,
+    completionTrigger: "User replies that the required action is completed.",
+    userChecklist: items,
+    assistantMessageTemplate: lines.join("\n")
+  };
+}
+
+function buildToolTextResponse(payload) {
+  return truncateText(JSON.stringify(payload, null, 2), DEFAULT_JSON_TEXT_LIMIT);
+}
+
+function toolSchema() {
+  return {
+    profiles: z.array(z.string().min(1)).optional().describe("Optional AWS profiles."),
+    regions: z.array(z.string().min(1)).optional().describe("Optional AWS regions."),
+    instanceIds: z.array(z.string().min(1)).optional().describe("Optional EC2 instance ids."),
+    includeLambda: z.boolean().optional().describe("If true, include Lambda inventory."),
+    includeEc2: z.boolean().optional().describe("If false, skip EC2 inventory."),
+    includeAlb: z.boolean().optional().describe("If true, include ALB/NLB and target group inventory."),
+    includeAsg: z.boolean().optional().describe("If true, include Auto Scaling Group inventory."),
+    includeRds: z.boolean().optional().describe("If true, include RDS DB instance inventory."),
+    includeElastiCache: z.boolean().optional().describe("If true, include ElastiCache cluster inventory."),
+    includeRoute53: z.boolean().optional().describe("If true, include Route53 hosted zone inventory."),
+    publicOnly: z.boolean().optional().describe("If true, include only public IPv4 instances."),
+    managedOnly: z.boolean().optional().describe("If true, include only SSM-managed instances."),
+    autoRemediateSsm: z.boolean().optional().describe("If true, try attaching/replacing instance profile for unmanaged instances."),
+    ssmInstanceProfileName: z.string().min(1).optional().describe("Instance profile name used for remediation."),
+    ssmInstanceProfileArn: z.string().min(1).optional().describe("Instance profile ARN used for remediation."),
+    allowReplaceProfile: z.boolean().optional().describe("Allow replacement when instance already has a profile."),
+    remediationWaitSec: z.number().positive().optional().describe("Seconds to wait before post-remediation SSM recheck."),
+    runtimeSnapshot: z.boolean().optional().describe("Enable/disable runtime snapshot collection."),
+    snapshotTimeoutSec: z.number().positive().optional().describe("SSM command timeout in seconds."),
+    snapshotConcurrency: z.number().int().positive().optional().describe("Parallel workers for runtime snapshots."),
+    snapshotMaxKb: z.number().int().positive().optional().describe("Max runtime snapshot output size per instance in KB."),
+    manualServerListPath: z.string().min(1).optional().describe("JSON/CSV manual server list path (fallback when AWS auth is unavailable)."),
+    pemPaths: z.array(z.string().min(1)).optional().describe("Optional PEM key paths for SSH runtime snapshot in manual mode."),
+    sshUser: z.string().min(1).optional().describe("Default SSH username for manual mode (default: ec2-user)."),
+    sshPort: z.number().int().positive().optional().describe("Default SSH port for manual mode (default: 22)."),
+    sshConnectTimeoutSec: z.number().positive().optional().describe("SSH connect timeout seconds (default: 8)."),
+    htmlOutPath: z.string().min(1).optional().describe("Optional HTML GUI report output path."),
+    openHtml: z.boolean().optional().describe("If true, attempt to open the generated HTML report."),
+    autoSsoLogin: z.boolean().optional().describe("Enable/disable automatic aws sso login retry."),
+    noProgress: z.boolean().optional().describe("Suppress CLI progress logs."),
+    timeoutSec: z.number().positive().max(3600).optional().describe("Wrapper timeout for CLI process."),
+    workingDirectory: z.string().min(1).optional().describe("Optional working directory for subprocess."),
+    maxRecords: z.number().int().positive().max(10000).optional().describe("Optional max records in MCP response."),
+    includeStderr: z.boolean().optional().describe("Include stderr logs in response.")
+  };
+}
+
+function registerDiscoverTool(server, name, title, description) {
+  server.registerTool(
+    name,
+    {
+      title,
+      description,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      inputSchema: toolSchema()
+    },
+    async (args) => {
+      const startedAt = new Date().toISOString();
+      const cliResult = await runDiscoverCli(args);
+      const logInfo = parseStderr(cliResult.stderr);
+
+      if (cliResult.spawnError) {
+        return {
+          content: [{ type: "text", text: `Failed to start CLI subprocess: ${cliResult.spawnError}` }],
+          isError: true
+        };
+      }
+
+      if (cliResult.timedOut) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: buildToolTextResponse({
+                ok: false,
+                error: "CLI process timed out",
+                startedAt,
+                timeoutSec: typeof args.timeoutSec === "number" ? args.timeoutSec : DEFAULT_TIMEOUT_SEC,
+                exitCode: cliResult.exitCode,
+                signal: cliResult.signal,
+                stderr: truncateText(cliResult.stderr)
+              })
+            }
+          ],
+          isError: true
+        };
+      }
+
+      const parsed = tryParseJsonArray(cliResult.stdout);
+      if (!parsed.ok) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: buildToolTextResponse({
+                ok: false,
+                error: "Failed to parse CLI JSON output",
+                parseError: parsed.error,
+                exitCode: cliResult.exitCode,
+                signal: cliResult.signal,
+                stderr: truncateText(cliResult.stderr),
+                stdout: truncateText(cliResult.stdout)
+              })
+            }
+          ],
+          isError: true
+        };
+      }
+
+      const allRecords = parsed.value;
+      const maxRecords =
+        typeof args.maxRecords === "number" && Number.isFinite(args.maxRecords)
+          ? args.maxRecords
+          : null;
+      const records = maxRecords && allRecords.length > maxRecords ? allRecords.slice(0, maxRecords) : allRecords;
+
+      const acceptedExitCodes = new Set([0, 2, 3]);
+      const requiresUserAction = logInfo.requiredActions.length > 0 || cliResult.exitCode === 3;
+      const guidance = buildAgentGuidance(logInfo.requiredActions, name, args);
+
+      const response = {
+        ok: acceptedExitCodes.has(cliResult.exitCode),
+        startedAt,
+        finishedAt: new Date().toISOString(),
+        exitCode: cliResult.exitCode,
+        signal: cliResult.signal,
+        requiresUserAction,
+        requiredActions: logInfo.requiredActions,
+        guidance,
+        summary: {
+          ...summarizeRecords(allRecords),
+          returnedRecords: records.length,
+          truncated: records.length !== allRecords.length,
+          warningCount: logInfo.warnings.length,
+          summaryLine: logInfo.summaryLine
+        },
+        records
+      };
+
+      if (args.includeStderr) {
+        response.stderr = truncateText(cliResult.stderr);
+      }
+
+      if (!acceptedExitCodes.has(cliResult.exitCode)) {
+        return {
+          content: [{ type: "text", text: buildToolTextResponse({ ...response, ok: false, stderr: truncateText(cliResult.stderr) }) }],
+          isError: true
+        };
+      }
+
+      return {
+        content: [{ type: "text", text: buildToolTextResponse(response) }],
+        isError: false
+      };
+    }
+  );
 }
 
-function toolSchema() {
+function ec2ActionSchema(extra = {}) {
   return {
-    profiles: z.array(z.string().min(1)).optional().describe("Optional AWS profiles."),
-    regions: z.array(z.string().min(1)).optional().describe("Optional AWS regions."),
-    instanceIds: z.array(z.string().min(1)).optional().describe("Optional EC2 instance ids."),
-    includeLambda: z.boolean().optional().describe("If true, include Lambda inventory."),
-    includeEc2: z.boolean().optional().describe("If false, skip EC2 inventory."),
-    includeAlb: z.boolean().optional().describe("If true, include ALB/NLB and target group inventory."),
-    includeAsg: z.boolean().optional().describe("If true, include Auto Scaling Group inventory."),
-    includeRds: z.boolean().optional().describe("If true, include RDS DB instance inventory."),
-    includeElastiCache: z.boolean().optional().describe("If true, include ElastiCache cluster inventory."),
-    includeRoute53: z.boolean().optional().describe("If true, include Route53 hosted zone inventory."),
-    publicOnly: z.boolean().optional().describe("If true, include only public IPv4 instances."),
-    managedOnly: z.boolean().optional().describe("If true, include only SSM-managed instances."),
-    autoRemediateSsm: z.boolean().optional().describe("If true, try attaching/replacing instance profile for unmanaged instances."),
-    ssmInstanceProfileName: z.string().min(1).optional().describe("Instance profile name used for remediation."),
-    ssmInstanceProfileArn: z.string().min(1).optional().describe("Instance profile ARN used for remediation."),
-    allowReplaceProfile: z.boolean().optional().describe("Allow replacement when instance already has a profile."),
-    remediationWaitSec: z.number().positive().optional().describe("Seconds to wait before post-remediation SSM recheck."),
-    runtimeSnapshot: z.boolean().optional().describe("Enable/disable runtime snapshot collection."),
-    snapshotTimeoutSec: z.number().positive().optional().describe("SSM command timeout in seconds."),
-    snapshotConcurrency: z.number().int().positive().optional().describe("Parallel workers for runtime snapshots."),
-    snapshotMaxKb: z.number().int().positive().optional().describe("Max runtime snapshot output size per instance in KB."),
-    autoSsoLogin: z.boolean().optional().describe("Enable/disable automatic aws sso login retry."),
-    noProgress: z.boolean().optional().describe("Suppress CLI progress logs."),
-    timeoutSec: z.number().positive().max(3600).optional().describe("Wrapper timeout for CLI process."),
-    workingDirectory: z.string().min(1).optional().describe("Optional working directory for subprocess."),
-    maxRecords: z.number().int().positive().max(10000).optional().describe("Optional max records in MCP response."),
-    includeStderr: z.boolean().optional().describe("Include stderr logs in response.")
+    profile: z.string().min(1).optional().describe("AWS profile name (default: default)."),
+    region: z.string().min(1).describe("AWS region, e.g. ap-southeast-1."),
+    instanceIds: z.array(z.string().min(1)).min(1).describe("Target EC2 instance ids."),
+    dryRun: z.boolean().optional().describe("If true, AWS DryRun is used where supported."),
+    ...extra
   };
 }
 
-function registerDiscoverTool(server, name, title, description) {
+function registerEc2MutationTool(server, name, title, description, action, schema = ec2ActionSchema()) {
   server.registerTool(
     name,
     {
       title,
       description,
       annotations: {
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
         openWorldHint: true
       },
-      inputSchema: toolSchema()
+      inputSchema: schema
     },
     async (args) => {
       const startedAt = new Date().toISOString();
-      const cliResult = await runDiscoverCli(args);
-      const logInfo = parseStderr(cliResult.stderr);
-
-      if (cliResult.spawnError) {
-        return {
-          content: [{ type: "text", text: `Failed to start CLI subprocess: ${cliResult.spawnError}` }],
-          isError: true
+      const result = await runEc2InstanceAction(args, action);
+      if (!result.ok) {
+        const payload = {
+          ok: false,
+          action,
+          startedAt,
+          finishedAt: new Date().toISOString(),
+          error: result.error,
+          requiredActions: result.requiredAction ? [result.requiredAction] : []
         };
-      }
-
-      if (cliResult.timedOut) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: buildToolTextResponse({
-                ok: false,
-                error: "CLI process timed out",
-                startedAt,
-                timeoutSec: typeof args.timeoutSec === "number" ? args.timeoutSec : DEFAULT_TIMEOUT_SEC,
-                exitCode: cliResult.exitCode,
-                signal: cliResult.signal,
-                stderr: truncateText(cliResult.stderr)
-              })
-            }
-          ],
-          isError: true
-        };
-      }
-
-      const parsed = tryParseJsonArray(cliResult.stdout);
-      if (!parsed.ok) {
         return {
-          content: [
-            {
-              type: "text",
-              text: buildToolTextResponse({
-                ok: false,
-                error: "Failed to parse CLI JSON output",
-                parseError: parsed.error,
-                exitCode: cliResult.exitCode,
-                signal: cliResult.signal,
-                stderr: truncateText(cliResult.stderr),
-                stdout: truncateText(cliResult.stdout)
-              })
-            }
-          ],
+          content: [{ type: "text", text: buildToolTextResponse(payload) }],
           isError: true
         };
       }
-
-      const allRecords = parsed.value;
-      const maxRecords =
-        typeof args.maxRecords === "number" && Number.isFinite(args.maxRecords)
-          ? args.maxRecords
-          : null;
-      const records = maxRecords && allRecords.length > maxRecords ? allRecords.slice(0, maxRecords) : allRecords;
-
-      const acceptedExitCodes = new Set([0, 2, 3]);
-      const requiresUserAction = logInfo.requiredActions.length > 0 || cliResult.exitCode === 3;
-      const guidance = buildAgentGuidance(logInfo.requiredActions, name, args);
-
-      const response = {
-        ok: acceptedExitCodes.has(cliResult.exitCode),
-        startedAt,
-        finishedAt: new Date().toISOString(),
-        exitCode: cliResult.exitCode,
-        signal: cliResult.signal,
-        requiresUserAction,
-        requiredActions: logInfo.requiredActions,
-        guidance,
-        summary: {
-          ...summarizeRecords(allRecords),
-          returnedRecords: records.length,
-          truncated: records.length !== allRecords.length,
-          warningCount: logInfo.warnings.length,
-          summaryLine: logInfo.summaryLine
-        },
-        records
+      return {
+        content: [{
+          type: "text",
+          text: buildToolTextResponse({
+            ok: true,
+            action,
+            startedAt,
+            finishedAt: new Date().toISOString(),
+            ...result
+          })
+        }],
+        isError: false
       };
+    }
+  );
+}
 
-      if (args.includeStderr) {
-        response.stderr = truncateText(cliResult.stderr);
+function registerEc2ProfileTool(server) {
+  server.registerTool(
+    "ec2_apply_instance_profile",
+    {
+      title: "Apply EC2 IAM Instance Profile",
+      description: "Associates or replaces IAM instance profile on one EC2 instance.",
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true
+      },
+      inputSchema: {
+        profile: z.string().min(1).optional().describe("AWS profile name (default: default)."),
+        region: z.string().min(1).describe("AWS region, e.g. ap-southeast-1."),
+        instanceId: z.string().min(1).describe("Target EC2 instance id."),
+        instanceProfileName: z.string().min(1).optional().describe("Target instance profile name."),
+        instanceProfileArn: z.string().min(1).optional().describe("Target instance profile ARN."),
+        allowReplaceProfile: z.boolean().optional().describe("If true, existing association can be replaced.")
       }
-
-      if (!acceptedExitCodes.has(cliResult.exitCode)) {
+    },
+    async (args) => {
+      const startedAt = new Date().toISOString();
+      const result = await applyInstanceProfile(args);
+      if (!result.ok) {
+        const payload = {
+          ok: false,
+          action: "ec2_apply_instance_profile",
+          startedAt,
+          finishedAt: new Date().toISOString(),
+          error: result.error,
+          requiredActions: result.requiredAction ? [result.requiredAction] : []
+        };
         return {
-          content: [{ type: "text", text: buildToolTextResponse({ ...response, ok: false, stderr: truncateText(cliResult.stderr) }) }],
+          content: [{ type: "text", text: buildToolTextResponse(payload) }],
           isError: true
         };
       }
-
       return {
-        content: [{ type: "text", text: buildToolTextResponse(response) }],
+        content: [{
+          type: "text",
+          text: buildToolTextResponse({
+            ok: true,
+            action: "ec2_apply_instance_profile",
+            startedAt,
+            finishedAt: new Date().toISOString(),
+            ...result
+          })
+        }],
         isError: false
       };
     }
   );
-}
+}
 
 async function registerTools(server) {
   registerDiscoverTool(
     server,
     "discover_ec2_with_ssm",
-    "Discover AWS Inventory (multi-service + SSM runtime)",
-    "Runs mcp-aws-manager and returns inventory across EC2/Lambda/ALB/ASG/RDS/ElastiCache/Route53 with optional SSM runtime snapshots."
+    "Discover AWS Inventory (multi-service + SSM runtime)",
+    "Runs mcp-aws-manager and returns inventory across EC2/Lambda/ALB/ASG/RDS/ElastiCache/Route53 with optional runtime snapshots (SSM or manual-server-list + PEM SSH)."
   );
 
-  server.registerTool(
-    "mcp_aws_discover_cli_help",
-    {
-      title: "Show CLI Help",
-      description: "Returns the local mcp-aws-manager CLI usage text.",
-      annotations: {
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: false
-      }
-    },
-    async () => {
-      const child = await new Promise((resolve) => {
-        const proc = spawn(process.execPath, [CLI_SCRIPT_PATH, "--help"], {
-          cwd: process.cwd(),
-          env: process.env,
-          stdio: ["ignore", "pipe", "pipe"]
-        });
-
-        let stdout = "";
-        let stderr = "";
-        if (proc.stdout) {
-          proc.stdout.setEncoding("utf8");
-          proc.stdout.on("data", (c) => { stdout += c; });
-        }
-        if (proc.stderr) {
-          proc.stderr.setEncoding("utf8");
-          proc.stderr.on("data", (c) => { stderr += c; });
-        }
-
-        proc.on("close", (code, signal) => {
-          resolve({ code: code == null ? null : code, signal, stdout, stderr });
-        });
-        proc.on("error", (error) => {
-          resolve({ code: null, signal: null, stdout, stderr: String(error && error.message ? error.message : error) });
-        });
-      });
-
-      const payload = {
-        ok: child.code === 0,
-        exitCode: child.code,
-        signal: child.signal || null,
-        stdout: truncateText(child.stdout, DEFAULT_JSON_TEXT_LIMIT),
-        stderr: truncateText(child.stderr)
-      };
-
-      return {
-        content: [{ type: "text", text: buildToolTextResponse(payload) }],
-        isError: child.code !== 0
-      };
-    }
+  registerEc2MutationTool(
+    server,
+    "ec2_start_instances",
+    "Start EC2 Instances",
+    "Starts EC2 instances in a region.",
+    "start"
   );
-}
-
-async function main() {
-  if (shouldShowHelp(process.argv.slice(2))) {
-    process.stdout.write(usageText());
-    return;
-  }
 
-  const server = new McpServer({
-    name: "mcp-aws-manager",
-    version: pkg.version
-  });
+  registerEc2MutationTool(
+    server,
+    "ec2_stop_instances",
+    "Stop EC2 Instances",
+    "Stops EC2 instances in a region (supports force).",
+    "stop",
+    ec2ActionSchema({
+      force: z.boolean().optional().describe("If true, force stop is requested.")
+    })
+  );
 
-  await registerTools(server);
+  registerEc2MutationTool(
+    server,
+    "ec2_reboot_instances",
+    "Reboot EC2 Instances",
+    "Reboots EC2 instances in a region.",
+    "reboot"
+  );
 
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-}
+  registerEc2ProfileTool(server);
 
-main().catch((error) => {
-  const message = error && error.stack ? error.stack : String(error);
-  process.stderr.write(`mcp-aws-manager-mcp startup error: ${message}\n`);
-  process.exitCode = 1;
+  server.registerTool(
+    "mcp_aws_discover_cli_help",
+    {
+      title: "Show CLI Help",
+      description: "Returns the local mcp-aws-manager CLI usage text.",
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async () => {
+      const child = await new Promise((resolve) => {
+        const proc = spawn(process.execPath, [CLI_SCRIPT_PATH, "--help"], {
+          cwd: process.cwd(),
+          env: process.env,
+          stdio: ["ignore", "pipe", "pipe"]
+        });
+
+        let stdout = "";
+        let stderr = "";
+        if (proc.stdout) {
+          proc.stdout.setEncoding("utf8");
+          proc.stdout.on("data", (c) => { stdout += c; });
+        }
+        if (proc.stderr) {
+          proc.stderr.setEncoding("utf8");
+          proc.stderr.on("data", (c) => { stderr += c; });
+        }
+
+        proc.on("close", (code, signal) => {
+          resolve({ code: code == null ? null : code, signal, stdout, stderr });
+        });
+        proc.on("error", (error) => {
+          resolve({ code: null, signal: null, stdout, stderr: String(error && error.message ? error.message : error) });
+        });
+      });
+
+      const payload = {
+        ok: child.code === 0,
+        exitCode: child.code,
+        signal: child.signal || null,
+        stdout: truncateText(child.stdout, DEFAULT_JSON_TEXT_LIMIT),
+        stderr: truncateText(child.stderr)
+      };
+
+      return {
+        content: [{ type: "text", text: buildToolTextResponse(payload) }],
+        isError: child.code !== 0
+      };
+    }
+  );
+}
+
+async function main() {
+  if (shouldShowHelp(process.argv.slice(2))) {
+    process.stdout.write(usageText());
+    return;
+  }
+
+  const server = new McpServer({
+    name: "mcp-aws-manager",
+    version: pkg.version
+  });
+
+  await registerTools(server);
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((error) => {
+  const message = error && error.stack ? error.stack : String(error);
+  process.stderr.write(`mcp-aws-manager-mcp startup error: ${message}\n`);
+  process.exitCode = 1;
 });