mcp-aws-manager 0.3.1 → 0.3.3

package/AGENT_GUIDANCE_LOOP_TEMPLATE_KO.md

@@ -8,6 +8,22 @@
 - 수동 개입이 필요한 순간에만 사용자를 안내한다.
 - 사용자가 조치를 완료하면 같은 입력으로 자동 재시도한다.
 
+## 초기 설정 온보딩 모드
+
+처음 사용하는 사용자에게는 아래 순서로 진행한다.
+
+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에는 아래 필드가 포함된다.
@@ -46,7 +62,7 @@ MCP 응답 JSON에는 아래 필드가 포함된다.
 
 완료 시 아래를 간단히 보고한다.
 
-1. 전체 인스턴스 수
-2. SSM 관리/온라인 수
+1. 전체 리소스 수(EC2/Lambda)
+2. EC2 기준 SSM 관리/온라인 수
 3. 주요 경고 유무
-4. 다음 선택 사항(예: 런타임 스냅샷 확장)
+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,14 +1,13 @@
 # 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`
-- Compatibility aliases: `mcp-aws-discover`, `mcp-aws-discover-mcp`
 
 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 +18,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 +26,11 @@ Verification:
 mcp-aws-manager doctor
 ```
 
+## Agent-Led Setup Flow
+
+Detailed onboarding flow is maintained in `USAGE_GUIDE.md` ("Agent-Assisted First-Time Setup").
+This document only covers MCP server registration/configuration.
+
 ## Explicit Registration
 
 ```bash
@@ -39,6 +43,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 +101,6 @@ Use only when automatic registration is unavailable in your environment.
 
 ## Notes
 
-- 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, 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.
+- 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).
+- 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,112 +38,18 @@ 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).
 
-## Prerequisites
+For first-time users, follow the agent-assisted onboarding flow in `USAGE_GUIDE.md` ("Agent-Assisted First-Time Setup").
 
-- 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 auto remediation: EC2/IAM permissions (`ec2:AssociateIamInstanceProfile`, optionally `ec2:ReplaceIamInstanceProfileAssociation`, `iam:PassRole`)
+## Document Map
 
-## Quick Start
+- End-user setup and run commands: `USAGE_GUIDE.md`
+- MCP client registration and stdio config: `MCP_CLIENT_SETUP.md`
+- Agent retry/guidance loop template: `AGENT_GUIDANCE_LOOP_TEMPLATE_KO.md`
+- Implementation APIs/CLI wiring: `IMPLEMENTATION_INTEGRATIONS.md`
+- Positioning vs existing AWS MCPs: `MCP_DIFFERENTIATION.md`
 
-Bootstrap / setup / doctor:
+## Differentiation
 
-```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 discover --profiles default
-```
-
-Only public IP instances:
-
-```bash
-mcp-aws-manager discover --profiles default --public-only
-```
-
-Collect runtime snapshots:
-
-```bash
-mcp-aws-manager discover --profiles default --runtime-snapshot
-```
-
-Try automatic remediation for unmanaged instances:
-
-```bash
-mcp-aws-manager discover \
-  --profiles default \
-  --auto-remediate-ssm \
-  --ssm-instance-profile-name MySsmInstanceProfile
-```
-
-Output CSV file:
-
-```bash
-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:
-
-```bash
-mcp-aws-manager-mcp
-```
-
-Exposed MCP tools:
-
-- `discover_ec2_with_ssm` (primary)
-- `discover_public_ec2_with_pem` (compatibility alias, same SSM-only behavior)
-- `mcp_aws_discover_cli_help`
-
-Example tool arguments:
-
-```json
-{
-  "profiles": ["default"],
-  "publicOnly": true,
-  "runtimeSnapshot": true,
-  "autoSsoLogin": true,
-  "noProgress": true
-}
-```
-
-## Human-in-the-loop Behavior
-
-When fully automatic execution is not possible, the CLI/MCP returns actionable guidance:
-
-- `ACTION_REQUIRED: [SSO_LOGIN_NEEDED] ...`
-- `ACTION_REQUIRED: [SSM_ROLE_OR_AGENT_REQUIRED] ...`
-- `ACTION_REQUIRED: [IAM_PROFILE_ASSOCIATION_FAILED] ...`
-
-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
-
-- Prefer IAM role + SSM over SSH key based access.
-- Restrict RunCommand scopes with IAM policies and resource conditions.
-- Review remediation permissions before enabling `--auto-remediate-ssm`.
-
-## Compatibility Aliases
-
-These legacy commands are still available:
-
-- `mcp-aws-discover`
-- `mcp-aws-discover-mcp`
+This project does not delegate runtime execution to other AWS management MCP servers.