mcp-aws-manager 0.4.0 → 0.4.1

package/README.md

@@ -39,7 +39,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 +51,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,6 +142,11 @@ 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:
 
@@ -231,7 +236,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 +509,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 +962,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

@@ -39,7 +39,7 @@ mcp-aws-manager discover --profiles default --no-progress
 
 비교/경계는 아래 문서를 참고하세요.
 
-- `MCP_DIFFERENTIATION.md`
+- `docs/MCP_DIFFERENTIATION.md`
 
 ## 빠른 비교 요약
 
@@ -51,7 +51,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,6 +142,11 @@ 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`
 
 명시적 등록 예시:
 
@@ -232,7 +237,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 +510,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 +956,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();
@@ -545,7 +742,7 @@ 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)",
+    "  (target: mcp-aws-manager => auto-resolved runtime command for mcp-aws-manager-mcp)",
     `  --clients <${clientList}>        (default: codex,claude)`,
     "  --force                         (setup/bootstrap only; always remove then add)",
     "  -h, --help",
@@ -873,9 +1070,10 @@ function parseRegistrationArgs(argv, opts = {}) {
     return { help: true };
   }
 
+  const defaultTarget = resolveDefaultRegistrationTarget();
   return {
     help: false,
-    targets: [{ serverName: DEFAULT_SERVER_NAME, mcpCommand: DEFAULT_MCP_COMMAND, mcpArgs: [] }],
+    targets: [defaultTarget],
     clients: options.clients ? parseClients(options.clients) : ["codex", "claude"],
     force: options.force
   };
@@ -2264,16 +2462,17 @@ function targetCommandLabel(target) {
 
 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: [] }];
+    : [defaultTarget];
   const clients = config.clients.filter((cli) =>
     clientHelpAttempts(cli).some((args) => commandExists(cli, args))
   );
   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");
@@ -2343,16 +2542,17 @@ 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];
   process.stdout.write("Doctor start.\n");
   process.stdout.write(`Targets: ${targets.map((t) => `${t.serverName}=>${targetCommandLabel(t)}`).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 {

package/package.json

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