mcp-aws-manager 0.4.0 → 0.4.2

package/README.md

@@ -8,6 +8,7 @@ This package orchestrates AWS operations (inventory/runtime/remediation) with a
 
 ```bash
 npm install -g mcp-aws-manager
+mcp-aws-manager --version
 mcp-aws-manager
 mcp-aws-manager doctor
 mcp-aws-manager discover --profiles default --no-progress
@@ -39,7 +40,7 @@ Use `mcp-aws-manager` when you need an operations workflow MCP, not just generic
 
 See detailed comparison and product boundaries in:
 
-- `MCP_DIFFERENTIATION.md`
+- `docs/MCP_DIFFERENTIATION.md`
 
 ## Quick Comparison
 
@@ -51,7 +52,7 @@ See detailed comparison and product boundaries in:
 | Response contract | Normalized (`ok/summary/records/requiredActions/meta`) | Varies by implementation |
 | Best fit | Reproducible ops loops with operator guidance | Exploratory or wide API probing |
 
-For full rationale and boundaries, see `MCP_DIFFERENTIATION.md` and `MCP_DIFFERENTIATION_KO.md`.
+For full rationale and boundaries, see `docs/MCP_DIFFERENTIATION.md` and `docs/MCP_DIFFERENTIATION_KO.md`.
 
 ## API Coverage Snapshot
 
@@ -142,21 +143,43 @@ mcp-aws-manager
 Bootstrap registers the default single MCP server for detected clients:
 
 - `mcp-aws-manager` (single-entry, `--surface all`)
+- Runtime command is auto-resolved for host stability.
+- Windows priority: absolute `mcp-aws-manager-mcp.cmd`
+- macOS/Linux priority: absolute `mcp-aws-manager-mcp` binary
+- Fallback: `node <installed-package>/bin/mcp-aws-manager-mcp.js`
+- Last fallback (ephemeral npx context): pinned `npx -y -p mcp-aws-manager@<version> mcp-aws-manager-mcp`
 
 Optional explicit registration:
 
 ```bash
 mcp-aws-manager setup
-mcp-aws-manager setup --clients codex,claude
-mcp-aws-manager setup --clients cursor,windsurf,antigravity
+mcp-aws-manager setup --clients cursor
+mcp-aws-manager setup --clients codex
+mcp-aws-manager setup --clients claude
 ```
 
+Default behavior (`setup`/`bootstrap` without `--clients`) auto-detects installed clients and registers only detected CLIs.
+
 2. Health check:
 
 ```bash
 mcp-aws-manager doctor
 ```
 
+Default behavior (`doctor` without `--clients`) auto-detects installed clients and skips non-installed CLIs.
+
+### Agent Instruction Snippet (Any Client)
+
+When asking an agent to check AWS status, use this exact sequence first:
+
+```bash
+mcp-aws-manager setup --force
+mcp-aws-manager doctor
+mcp-aws-manager discover --profiles default --no-progress
+```
+
+Require the agent to include `runId`/`started_at` (live run evidence) in the response. If missing, treat it as file-only/cached summary.
+
 3. Configure AWS auth (SSO recommended):
 
 ```bash
@@ -231,7 +254,22 @@ Use this only when automatic `bootstrap/setup` registration is unavailable.
 }
 ```
 
-2) Global npm install:
+2) Global npm install (manual fallback):
+
+Windows (recommended):
+
+```json
+{
+  "mcpServers": {
+    "mcp-aws-manager": {
+      "command": "C:\\Users\\<user>\\AppData\\Roaming\\npm\\mcp-aws-manager-mcp.cmd",
+      "args": ["--surface", "all"]
+    }
+  }
+}
+```
+
+macOS/Linux:
 
 ```json
 {
@@ -489,7 +527,7 @@ Common `ACTION_REQUIRED` codes:
   - `rawNormalized` (always included for re-processing stability)
   - `schema` / `schemaVersion`
 - Contract schema: `schemas/mcp-tool-response.schema.json`
-- Compatibility policy: `RESPONSE_COMPATIBILITY_POLICY.md`
+- Compatibility policy: `docs/RESPONSE_COMPATIBILITY_POLICY.md`
 
 <details>
 <summary>Detailed AWS Auth Setup (SSO vs Access Key)</summary>
@@ -942,15 +980,16 @@ Manual fallback mode:
 ## Related Docs
 
 Document status:
-- Canonical (keep synchronized with implementation): `README.md`, `RESPONSE_COMPATIBILITY_POLICY.md`
-- Reference (detail/positioning): `IMPLEMENTATION_INTEGRATIONS.md`, `MCP_DIFFERENTIATION.md`, `MCP_DIFFERENTIATION_KO.md`, `AGENT_WORKING_CONTEXT_KO.md`, `RECORDS_FIELD_REFERENCE_KO.md`
+- Canonical (keep synchronized with implementation): `README.md`, `docs/RESPONSE_COMPATIBILITY_POLICY.md`
+- Reference (detail/positioning): `docs/IMPLEMENTATION_INTEGRATIONS.md`, `docs/MCP_DIFFERENTIATION.md`, `docs/MCP_DIFFERENTIATION_KO.md`, `workflow/AGENT_WORKING_CONTEXT_KO.md`, `docs/RECORDS_FIELD_REFERENCE_KO.md`
 
 - `README_KO.md`: Korean overview and quick start
-- `IMPLEMENTATION_INTEGRATIONS.md`: API/CLI integration inventory
-- `MCP_DIFFERENTIATION.md`: differentiation from existing AWS MCP servers
-- `MCP_DIFFERENTIATION_KO.md`: Korean differentiation guide and selection criteria
-- `AGENT_WORKING_CONTEXT_KO.md`: agent-focused implementation invariants, gateway loop, and operation catalog quick reference
-- `RECORDS_FIELD_REFERENCE_KO.md`: full `records[]` field reference (292 fields)
-- `RESPONSE_COMPATIBILITY_POLICY.md`: response schema/version compatibility rules
+- `docs/IMPLEMENTATION_INTEGRATIONS.md`: API/CLI integration inventory
+- `docs/MCP_DIFFERENTIATION.md`: differentiation from existing AWS MCP servers
+- `docs/MCP_DIFFERENTIATION_KO.md`: Korean differentiation guide and selection criteria
+- `workflow/AGENT_WORKING_CONTEXT_KO.md`: agent-focused implementation invariants, gateway loop, and operation catalog quick reference
+- `docs/RECORDS_FIELD_REFERENCE_KO.md`: full `records[]` field reference (292 fields)
+- `docs/RESPONSE_COMPATIBILITY_POLICY.md`: response schema/version compatibility rules
 - `schemas/mcp-tool-response.schema.json`: canonical tool response JSON schema
 
+

package/README_KO.md

@@ -8,6 +8,7 @@ SSM 우선(SSM-first) 방식의 AWS 운영 CLI + MCP stdio 서버입니다.
 
 ```bash
 npm install -g mcp-aws-manager
+mcp-aws-manager --version
 mcp-aws-manager
 mcp-aws-manager doctor
 mcp-aws-manager discover --profiles default --no-progress
@@ -39,7 +40,7 @@ mcp-aws-manager discover --profiles default --no-progress
 
 비교/경계는 아래 문서를 참고하세요.
 
-- `MCP_DIFFERENTIATION.md`
+- `docs/MCP_DIFFERENTIATION.md`
 
 ## 빠른 비교 요약
 
@@ -51,7 +52,7 @@ mcp-aws-manager discover --profiles default --no-progress
 | 응답 계약 | 정규화(`ok/summary/records/requiredActions/meta`) | 구현마다 상이 |
 | 적합한 상황 | 반복 가능한 운영 루프 + 운영자 가이드 필요 | 탐색/실험 위주의 광범위 API 접근 |
 
-상세 근거와 경계는 `MCP_DIFFERENTIATION.md`, `MCP_DIFFERENTIATION_KO.md`를 참고하세요.
+상세 근거와 경계는 `docs/MCP_DIFFERENTIATION.md`, `docs/MCP_DIFFERENTIATION_KO.md`를 참고하세요.
 
 ## API 커버리지 스냅샷
 
@@ -142,21 +143,43 @@ mcp-aws-manager
 bootstrap/setup 기본 동작은 단일 서버 1개를 등록합니다.
 
 - `mcp-aws-manager` (single-entry, `--surface all`)
+- 런타임 커맨드는 호스트 안정성을 위해 자동으로 해석됩니다.
+- Windows 우선순위: 절대경로 `mcp-aws-manager-mcp.cmd`
+- macOS/Linux 우선순위: 절대경로 `mcp-aws-manager-mcp` 바이너리
+- 폴백: `node <installed-package>/bin/mcp-aws-manager-mcp.js`
+- 최종 폴백(npx 임시 실행 컨텍스트): 버전 고정 `npx -y -p mcp-aws-manager@<version> mcp-aws-manager-mcp`
 
 명시적 등록 예시:
 
 ```bash
 mcp-aws-manager setup
-mcp-aws-manager setup --clients codex,claude
-mcp-aws-manager setup --clients cursor,windsurf,antigravity
+mcp-aws-manager setup --clients cursor
+mcp-aws-manager setup --clients codex
+mcp-aws-manager setup --clients claude
 ```
 
+기본 동작(`--clients` 없이 `setup`/`bootstrap`)은 설치된 클라이언트를 자동 감지해, 감지된 CLI만 등록합니다.
+
 2. 상태 점검:
 
 ```bash
 mcp-aws-manager doctor
 ```
 
+기본 동작(`--clients` 없이 `doctor`)은 설치된 클라이언트를 자동 감지하고, 미설치 CLI는 skip 처리합니다.
+
+### 에이전트 지시용 공통 스니펫
+
+에이전트에게 AWS 상태 점검을 지시할 때는 먼저 아래 순서를 그대로 실행하도록 요청하세요.
+
+```bash
+mcp-aws-manager setup --force
+mcp-aws-manager doctor
+mcp-aws-manager discover --profiles default --no-progress
+```
+
+응답에는 반드시 `runId`/`started_at`(라이브 실행 증거)를 포함하도록 요구하세요. 없으면 파일 기반/캐시 요약으로 간주하세요.
+
 3. AWS 인증 설정(권장: SSO):
 
 ```bash
@@ -232,7 +255,22 @@ mcp-aws-manager discover --profiles default --html-out ./inventory.html --open-h
 }
 ```
 
-2) 전역 npm 설치:
+2) 전역 npm 설치(수동 대체 경로):
+
+Windows(권장):
+
+```json
+{
+  "mcpServers": {
+    "mcp-aws-manager": {
+      "command": "C:\\Users\\<user>\\AppData\\Roaming\\npm\\mcp-aws-manager-mcp.cmd",
+      "args": ["--surface", "all"]
+    }
+  }
+}
+```
+
+macOS/Linux:
 
 ```json
 {
@@ -490,7 +528,7 @@ Discover 연산 참고:
   - `rawNormalized` (재처리 안정성을 위해 항상 포함)
   - `schema` / `schemaVersion`
 - 계약 스키마: `schemas/mcp-tool-response.schema.json`
-- 호환성 정책: `RESPONSE_COMPATIBILITY_POLICY.md`
+- 호환성 정책: `docs/RESPONSE_COMPATIBILITY_POLICY.md`
 
 <details>
 <summary>상세 AWS 인증 설정 (SSO vs Access Key)</summary>
@@ -936,16 +974,17 @@ E2E 러너 검증 항목:
 ## 관련 문서
 
 문서 상태:
-- Canonical(구현과 동기화 필수): `README.md`, `RESPONSE_COMPATIBILITY_POLICY.md`
-- Reference(상세/비교 참고): `IMPLEMENTATION_INTEGRATIONS.md`, `MCP_DIFFERENTIATION.md`, `MCP_DIFFERENTIATION_KO.md`, `AGENT_WORKING_CONTEXT_KO.md`, `RECORDS_FIELD_REFERENCE_KO.md`
+- Canonical(구현과 동기화 필수): `README.md`, `docs/RESPONSE_COMPATIBILITY_POLICY.md`
+- Reference(상세/비교 참고): `docs/IMPLEMENTATION_INTEGRATIONS.md`, `docs/MCP_DIFFERENTIATION.md`, `docs/MCP_DIFFERENTIATION_KO.md`, `workflow/AGENT_WORKING_CONTEXT_KO.md`, `docs/RECORDS_FIELD_REFERENCE_KO.md`
 
 - `README_KO.md`: 한국어 개요/빠른 시작
-- `IMPLEMENTATION_INTEGRATIONS.md`: API/CLI 연동 인벤토리
-- `MCP_DIFFERENTIATION.md`: AWS MCP 대안 대비 차별점
-- `MCP_DIFFERENTIATION_KO.md`: 한국어 차별화/선택 가이드
-- `AGENT_WORKING_CONTEXT_KO.md`: 에이전트 협업 시 불변 원칙/작업 루프/operationId 빠른 참조
-- `RECORDS_FIELD_REFERENCE_KO.md`: `records[]` 전수 필드(292개) 레퍼런스
-- `RESPONSE_COMPATIBILITY_POLICY.md`: 응답 스키마/버전 호환 정책
+- `docs/IMPLEMENTATION_INTEGRATIONS.md`: API/CLI 연동 인벤토리
+- `docs/MCP_DIFFERENTIATION.md`: AWS MCP 대안 대비 차별점
+- `docs/MCP_DIFFERENTIATION_KO.md`: 한국어 차별화/선택 가이드
+- `workflow/AGENT_WORKING_CONTEXT_KO.md`: 에이전트 협업 시 불변 원칙/작업 루프/operationId 빠른 참조
+- `docs/RECORDS_FIELD_REFERENCE_KO.md`: `records[]` 전수 필드(292개) 레퍼런스
+- `docs/RESPONSE_COMPATIBILITY_POLICY.md`: 응답 스키마/버전 호환 정책
 - `schemas/mcp-tool-response.schema.json`: 표준 도구 응답 JSON 스키마
 
 
+

package/bin/mcp-aws-manager.js

@@ -52,6 +52,8 @@ const APP_ANALYSIS_MEM_HIGH_PCT = 90;
 const ACM_EXPIRING_SOON_DAYS = 30;
 const DEFAULT_SERVER_NAME = "mcp-aws-manager";
 const DEFAULT_MCP_COMMAND = "mcp-aws-manager-mcp";
+const DEFAULT_MCP_COMMAND_ENTRY = path.resolve(__dirname, "mcp-aws-manager-mcp.js");
+const PACKAGE_JSON_PATH = path.resolve(__dirname, "..", "package.json");
 const DEFAULT_HTML_REPORT_NAME = "aws-inventory.html";
 const DEFAULT_TOPOLOGY_REPORT_NAME = "aws-topology.json";
 const DEFAULT_RELATIONSHIPS_REPORT_NAME = "aws-relationships.json";
@@ -154,6 +156,7 @@ const REQUIRED_ACTION_DEFAULTS = Object.freeze({
 const POLICY_PACK_NAMES = Object.keys(POLICY_PACKS);
 const ASSUMED_PROFILE_PREFIX = "assume-role://";
 const assumeRoleProviderCache = new Map();
+let packageVersionCache = null;
 
 function eprint(msg) {
   process.stderr.write(String(msg) + "\n");
@@ -187,6 +190,200 @@ function parseCsv(raw) {
   return list.length ? list : null;
 }
 
+function pathCompareKey(value) {
+  const resolved = path.resolve(String(value || ""));
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
+function uniquePaths(values) {
+  const out = [];
+  const seen = new Set();
+  for (const raw of Array.isArray(values) ? values : []) {
+    const text = String(raw || "").trim();
+    if (!text) continue;
+    const key = pathCompareKey(text);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(path.resolve(text));
+  }
+  return out;
+}
+
+function readPathEnvDirs() {
+  const raw = process.env.PATH || process.env.Path || process.env.path || "";
+  if (!raw) return [];
+  return String(raw)
+    .split(path.delimiter)
+    .map((item) => String(item || "").trim())
+    .filter(Boolean);
+}
+
+function fileExists(filePath) {
+  try {
+    return fs.statSync(filePath).isFile();
+  } catch (_error) {
+    return false;
+  }
+}
+
+function readCurrentPackageVersion() {
+  if (packageVersionCache) return packageVersionCache;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(PACKAGE_JSON_PATH, "utf8"));
+    const value = String(parsed && parsed.version ? parsed.version : "").trim();
+    packageVersionCache = value || "latest";
+  } catch (_error) {
+    packageVersionCache = "latest";
+  }
+  return packageVersionCache;
+}
+
+function isLikelyNpxCachePath(filePath) {
+  const normalized = String(filePath || "")
+    .replace(/\\/g, "/")
+    .toLowerCase();
+  return normalized.includes("/_npx/");
+}
+
+function lookupCommandInPath(commandName) {
+  const bin = String(commandName || "").trim();
+  if (!bin) return null;
+  const lookupTool = process.platform === "win32" ? "where.exe" : "which";
+  try {
+    const run = spawnSync(lookupTool, [bin], {
+      stdio: "pipe",
+      encoding: "utf8",
+      shell: false,
+      timeout: 2500,
+      windowsHide: true
+    });
+    if (!run || run.status !== 0) return null;
+    const lines = String(run.stdout || "")
+      .split(/\r?\n/)
+      .map((line) => String(line || "").trim())
+      .filter(Boolean);
+    for (const line of lines) {
+      const resolved = path.resolve(line);
+      if (fileExists(resolved)) return resolved;
+    }
+  } catch (_error) {
+    return null;
+  }
+  return null;
+}
+
+function resolveNpxCommandBinary() {
+  if (process.platform === "win32") {
+    const nodeDir = path.dirname(path.resolve(String(process.execPath || "")));
+    const bundled = path.join(nodeDir, "npx.cmd");
+    if (fileExists(bundled)) return bundled;
+    return lookupCommandInPath("npx.cmd") || lookupCommandInPath("npx") || "npx";
+  }
+  return lookupCommandInPath("npx") || "npx";
+}
+
+function resolveWindowsMcpCommand() {
+  if (process.platform !== "win32") return null;
+
+  const fromPathCmd = lookupCommandInPath(`${DEFAULT_MCP_COMMAND}.cmd`);
+  if (fromPathCmd) {
+    return { mcpCommand: fromPathCmd, mcpArgs: [], resolution: "windows-cmd-path" };
+  }
+
+  const packageRoot = path.resolve(__dirname, "..");
+  const nodeModulesDir = path.dirname(packageRoot);
+  const npmRootCandidate = path.dirname(nodeModulesDir);
+  const npmPrefix = envText("npm_config_prefix");
+  const appData = envText("APPDATA");
+  const candidateDirs = uniquePaths([
+    path.join(nodeModulesDir, ".bin"),
+    npmRootCandidate,
+    npmPrefix ? path.resolve(expandHome(npmPrefix)) : null,
+    appData ? path.join(path.resolve(appData), "npm") : null,
+    ...readPathEnvDirs()
+  ]);
+
+  for (const dirPath of candidateDirs) {
+    const candidate = path.join(dirPath, `${DEFAULT_MCP_COMMAND}.cmd`);
+    if (!fileExists(candidate)) continue;
+    return { mcpCommand: candidate, mcpArgs: [], resolution: "windows-cmd-absolute" };
+  }
+
+  const fromPathGeneric = lookupCommandInPath(DEFAULT_MCP_COMMAND);
+  if (fromPathGeneric && fromPathGeneric.toLowerCase().endsWith(".cmd")) {
+    return { mcpCommand: fromPathGeneric, mcpArgs: [], resolution: "windows-cmd-generic" };
+  }
+  return null;
+}
+
+function resolvePosixMcpCommand() {
+  if (process.platform === "win32") return null;
+
+  const fromPath = lookupCommandInPath(DEFAULT_MCP_COMMAND);
+  if (fromPath) {
+    return { mcpCommand: fromPath, mcpArgs: [], resolution: "posix-path-absolute" };
+  }
+
+  const packageRoot = path.resolve(__dirname, "..");
+  const localBin = path.join(path.dirname(packageRoot), ".bin", DEFAULT_MCP_COMMAND);
+  if (fileExists(localBin)) {
+    return { mcpCommand: localBin, mcpArgs: [], resolution: "posix-local-bin" };
+  }
+  return null;
+}
+
+function resolveNodeScriptMcpTarget() {
+  if (!fileExists(DEFAULT_MCP_COMMAND_ENTRY)) return null;
+  const nodeBin = path.resolve(String(process.execPath || ""));
+  if (!fileExists(nodeBin)) return null;
+  const ephemeral = isLikelyNpxCachePath(DEFAULT_MCP_COMMAND_ENTRY);
+  return {
+    mcpCommand: nodeBin,
+    mcpArgs: [DEFAULT_MCP_COMMAND_ENTRY],
+    resolution: ephemeral ? "node-script-ephemeral" : "node-script-absolute",
+    ephemeral
+  };
+}
+
+function resolveNpxMcpTarget() {
+  const npxCommand = resolveNpxCommandBinary();
+  if (!npxCommand) return null;
+  const version = readCurrentPackageVersion();
+  return {
+    mcpCommand: npxCommand,
+    mcpArgs: ["-y", "-p", `mcp-aws-manager@${version}`, DEFAULT_MCP_COMMAND],
+    resolution: "npx-pinned"
+  };
+}
+
+function resolveDefaultRegistrationTarget() {
+  const serverName = DEFAULT_SERVER_NAME;
+  const windowsCmdTarget = resolveWindowsMcpCommand();
+  const posixTarget = resolvePosixMcpCommand();
+  const nodeScriptTarget = resolveNodeScriptMcpTarget();
+  const npxTarget = resolveNpxMcpTarget();
+
+  if (process.platform === "win32") {
+    if (windowsCmdTarget) return { serverName, ...windowsCmdTarget };
+    if (nodeScriptTarget && !nodeScriptTarget.ephemeral) return { serverName, ...nodeScriptTarget };
+    if (npxTarget) return { serverName, ...npxTarget };
+    if (nodeScriptTarget) return { serverName, ...nodeScriptTarget };
+    return { serverName, mcpCommand: DEFAULT_MCP_COMMAND, mcpArgs: [], resolution: "path-default" };
+  }
+
+  if (posixTarget) return { serverName, ...posixTarget };
+  if (nodeScriptTarget && !nodeScriptTarget.ephemeral) return { serverName, ...nodeScriptTarget };
+  if (npxTarget) return { serverName, ...npxTarget };
+  if (nodeScriptTarget) return { serverName, ...nodeScriptTarget };
+  return { serverName, mcpCommand: DEFAULT_MCP_COMMAND, mcpArgs: [], resolution: "path-default" };
+}
+
+function registrationTargetHelpArgs(target) {
+  const args = Array.isArray(target && target.mcpArgs) ? target.mcpArgs.slice() : [];
+  args.push("--help");
+  return args;
+}
+
 function parseShardSpec(raw, label) {
   if (raw == null || String(raw).trim() === "") return null;
   const text = String(raw).trim();
@@ -526,6 +723,8 @@ function usageText() {
   return [
     "Usage:",
     "  mcp-aws-manager",
+    "  mcp-aws-manager version",
+    "  mcp-aws-manager --version",
     "  mcp-aws-manager bootstrap [options]",
     "  mcp-aws-manager setup [options]",
     "  mcp-aws-manager doctor [options]",
@@ -537,6 +736,7 @@ function usageText() {
     "SSM-first AWS inventory/runtime collector (EC2/Lambda/ALB/ASG/RDS/ElastiCache/Route53 + VPC/ECS/S3/IAM/KMS/CloudWatch/CloudTrail/Config/ECR/DynamoDB/SNS/SQS/Budgets/CostAnomaly + EBS/EFS/EKS/APIGateway/CloudFront/WAF/Shield/StepFunctions/CloudWatchLogs/X-Ray/Inspector2/Redshift/OpenSearch/Organizations/ControlTower + ACM/Kinesis/MSK) plus MCP client setup helper.",
     "",
     "Commands:",
+    "  version                 Print CLI package version",
     "  bootstrap               Ensure mcp-aws-manager MCP server is registered (default command)",
     "  setup                   Register/re-register MCP server for supported clients",
     "  doctor                  Check install and registration health",
@@ -545,8 +745,8 @@ function usageText() {
     "  discover                Run multi-service inventory workflow (EC2/Lambda/ALB/ASG/RDS/ElastiCache/Route53 + VPC/ECS/S3/IAM/KMS/CloudWatch + extended platform/security/analytics services)",
     "",
     "Setup/Bootstrap/Doctor options:",
-    "  (fixed target: mcp-aws-manager => mcp-aws-manager-mcp)",
-    `  --clients <${clientList}>        (default: codex,claude)`,
+    "  (target: mcp-aws-manager => auto-resolved runtime command for mcp-aws-manager-mcp)",
+    `  --clients <${clientList}>        (default: auto-detect installed clients)`,
     "  --force                         (setup/bootstrap only; always remove then add)",
     "  -h, --help",
     "",
@@ -798,6 +998,9 @@ function parseCommand(argv) {
   }
 
   const first = String(args[0] || "");
+  if (first === "-v" || first === "--version" || first === "version") {
+    return { command: "version", args: [] };
+  }
   if (first === "-h" || first === "--help") {
     return { command: "help", args: [] };
   }
@@ -873,10 +1076,13 @@ function parseRegistrationArgs(argv, opts = {}) {
     return { help: true };
   }
 
+  const defaultTarget = resolveDefaultRegistrationTarget();
+  const clientsExplicit = Boolean(options.clients && String(options.clients).trim());
   return {
     help: false,
-    targets: [{ serverName: DEFAULT_SERVER_NAME, mcpCommand: DEFAULT_MCP_COMMAND, mcpArgs: [] }],
-    clients: options.clients ? parseClients(options.clients) : ["codex", "claude"],
+    targets: [defaultTarget],
+    clients: options.clients ? parseClients(options.clients) : Array.from(SUPPORTED_CLIENTS),
+    clientsExplicit,
     force: options.force
   };
 }
@@ -2262,23 +2468,39 @@ function targetCommandLabel(target) {
   return [command, ...args].join(" ");
 }
 
+function detectClientAvailability(clients) {
+  const candidateClients = Array.isArray(clients) && clients.length
+    ? clients
+    : Array.from(SUPPORTED_CLIENTS);
+  return candidateClients.map((cliBin) => {
+    const exists = clientHelpAttempts(cliBin).some((args) => commandExists(cliBin, args));
+    return { cliBin, exists };
+  });
+}
+
 function runSetupInternal(config, options = {}) {
   const ensureOnly = options.ensureOnly === true;
+  const defaultTarget = resolveDefaultRegistrationTarget();
   const targets = Array.isArray(config.targets) && config.targets.length
     ? config.targets
-    : [{ serverName: DEFAULT_SERVER_NAME, mcpCommand: DEFAULT_MCP_COMMAND, mcpArgs: [] }];
-  const clients = config.clients.filter((cli) =>
-    clientHelpAttempts(cli).some((args) => commandExists(cli, args))
-  );
+    : [defaultTarget];
+  const clientsExplicit = config && config.clientsExplicit === true;
+  const availability = detectClientAvailability(config.clients);
+  const clients = availability.filter((row) => row.exists).map((row) => row.cliBin);
+  const missingClients = availability.filter((row) => !row.exists).map((row) => row.cliBin);
   const results = [];
   const commandChecks = targets.map((target) => ({
     ...target,
-    ok: commandExists(target.mcpCommand, ["--help"])
+    ok: commandExists(target.mcpCommand, registrationTargetHelpArgs(target))
   }));
 
   process.stdout.write(ensureOnly ? "Bootstrap start.\n" : "Setup start.\n");
   process.stdout.write(`Targets: ${targets.map((t) => `${t.serverName}=>${targetCommandLabel(t)}`).join(", ")}\n`);
-  process.stdout.write(`Clients: ${config.clients.join(",")}\n`);
+  process.stdout.write(`Clients(requested): ${availability.map((row) => row.cliBin).join(",")}\n`);
+  process.stdout.write(`Clients(detected): ${clients.length ? clients.join(",") : "none"}\n`);
+  if (!clientsExplicit && missingClients.length) {
+    process.stdout.write(`Clients(skipped): ${missingClients.join(",")} (not installed or not available in PATH)\n`);
+  }
 
   if (!clients.length) {
     process.stdout.write(`No supported client CLI found. Supported: ${Array.from(SUPPORTED_CLIENTS).join(", ")}\n`);
@@ -2343,16 +2565,20 @@ function runSetupInternal(config, options = {}) {
 }
 
 function runDoctor(config) {
+  const defaultTarget = resolveDefaultRegistrationTarget();
   const targets = Array.isArray(config.targets) && config.targets.length
     ? config.targets
-    : [{ serverName: DEFAULT_SERVER_NAME, mcpCommand: DEFAULT_MCP_COMMAND, mcpArgs: [] }];
+    : [defaultTarget];
+  const clientsExplicit = config && config.clientsExplicit === true;
+  const availability = detectClientAvailability(config.clients);
   process.stdout.write("Doctor start.\n");
   process.stdout.write(`Targets: ${targets.map((t) => `${t.serverName}=>${targetCommandLabel(t)}`).join(", ")}\n`);
+  process.stdout.write(`Clients(requested): ${availability.map((row) => row.cliBin).join(",")}\n`);
   let hasIssue = false;
   let foundClient = false;
 
   for (const target of targets) {
-    const mcpCommandRun = runCLICommand(target.mcpCommand, ["--help"], { stdio: "pipe" });
+    const mcpCommandRun = runCLICommand(target.mcpCommand, registrationTargetHelpArgs(target), { stdio: "pipe" });
     if (mcpCommandRun && mcpCommandRun.status === 0) {
       process.stdout.write(`mcp-command: ok (${target.serverName}=>${targetCommandLabel(target)})\n`);
     } else {
@@ -2363,11 +2589,15 @@ function runDoctor(config) {
     }
   }
 
-  for (const cliBin of config.clients) {
-    const exists = clientHelpAttempts(cliBin).some((args) => commandExists(cliBin, args));
-    if (!exists) {
-      hasIssue = true;
-      process.stdout.write(`${cliBin}: not installed or not available in PATH\n`);
+  for (const row of availability) {
+    const cliBin = row.cliBin;
+    if (!row.exists) {
+      if (clientsExplicit) {
+        hasIssue = true;
+        process.stdout.write(`${cliBin}: not installed or not available in PATH\n`);
+      } else {
+        process.stdout.write(`${cliBin}: skipped (not installed or not available in PATH)\n`);
+      }
       continue;
     }
 
@@ -2386,6 +2616,7 @@ function runDoctor(config) {
   }
 
   if (!foundClient) {
+    hasIssue = true;
     process.stdout.write("No requested clients detected. Install at least one supported client first.\n");
   }
 
@@ -11865,6 +12096,11 @@ async function runWorkflow(config) {
 async function main() {
   try {
     const parsed = parseCommand(process.argv.slice(2));
+    if (parsed.command === "version") {
+      process.stdout.write(`${readCurrentPackageVersion()}\n`);
+      process.exitCode = 0;
+      return;
+    }
     if (parsed.command === "help") {
       process.stdout.write(usageText());
       process.exitCode = 0;

package/package.json

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