mcp-aws-manager 0.1.0 → 0.2.0

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

@@ -20,17 +20,15 @@ function usageText() {
   return [
     "mcp-aws-manager-mcp",
     "",
-    "MCP stdio wrapper for the mcp-aws-manager CLI.",
-    "Starts an MCP server that exposes a discover tool for AI clients.",
+    "MCP stdio wrapper for the mcp-aws-manager CLI (SSM-only).",
     "",
     "Usage:",
     "  mcp-aws-manager-mcp",
     "  mcp-aws-manager-mcp --help",
     "",
     "Notes:",
-    "  - This process is an MCP stdio server. Do not run it interactively unless your client",
-    "    speaks MCP over stdio (Claude Desktop, Cursor, Cline, etc.).",
-    "  - The discover tool mirrors the CLI PEM resolution rules (arg/env/cwd auto-discovery).",
+    "  - This process is an MCP stdio server.",
+    "  - Exposes SSM inventory/runtime snapshot discovery tools.",
     ""
   ].join("\n");
 }
@@ -40,17 +38,13 @@ function shouldShowHelp(argv) {
 }
 
 function toCsvArg(values) {
-  if (!Array.isArray(values) || !values.length) {
-    return null;
-  }
+  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;
-  }
+  if (text.length <= maxLength) return text;
   const suffix = `\n... [truncated ${text.length - maxLength} chars]`;
   return text.slice(0, maxLength) + suffix;
 }
@@ -61,60 +55,70 @@ function parseStderr(stderrText) {
     .map((line) => line.trim())
     .filter(Boolean);
 
-  const warnings = lines.filter((line) => line.startsWith("WARNING: "));
-  const summaryLine = lines.find((line) => line.startsWith("Summary: ")) || null;
+  const warnings = [];
+  const requiredActions = [];
+  let summaryLine = null;
 
-  return {
-    lines,
-    warnings,
-    summaryLine
-  };
+  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 pemPaths = toCsvArg(input.pemPaths);
-  if (pemPaths) {
-    args.push("--pem-path", pemPaths);
-  } else if (input.pemPath) {
-    args.push("--pem-path", input.pemPath);
-  }
-
   const profiles = toCsvArg(input.profiles);
-  if (profiles) {
-    args.push("--profiles", profiles);
-  }
+  if (profiles) args.push("--profiles", profiles);
 
   const regions = toCsvArg(input.regions);
-  if (regions) {
-    args.push("--regions", regions);
-  }
+  if (regions) args.push("--regions", regions);
 
-  if (input.keyName) {
-    args.push("--key-name", input.keyName);
-  }
+  const instanceIds = toCsvArg(input.instanceIds);
+  if (instanceIds) args.push("--instance-ids", instanceIds);
 
-  if (input.sshCheck) {
-    args.push("--ssh-check");
-  }
+  if (input.publicOnly) args.push("--public-only");
+  if (input.managedOnly) args.push("--managed-only");
 
-  const sshUsernames = toCsvArg(input.sshUsernames);
-  if (sshUsernames) {
-    args.push("--ssh-usernames", sshUsernames);
-  }
+  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.sshTimeoutSec != null) {
-    args.push("--ssh-timeout", String(input.sshTimeoutSec));
-  }
+  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.matchedOnly) {
-    args.push("--matched-only");
-  }
+  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");
-  }
+  if (input.noProgress !== false) args.push("--no-progress");
 
   return args;
 }
@@ -144,7 +148,6 @@ function runDiscoverCli(input) {
         stdout += chunk;
       });
     }
-
     if (child.stderr) {
       child.stderr.setEncoding("utf8");
       child.stderr.on("data", (chunk) => {
@@ -153,18 +156,12 @@ function runDiscoverCli(input) {
     }
 
     const timer = setTimeout(() => {
-      if (exited) {
-        return;
-      }
+      if (exited) return;
       timedOut = true;
-      try {
-        child.kill("SIGTERM");
-      } catch {}
+      try { child.kill("SIGTERM"); } catch {}
       setTimeout(() => {
         if (!exited) {
-          try {
-            child.kill("SIGKILL");
-          } catch {}
+          try { child.kill("SIGKILL"); } catch {}
         }
       }, 3000).unref();
     }, timeoutMs);
@@ -198,7 +195,7 @@ function runDiscoverCli(input) {
       });
     });
   });
-}
+}
 
 function tryParseJsonArray(text) {
   const trimmed = String(text || "").trim();
@@ -212,140 +209,87 @@ function tryParseJsonArray(text) {
     }
     return { ok: true, value: parsed };
   } catch (error) {
-    return {
-      ok: false,
-      error: error && error.message ? error.message : String(error)
-    };
+    return { ok: false, error: error && error.message ? error.message : String(error) };
   }
 }
 
 function summarizeRecords(records) {
   const summary = {
-    totalRecords: Array.isArray(records) ? records.length : 0,
-    matchedCount: 0,
-    sshCheckedCount: 0,
-    sshReachableCount: 0,
+    totalRecords: 0,
+    publicIpRecords: 0,
+    ssmManagedCount: 0,
+    ssmOnlineCount: 0,
+    runtimeSnapshotCount: 0,
+    runtimeSnapshotSuccessCount: 0,
     profiles: [],
     regions: []
   };
 
-  const profiles = new Set();
-  const regions = new Set();
+  const profileSet = new Set();
+  const regionSet = new Set();
 
   for (const item of Array.isArray(records) ? records : []) {
-    if (item && item.keyFingerprintMatch === true) {
-      summary.matchedCount += 1;
-    }
-    if (item && item.sshReachable !== null && item.sshReachable !== undefined) {
-      summary.sshCheckedCount += 1;
-    }
-    if (item && item.sshReachable === true) {
-      summary.sshReachableCount += 1;
-    }
-    if (item && item.profile) {
-      profiles.add(String(item.profile));
-    }
-    if (item && item.region) {
-      regions.add(String(item.region));
+    summary.totalRecords += 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(profiles).sort();
-  summary.regions = Array.from(regions).sort();
+  summary.profiles = Array.from(profileSet).sort();
+  summary.regions = Array.from(regionSet).sort();
   return summary;
 }
 
 function buildToolTextResponse(payload) {
-  const text = JSON.stringify(payload, null, 2);
-  return truncateText(text, DEFAULT_JSON_TEXT_LIMIT);
+  return truncateText(JSON.stringify(payload, null, 2), DEFAULT_JSON_TEXT_LIMIT);
 }
 
-async function registerTools(server) {
+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."),
+    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.")
+  };
+}
+
+function registerDiscoverTool(server, name, title, description) {
   server.registerTool(
-    "discover_public_ec2_with_pem",
+    name,
     {
-      title: "Discover EC2 Public IP Inventory (PEM-based)",
-      description:
-        "Runs the local mcp-aws-manager CLI and returns EC2 instances with public IPv4 addresses, including PEM fingerprint matching and optional SSH reachability checks.",
+      title,
+      description,
       annotations: {
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
         openWorldHint: true
       },
-      inputSchema: {
-        pemPaths: z
-          .array(z.string().min(1))
-          .optional()
-          .describe(
-            "Optional list of local PEM private key file paths. Preferred when multiple keys should be used."
-          ),
-        pemPath: z
-          .string()
-          .min(1)
-          .optional()
-          .describe(
-            "Optional single PEM path. Ignored when pemPaths is provided. If omitted, CLI auto-discovers .pem files in workingDirectory/current directory."
-          ),
-        profiles: z
-          .array(z.string().min(1))
-          .optional()
-          .describe("Optional AWS profile names to scan."),
-        regions: z
-          .array(z.string().min(1))
-          .optional()
-          .describe("Optional AWS regions to scan."),
-        keyName: z
-          .string()
-          .min(1)
-          .optional()
-          .describe("Optional EC2 KeyPair name fallback for matching."),
-        sshCheck: z
-          .boolean()
-          .optional()
-          .describe("If true, attempt SSH authentication checks."),
-        sshUsernames: z
-          .array(z.string().min(1))
-          .optional()
-          .describe("Optional SSH usernames to try when sshCheck=true."),
-        sshTimeoutSec: z
-          .number()
-          .positive()
-          .optional()
-          .describe("SSH timeout in seconds."),
-        matchedOnly: z
-          .boolean()
-          .optional()
-          .describe("If true, return only records matched to the PEM."),
-        noProgress: z
-          .boolean()
-          .optional()
-          .describe("Suppress CLI step progress logs (defaults to true in the MCP wrapper)."),
-        timeoutSec: z
-          .number()
-          .positive()
-          .max(3600)
-          .optional()
-          .describe("Wrapper timeout for the CLI process (default 300s)."),
-        workingDirectory: z
-          .string()
-          .min(1)
-          .optional()
-          .describe(
-            "Optional working directory. Used for relative PEM path resolution and auto .pem discovery when pemPath/pemPaths are omitted."
-          ),
-        maxRecords: z
-          .number()
-          .int()
-          .positive()
-          .max(10000)
-          .optional()
-          .describe("Optional max number of records to include in the MCP response."),
-        includeStderr: z
-          .boolean()
-          .optional()
-          .describe("If true, include CLI stderr logs in the response (truncated).")
-      }
+      inputSchema: toolSchema()
     },
     async (args) => {
       const startedAt = new Date().toISOString();
@@ -354,12 +298,7 @@ async function registerTools(server) {
 
       if (cliResult.spawnError) {
         return {
-          content: [
-            {
-              type: "text",
-              text: `Failed to start CLI subprocess: ${cliResult.spawnError}`
-            }
-          ],
+          content: [{ type: "text", text: `Failed to start CLI subprocess: ${cliResult.spawnError}` }],
           isError: true
         };
       }
@@ -373,8 +312,7 @@ async function registerTools(server) {
                 ok: false,
                 error: "CLI process timed out",
                 startedAt,
-                timeoutSec:
-                  typeof args.timeoutSec === "number" ? args.timeoutSec : DEFAULT_TIMEOUT_SEC,
+                timeoutSec: typeof args.timeoutSec === "number" ? args.timeoutSec : DEFAULT_TIMEOUT_SEC,
                 exitCode: cliResult.exitCode,
                 signal: cliResult.signal,
                 stderr: truncateText(cliResult.stderr)
@@ -411,17 +349,19 @@ async function registerTools(server) {
         typeof args.maxRecords === "number" && Number.isFinite(args.maxRecords)
           ? args.maxRecords
           : null;
-      const records =
-        maxRecords && allRecords.length > maxRecords
-          ? allRecords.slice(0, maxRecords)
-          : allRecords;
+      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 response = {
-        ok: cliResult.exitCode === 0 || cliResult.exitCode === 2,
+        ok: acceptedExitCodes.has(cliResult.exitCode),
         startedAt,
         finishedAt: new Date().toISOString(),
         exitCode: cliResult.exitCode,
         signal: cliResult.signal,
+        requiresUserAction,
+        requiredActions: logInfo.requiredActions,
         summary: {
           ...summarizeRecords(allRecords),
           returnedRecords: records.length,
@@ -436,39 +376,41 @@ async function registerTools(server) {
         response.stderr = truncateText(cliResult.stderr);
       }
 
-      if (cliResult.exitCode !== 0 && cliResult.exitCode !== 2) {
+      if (!acceptedExitCodes.has(cliResult.exitCode)) {
         return {
-          content: [
-            {
-              type: "text",
-              text: buildToolTextResponse({
-                ...response,
-                ok: false,
-                stderr: truncateText(cliResult.stderr)
-              })
-            }
-          ],
+          content: [{ type: "text", text: buildToolTextResponse({ ...response, ok: false, stderr: truncateText(cliResult.stderr) }) }],
           isError: true
         };
       }
 
       return {
-        content: [
-          {
-            type: "text",
-            text: buildToolTextResponse(response)
-          }
-        ]
+        content: [{ type: "text", text: buildToolTextResponse(response) }],
+        isError: false
       };
     }
   );
+}
+
+async function registerTools(server) {
+  registerDiscoverTool(
+    server,
+    "discover_ec2_with_ssm",
+    "Discover EC2 + SSM Inventory",
+    "Runs mcp-aws-manager in SSM-only mode and returns EC2 inventory with SSM management/online status and optional runtime snapshots."
+  );
+
+  registerDiscoverTool(
+    server,
+    "discover_public_ec2_with_pem",
+    "Discover EC2 + SSM Inventory (compat alias)",
+    "Compatibility alias. Internally runs the same SSM-only discovery flow."
+  );
 
   server.registerTool(
     "mcp_aws_discover_cli_help",
     {
       title: "Show CLI Help",
-      description:
-        "Returns the local mcp-aws-manager CLI usage text for reference inside AI clients.",
+      description: "Returns the local mcp-aws-manager CLI usage text.",
       annotations: {
         readOnlyHint: true,
         destructiveHint: false,
@@ -483,30 +425,27 @@ async function registerTools(server) {
           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));
+          proc.stdout.on("data", (c) => { stdout += c; });
         }
         if (proc.stderr) {
           proc.stderr.setEncoding("utf8");
-          proc.stderr.on("data", (c) => (stderr += c));
+          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)
-          })
-        );
+
+        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 result = {
+      const payload = {
         ok: child.code === 0,
         exitCode: child.code,
         signal: child.signal || null,
@@ -515,12 +454,7 @@ async function registerTools(server) {
       };
 
       return {
-        content: [
-          {
-            type: "text",
-            text: buildToolTextResponse(result)
-          }
-        ],
+        content: [{ type: "text", text: buildToolTextResponse(payload) }],
         isError: child.code !== 0
       };
     }
@@ -539,6 +473,7 @@ async function main() {
   });
 
   await registerTools(server);
+
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }
@@ -547,4 +482,4 @@ 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;
-});
+});