mcp-aws-manager 0.2.0 → 0.3.1

package/AGENT_GUIDANCE_LOOP_TEMPLATE_KO.md

@@ -0,0 +1,52 @@
+# Agent Guidance Loop Template (KO)
+
+아래 규칙은 `discover_ec2_with_ssm` 또는 호환 alias 호출 결과를 바탕으로 사용자 개입을 최소화하기 위한 시스템 프롬프트 템플릿입니다.
+
+## 목적
+
+- 가능한 범위는 자동으로 끝까지 처리한다.
+- 수동 개입이 필요한 순간에만 사용자를 안내한다.
+- 사용자가 조치를 완료하면 같은 입력으로 자동 재시도한다.
+
+## 입력 가정
+
+MCP 응답 JSON에는 아래 필드가 포함된다.
+
+- `requiresUserAction: boolean`
+- `requiredActions: [{ code, message, hint }]`
+- `guidance: { assistantMessageTemplate, retryTool, retryArgs, userChecklist, completionTrigger }`
+
+## 실행 규칙
+
+1. 먼저 도구를 실행한다.
+2. `requiresUserAction=false`이면 결과를 요약하고 종료한다.
+3. `requiresUserAction=true`이면 `guidance.assistantMessageTemplate`을 사용자에게 그대로 전달한다.
+4. 사용자의 답변이 `완료` 또는 완료 의사표시이면, `guidance.retryTool` + `guidance.retryArgs`로 동일 요청을 즉시 재실행한다.
+5. 여전히 `requiresUserAction=true`이면 다음 액션을 다시 안내한다.
+6. 성공(`requiresUserAction=false`)할 때까지 반복한다.
+
+## 사용자 안내 스타일
+
+- 한 번에 하나의 액션만 안내한다.
+- 필요한 명령어는 복붙 가능한 한 줄로 제시한다.
+- 사용자의 AWS 지식 수준을 가정하지 않는다.
+- 매 단계 끝에 반드시 재시도 트리거 문구를 넣는다.
+
+예시 트리거 문구:
+
+- `조치가 끝나면 "완료"라고 답해주세요. 제가 바로 같은 요청으로 다시 확인하겠습니다.`
+
+## 금지 사항
+
+- 사용자가 요청하지 않은 파괴적 작업을 임의 실행하지 않는다.
+- 여러 개의 복잡한 선택지를 한 번에 던지지 않는다.
+- 내부 오류 로그를 장황하게 그대로 노출하지 않는다.
+
+## 최종 완료 응답
+
+완료 시 아래를 간단히 보고한다.
+
+1. 전체 인스턴스 수
+2. SSM 관리/온라인 수
+3. 주요 경고 유무
+4. 다음 선택 사항(예: 런타임 스냅샷 확장)

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
 {
@@ -66,5 +93,5 @@ 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.
+- When `requiresUserAction=true` is returned, use `guidance.assistantMessageTemplate` to prompt the user, then retry with `guidance.retryTool` + `guidance.retryArgs` after user confirmation.
+- 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:
@@ -98,7 +122,11 @@ When fully automatic execution is not possible, the CLI/MCP returns actionable g
 - `ACTION_REQUIRED: [SSM_ROLE_OR_AGENT_REQUIRED] ...`
 - `ACTION_REQUIRED: [IAM_PROFILE_ASSOCIATION_FAILED] ...`
 
-The MCP wrapper surfaces these in a structured `requiredActions` list.
+The MCP wrapper surfaces these in a structured `requiredActions` list and a `guidance` object (`assistantMessageTemplate`, `retryTool`, `retryArgs`).
+
+For agent orchestration, see:
+
+- `AGENT_GUIDANCE_LOOP_TEMPLATE_KO.md`
 
 ## Security Notes
 
@@ -111,4 +139,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-mcp.js

@@ -248,6 +248,157 @@ function summarizeRecords(records) {
   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: [
+          `터미널에서 다음 명령을 실행하세요: ${cmd}`,
+          "브라우저 인증/MFA를 완료하세요.",
+          "완료 후 '완료'라고 답해주세요."
+        ],
+        confirmText: "SSO 로그인이 끝났다면 '완료'라고 답해주세요."
+      };
+    }
+    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 권한 반영이 끝났다면 '완료'라고 답해주세요."
+      };
+    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: "사용자가 '완료' 또는 조치 완료를 확인하면 같은 입력으로 도구를 재실행",
+    userChecklist: items,
+    assistantMessageTemplate: lines.join("\n")
+  };
+}
+
 function buildToolTextResponse(payload) {
   return truncateText(JSON.stringify(payload, null, 2), DEFAULT_JSON_TEXT_LIMIT);
 }
@@ -353,6 +504,7 @@ function registerDiscoverTool(server, name, title, description) {
 
       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),
@@ -362,6 +514,7 @@ function registerDiscoverTool(server, name, title, description) {
         signal: cliResult.signal,
         requiresUserAction,
         requiredActions: logInfo.requiredActions,
+        guidance,
         summary: {
           ...summarizeRecords(allRecords),
           returnedRecords: records.length,

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.1",
   "description": "AWS operations CLI and MCP server (SSM-only) for EC2 inventory, remediation, and runtime snapshots",
   "license": "MIT",
   "publishConfig": {
@@ -23,7 +23,8 @@
   },
   "files": [
     "bin",
-    "MCP_CLIENT_SETUP.md"
+    "MCP_CLIENT_SETUP.md",
+    "AGENT_GUIDANCE_LOOP_TEMPLATE_KO.md"
   ],
   "engines": {
     "node": ">=18"