mcp-aws-manager 0.3.5 → 0.3.7

package/README.md

@@ -2,37 +2,54 @@
 
 AWS operations CLI + MCP stdio server (SSM-first).
 
-This package is not a plain AWS CLI wrapper. It orchestrates multi-step operations:
+This package orchestrates AWS operations (inventory/runtime/remediation) with a normalized output schema and `ACTION_REQUIRED` guidance. It is not a plain AWS CLI wrapper.
 
-- Multi-service inventory (EC2/Lambda/ALB/ASG/RDS/ElastiCache/Route53)
-- SSM management/online status
-- Optional runtime snapshot and SSM remediation
-- Normalized output + `ACTION_REQUIRED` guidance for human-in-the-loop retries
-
-Execution path is internal-only (AWS SDK + AWS CLI). It does not delegate runtime execution to external AWS management MCP backends.
-
-## Binaries
-
-- CLI: `mcp-aws-manager`
-- MCP stdio server: `mcp-aws-manager-mcp`
-
-## Install
+## TL;DR
 
 ```bash
 npm install -g mcp-aws-manager
+mcp-aws-manager
+mcp-aws-manager doctor
+mcp-aws-manager discover --profiles default --no-progress
 ```
 
-## First Run (Recommended)
+## What It Does
 
-```bash
-mcp-aws-manager
-```
+- Multi-service inventory: EC2, Lambda, ALB/NLB, ASG, RDS, ElastiCache, Route53
+- SSM state visibility: managed/online status
+- Optional runtime snapshot and SSM remediation
+- Manual fallback mode: JSON/CSV server list + PEM SSH runtime snapshot (when AWS auth is unavailable)
+- Human-in-the-loop retry flow via `ACTION_REQUIRED`
+- Internal-only execution path (AWS SDK + AWS CLI)
+
+## API Coverage Snapshot
+
+- AWS API total: no fixed official single number, but the action surface is on the order of tens of thousands across services (and continuously expanding).
+- Current implementation scope is not "all AWS APIs".
+- AWS SDK service clients used: `9`
+- AWS SDK operation calls used: `20`
+- AWS CLI commands used: `1` (`aws sso login --profile <profile>`)
+
+Current 20 AWS SDK operations:
+
+- STS: `GetCallerIdentity`
+- EC2: `DescribeRegions`, `DescribeInstances`, `StartInstances`, `StopInstances`, `RebootInstances`, `DescribeIamInstanceProfileAssociations`, `AssociateIamInstanceProfile`, `ReplaceIamInstanceProfileAssociation`
+- SSM: `DescribeInstanceInformation`, `SendCommand`, `GetCommandInvocation`
+- Lambda: `ListFunctions`
+- ELBv2: `DescribeLoadBalancers`, `DescribeTargetGroups`
+- Auto Scaling: `DescribeAutoScalingGroups`
+- RDS: `DescribeDBInstances`
+- ElastiCache: `DescribeCacheClusters`
+- Route53: `ListHostedZones`, `ListResourceRecordSets`
 
-This bootstraps MCP server registration for detected clients (`codex`, `claude` by default).
+## Binaries
+
+- CLI: `mcp-aws-manager`
+- MCP stdio server: `mcp-aws-manager-mcp`
 
 ## Agent-Assisted First-Time Setup
 
-Use this 5-step flow for new users.
+Use this flow for new users.
 
 1. Install and bootstrap:
 
@@ -68,62 +85,130 @@ mcp-aws-manager discover --profiles default --no-progress
 
 If blocked, follow one `ACTION_REQUIRED` item, then retry the same command.
 
+If AWS auth is not available, use manual fallback:
+
+```bash
+mcp-aws-manager discover --manual-server-list ./servers.csv --pem-paths C:\keys\prod.pem --no-progress
+```
+
+GUI report is generated by default (`./aws-inventory.html`):
+
+```bash
+mcp-aws-manager discover --profiles default --no-progress
+```
+
+Custom path / open behavior:
+
+```bash
+mcp-aws-manager discover --profiles default --html-out ./inventory.html --open-html --no-progress
+```
+
 ## User Confirmation Required
 
-These are expected manual steps (agent-guided):
+These are normally the only manual steps (agent-guided):
 
 - SSO browser login and MFA confirmation
 - IAM permission approval in organization account
 - For EC2 runtime visibility: attach `AmazonSSMManagedInstanceCore` and keep SSM Agent/network healthy
 
-## Prerequisites
+## MCP Tool Usage
+
+Run MCP server:
+
+```bash
+mcp-aws-manager-mcp
+```
+
+Exposed MCP tools:
+
+- `discover_ec2_with_ssm`
+- `ec2_start_instances`
+- `ec2_stop_instances`
+- `ec2_reboot_instances`
+- `ec2_apply_instance_profile`
+- `mcp_aws_discover_cli_help`
+
+Mutation tool examples:
+
+- `ec2_start_instances`: `{ "profile": "default", "region": "ap-southeast-1", "instanceIds": ["i-123"] }`
+- `ec2_stop_instances`: `{ "profile": "default", "region": "ap-southeast-1", "instanceIds": ["i-123"], "force": false }`
+- `ec2_reboot_instances`: `{ "profile": "default", "region": "ap-southeast-1", "instanceIds": ["i-123"] }`
+- `ec2_apply_instance_profile`: `{ "profile": "default", "region": "ap-southeast-1", "instanceId": "i-123", "instanceProfileName": "my-ssm-profile", "allowReplaceProfile": true }`
+
+Example tool args:
+
+```json
+{
+  "profiles": ["default"],
+  "regions": ["ap-northeast-2"],
+  "includeLambda": true,
+  "publicOnly": true,
+  "runtimeSnapshot": true,
+  "htmlOutPath": "C:\\tmp\\inventory.html",
+  "openHtml": true,
+  "manualServerListPath": "C:\\tmp\\servers.csv",
+  "pemPaths": ["C:\\keys\\prod.pem"],
+  "sshUser": "ec2-user",
+  "sshPort": 22,
+  "sshConnectTimeoutSec": 8,
+  "autoSsoLogin": true,
+  "noProgress": true
+}
+```
+
+## Action Codes
 
-- Node.js `>=18`
-- AWS credentials on the host where CLI/MCP runs:
-  - SSO: `aws configure sso --profile <profile>` then `aws sso login --profile <profile>`
-  - Access key: `aws configure --profile <profile>`
-- Verify auth:
-  - `aws sts get-caller-identity --profile <profile>`
-- Runtime snapshot permissions:
-  - `ssm:SendCommand`, `ssm:GetCommandInvocation`, `ssm:DescribeInstanceInformation`
-- Auto-remediation permissions:
-  - `ec2:AssociateIamInstanceProfile`
-  - optional `ec2:ReplaceIamInstanceProfileAssociation`
-  - `iam:PassRole`
+Common `ACTION_REQUIRED` codes:
 
-Why SSO is recommended:
+- `SSO_LOGIN_NEEDED`
+- `AWS_CREDENTIALS_REQUIRED`
+- `IAM_PERMISSION_REQUIRED`
+- `AWS_OPERATION_FAILED`
+- `SSM_ROLE_OR_AGENT_REQUIRED`
+- `INSTANCE_HAS_PROFILE`
+- `IAM_PROFILE_ASSOCIATION_FAILED`
+- `SSM_RUNCOMMAND_PERMISSION_REQUIRED`
+- `LAMBDA_LIST_PERMISSION_REQUIRED`
+- `ELBV2_LIST_PERMISSION_REQUIRED`
+- `ASG_LIST_PERMISSION_REQUIRED`
+- `RDS_LIST_PERMISSION_REQUIRED`
+- `ELASTICACHE_LIST_PERMISSION_REQUIRED`
+- `ROUTE53_LIST_PERMISSION_REQUIRED`
+- `MANUAL_SERVER_LIST_EMPTY`
+- `MANUAL_SERVER_HOST_REQUIRED`
+- `PEM_KEY_NOT_FOUND`
+- `PEM_MAPPING_REQUIRED`
+- `SSH_CLIENT_NOT_FOUND`
+- `SSH_AUTH_OR_CONNECT_FAILED`
 
-- Avoid long-lived access keys on user machines
-- Easier MFA/session-based enforcement
-- Better centralized revoke/audit handling
+<details>
+<summary>Detailed AWS Auth Setup (SSO vs Access Key)</summary>
 
-## Commands
+SSO is recommended because:
 
-- `mcp-aws-manager`: bootstrap mode (default)
-- `mcp-aws-manager setup`: register/re-register MCP server
-- `mcp-aws-manager doctor`: check install/registration/auth readiness
-- `mcp-aws-manager discover ...`: run inventory/runtime workflow
+- Avoids long-lived access keys on user machines
+- Enforces session-based login and MFA more easily
+- Improves centralized revoke/audit handling
 
-## Quick Commands
+SSO setup:
 
 ```bash
-mcp-aws-manager
-mcp-aws-manager doctor
-mcp-aws-manager discover --profiles default
-mcp-aws-manager discover --profiles default --include-lambda
-mcp-aws-manager discover --profiles default --include-alb --include-asg --include-rds --include-elasticache --include-route53
-mcp-aws-manager discover --profiles default --public-only
-mcp-aws-manager discover --profiles default --runtime-snapshot
-mcp-aws-manager discover --profiles default --auto-remediate-ssm --ssm-instance-profile-name MySsmInstanceProfile
+aws configure sso --profile default
+aws sso login --profile default
+aws sts get-caller-identity --profile default
 ```
 
-Legacy invocation form (still supported):
+Access key setup (optional):
 
 ```bash
-mcp-aws-manager --profiles default --public-only
+aws configure --profile default
+aws sts get-caller-identity --profile default
 ```
 
-## Important Discover Options
+</details>
+
+<details>
+<summary>Discover Option Reference</summary>
 
 - `--profiles <a,b,c>`
 - `--regions <a,b,c>`
@@ -144,52 +229,47 @@ mcp-aws-manager --profiles default --public-only
 - `--snapshot-timeout <seconds>`
 - `--snapshot-concurrency <n>`
 - `--snapshot-max-kb <n>`
+- `--manual-server-list <path>` (JSON/CSV)
+- `--pem-paths <a,b,c>`
+- `--ssh-user <name>`
+- `--ssh-port <port>`
+- `--ssh-connect-timeout <seconds>`
+- `--html-out <path>` (default: `./aws-inventory.html`)
+- `--open-html` (force open)
+- `--no-open-html` (disable auto-open)
 - `--auto-sso-login` / `--no-auto-sso-login`
 - `--format <json|csv>`
 - `--out <path>`
 
-## MCP Tool Usage
+</details>
 
-Run MCP server:
+<details>
+<summary>Permission Checklist</summary>
 
-```bash
-mcp-aws-manager-mcp
-```
+Minimum permissions depend on enabled features.
 
-Exposed MCP tools:
+- Core inventory: `ec2:DescribeRegions`, `ec2:DescribeInstances`
+- Lambda: `lambda:ListFunctions`
+- ALB/TargetGroups: `elasticloadbalancing:DescribeLoadBalancers`, `elasticloadbalancing:DescribeTargetGroups`
+- ASG: `autoscaling:DescribeAutoScalingGroups`
+- RDS: `rds:DescribeDBInstances`
+- ElastiCache: `elasticache:DescribeCacheClusters`
+- Route53: `route53:ListHostedZones`, `route53:ListResourceRecordSets`
+- Runtime snapshot: `ssm:SendCommand`, `ssm:GetCommandInvocation`, `ssm:DescribeInstanceInformation`
+- Auto-remediation: `ec2:AssociateIamInstanceProfile`, optional `ec2:ReplaceIamInstanceProfileAssociation`, `iam:PassRole`
 
-- `discover_ec2_with_ssm`
-- `mcp_aws_discover_cli_help`
+Manual fallback mode:
 
-Example tool args:
+- Inventory uses user-provided server list file (no AWS API required)
+- Runtime snapshot uses local `ssh` client + PEM key access
 
-```json
-{
-  "profiles": ["default"],
-  "regions": ["ap-northeast-2"],
-  "includeLambda": true,
-  "publicOnly": true,
-  "runtimeSnapshot": true,
-  "autoSsoLogin": true,
-  "noProgress": true
-}
-```
-
-## ACTION_REQUIRED Examples
-
-- `SSO_LOGIN_NEEDED`
-- `SSM_ROLE_OR_AGENT_REQUIRED`
-- `IAM_PROFILE_ASSOCIATION_FAILED`
-- `SSM_RUNCOMMAND_PERMISSION_REQUIRED`
-- `LAMBDA_LIST_PERMISSION_REQUIRED`
-- `ELBV2_LIST_PERMISSION_REQUIRED`
-- `ASG_LIST_PERMISSION_REQUIRED`
-- `RDS_LIST_PERMISSION_REQUIRED`
-- `ELASTICACHE_LIST_PERMISSION_REQUIRED`
-- `ROUTE53_LIST_PERMISSION_REQUIRED`
+</details>
 
 ## Related Docs
 
+- `README_KO.md`: Korean overview and quick start
+- `MCP_CLIENT_SETUP_KO.md`: Korean MCP client registration guide
+- `AWS_SSO_SETUP_GUIDE_KO.md`: Korean AWS auth setup guide
 - `MCP_CLIENT_SETUP.md`: MCP registration and stdio config details
 - `AGENT_GUIDANCE_LOOP_TEMPLATE_KO.md`: agent retry/guidance template
 - `IMPLEMENTATION_INTEGRATIONS.md`: API/CLI integration inventory

package/README_KO.md

@@ -0,0 +1,117 @@
+# mcp-aws-manager (한국어 안내)
+
+AWS 운영 작업용 CLI + MCP stdio 서버입니다.
+
+이 패키지는 AWS 인벤토리/런타임/완화 작업을 정규화된 출력 스키마와 `ACTION_REQUIRED` 가이드로 제공합니다. 단순 AWS CLI 래퍼가 아니라, 에이전트 친화적인 운영 워크플로우를 목표로 합니다.
+
+## 빠른 시작
+
+```bash
+npm install -g mcp-aws-manager
+mcp-aws-manager
+mcp-aws-manager doctor
+mcp-aws-manager discover --profiles default --no-progress
+```
+
+## 핵심 기능
+
+- 멀티 서비스 인벤토리: EC2, Lambda, ALB/NLB, ASG, RDS, ElastiCache, Route53
+- SSM 상태 확인: managed/online
+- 런타임 스냅샷(선택), SSM 완화(선택)
+- AWS 인증이 안 될 때 수동 모드: JSON/CSV 서버 목록 + PEM SSH
+- GUI 리포트 기본 생성: `./aws-inventory.html` (검색/필터/CSV 다운로드 버튼 포함)
+- 사람이 개입해야 할 상황을 `ACTION_REQUIRED`로 표준화
+
+## 바이너리
+
+- CLI: `mcp-aws-manager`
+- MCP stdio server: `mcp-aws-manager-mcp`
+
+## 최초 설정(권장 흐름)
+
+1. 설치 및 부트스트랩
+
+```bash
+npm.cmd install -g mcp-aws-manager@latest
+mcp-aws-manager
+```
+
+2. 상태 확인
+
+```bash
+mcp-aws-manager doctor
+```
+
+3. AWS 인증 설정(권장: SSO)
+
+```bash
+aws configure sso --profile default
+aws sso login --profile default
+```
+
+4. 인증 확인
+
+```bash
+aws sts get-caller-identity --profile default
+```
+
+5. 인벤토리 실행
+
+```bash
+mcp-aws-manager discover --profiles default --no-progress
+```
+
+## 인증 불가 시 수동 모드
+
+```bash
+mcp-aws-manager discover --manual-server-list ./servers.csv --pem-paths C:\keys\prod.pem --no-progress
+```
+
+## GUI 리포트
+
+```bash
+mcp-aws-manager discover --profiles default --no-progress
+```
+
+- 기본 경로: `./aws-inventory.html`
+- `--html-out <path>`: 리포트 경로 변경
+- `--open-html`: 생성 후 브라우저 오픈 강제
+- `--no-open-html`: 자동 오픈 비활성화
+- GUI에서 현재 뷰 기준 CSV 다운로드 가능
+
+## MCP 도구
+
+조회:
+
+- `discover_ec2_with_ssm`
+- `mcp_aws_discover_cli_help`
+
+변경:
+
+- `ec2_start_instances`
+- `ec2_stop_instances`
+- `ec2_reboot_instances`
+- `ec2_apply_instance_profile`
+
+예시:
+
+- `ec2_start_instances`: `{ "profile": "default", "region": "ap-southeast-1", "instanceIds": ["i-123"] }`
+- `ec2_apply_instance_profile`: `{ "profile": "default", "region": "ap-southeast-1", "instanceId": "i-123", "instanceProfileName": "my-ssm-profile", "allowReplaceProfile": true }`
+
+## 자주 쓰는 ACTION_REQUIRED
+
+- 인증: `SSO_LOGIN_NEEDED`, `AWS_CREDENTIALS_REQUIRED`
+- 권한: `IAM_PERMISSION_REQUIRED`, `AWS_OPERATION_FAILED`
+- SSM/런타임: `SSM_ROLE_OR_AGENT_REQUIRED`, `SSM_RUNCOMMAND_PERMISSION_REQUIRED`
+- 수동 모드: `MANUAL_SERVER_LIST_EMPTY`, `MANUAL_SERVER_HOST_REQUIRED`, `PEM_KEY_NOT_FOUND`, `PEM_MAPPING_REQUIRED`, `SSH_CLIENT_NOT_FOUND`
+
+## 한국어 관련 문서
+
+- `MCP_CLIENT_SETUP_KO.md`
+- `AWS_SSO_SETUP_GUIDE_KO.md`
+
+## 원문(영문) 문서
+
+- `README.md`
+- `MCP_CLIENT_SETUP.md`
+- `AWS_SSO_SETUP_GUIDE.md`