mcp-aws-manager 0.3.0 → 0.3.2

package/AGENT_GUIDANCE_LOOP_TEMPLATE_KO.md

@@ -0,0 +1,68 @@
+# Agent Guidance Loop Template (KO)
+
+아래 규칙은 `discover_ec2_with_ssm` 또는 호환 alias 호출 결과를 바탕으로 사용자 개입을 최소화하기 위한 시스템 프롬프트 템플릿입니다.
+
+## 목적
+
+- 가능한 범위는 자동으로 끝까지 처리한다.
+- 수동 개입이 필요한 순간에만 사용자를 안내한다.
+- 사용자가 조치를 완료하면 같은 입력으로 자동 재시도한다.
+
+## 초기 설정 온보딩 모드
+
+처음 사용하는 사용자에게는 아래 순서로 진행한다.
+
+1. `mcp-aws-manager doctor` 실행
+2. 인증 누락 시 `aws configure sso --profile <profile>` 안내
+3. `aws sso login --profile <profile>` 안내
+4. `aws sts get-caller-identity --profile <profile>` 검증
+5. `discover_ec2_with_ssm` 또는 `mcp-aws-manager discover` 재실행
+
+원칙:
+
+- 한 번에 하나의 조치만 요청
+- 조치 완료 답변(예: `완료`)을 받으면 즉시 같은 요청 재시도
+- 실패하면 다음 `ACTION_REQUIRED` 1건만 이어서 안내
+
+## 입력 가정
+
+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. 전체 리소스 수(EC2/Lambda)
+2. EC2 기준 SSM 관리/온라인 수
+3. 주요 경고 유무
+4. 다음 선택 사항(예: 런타임 스냅샷 확장)

package/IMPLEMENTATION_INTEGRATIONS.md

@@ -0,0 +1,91 @@
+# Implementation Integrations
+
+This document lists MCP/API/CLI integrations used by `mcp-aws-manager`.
+
+## 1) MCP integration (provided by this project)
+
+Tools:
+
+- `discover_ec2_with_ssm`
+- `discover_public_ec2_with_pem` (compat alias)
+- `mcp_aws_discover_cli_help`
+
+Files:
+
+- `bin/mcp-aws-manager-mcp.js`
+- `bin/mcp-aws-manager.js`
+
+Behavior:
+
+- MCP tool input is translated to CLI args
+- CLI runs inventory/runtime workflow
+- Result is normalized as structured JSON payload (`summary`, `requiredActions`, `guidance`)
+
+## 2) Important implementation scope decision
+
+- External AWS management MCP backends are **not used** in runtime execution.
+- Execution is internal-only using AWS SDK + AWS CLI.
+- No bridge command / adapter map is required for normal operation.
+
+## 3) AWS SDK integrations (internal execution)
+
+File:
+
+- `bin/mcp-aws-manager.js`
+
+SDK clients:
+
+- `@aws-sdk/client-sts`
+- `@aws-sdk/client-ec2`
+- `@aws-sdk/client-ssm`
+- `@aws-sdk/client-lambda`
+- `@aws-sdk/client-elastic-load-balancing-v2`
+- `@aws-sdk/client-auto-scaling`
+- `@aws-sdk/client-rds`
+- `@aws-sdk/client-elasticache`
+- `@aws-sdk/client-route-53`
+
+Core API calls:
+
+- STS: `GetCallerIdentity`
+- EC2: `DescribeRegions`, `DescribeInstances`, `DescribeIamInstanceProfileAssociations`, `AssociateIamInstanceProfile`, `ReplaceIamInstanceProfileAssociation`
+- SSM: `DescribeInstanceInformation`, `SendCommand`, `GetCommandInvocation`
+- Lambda: `ListFunctions`
+- ELBv2: `DescribeLoadBalancers`, `DescribeTargetGroups`
+- Auto Scaling: `DescribeAutoScalingGroups`
+- RDS: `DescribeDBInstances`
+- ElastiCache: `DescribeCacheClusters`
+- Route53: `ListHostedZones`, `ListResourceRecordSets`
+
+## 4) AWS CLI integration
+
+File:
+
+- `bin/mcp-aws-manager.js`
+
+Command used:
+
+- `aws sso login --profile <profile>`
+
+Purpose:
+
+- Automatic recovery when SSO credentials expire.
+
+## 5) Local MCP client registration automation
+
+Supported clients:
+
+- `codex`
+- `claude`
+- `cursor`
+- `windsurf`
+- `antigravity`
+
+The setup flow tries multiple `mcp` command variants (`get/show`, `add`, `remove/rm`, scope variations) to maximize compatibility.
+
+## 6) Related docs
+
+- `README.md`
+- `USAGE_GUIDE.md`
+- `MCP_CLIENT_SETUP.md`
+- `MCP_DIFFERENTIATION.md`

package/MCP_CLIENT_SETUP.md

@@ -1,6 +1,6 @@
 # MCP Client Setup (stdio)
 
-This project provides an MCP stdio wrapper around the SSM-only CLI.
+This project provides an MCP stdio wrapper around the SSM-first AWS operations CLI.
 
 - Preferred CLI command: `mcp-aws-manager`
 - Preferred MCP server command: `mcp-aws-manager-mcp`
@@ -8,7 +8,7 @@ This project provides an MCP stdio wrapper around the SSM-only CLI.
 
 Exposed MCP tools:
 
-- `discover_ec2_with_ssm` (primary)
+- `discover_ec2_with_ssm` (primary, multi-service inventory + SSM runtime)
 - `discover_public_ec2_with_pem` (compatibility alias, same behavior)
 - `mcp_aws_discover_cli_help`
 
@@ -19,7 +19,7 @@ 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`).
+`mcp-aws-manager` (no args) runs bootstrap and registers the MCP server for detected clients (`codex`, `claude` by default).
 
 Verification:
 
@@ -27,6 +27,22 @@ Verification:
 mcp-aws-manager doctor
 ```
 
+## Agent-Led Setup Flow
+
+When the user is unfamiliar with AWS setup, run this sequence through the agent:
+
+1. `mcp-aws-manager doctor`
+2. If AWS auth missing, guide:
+   - `aws configure sso --profile default`
+   - `aws sso login --profile default`
+3. Validate:
+   - `aws sts get-caller-identity --profile default`
+4. Validate MCP discovery path:
+   - `mcp-aws-manager discover --profiles default --no-progress`
+5. If `requiresUserAction=true`, ask for one manual action only, then retry same request.
+
+Manual user actions are typically limited to SSO browser/MFA and IAM approval.
+
 ## Explicit Registration
 
 ```bash
@@ -39,6 +55,12 @@ Custom name/command:
 mcp-aws-manager setup --name mcp-aws-manager --mcp-command mcp-aws-manager-mcp --clients codex,claude
 ```
 
+Cursor/Windsurf/Antigravity target example:
+
+```bash
+mcp-aws-manager setup --name mcp-aws-manager --mcp-command mcp-aws-manager-mcp --clients cursor,windsurf,antigravity
+```
+
 ## Manual Configuration (Fallback)
 
 Use only when automatic registration is unavailable in your environment.
@@ -91,7 +113,10 @@ Use only when automatic registration is unavailable in your environment.
 
 ## Notes
 
-- Discovery is SSM-only; PEM path arguments are no longer required.
+- Discovery is SSM-first for host/runtime access; PEM path arguments are no longer required.
+- Runtime execution uses this package's internal AWS SDK/CLI path only (no external AWS management MCP backend dependency).
+- Use include flags (`includeLambda`, `includeAlb`, `includeAsg`, `includeRds`, `includeElastiCache`, `includeRoute53`) to expand inventory scope.
 - 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.
+- Supported setup clients: `codex`, `claude`, `cursor`, `windsurf`, `antigravity`.

package/MCP_DIFFERENTIATION.md

@@ -0,0 +1,39 @@
+# MCP Differentiation
+
+This document clarifies how `mcp-aws-manager` differs from existing AWS-oriented MCP servers.
+
+## Scope statement
+
+- `mcp-aws-manager` is an internal-execution operations MCP.
+- Runtime does not call external AWS management MCP servers.
+- Discovery/remediation/snapshot are executed directly with AWS SDK and AWS CLI.
+
+## Compared targets
+
+- AWS MCP Server (Anthropic/community variants)
+- aws-mcp style general AWS control MCPs
+- SSH/filesystem MCP combinations for server introspection
+
+## Comparison summary
+
+| Area | Existing AWS management MCPs (generic) | `mcp-aws-manager` |
+|---|---|---|
+| Runtime dependency | Often depends on that MCP server’s own tool/runtime behavior | No external runtime dependency; internal execution only |
+| Product intent | Broad cloud control (many services, ad-hoc actions) | Server operations workflow (inventory + runtime + guided remediation) |
+| Output contract | Tool-specific response shapes | Single normalized multi-service schema (EC2/Lambda/ALB/ASG/RDS/ElastiCache/Route53/SSM) |
+| Runtime insight | Not always integrated with SSM snapshot flow | SSM-first runtime snapshot in same workflow |
+| Failure handling | Varies by server/tool | Standardized `ACTION_REQUIRED` codes and retry guidance payload |
+| Onboarding | Usually per-client manual MCP config | Built-in `bootstrap/setup/doctor` for `codex`, `claude`, `cursor`, `windsurf`, `antigravity` |
+| Governance/audit | Varies | Step-aligned summary and evidence metadata hooks |
+
+## Practical differentiation
+
+- Deterministic 9-step workflow execution (same ordering every run).
+- Operationally focused defaults (inventory + SSM state + optional remediation/snapshot).
+- User intervention loop designed for agents (ask user only when blocked, then continue).
+- Vendor-agnostic from external MCP backends (no backend lock-in).
+
+## Intentional non-goals
+
+- Full replacement of every existing AWS management MCP capability.
+- External MCP-to-MCP bridge compatibility as a primary architecture.

package/README.md

@@ -1,6 +1,6 @@
 # mcp-aws-manager
 
-AWS operations CLI and MCP server package (SSM-only mode).
+AWS operations CLI and MCP server package (SSM-first mode).
 
 ## What It Provides
 
@@ -9,13 +9,20 @@ AWS operations CLI and MCP server package (SSM-only mode).
 
 Current implementation focuses on:
 
+- Internal-only execution (AWS SDK + AWS CLI), no external AWS management MCP backend dependency
 - EC2 inventory discovery (multi profile / multi region)
+- Optional Lambda function inventory (same profile/region sweep)
+- Optional ALB/NLB + Target Group inventory
+- Optional Auto Scaling Group inventory
+- Optional RDS inventory
+- Optional ElastiCache inventory
+- Optional Route53 hosted zone inventory
 - SSM management and online-state visibility
 - Optional SSM runtime snapshot collection (`RunCommand`)
 - 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
+- MCP registration bootstrap helpers (`codex`, `claude`, `cursor`, `windsurf`, `antigravity`)
 
 ## Install
 
@@ -31,14 +38,21 @@ After install, run once:
 mcp-aws-manager
 ```
 
-This ensures `mcp-aws-manager` is registered in detected clients (`codex`, `claude`).
+This ensures `mcp-aws-manager` is registered in detected clients (`codex`, `claude` by default).
+
+For first-time users, follow the agent-assisted onboarding flow in `USAGE_GUIDE.md` ("Agent-Assisted First-Time Setup").
 
 ## Prerequisites
 
 - Node.js `>=18`
 - AWS credentials/profile (or IAM role) on the machine running the CLI/MCP server
-- For runtime snapshots: SSM permissions (`ssm:SendCommand`, `ssm:GetCommandInvocation`)
+- For runtime snapshots: SSM permissions (`ssm:SendCommand`, `ssm:GetCommandInvocation`, `ssm:DescribeInstanceInformation`)
 - For auto remediation: EC2/IAM permissions (`ec2:AssociateIamInstanceProfile`, optionally `ec2:ReplaceIamInstanceProfileAssociation`, `iam:PassRole`)
+- For ALB inventory: `elasticloadbalancing:DescribeLoadBalancers`, `elasticloadbalancing:DescribeTargetGroups`
+- For ASG inventory: `autoscaling:DescribeAutoScalingGroups`
+- For RDS inventory: `rds:DescribeDBInstances`
+- For ElastiCache inventory: `elasticache:DescribeCacheClusters`
+- For Route53 inventory: `route53:ListHostedZones` (record counts require `route53:ListResourceRecordSets`)
 
 ## Quick Start
 
@@ -56,6 +70,26 @@ Basic discovery:
 mcp-aws-manager discover --profiles default
 ```
 
+Include Lambda inventory together:
+
+```bash
+mcp-aws-manager discover --profiles default --include-lambda
+```
+
+Include core service topology (ALB/ASG/RDS/ElastiCache/Route53):
+
+```bash
+mcp-aws-manager discover \
+  --profiles default \
+  --include-alb --include-asg --include-rds --include-elasticache --include-route53
+```
+
+Lambda-only inventory:
+
+```bash
+mcp-aws-manager discover --profiles default --include-lambda --no-ec2 --no-runtime-snapshot
+```
+
 Only public IP instances:
 
 ```bash
@@ -98,8 +132,8 @@ mcp-aws-manager-mcp
 
 Exposed MCP tools:
 
-- `discover_ec2_with_ssm` (primary)
-- `discover_public_ec2_with_pem` (compatibility alias, same SSM-only behavior)
+- `discover_ec2_with_ssm` (primary, multi-service inventory + SSM runtime)
+- `discover_public_ec2_with_pem` (compatibility alias, same behavior)
 - `mcp_aws_discover_cli_help`
 
 Example tool arguments:
@@ -107,6 +141,7 @@ Example tool arguments:
 ```json
 {
   "profiles": ["default"],
+  "includeLambda": true,
   "publicOnly": true,
   "runtimeSnapshot": true,
   "autoSsoLogin": true,
@@ -121,8 +156,18 @@ When fully automatic execution is not possible, the CLI/MCP returns actionable g
 - `ACTION_REQUIRED: [SSO_LOGIN_NEEDED] ...`
 - `ACTION_REQUIRED: [SSM_ROLE_OR_AGENT_REQUIRED] ...`
 - `ACTION_REQUIRED: [IAM_PROFILE_ASSOCIATION_FAILED] ...`
+- `ACTION_REQUIRED: [LAMBDA_LIST_PERMISSION_REQUIRED] ...`
+- `ACTION_REQUIRED: [ELBV2_LIST_PERMISSION_REQUIRED] ...`
+- `ACTION_REQUIRED: [ASG_LIST_PERMISSION_REQUIRED] ...`
+- `ACTION_REQUIRED: [RDS_LIST_PERMISSION_REQUIRED] ...`
+- `ACTION_REQUIRED: [ELASTICACHE_LIST_PERMISSION_REQUIRED] ...`
+- `ACTION_REQUIRED: [ROUTE53_LIST_PERMISSION_REQUIRED] ...`
 
-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
 
@@ -136,3 +181,11 @@ These legacy commands are still available:
 
 - `mcp-aws-discover`
 - `mcp-aws-discover-mcp`
+
+## Differentiation Docs
+
+This project does not delegate runtime execution to other AWS management MCP servers.
+Implementation details and differentiation are documented in:
+
+- `IMPLEMENTATION_INTEGRATIONS.md` (implemented MCP/API/CLI inventory)
+- `MCP_DIFFERENTIATION.md` (differences from existing AWS management MCPs)