mcp-aws-manager 0.3.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

@@ -93,5 +93,5 @@ Use only when automatic registration is unavailable in your environment.
 
 - 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.
+- 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

@@ -122,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
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-aws-manager",
-  "version": "0.3.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"