mcp-aws-manager 0.3.5 → 0.3.6

package/AWS_SSO_SETUP_GUIDE.md

@@ -0,0 +1,133 @@
+# AWS 인증 설정 가이드 (SSO / Access Key)
+
+## 1. 목적
+- AWS CLI/콘솔 인증 방식을 표준화하고, 운영에 맞는 방식(SSO 또는 Access Key)을 선택해 안전하게 설정한다.
+
+## 2. SSO vs Access Key 비교
+
+| 항목 | SSO (IAM Identity Center) | Access Key (IAM User) |
+|---|---|---|
+| 기본 개념 | 브라우저 로그인 후 단기 자격증명 사용 | 고정 `Access key ID/Secret access key` 사용 |
+| 보안성 | 높음 (단기 토큰, 중앙 통제, MFA 연계 용이) | 상대적으로 낮음 (장기 키 유출 위험) |
+| 권한 관리 | Permission Set 중심 중앙 관리 | 사용자/그룹 정책으로 개별 관리 |
+| 감사 추적 | 사용자/역할 매핑이 명확 | 키 공유 시 추적성 저하 |
+| 운영 편의 | 최초 구성은 복잡, 이후 일관성 높음 | 초기 진입 쉬움, 장기 운영 리스크 큼 |
+| 만료/회전 | 자동 만료(재로그인) | 수동 회전 필요 |
+| 권장 용도 | 사람(개발자/운영자) 인터랙티브 작업 | 레거시/임시 작업. 자동화는 가급적 Role/OIDC 권장 |
+
+권장 기준:
+- 사람의 일상 작업: `SSO` 우선
+- 임시 테스트/단일 계정 빠른 접근: `Access Key` 가능
+- CI/CD 같은 자동화: IAM User Access Key보다 `IAM Role`(OIDC/AssumeRole) 우선
+
+## 3. SSO 설정 과정 (IAM Identity Center)
+
+### 3.1 사전 조건
+- AWS CLI v2
+
+```powershell
+aws --version
+```
+
+- `AWS Organizations` 미사용이면 먼저 조직 생성 필요
+- IAM Identity Center는 `Organization instance` 사용 권장
+
+### 3.2 콘솔 설정
+1. `AWS Organizations`에서 `Create organization` 수행 (미사용 시)
+2. `IAM Identity Center` 활성화
+3. `AWS access portal URL` 확인
+   - 예: `https://d-xxxxxxxxxx.awsapps.com/start`
+4. `Permission set` 생성
+   - 예: `AdministratorAccess`, `ReadOnlyAccess`
+5. 사용자/그룹에 대상 계정 + Permission Set 할당
+
+### 3.3 로컬 CLI 설정
+```powershell
+aws configure sso --profile default
+```
+
+입력 항목:
+- `SSO start URL`: 포털 URL
+- `SSO region`: Identity Center 리전
+- `Account` / `Role`: 할당된 항목 선택
+- `Default region`: 예) `ap-southeast-1`
+- `Default output`: `json`
+
+로그인/검증:
+
+```powershell
+aws sso login --profile default
+aws sts get-caller-identity --profile default
+```
+
+## 4. Access Key 설정 과정 (IAM User)
+
+### 4.1 사전 조건
+- IAM 사용자 권한 정책이 먼저 정의되어 있어야 함
+- `Root` 계정 Access Key는 사용 금지
+
+### 4.2 콘솔에서 키 발급
+1. AWS 콘솔 `IAM > Users > (본인 사용자) > Security credentials`
+2. `Create access key` 선택
+3. 사용 시나리오 선택 후 키 생성
+4. `Access key ID`, `Secret access key` 안전 저장
+   - Secret은 생성 시점에만 확인 가능
+
+### 4.3 로컬 CLI 등록
+```powershell
+aws configure --profile default
+```
+
+입력 항목:
+- `AWS Access Key ID`
+- `AWS Secret Access Key`
+- `Default region name` (예: `ap-southeast-1`)
+- `Default output format` (`json`)
+
+검증:
+
+```powershell
+aws sts get-caller-identity --profile default
+```
+
+### 4.4 회전(Rotation) 권장 절차
+1. 두 번째 키를 먼저 발급
+2. 애플리케이션/로컬 설정을 새 키로 전환
+3. 정상 동작 검증
+4. 이전 키 비활성화/삭제
+
+## 5. 공통 점검 명령
+
+```powershell
+aws configure list-profiles
+aws sts get-caller-identity --profile default
+aws ec2 describe-regions --profile default
+```
+
+## 6. 자주 발생하는 문제
+
+### 6.1 SSO 오류: `Missing the following required SSO configuration values`
+- 원인: `sso_start_url`, `sso_region` 누락
+- 조치: `aws configure sso --profile default` 재실행
+
+### 6.2 SSO 오류: `Unable to locate credentials`
+- 원인: 로그인 전
+- 조치:
+
+```powershell
+aws sso login --profile default
+```
+
+### 6.3 Access Key 오류: `InvalidClientTokenId` 또는 `SignatureDoesNotMatch`
+- 원인: 키 오입력 또는 비활성/삭제된 키 사용
+- 조치: 키 재발급 후 `aws configure` 재등록
+
+### 6.4 AccessDenied
+- 원인: 역할/사용자 권한 부족
+- 조치: 정책 또는 Permission Set 조정
+
+## 7. 운영 권장안
+- 기본 전략: 사람은 `SSO`, 자동화는 `Role`, 장기 `Access Key` 최소화
+- 변경 권한과 조회 권한 분리 (예: 운영은 `ReadOnly` 기본)
+- 키/권한 변경 시 즉시 검증 명령 실행
+

package/AWS_SSO_SETUP_GUIDE_KO.md

@@ -0,0 +1,70 @@
+# AWS 인증 설정 가이드 (SSO / Access Key)
+
+이 문서는 `mcp-aws-manager` 사용 전 필요한 AWS 인증 설정을 한국어로 정리한 가이드입니다.
+
+## 어떤 방식이 더 좋은가
+
+- 권장: `SSO` (IAM Identity Center)
+- 대안: `Access Key` (정책/조직 제약상 SSO 불가 시)
+
+SSO 권장 이유:
+
+- 장기 키를 로컬에 보관하지 않아 보안 위험 감소
+- MFA와 세션 만료 관리가 쉬움
+- 조직 단위 권한/회수 정책과 잘 맞음
+
+## 1) SSO 설정
+
+```bash
+aws configure sso --profile default
+aws sso login --profile default
+aws sts get-caller-identity --profile default
+```
+
+정상이라면 마지막 명령에서 `Account`, `Arn`, `UserId`가 출력됩니다.
+
+## 2) Access Key 설정
+
+```bash
+aws configure --profile default
+aws sts get-caller-identity --profile default
+```
+
+## 3) 현재 상태 점검
+
+```bash
+aws configure list-profiles
+aws configure list --profile default
+aws sts get-caller-identity --profile default
+```
+
+## 4) 자주 나는 오류
+
+`Unable to locate credentials`
+
+- 원인: 인증 미설정 또는 SSO 로그인 만료
+- 조치: SSO 로그인 재실행 또는 Access Key 재설정
+
+`AccessDenied` / `not authorized`
+
+- 원인: IAM 권한 부족
+- 조치: 필요한 API 권한 정책 추가
+
+## 5) mcp-aws-manager 사용 전 최소 준비
+
+- 조회 중심이면: AWS API 조회 권한 + 인증(SSO 또는 Access Key)
+- EC2 런타임(SSM)도 보려면:
+  - 인스턴스 프로파일에 `AmazonSSMManagedInstanceCore`
+  - SSM Agent 정상
+  - SSM 통신 가능한 네트워크/엔드포인트
+
+## 6) 인증이 아예 불가한 환경이라면
+
+수동 모드로 진행 가능합니다.
+
+```bash
+mcp-aws-manager discover --manual-server-list ./servers.csv --pem-paths C:\keys\prod.pem --no-progress
+```
+
+- 서버 목록(JSON/CSV)을 직접 제공
+- PEM SSH 기반으로 런타임 스냅샷 수행

package/IMPLEMENTATION_INTEGRATIONS.md

@@ -7,6 +7,10 @@ This document lists MCP/API/CLI integrations used by `mcp-aws-manager`.
 Tools:
 
 - `discover_ec2_with_ssm`
+- `ec2_start_instances`
+- `ec2_stop_instances`
+- `ec2_reboot_instances`
+- `ec2_apply_instance_profile`
 - `mcp_aws_discover_cli_help`
 
 Files:
@@ -32,6 +36,13 @@ File:
 
 - `bin/mcp-aws-manager.js`
 
+Coverage summary:
+
+- AWS API "all features" are not fully implemented in this project.
+- AWS API total has no fixed official single number because services/actions keep growing.
+- Current implementation uses `9` AWS SDK service clients and `20` AWS SDK operations.
+- AWS CLI integration count is `1` command (`aws sso login --profile <profile>`).
+
 SDK clients:
 
 - `@aws-sdk/client-sts`
@@ -47,7 +58,7 @@ SDK clients:
 Core API calls:
 
 - STS: `GetCallerIdentity`
-- EC2: `DescribeRegions`, `DescribeInstances`, `DescribeIamInstanceProfileAssociations`, `AssociateIamInstanceProfile`, `ReplaceIamInstanceProfileAssociation`
+- EC2: `DescribeRegions`, `DescribeInstances`, `StartInstances`, `StopInstances`, `RebootInstances`, `DescribeIamInstanceProfileAssociations`, `AssociateIamInstanceProfile`, `ReplaceIamInstanceProfileAssociation`
 - SSM: `DescribeInstanceInformation`, `SendCommand`, `GetCommandInvocation`
 - Lambda: `ListFunctions`
 - ELBv2: `DescribeLoadBalancers`, `DescribeTargetGroups`
@@ -70,7 +81,31 @@ Purpose:
 
 - Automatic recovery when SSO credentials expire.
 
-## 5) Local MCP client registration automation
+## 5) Manual inventory + SSH(PEM) fallback
+
+File:
+
+- `bin/mcp-aws-manager.js`
+
+Behavior:
+
+- When `--manual-server-list` is set, inventory is loaded from JSON/CSV without AWS API auth.
+- Optional runtime snapshot uses local OpenSSH client with PEM keys (`--pem-paths` / per-row `pemPath`).
+- Manual rows are normalized into the same EC2 output schema.
+
+## 6) GUI report output
+
+File:
+
+- `bin/mcp-aws-manager.js`
+
+Behavior:
+
+- `discover` supports `--html-out <path>` to generate interactive local HTML inventory report.
+- Report supports search/filter and client-side CSV download from current view.
+- Optional `--open-html` tries opening the generated report in default browser.
+
+## 7) Local MCP client registration automation
 
 Supported clients:
 
@@ -82,7 +117,7 @@ Supported clients:
 
 The setup flow tries multiple `mcp` command variants (`get/show`, `add`, `remove/rm`, scope variations) to maximize compatibility.
 
-## 6) Related docs
+## 8) Related docs
 
 - `README.md`
 - `MCP_CLIENT_SETUP.md`

package/MCP_CLIENT_SETUP.md

@@ -1,5 +1,7 @@
 # MCP Client Setup (stdio)
 
+Korean translation: `MCP_CLIENT_SETUP_KO.md`
+
 This project provides an MCP stdio wrapper around the SSM-first AWS operations CLI.
 
 - Preferred CLI command: `mcp-aws-manager`

package/MCP_CLIENT_SETUP_KO.md

@@ -0,0 +1,107 @@
+# MCP 클라이언트 설정 가이드 (stdio)
+
+이 프로젝트는 `mcp-aws-manager` CLI를 감싸는 MCP stdio 서버를 제공합니다.
+
+- 권장 CLI 명령: `mcp-aws-manager`
+- 권장 MCP 서버 명령: `mcp-aws-manager-mcp`
+
+## 노출 도구
+
+조회:
+
+- `discover_ec2_with_ssm`
+- `mcp_aws_discover_cli_help`
+
+변경:
+
+- `ec2_start_instances`
+- `ec2_stop_instances`
+- `ec2_reboot_instances`
+- `ec2_apply_instance_profile`
+
+## 권장 설치(1회)
+
+```bash
+npm install -g mcp-aws-manager
+mcp-aws-manager
+```
+
+`mcp-aws-manager`를 인자 없이 실행하면 bootstrap이 동작하며, 감지된 클라이언트(`codex`, `claude` 기본)에 MCP 서버를 등록합니다.
+
+검증:
+
+```bash
+mcp-aws-manager doctor
+```
+
+## 명시적 등록
+
+```bash
+mcp-aws-manager setup
+```
+
+이름/명령 커스텀:
+
+```bash
+mcp-aws-manager setup --name mcp-aws-manager --mcp-command mcp-aws-manager-mcp --clients codex,claude
+```
+
+Cursor/Windsurf/Antigravity 예시:
+
+```bash
+mcp-aws-manager setup --name mcp-aws-manager --mcp-command mcp-aws-manager-mcp --clients cursor,windsurf,antigravity
+```
+
+## 수동 설정(자동 등록 불가 시)
+
+### 1) 로컬 저장소(개발)
+
+```json
+{
+  "mcpServers": {
+    "mcp-aws-manager": {
+      "command": "node",
+      "args": [
+        "C:/Users/mybin/gesia/mcp_aws/bin/mcp-aws-manager-mcp.js"
+      ],
+      "cwd": "C:/Users/mybin/gesia/mcp_aws"
+    }
+  }
+}
+```
+
+### 2) 전역 npm 설치 사용
+
+```json
+{
+  "mcpServers": {
+    "mcp-aws-manager": {
+      "command": "mcp-aws-manager-mcp"
+    }
+  }
+}
+```
+
+### 3) npx 사용(전역 설치 없이)
+
+```json
+{
+  "mcpServers": {
+    "mcp-aws-manager": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "-p",
+        "mcp-aws-manager",
+        "mcp-aws-manager-mcp"
+      ]
+    }
+  }
+}
+```
+
+## 참고
+
+- 런타임 접근 기본은 SSM 우선이며, 필요 시 수동 서버리스트 + PEM SSH 경로를 사용합니다.
+- 실행 경로는 이 패키지 내부 AWS SDK/CLI를 사용합니다(외부 AWS 관리 MCP 백엔드 미의존).
+- 지원 클라이언트: `codex`, `claude`, `cursor`, `windsurf`, `antigravity`.