mcp-aws-manager 0.2.0 → 0.3.0

package/MCP_CLIENT_SETUP.md

@@ -1,4 +1,4 @@
-# MCP Client Setup (stdio)
+# MCP Client Setup (stdio)
 
 This project provides an MCP stdio wrapper around the SSM-only CLI.
 
@@ -12,7 +12,38 @@ Exposed MCP tools:
 - `discover_public_ec2_with_pem` (compatibility alias, same behavior)
 - `mcp_aws_discover_cli_help`
 
-## 1) Local Repo (development)
+## Recommended (Install Once)
+
+```bash
+npm install -g mcp-aws-manager
+mcp-aws-manager
+```
+
+`mcp-aws-manager` (no args) runs bootstrap and registers the MCP server for detected clients (`codex`, `claude`).
+
+Verification:
+
+```bash
+mcp-aws-manager doctor
+```
+
+## Explicit Registration
+
+```bash
+mcp-aws-manager setup
+```
+
+Custom name/command:
+
+```bash
+mcp-aws-manager setup --name mcp-aws-manager --mcp-command mcp-aws-manager-mcp --clients codex,claude
+```
+
+## Manual Configuration (Fallback)
+
+Use only when automatic registration is unavailable in your environment.
+
+### 1) Local Repo (development)
 
 ```json
 {
@@ -28,11 +59,7 @@ Exposed MCP tools:
 }
 ```
 
-## 2) Global npm Install
-
-```bash
-npm install -g mcp-aws-manager
-```
+### 2) Global npm Install
 
 ```json
 {
@@ -44,7 +71,7 @@ npm install -g mcp-aws-manager
 }
 ```
 
-## 3) npx (no global install)
+### 3) npx (no global install)
 
 ```json
 {
@@ -67,4 +94,4 @@ npm install -g mcp-aws-manager
 - Discovery is SSM-only; PEM path arguments are no longer required.
 - Keep AWS credentials/profiles available on the host running MCP.
 - When `requiresUserAction=true` is returned, surface `requiredActions` to the user and retry after intervention.
-- For auto remediation, pass `autoRemediateSsm` and an instance profile name/arn.
+- For auto remediation, pass `autoRemediateSsm` and an instance profile name/arn.

package/README.md

@@ -1,4 +1,4 @@
-# mcp-aws-manager
+# mcp-aws-manager
 
 AWS operations CLI and MCP server package (SSM-only mode).
 
@@ -15,6 +15,7 @@ Current implementation focuses on:
 - Optional SSM auto-remediation (instance profile association)
 - Human-in-the-loop guidance via `ACTION_REQUIRED` messages
 - JSON/CSV output (CLI)
+- Codex/Claude MCP registration bootstrap helpers
 
 ## Install
 
@@ -22,6 +23,16 @@ Current implementation focuses on:
 npm install -g mcp-aws-manager
 ```
 
+## One-Time Bootstrap (Recommended)
+
+After install, run once:
+
+```bash
+mcp-aws-manager
+```
+
+This ensures `mcp-aws-manager` is registered in detected clients (`codex`, `claude`).
+
 ## Prerequisites
 
 - Node.js `>=18`
@@ -31,28 +42,36 @@ npm install -g mcp-aws-manager
 
 ## Quick Start
 
+Bootstrap / setup / doctor:
+
+```bash
+mcp-aws-manager                     # bootstrap (default command)
+mcp-aws-manager setup              # register/re-register MCP server
+mcp-aws-manager doctor             # verify install + registration
+```
+
 Basic discovery:
 
 ```bash
-mcp-aws-manager --profiles default
+mcp-aws-manager discover --profiles default
 ```
 
 Only public IP instances:
 
 ```bash
-mcp-aws-manager --profiles default --public-only
+mcp-aws-manager discover --profiles default --public-only
 ```
 
 Collect runtime snapshots:
 
 ```bash
-mcp-aws-manager --profiles default --runtime-snapshot
+mcp-aws-manager discover --profiles default --runtime-snapshot
 ```
 
 Try automatic remediation for unmanaged instances:
 
 ```bash
-mcp-aws-manager \
+mcp-aws-manager discover \
   --profiles default \
   --auto-remediate-ssm \
   --ssm-instance-profile-name MySsmInstanceProfile
@@ -61,9 +80,14 @@ mcp-aws-manager \
 Output CSV file:
 
 ```bash
-mcp-aws-manager --profiles default --format csv --out ./inventory.csv
+mcp-aws-manager discover --profiles default --format csv --out ./inventory.csv
 ```
 
+Compatibility note:
+
+- Legacy invocation without subcommand still works for discovery when options are passed.
+- Example: `mcp-aws-manager --profiles default --public-only`
+
 ## MCP (LLM Tool) Usage
 
 Run as an MCP stdio server:
@@ -111,4 +135,4 @@ The MCP wrapper surfaces these in a structured `requiredActions` list.
 These legacy commands are still available:
 
 - `mcp-aws-discover`
-- `mcp-aws-discover-mcp`
+- `mcp-aws-discover-mcp`

package/bin/mcp-aws-manager.js

@@ -4,11 +4,14 @@
 const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
-const { spawn } = require("node:child_process");
+const { spawn, spawnSync } = require("node:child_process");
 
 const TOTAL_STEPS = 9;
 const DEFAULT_SNAPSHOT_CONCURRENCY = 3;
 const MAX_SSM_FILTER_IDS = 50;
+const DEFAULT_SERVER_NAME = "mcp-aws-manager";
+const DEFAULT_MCP_COMMAND = "mcp-aws-manager-mcp";
+const SUPPORTED_CLIENTS = new Set(["codex", "claude"]);
 
 function eprint(msg) {
   process.stderr.write(String(msg) + "\n");
@@ -63,11 +66,30 @@ function expandHome(input) {
 
 function usageText() {
   return [
-    "Usage: mcp-aws-manager [options]",
+    "Usage:",
+    "  mcp-aws-manager",
+    "  mcp-aws-manager bootstrap [options]",
+    "  mcp-aws-manager setup [options]",
+    "  mcp-aws-manager doctor [options]",
+    "  mcp-aws-manager discover [discover-options]",
+    "  mcp-aws-manager [discover-options]",
     "",
-    "SSM-only AWS EC2 inventory and runtime snapshot collector.",
+    "SSM-only AWS EC2 inventory/runtime collector plus MCP client setup helper.",
     "",
-    "Options:",
+    "Commands:",
+    "  bootstrap               Ensure mcp-aws-manager MCP server is registered (default command)",
+    "  setup                   Register/re-register MCP server for Codex/Claude",
+    "  doctor                  Check install and registration health",
+    "  discover                Run EC2+SSM inventory workflow",
+    "",
+    "Setup/Bootstrap/Doctor options:",
+    "  --name <server-name>            (default: mcp-aws-manager)",
+    "  --mcp-command <command>         (default: mcp-aws-manager-mcp)",
+    "  --clients <codex,claude>        (default: codex,claude)",
+    "  --force                         (setup/bootstrap only; always remove then add)",
+    "  -h, --help",
+    "",
+    "Discover options:",
     "  --profiles <a,b,c>",
     "  --regions <a,b,c>",
     "  --instance-ids <id1,id2>",
@@ -100,7 +122,131 @@ function usageText() {
   ].join("\n");
 }
 
-function parseArgs(argv) {
+function parseClients(raw) {
+  const values = parseCsv(raw) || [];
+  if (!values.length) {
+    throw new Error("--clients must include at least one of: codex, claude");
+  }
+  const out = [];
+  const seen = new Set();
+  for (const value of values) {
+    const name = String(value).trim().toLowerCase();
+    if (!SUPPORTED_CLIENTS.has(name)) {
+      throw new Error(`Unsupported client '${value}'. Supported: codex, claude`);
+    }
+    if (!seen.has(name)) {
+      seen.add(name);
+      out.push(name);
+    }
+  }
+  return out;
+}
+
+function parseCommand(argv) {
+  const args = Array.from(argv || []);
+  if (!args.length) {
+    return { command: "bootstrap", args: [] };
+  }
+
+  const first = String(args[0] || "");
+  if (first === "-h" || first === "--help") {
+    return { command: "help", args: [] };
+  }
+
+  if (first === "bootstrap" || first === "init") {
+    return { command: "bootstrap", args: args.slice(1) };
+  }
+  if (first === "setup" || first === "doctor" || first === "discover") {
+    return { command: first, args: args.slice(1) };
+  }
+  if (first.startsWith("-")) {
+    return { command: "discover", args };
+  }
+
+  throw new Error(`Unknown command '${first}'. Run --help for usage.`);
+}
+
+function parseRegistrationArgs(argv, opts = {}) {
+  const allowForce = opts.allowForce === true;
+  const options = {
+    serverName: null,
+    mcpCommand: null,
+    clients: null,
+    force: false,
+    help: false
+  };
+
+  function setKV(key, value) {
+    switch (key) {
+      case "name":
+        options.serverName = String(value || "").trim();
+        break;
+      case "mcp-command":
+        options.mcpCommand = String(value || "").trim();
+        break;
+      case "clients":
+        options.clients = String(value || "").trim();
+        break;
+      default:
+        throw new Error(`Unknown option --${key}`);
+    }
+  }
+
+  const args = Array.from(argv || []);
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = String(args[i] || "");
+    if (arg === "-h" || arg === "--help") {
+      options.help = true;
+      continue;
+    }
+    if (arg === "--force") {
+      if (!allowForce) {
+        throw new Error("--force is only supported by setup/bootstrap");
+      }
+      options.force = true;
+      continue;
+    }
+    if (!arg.startsWith("--")) {
+      throw new Error(`Unexpected argument: ${arg}`);
+    }
+
+    const eq = arg.indexOf("=");
+    if (eq >= 0) {
+      const key = arg.slice(2, eq);
+      const value = arg.slice(eq + 1);
+      if (!value) throw new Error(`Missing value for --${key}`);
+      setKV(key, value);
+      continue;
+    }
+
+    const key = arg.slice(2);
+    const next = args[i + 1];
+    if (!next || String(next).startsWith("--")) {
+      throw new Error(`Missing value for --${key}`);
+    }
+    setKV(key, next);
+    i += 1;
+  }
+
+  if (options.help) {
+    return { help: true };
+  }
+
+  const serverName = options.serverName || DEFAULT_SERVER_NAME;
+  const mcpCommand = options.mcpCommand || DEFAULT_MCP_COMMAND;
+  if (!serverName) throw new Error("--name cannot be empty");
+  if (!mcpCommand) throw new Error("--mcp-command cannot be empty");
+
+  return {
+    help: false,
+    serverName,
+    mcpCommand,
+    clients: options.clients ? parseClients(options.clients) : ["codex", "claude"],
+    force: options.force
+  };
+}
+
+function parseDiscoverArgs(argv) {
   const options = {
     profiles: null,
     regions: null,
@@ -136,7 +282,7 @@ function parseArgs(argv) {
       case "snapshot-max-kb": options.snapshotMaxKb = value; break;
       case "format": options.format = value; break;
       case "out": options.outPath = value; break;
-      default: throw new Error(`Unknown option --${key}`);
+      default: throw new Error(`Unknown discover option --${key}`);
     }
   }
 
@@ -254,6 +400,179 @@ function listLocalAwsProfiles() {
   return Array.from(found).filter(Boolean).sort();
 }
 
+function runCLICommand(cliBin, args, options = {}) {
+  const execOptions = {
+    cwd: process.cwd(),
+    env: process.env,
+    stdio: options.stdio || "pipe",
+    encoding: "utf8",
+    shell: false
+  };
+
+  const direct = spawnSync(cliBin, args, execOptions);
+  if (process.platform !== "win32") {
+    return direct;
+  }
+
+  const errCode = String(direct && direct.error && direct.error.code ? direct.error.code : "");
+  if (!direct.error || (errCode !== "ENOENT" && errCode !== "EINVAL")) {
+    return direct;
+  }
+
+  // On Windows, global npm CLIs are often .cmd wrappers and can fail direct lookup.
+  return spawnSync("cmd.exe", ["/d", "/s", "/c", cliBin, ...args], execOptions);
+}
+
+function runStatusLabel(run) {
+  if (run && typeof run.status === "number") {
+    return `exit ${run.status}`;
+  }
+  if (run && run.error) {
+    return run.error.message || String(run.error);
+  }
+  return "unknown";
+}
+
+function commandExists(bin, checkArgs) {
+  const run = runCLICommand(bin, Array.isArray(checkArgs) ? checkArgs : ["--help"], { stdio: "ignore" });
+  return run && run.status === 0;
+}
+
+function removeRegistration(cliBin, serverName) {
+  if (cliBin === "claude") {
+    runCLICommand(cliBin, ["mcp", "remove", serverName, "-s", "user"], { stdio: "ignore" });
+    runCLICommand(cliBin, ["mcp", "remove", serverName, "-s", "local"], { stdio: "ignore" });
+    return;
+  }
+  runCLICommand(cliBin, ["mcp", "remove", serverName], { stdio: "ignore" });
+}
+
+function isRegistered(cliBin, serverName) {
+  const args = cliBin === "claude"
+    ? ["mcp", "get", serverName]
+    : ["mcp", "get", serverName, "--json"];
+  const run = runCLICommand(cliBin, args, { stdio: "ignore" });
+  return run && run.status === 0;
+}
+
+function registrationAttempts(cliBin, serverName, mcpCommand) {
+  if (cliBin === "claude") {
+    return [
+      ["mcp", "add", "--scope", "user", serverName, "--", mcpCommand],
+      ["mcp", "add", "--scope", "user", serverName, mcpCommand]
+    ];
+  }
+  return [
+    ["mcp", "add", serverName, "--", mcpCommand],
+    ["mcp", "add", serverName, mcpCommand]
+  ];
+}
+
+function tryRegister(cliBin, serverName, mcpCommand) {
+  const attempts = registrationAttempts(cliBin, serverName, mcpCommand);
+  let lastRun = null;
+  let lastArgs = null;
+  for (const args of attempts) {
+    const run = runCLICommand(cliBin, args, { stdio: "pipe" });
+    if (run && run.status === 0) {
+      return { ok: true, args, run };
+    }
+    lastRun = run;
+    lastArgs = args;
+  }
+  return { ok: false, args: lastArgs, run: lastRun };
+}
+
+function runSetupInternal(config, options = {}) {
+  const ensureOnly = options.ensureOnly === true;
+  const clients = config.clients.filter((cli) => commandExists(cli, ["mcp", "--help"]));
+  const results = [];
+
+  process.stdout.write(ensureOnly ? "Bootstrap start.\n" : "Setup start.\n");
+  process.stdout.write(`Server:  ${config.serverName}\n`);
+  process.stdout.write(`Command: ${config.mcpCommand}\n`);
+  process.stdout.write(`Clients: ${config.clients.join(",")}\n`);
+
+  if (!clients.length) {
+    process.stdout.write("No codex/claude CLI found. Registration skipped.\n");
+    return 2;
+  }
+
+  for (const cliBin of clients) {
+    const alreadyRegistered = isRegistered(cliBin, config.serverName);
+    if (config.force || !ensureOnly || alreadyRegistered) {
+      removeRegistration(cliBin, config.serverName);
+    }
+
+    const registered = tryRegister(cliBin, config.serverName, config.mcpCommand);
+    if (registered.ok) {
+      const action = ensureOnly
+        ? (alreadyRegistered ? "updated" : "registered")
+        : (alreadyRegistered ? "re-registered" : "registered");
+      results.push({ cliBin, ok: true, action, detail: "" });
+      continue;
+    }
+
+    const stderr = String(registered.run && registered.run.stderr ? registered.run.stderr : "").trim();
+    const stdout = String(registered.run && registered.run.stdout ? registered.run.stdout : "").trim();
+    const detail = stderr || stdout || runStatusLabel(registered.run);
+    results.push({ cliBin, ok: false, action: "registration failed", detail });
+  }
+
+  for (const row of results) {
+    process.stdout.write(`${row.cliBin}: ${row.action}\n`);
+    if (!row.ok && row.detail) {
+      process.stdout.write(`  detail: ${row.detail}\n`);
+    }
+  }
+
+  const failed = results.filter((r) => !r.ok).length;
+  process.stdout.write(failed ? "Setup finished with failures.\n" : "Setup finished successfully.\n");
+  return failed ? 2 : 0;
+}
+
+function runDoctor(config) {
+  process.stdout.write("Doctor start.\n");
+  let hasIssue = false;
+  let foundClient = false;
+
+  const mcpCommandRun = runCLICommand(config.mcpCommand, ["--help"], { stdio: "pipe" });
+  if (mcpCommandRun && mcpCommandRun.status === 0) {
+    process.stdout.write(`mcp-command: ok (${config.mcpCommand})\n`);
+  } else {
+    hasIssue = true;
+    const detail = String(mcpCommandRun && (mcpCommandRun.stderr || mcpCommandRun.stdout) ? (mcpCommandRun.stderr || mcpCommandRun.stdout) : "").trim();
+    process.stdout.write(`mcp-command: fail (${config.mcpCommand})\n`);
+    if (detail) process.stdout.write(`  detail: ${detail}\n`);
+  }
+
+  for (const cliBin of config.clients) {
+    const exists = commandExists(cliBin, ["mcp", "--help"]);
+    if (!exists) {
+      hasIssue = true;
+      process.stdout.write(`${cliBin}: not installed or not available in PATH\n`);
+      continue;
+    }
+
+    foundClient = true;
+    const registered = isRegistered(cliBin, config.serverName);
+    if (registered) {
+      process.stdout.write(`${cliBin}: registered (${config.serverName})\n`);
+    } else {
+      hasIssue = true;
+      process.stdout.write(`${cliBin}: missing registration (${config.serverName})\n`);
+      process.stdout.write(`  action: mcp-aws-manager setup --name ${config.serverName} --mcp-command ${config.mcpCommand} --clients ${cliBin}\n`);
+    }
+  }
+
+  if (!foundClient) {
+    process.stdout.write("No requested clients detected. Install Codex or Claude Code first.\n");
+  }
+
+  process.stdout.write(hasIssue ? "Doctor result: issues found.\n" : "Doctor result: healthy.\n");
+  return hasIssue ? 2 : 0;
+}
+
 let awsModulesCache = null;
 function loadAwsModules() {
   if (awsModulesCache) return awsModulesCache;
@@ -1058,7 +1377,47 @@ async function runWorkflow(config) {
 
 async function main() {
   try {
-    const config = parseArgs(process.argv.slice(2));
+    const parsed = parseCommand(process.argv.slice(2));
+    if (parsed.command === "help") {
+      process.stdout.write(usageText());
+      process.exitCode = 0;
+      return;
+    }
+
+    if (parsed.command === "setup") {
+      const config = parseRegistrationArgs(parsed.args, { allowForce: true });
+      if (config.help) {
+        process.stdout.write(usageText());
+        process.exitCode = 0;
+        return;
+      }
+      process.exitCode = runSetupInternal(config, { ensureOnly: false });
+      return;
+    }
+
+    if (parsed.command === "bootstrap") {
+      const config = parseRegistrationArgs(parsed.args, { allowForce: true });
+      if (config.help) {
+        process.stdout.write(usageText());
+        process.exitCode = 0;
+        return;
+      }
+      process.exitCode = runSetupInternal(config, { ensureOnly: true });
+      return;
+    }
+
+    if (parsed.command === "doctor") {
+      const config = parseRegistrationArgs(parsed.args, { allowForce: false });
+      if (config.help) {
+        process.stdout.write(usageText());
+        process.exitCode = 0;
+        return;
+      }
+      process.exitCode = runDoctor(config);
+      return;
+    }
+
+    const config = parseDiscoverArgs(parsed.args);
     if (config.help) {
       process.stdout.write(usageText());
       process.exitCode = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-aws-manager",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "AWS operations CLI and MCP server (SSM-only) for EC2 inventory, remediation, and runtime snapshots",
   "license": "MIT",
   "publishConfig": {