mcp-aws-manager 0.3.4 → 0.3.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AWS_SSO_SETUP_GUIDE.md +133 -0
- package/AWS_SSO_SETUP_GUIDE_KO.md +70 -0
- package/IMPLEMENTATION_INTEGRATIONS.md +38 -4
- package/MCP_CLIENT_SETUP.md +3 -1
- package/MCP_CLIENT_SETUP_KO.md +107 -0
- package/README.md +248 -30
- package/README_KO.md +115 -0
- package/bin/mcp-aws-manager-mcp.js +1097 -649
- package/bin/mcp-aws-manager.js +970 -27
- package/package.json +6 -2
- package/AGENT_GUIDANCE_LOOP_TEMPLATE_KO.md +0 -68
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
# AWS 인증 설정 가이드 (SSO / Access Key)
|
|
2
|
+
|
|
3
|
+
## 1. 목적
|
|
4
|
+
- AWS CLI/콘솔 인증 방식을 표준화하고, 운영에 맞는 방식(SSO 또는 Access Key)을 선택해 안전하게 설정한다.
|
|
5
|
+
|
|
6
|
+
## 2. SSO vs Access Key 비교
|
|
7
|
+
|
|
8
|
+
| 항목 | SSO (IAM Identity Center) | Access Key (IAM User) |
|
|
9
|
+
|---|---|---|
|
|
10
|
+
| 기본 개념 | 브라우저 로그인 후 단기 자격증명 사용 | 고정 `Access key ID/Secret access key` 사용 |
|
|
11
|
+
| 보안성 | 높음 (단기 토큰, 중앙 통제, MFA 연계 용이) | 상대적으로 낮음 (장기 키 유출 위험) |
|
|
12
|
+
| 권한 관리 | Permission Set 중심 중앙 관리 | 사용자/그룹 정책으로 개별 관리 |
|
|
13
|
+
| 감사 추적 | 사용자/역할 매핑이 명확 | 키 공유 시 추적성 저하 |
|
|
14
|
+
| 운영 편의 | 최초 구성은 복잡, 이후 일관성 높음 | 초기 진입 쉬움, 장기 운영 리스크 큼 |
|
|
15
|
+
| 만료/회전 | 자동 만료(재로그인) | 수동 회전 필요 |
|
|
16
|
+
| 권장 용도 | 사람(개발자/운영자) 인터랙티브 작업 | 레거시/임시 작업. 자동화는 가급적 Role/OIDC 권장 |
|
|
17
|
+
|
|
18
|
+
권장 기준:
|
|
19
|
+
- 사람의 일상 작업: `SSO` 우선
|
|
20
|
+
- 임시 테스트/단일 계정 빠른 접근: `Access Key` 가능
|
|
21
|
+
- CI/CD 같은 자동화: IAM User Access Key보다 `IAM Role`(OIDC/AssumeRole) 우선
|
|
22
|
+
|
|
23
|
+
## 3. SSO 설정 과정 (IAM Identity Center)
|
|
24
|
+
|
|
25
|
+
### 3.1 사전 조건
|
|
26
|
+
- AWS CLI v2
|
|
27
|
+
|
|
28
|
+
```powershell
|
|
29
|
+
aws --version
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
- `AWS Organizations` 미사용이면 먼저 조직 생성 필요
|
|
33
|
+
- IAM Identity Center는 `Organization instance` 사용 권장
|
|
34
|
+
|
|
35
|
+
### 3.2 콘솔 설정
|
|
36
|
+
1. `AWS Organizations`에서 `Create organization` 수행 (미사용 시)
|
|
37
|
+
2. `IAM Identity Center` 활성화
|
|
38
|
+
3. `AWS access portal URL` 확인
|
|
39
|
+
- 예: `https://d-xxxxxxxxxx.awsapps.com/start`
|
|
40
|
+
4. `Permission set` 생성
|
|
41
|
+
- 예: `AdministratorAccess`, `ReadOnlyAccess`
|
|
42
|
+
5. 사용자/그룹에 대상 계정 + Permission Set 할당
|
|
43
|
+
|
|
44
|
+
### 3.3 로컬 CLI 설정
|
|
45
|
+
```powershell
|
|
46
|
+
aws configure sso --profile default
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
입력 항목:
|
|
50
|
+
- `SSO start URL`: 포털 URL
|
|
51
|
+
- `SSO region`: Identity Center 리전
|
|
52
|
+
- `Account` / `Role`: 할당된 항목 선택
|
|
53
|
+
- `Default region`: 예) `ap-southeast-1`
|
|
54
|
+
- `Default output`: `json`
|
|
55
|
+
|
|
56
|
+
로그인/검증:
|
|
57
|
+
|
|
58
|
+
```powershell
|
|
59
|
+
aws sso login --profile default
|
|
60
|
+
aws sts get-caller-identity --profile default
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## 4. Access Key 설정 과정 (IAM User)
|
|
64
|
+
|
|
65
|
+
### 4.1 사전 조건
|
|
66
|
+
- IAM 사용자 권한 정책이 먼저 정의되어 있어야 함
|
|
67
|
+
- `Root` 계정 Access Key는 사용 금지
|
|
68
|
+
|
|
69
|
+
### 4.2 콘솔에서 키 발급
|
|
70
|
+
1. AWS 콘솔 `IAM > Users > (본인 사용자) > Security credentials`
|
|
71
|
+
2. `Create access key` 선택
|
|
72
|
+
3. 사용 시나리오 선택 후 키 생성
|
|
73
|
+
4. `Access key ID`, `Secret access key` 안전 저장
|
|
74
|
+
- Secret은 생성 시점에만 확인 가능
|
|
75
|
+
|
|
76
|
+
### 4.3 로컬 CLI 등록
|
|
77
|
+
```powershell
|
|
78
|
+
aws configure --profile default
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
입력 항목:
|
|
82
|
+
- `AWS Access Key ID`
|
|
83
|
+
- `AWS Secret Access Key`
|
|
84
|
+
- `Default region name` (예: `ap-southeast-1`)
|
|
85
|
+
- `Default output format` (`json`)
|
|
86
|
+
|
|
87
|
+
검증:
|
|
88
|
+
|
|
89
|
+
```powershell
|
|
90
|
+
aws sts get-caller-identity --profile default
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
### 4.4 회전(Rotation) 권장 절차
|
|
94
|
+
1. 두 번째 키를 먼저 발급
|
|
95
|
+
2. 애플리케이션/로컬 설정을 새 키로 전환
|
|
96
|
+
3. 정상 동작 검증
|
|
97
|
+
4. 이전 키 비활성화/삭제
|
|
98
|
+
|
|
99
|
+
## 5. 공통 점검 명령
|
|
100
|
+
|
|
101
|
+
```powershell
|
|
102
|
+
aws configure list-profiles
|
|
103
|
+
aws sts get-caller-identity --profile default
|
|
104
|
+
aws ec2 describe-regions --profile default
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## 6. 자주 발생하는 문제
|
|
108
|
+
|
|
109
|
+
### 6.1 SSO 오류: `Missing the following required SSO configuration values`
|
|
110
|
+
- 원인: `sso_start_url`, `sso_region` 누락
|
|
111
|
+
- 조치: `aws configure sso --profile default` 재실행
|
|
112
|
+
|
|
113
|
+
### 6.2 SSO 오류: `Unable to locate credentials`
|
|
114
|
+
- 원인: 로그인 전
|
|
115
|
+
- 조치:
|
|
116
|
+
|
|
117
|
+
```powershell
|
|
118
|
+
aws sso login --profile default
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### 6.3 Access Key 오류: `InvalidClientTokenId` 또는 `SignatureDoesNotMatch`
|
|
122
|
+
- 원인: 키 오입력 또는 비활성/삭제된 키 사용
|
|
123
|
+
- 조치: 키 재발급 후 `aws configure` 재등록
|
|
124
|
+
|
|
125
|
+
### 6.4 AccessDenied
|
|
126
|
+
- 원인: 역할/사용자 권한 부족
|
|
127
|
+
- 조치: 정책 또는 Permission Set 조정
|
|
128
|
+
|
|
129
|
+
## 7. 운영 권장안
|
|
130
|
+
- 기본 전략: 사람은 `SSO`, 자동화는 `Role`, 장기 `Access Key` 최소화
|
|
131
|
+
- 변경 권한과 조회 권한 분리 (예: 운영은 `ReadOnly` 기본)
|
|
132
|
+
- 키/권한 변경 시 즉시 검증 명령 실행
|
|
133
|
+
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# AWS 인증 설정 가이드 (SSO / Access Key)
|
|
2
|
+
|
|
3
|
+
이 문서는 `mcp-aws-manager` 사용 전 필요한 AWS 인증 설정을 한국어로 정리한 가이드입니다.
|
|
4
|
+
|
|
5
|
+
## 어떤 방식이 더 좋은가
|
|
6
|
+
|
|
7
|
+
- 권장: `SSO` (IAM Identity Center)
|
|
8
|
+
- 대안: `Access Key` (정책/조직 제약상 SSO 불가 시)
|
|
9
|
+
|
|
10
|
+
SSO 권장 이유:
|
|
11
|
+
|
|
12
|
+
- 장기 키를 로컬에 보관하지 않아 보안 위험 감소
|
|
13
|
+
- MFA와 세션 만료 관리가 쉬움
|
|
14
|
+
- 조직 단위 권한/회수 정책과 잘 맞음
|
|
15
|
+
|
|
16
|
+
## 1) SSO 설정
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
aws configure sso --profile default
|
|
20
|
+
aws sso login --profile default
|
|
21
|
+
aws sts get-caller-identity --profile default
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
정상이라면 마지막 명령에서 `Account`, `Arn`, `UserId`가 출력됩니다.
|
|
25
|
+
|
|
26
|
+
## 2) Access Key 설정
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
aws configure --profile default
|
|
30
|
+
aws sts get-caller-identity --profile default
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## 3) 현재 상태 점검
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
aws configure list-profiles
|
|
37
|
+
aws configure list --profile default
|
|
38
|
+
aws sts get-caller-identity --profile default
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## 4) 자주 나는 오류
|
|
42
|
+
|
|
43
|
+
`Unable to locate credentials`
|
|
44
|
+
|
|
45
|
+
- 원인: 인증 미설정 또는 SSO 로그인 만료
|
|
46
|
+
- 조치: SSO 로그인 재실행 또는 Access Key 재설정
|
|
47
|
+
|
|
48
|
+
`AccessDenied` / `not authorized`
|
|
49
|
+
|
|
50
|
+
- 원인: IAM 권한 부족
|
|
51
|
+
- 조치: 필요한 API 권한 정책 추가
|
|
52
|
+
|
|
53
|
+
## 5) mcp-aws-manager 사용 전 최소 준비
|
|
54
|
+
|
|
55
|
+
- 조회 중심이면: AWS API 조회 권한 + 인증(SSO 또는 Access Key)
|
|
56
|
+
- EC2 런타임(SSM)도 보려면:
|
|
57
|
+
- 인스턴스 프로파일에 `AmazonSSMManagedInstanceCore`
|
|
58
|
+
- SSM Agent 정상
|
|
59
|
+
- SSM 통신 가능한 네트워크/엔드포인트
|
|
60
|
+
|
|
61
|
+
## 6) 인증이 아예 불가한 환경이라면
|
|
62
|
+
|
|
63
|
+
수동 모드로 진행 가능합니다.
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
mcp-aws-manager discover --manual-server-list ./servers.csv --pem-paths C:\keys\prod.pem --no-progress
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
- 서버 목록(JSON/CSV)을 직접 제공
|
|
70
|
+
- PEM SSH 기반으로 런타임 스냅샷 수행
|
|
@@ -7,6 +7,10 @@ This document lists MCP/API/CLI integrations used by `mcp-aws-manager`.
|
|
|
7
7
|
Tools:
|
|
8
8
|
|
|
9
9
|
- `discover_ec2_with_ssm`
|
|
10
|
+
- `ec2_start_instances`
|
|
11
|
+
- `ec2_stop_instances`
|
|
12
|
+
- `ec2_reboot_instances`
|
|
13
|
+
- `ec2_apply_instance_profile`
|
|
10
14
|
- `mcp_aws_discover_cli_help`
|
|
11
15
|
|
|
12
16
|
Files:
|
|
@@ -32,6 +36,13 @@ File:
|
|
|
32
36
|
|
|
33
37
|
- `bin/mcp-aws-manager.js`
|
|
34
38
|
|
|
39
|
+
Coverage summary:
|
|
40
|
+
|
|
41
|
+
- AWS API "all features" are not fully implemented in this project.
|
|
42
|
+
- AWS API total has no fixed official single number because services/actions keep growing.
|
|
43
|
+
- Current implementation uses `9` AWS SDK service clients and `20` AWS SDK operations.
|
|
44
|
+
- AWS CLI integration count is `1` command (`aws sso login --profile <profile>`).
|
|
45
|
+
|
|
35
46
|
SDK clients:
|
|
36
47
|
|
|
37
48
|
- `@aws-sdk/client-sts`
|
|
@@ -47,7 +58,7 @@ SDK clients:
|
|
|
47
58
|
Core API calls:
|
|
48
59
|
|
|
49
60
|
- STS: `GetCallerIdentity`
|
|
50
|
-
- EC2: `DescribeRegions`, `DescribeInstances`, `DescribeIamInstanceProfileAssociations`, `AssociateIamInstanceProfile`, `ReplaceIamInstanceProfileAssociation`
|
|
61
|
+
- EC2: `DescribeRegions`, `DescribeInstances`, `StartInstances`, `StopInstances`, `RebootInstances`, `DescribeIamInstanceProfileAssociations`, `AssociateIamInstanceProfile`, `ReplaceIamInstanceProfileAssociation`
|
|
51
62
|
- SSM: `DescribeInstanceInformation`, `SendCommand`, `GetCommandInvocation`
|
|
52
63
|
- Lambda: `ListFunctions`
|
|
53
64
|
- ELBv2: `DescribeLoadBalancers`, `DescribeTargetGroups`
|
|
@@ -70,7 +81,31 @@ Purpose:
|
|
|
70
81
|
|
|
71
82
|
- Automatic recovery when SSO credentials expire.
|
|
72
83
|
|
|
73
|
-
## 5)
|
|
84
|
+
## 5) Manual inventory + SSH(PEM) fallback
|
|
85
|
+
|
|
86
|
+
File:
|
|
87
|
+
|
|
88
|
+
- `bin/mcp-aws-manager.js`
|
|
89
|
+
|
|
90
|
+
Behavior:
|
|
91
|
+
|
|
92
|
+
- When `--manual-server-list` is set, inventory is loaded from JSON/CSV without AWS API auth.
|
|
93
|
+
- Optional runtime snapshot uses local OpenSSH client with PEM keys (`--pem-paths` / per-row `pemPath`).
|
|
94
|
+
- Manual rows are normalized into the same EC2 output schema.
|
|
95
|
+
|
|
96
|
+
## 6) GUI report output
|
|
97
|
+
|
|
98
|
+
File:
|
|
99
|
+
|
|
100
|
+
- `bin/mcp-aws-manager.js`
|
|
101
|
+
|
|
102
|
+
Behavior:
|
|
103
|
+
|
|
104
|
+
- `discover` supports `--html-out <path>` to generate interactive local HTML inventory report.
|
|
105
|
+
- Report supports search/filter and client-side CSV download from current view.
|
|
106
|
+
- Optional `--open-html` tries opening the generated report in default browser.
|
|
107
|
+
|
|
108
|
+
## 7) Local MCP client registration automation
|
|
74
109
|
|
|
75
110
|
Supported clients:
|
|
76
111
|
|
|
@@ -82,9 +117,8 @@ Supported clients:
|
|
|
82
117
|
|
|
83
118
|
The setup flow tries multiple `mcp` command variants (`get/show`, `add`, `remove/rm`, scope variations) to maximize compatibility.
|
|
84
119
|
|
|
85
|
-
##
|
|
120
|
+
## 8) Related docs
|
|
86
121
|
|
|
87
122
|
- `README.md`
|
|
88
|
-
- `USAGE_GUIDE.md`
|
|
89
123
|
- `MCP_CLIENT_SETUP.md`
|
|
90
124
|
- `MCP_DIFFERENTIATION.md`
|
package/MCP_CLIENT_SETUP.md
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# MCP Client Setup (stdio)
|
|
2
2
|
|
|
3
|
+
Korean translation: `MCP_CLIENT_SETUP_KO.md`
|
|
4
|
+
|
|
3
5
|
This project provides an MCP stdio wrapper around the SSM-first AWS operations CLI.
|
|
4
6
|
|
|
5
7
|
- Preferred CLI command: `mcp-aws-manager`
|
|
@@ -27,7 +29,7 @@ mcp-aws-manager doctor
|
|
|
27
29
|
|
|
28
30
|
## Agent-Led Setup Flow
|
|
29
31
|
|
|
30
|
-
Detailed onboarding flow is maintained in `
|
|
32
|
+
Detailed onboarding flow is maintained in `README.md` ("Agent-Assisted First-Time Setup").
|
|
31
33
|
This document only covers MCP server registration/configuration.
|
|
32
34
|
|
|
33
35
|
## Explicit Registration
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
# MCP 클라이언트 설정 가이드 (stdio)
|
|
2
|
+
|
|
3
|
+
이 프로젝트는 `mcp-aws-manager` CLI를 감싸는 MCP stdio 서버를 제공합니다.
|
|
4
|
+
|
|
5
|
+
- 권장 CLI 명령: `mcp-aws-manager`
|
|
6
|
+
- 권장 MCP 서버 명령: `mcp-aws-manager-mcp`
|
|
7
|
+
|
|
8
|
+
## 노출 도구
|
|
9
|
+
|
|
10
|
+
조회:
|
|
11
|
+
|
|
12
|
+
- `discover_ec2_with_ssm`
|
|
13
|
+
- `mcp_aws_discover_cli_help`
|
|
14
|
+
|
|
15
|
+
변경:
|
|
16
|
+
|
|
17
|
+
- `ec2_start_instances`
|
|
18
|
+
- `ec2_stop_instances`
|
|
19
|
+
- `ec2_reboot_instances`
|
|
20
|
+
- `ec2_apply_instance_profile`
|
|
21
|
+
|
|
22
|
+
## 권장 설치(1회)
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
npm install -g mcp-aws-manager
|
|
26
|
+
mcp-aws-manager
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
`mcp-aws-manager`를 인자 없이 실행하면 bootstrap이 동작하며, 감지된 클라이언트(`codex`, `claude` 기본)에 MCP 서버를 등록합니다.
|
|
30
|
+
|
|
31
|
+
검증:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
mcp-aws-manager doctor
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## 명시적 등록
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
mcp-aws-manager setup
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
이름/명령 커스텀:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
mcp-aws-manager setup --name mcp-aws-manager --mcp-command mcp-aws-manager-mcp --clients codex,claude
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Cursor/Windsurf/Antigravity 예시:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
mcp-aws-manager setup --name mcp-aws-manager --mcp-command mcp-aws-manager-mcp --clients cursor,windsurf,antigravity
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## 수동 설정(자동 등록 불가 시)
|
|
56
|
+
|
|
57
|
+
### 1) 로컬 저장소(개발)
|
|
58
|
+
|
|
59
|
+
```json
|
|
60
|
+
{
|
|
61
|
+
"mcpServers": {
|
|
62
|
+
"mcp-aws-manager": {
|
|
63
|
+
"command": "node",
|
|
64
|
+
"args": [
|
|
65
|
+
"C:/Users/mybin/gesia/mcp_aws/bin/mcp-aws-manager-mcp.js"
|
|
66
|
+
],
|
|
67
|
+
"cwd": "C:/Users/mybin/gesia/mcp_aws"
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### 2) 전역 npm 설치 사용
|
|
74
|
+
|
|
75
|
+
```json
|
|
76
|
+
{
|
|
77
|
+
"mcpServers": {
|
|
78
|
+
"mcp-aws-manager": {
|
|
79
|
+
"command": "mcp-aws-manager-mcp"
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### 3) npx 사용(전역 설치 없이)
|
|
86
|
+
|
|
87
|
+
```json
|
|
88
|
+
{
|
|
89
|
+
"mcpServers": {
|
|
90
|
+
"mcp-aws-manager": {
|
|
91
|
+
"command": "npx",
|
|
92
|
+
"args": [
|
|
93
|
+
"-y",
|
|
94
|
+
"-p",
|
|
95
|
+
"mcp-aws-manager",
|
|
96
|
+
"mcp-aws-manager-mcp"
|
|
97
|
+
]
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## 참고
|
|
104
|
+
|
|
105
|
+
- 런타임 접근 기본은 SSM 우선이며, 필요 시 수동 서버리스트 + PEM SSH 경로를 사용합니다.
|
|
106
|
+
- 실행 경로는 이 패키지 내부 AWS SDK/CLI를 사용합니다(외부 AWS 관리 MCP 백엔드 미의존).
|
|
107
|
+
- 지원 클라이언트: `codex`, `claude`, `cursor`, `windsurf`, `antigravity`.
|
package/README.md
CHANGED
|
@@ -1,51 +1,269 @@
|
|
|
1
1
|
# mcp-aws-manager
|
|
2
2
|
|
|
3
|
-
AWS operations CLI
|
|
3
|
+
AWS operations CLI + MCP stdio server (SSM-first).
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
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.
|
|
6
|
+
|
|
7
|
+
## TL;DR
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install -g mcp-aws-manager
|
|
11
|
+
mcp-aws-manager
|
|
12
|
+
mcp-aws-manager doctor
|
|
13
|
+
mcp-aws-manager discover --profiles default --no-progress
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## What It Does
|
|
17
|
+
|
|
18
|
+
- Multi-service inventory: EC2, Lambda, ALB/NLB, ASG, RDS, ElastiCache, Route53
|
|
19
|
+
- SSM state visibility: managed/online status
|
|
20
|
+
- Optional runtime snapshot and SSM remediation
|
|
21
|
+
- Manual fallback mode: JSON/CSV server list + PEM SSH runtime snapshot (when AWS auth is unavailable)
|
|
22
|
+
- Human-in-the-loop retry flow via `ACTION_REQUIRED`
|
|
23
|
+
- Internal-only execution path (AWS SDK + AWS CLI)
|
|
24
|
+
|
|
25
|
+
## API Coverage Snapshot
|
|
26
|
+
|
|
27
|
+
- 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).
|
|
28
|
+
- Current implementation scope is not "all AWS APIs".
|
|
29
|
+
- AWS SDK service clients used: `9`
|
|
30
|
+
- AWS SDK operation calls used: `20`
|
|
31
|
+
- AWS CLI commands used: `1` (`aws sso login --profile <profile>`)
|
|
32
|
+
|
|
33
|
+
Current 20 AWS SDK operations:
|
|
34
|
+
|
|
35
|
+
- STS: `GetCallerIdentity`
|
|
36
|
+
- EC2: `DescribeRegions`, `DescribeInstances`, `StartInstances`, `StopInstances`, `RebootInstances`, `DescribeIamInstanceProfileAssociations`, `AssociateIamInstanceProfile`, `ReplaceIamInstanceProfileAssociation`
|
|
37
|
+
- SSM: `DescribeInstanceInformation`, `SendCommand`, `GetCommandInvocation`
|
|
38
|
+
- Lambda: `ListFunctions`
|
|
39
|
+
- ELBv2: `DescribeLoadBalancers`, `DescribeTargetGroups`
|
|
40
|
+
- Auto Scaling: `DescribeAutoScalingGroups`
|
|
41
|
+
- RDS: `DescribeDBInstances`
|
|
42
|
+
- ElastiCache: `DescribeCacheClusters`
|
|
43
|
+
- Route53: `ListHostedZones`, `ListResourceRecordSets`
|
|
44
|
+
|
|
45
|
+
## Binaries
|
|
6
46
|
|
|
7
47
|
- CLI: `mcp-aws-manager`
|
|
8
48
|
- MCP stdio server: `mcp-aws-manager-mcp`
|
|
9
49
|
|
|
10
|
-
|
|
50
|
+
## Agent-Assisted First-Time Setup
|
|
11
51
|
|
|
12
|
-
|
|
13
|
-
- EC2 inventory discovery (multi profile / multi region)
|
|
14
|
-
- Optional Lambda function inventory (same profile/region sweep)
|
|
15
|
-
- Optional ALB/NLB + Target Group inventory
|
|
16
|
-
- Optional Auto Scaling Group inventory
|
|
17
|
-
- Optional RDS inventory
|
|
18
|
-
- Optional ElastiCache inventory
|
|
19
|
-
- Optional Route53 hosted zone inventory
|
|
20
|
-
- SSM management and online-state visibility
|
|
21
|
-
- Optional SSM runtime snapshot collection (`RunCommand`)
|
|
22
|
-
- Optional SSM auto-remediation (instance profile association)
|
|
23
|
-
- Human-in-the-loop guidance via `ACTION_REQUIRED` messages
|
|
24
|
-
- JSON/CSV output (CLI)
|
|
25
|
-
- MCP registration bootstrap helpers (`codex`, `claude`, `cursor`, `windsurf`, `antigravity`)
|
|
52
|
+
Use this flow for new users.
|
|
26
53
|
|
|
27
|
-
|
|
54
|
+
1. Install and bootstrap:
|
|
28
55
|
|
|
29
56
|
```bash
|
|
30
|
-
npm install -g mcp-aws-manager
|
|
57
|
+
npm.cmd install -g mcp-aws-manager@latest
|
|
58
|
+
mcp-aws-manager
|
|
31
59
|
```
|
|
32
60
|
|
|
33
|
-
|
|
61
|
+
2. Health check:
|
|
34
62
|
|
|
35
|
-
|
|
63
|
+
```bash
|
|
64
|
+
mcp-aws-manager doctor
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
3. Configure AWS auth (SSO recommended):
|
|
36
68
|
|
|
37
69
|
```bash
|
|
38
|
-
|
|
70
|
+
aws configure sso --profile default
|
|
71
|
+
aws sso login --profile default
|
|
39
72
|
```
|
|
40
73
|
|
|
41
|
-
|
|
74
|
+
4. Verify identity:
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
aws sts get-caller-identity --profile default
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
5. Run discovery:
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
mcp-aws-manager discover --profiles default --no-progress
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
If blocked, follow one `ACTION_REQUIRED` item, then retry the same command.
|
|
87
|
+
|
|
88
|
+
If AWS auth is not available, use manual fallback:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
mcp-aws-manager discover --manual-server-list ./servers.csv --pem-paths C:\keys\prod.pem --no-progress
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Generate GUI report (interactive HTML):
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
mcp-aws-manager discover --profiles default --html-out ./inventory.html --no-progress
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
## User Confirmation Required
|
|
101
|
+
|
|
102
|
+
These are normally the only manual steps (agent-guided):
|
|
103
|
+
|
|
104
|
+
- SSO browser login and MFA confirmation
|
|
105
|
+
- IAM permission approval in organization account
|
|
106
|
+
- For EC2 runtime visibility: attach `AmazonSSMManagedInstanceCore` and keep SSM Agent/network healthy
|
|
107
|
+
|
|
108
|
+
## MCP Tool Usage
|
|
109
|
+
|
|
110
|
+
Run MCP server:
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
mcp-aws-manager-mcp
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Exposed MCP tools:
|
|
117
|
+
|
|
118
|
+
- `discover_ec2_with_ssm`
|
|
119
|
+
- `ec2_start_instances`
|
|
120
|
+
- `ec2_stop_instances`
|
|
121
|
+
- `ec2_reboot_instances`
|
|
122
|
+
- `ec2_apply_instance_profile`
|
|
123
|
+
- `mcp_aws_discover_cli_help`
|
|
124
|
+
|
|
125
|
+
Mutation tool examples:
|
|
126
|
+
|
|
127
|
+
- `ec2_start_instances`: `{ "profile": "default", "region": "ap-southeast-1", "instanceIds": ["i-123"] }`
|
|
128
|
+
- `ec2_stop_instances`: `{ "profile": "default", "region": "ap-southeast-1", "instanceIds": ["i-123"], "force": false }`
|
|
129
|
+
- `ec2_reboot_instances`: `{ "profile": "default", "region": "ap-southeast-1", "instanceIds": ["i-123"] }`
|
|
130
|
+
- `ec2_apply_instance_profile`: `{ "profile": "default", "region": "ap-southeast-1", "instanceId": "i-123", "instanceProfileName": "my-ssm-profile", "allowReplaceProfile": true }`
|
|
131
|
+
|
|
132
|
+
Example tool args:
|
|
133
|
+
|
|
134
|
+
```json
|
|
135
|
+
{
|
|
136
|
+
"profiles": ["default"],
|
|
137
|
+
"regions": ["ap-northeast-2"],
|
|
138
|
+
"includeLambda": true,
|
|
139
|
+
"publicOnly": true,
|
|
140
|
+
"runtimeSnapshot": true,
|
|
141
|
+
"htmlOutPath": "C:\\tmp\\inventory.html",
|
|
142
|
+
"openHtml": true,
|
|
143
|
+
"manualServerListPath": "C:\\tmp\\servers.csv",
|
|
144
|
+
"pemPaths": ["C:\\keys\\prod.pem"],
|
|
145
|
+
"sshUser": "ec2-user",
|
|
146
|
+
"sshPort": 22,
|
|
147
|
+
"sshConnectTimeoutSec": 8,
|
|
148
|
+
"autoSsoLogin": true,
|
|
149
|
+
"noProgress": true
|
|
150
|
+
}
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
## Action Codes
|
|
154
|
+
|
|
155
|
+
Common `ACTION_REQUIRED` codes:
|
|
156
|
+
|
|
157
|
+
- `SSO_LOGIN_NEEDED`
|
|
158
|
+
- `AWS_CREDENTIALS_REQUIRED`
|
|
159
|
+
- `IAM_PERMISSION_REQUIRED`
|
|
160
|
+
- `AWS_OPERATION_FAILED`
|
|
161
|
+
- `SSM_ROLE_OR_AGENT_REQUIRED`
|
|
162
|
+
- `INSTANCE_HAS_PROFILE`
|
|
163
|
+
- `IAM_PROFILE_ASSOCIATION_FAILED`
|
|
164
|
+
- `SSM_RUNCOMMAND_PERMISSION_REQUIRED`
|
|
165
|
+
- `LAMBDA_LIST_PERMISSION_REQUIRED`
|
|
166
|
+
- `ELBV2_LIST_PERMISSION_REQUIRED`
|
|
167
|
+
- `ASG_LIST_PERMISSION_REQUIRED`
|
|
168
|
+
- `RDS_LIST_PERMISSION_REQUIRED`
|
|
169
|
+
- `ELASTICACHE_LIST_PERMISSION_REQUIRED`
|
|
170
|
+
- `ROUTE53_LIST_PERMISSION_REQUIRED`
|
|
171
|
+
- `MANUAL_SERVER_LIST_EMPTY`
|
|
172
|
+
- `MANUAL_SERVER_HOST_REQUIRED`
|
|
173
|
+
- `PEM_KEY_NOT_FOUND`
|
|
174
|
+
- `PEM_MAPPING_REQUIRED`
|
|
175
|
+
- `SSH_CLIENT_NOT_FOUND`
|
|
176
|
+
- `SSH_AUTH_OR_CONNECT_FAILED`
|
|
177
|
+
|
|
178
|
+
<details>
|
|
179
|
+
<summary>Detailed AWS Auth Setup (SSO vs Access Key)</summary>
|
|
180
|
+
|
|
181
|
+
SSO is recommended because:
|
|
182
|
+
|
|
183
|
+
- Avoids long-lived access keys on user machines
|
|
184
|
+
- Enforces session-based login and MFA more easily
|
|
185
|
+
- Improves centralized revoke/audit handling
|
|
186
|
+
|
|
187
|
+
SSO setup:
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
aws configure sso --profile default
|
|
191
|
+
aws sso login --profile default
|
|
192
|
+
aws sts get-caller-identity --profile default
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Access key setup (optional):
|
|
196
|
+
|
|
197
|
+
```bash
|
|
198
|
+
aws configure --profile default
|
|
199
|
+
aws sts get-caller-identity --profile default
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
</details>
|
|
203
|
+
|
|
204
|
+
<details>
|
|
205
|
+
<summary>Discover Option Reference</summary>
|
|
206
|
+
|
|
207
|
+
- `--profiles <a,b,c>`
|
|
208
|
+
- `--regions <a,b,c>`
|
|
209
|
+
- `--instance-ids <id1,id2>`
|
|
210
|
+
- `--include-lambda`
|
|
211
|
+
- `--include-ec2` / `--no-ec2`
|
|
212
|
+
- `--include-alb` / `--no-include-alb`
|
|
213
|
+
- `--include-asg` / `--no-include-asg`
|
|
214
|
+
- `--include-rds` / `--no-include-rds`
|
|
215
|
+
- `--include-elasticache` / `--no-include-elasticache`
|
|
216
|
+
- `--include-route53` / `--no-include-route53`
|
|
217
|
+
- `--public-only`
|
|
218
|
+
- `--managed-only`
|
|
219
|
+
- `--auto-remediate-ssm`
|
|
220
|
+
- `--ssm-instance-profile-name <name>` / `--ssm-instance-profile-arn <arn>`
|
|
221
|
+
- `--allow-replace-profile`
|
|
222
|
+
- `--runtime-snapshot` / `--no-runtime-snapshot`
|
|
223
|
+
- `--snapshot-timeout <seconds>`
|
|
224
|
+
- `--snapshot-concurrency <n>`
|
|
225
|
+
- `--snapshot-max-kb <n>`
|
|
226
|
+
- `--manual-server-list <path>` (JSON/CSV)
|
|
227
|
+
- `--pem-paths <a,b,c>`
|
|
228
|
+
- `--ssh-user <name>`
|
|
229
|
+
- `--ssh-port <port>`
|
|
230
|
+
- `--ssh-connect-timeout <seconds>`
|
|
231
|
+
- `--html-out <path>`
|
|
232
|
+
- `--open-html`
|
|
233
|
+
- `--auto-sso-login` / `--no-auto-sso-login`
|
|
234
|
+
- `--format <json|csv>`
|
|
235
|
+
- `--out <path>`
|
|
236
|
+
|
|
237
|
+
</details>
|
|
238
|
+
|
|
239
|
+
<details>
|
|
240
|
+
<summary>Permission Checklist</summary>
|
|
241
|
+
|
|
242
|
+
Minimum permissions depend on enabled features.
|
|
243
|
+
|
|
244
|
+
- Core inventory: `ec2:DescribeRegions`, `ec2:DescribeInstances`
|
|
245
|
+
- Lambda: `lambda:ListFunctions`
|
|
246
|
+
- ALB/TargetGroups: `elasticloadbalancing:DescribeLoadBalancers`, `elasticloadbalancing:DescribeTargetGroups`
|
|
247
|
+
- ASG: `autoscaling:DescribeAutoScalingGroups`
|
|
248
|
+
- RDS: `rds:DescribeDBInstances`
|
|
249
|
+
- ElastiCache: `elasticache:DescribeCacheClusters`
|
|
250
|
+
- Route53: `route53:ListHostedZones`, `route53:ListResourceRecordSets`
|
|
251
|
+
- Runtime snapshot: `ssm:SendCommand`, `ssm:GetCommandInvocation`, `ssm:DescribeInstanceInformation`
|
|
252
|
+
- Auto-remediation: `ec2:AssociateIamInstanceProfile`, optional `ec2:ReplaceIamInstanceProfileAssociation`, `iam:PassRole`
|
|
253
|
+
|
|
254
|
+
Manual fallback mode:
|
|
255
|
+
|
|
256
|
+
- Inventory uses user-provided server list file (no AWS API required)
|
|
257
|
+
- Runtime snapshot uses local `ssh` client + PEM key access
|
|
42
258
|
|
|
43
|
-
|
|
259
|
+
</details>
|
|
44
260
|
|
|
45
|
-
##
|
|
261
|
+
## Related Docs
|
|
46
262
|
|
|
47
|
-
-
|
|
48
|
-
- MCP client registration
|
|
49
|
-
-
|
|
50
|
-
-
|
|
51
|
-
-
|
|
263
|
+
- `README_KO.md`: Korean overview and quick start
|
|
264
|
+
- `MCP_CLIENT_SETUP_KO.md`: Korean MCP client registration guide
|
|
265
|
+
- `AWS_SSO_SETUP_GUIDE_KO.md`: Korean AWS auth setup guide
|
|
266
|
+
- `MCP_CLIENT_SETUP.md`: MCP registration and stdio config details
|
|
267
|
+
- `AGENT_GUIDANCE_LOOP_TEMPLATE_KO.md`: agent retry/guidance template
|
|
268
|
+
- `IMPLEMENTATION_INTEGRATIONS.md`: API/CLI integration inventory
|
|
269
|
+
- `MCP_DIFFERENTIATION.md`: differentiation from existing AWS MCP servers
|