mcp-aws-manager 0.3.8 → 0.4.0

package/README_KO.md

@@ -1,8 +1,8 @@
-# mcp-aws-manager (한국어 안내)
+# mcp-aws-manager (한국어 안내)
 
-AWS 운영 작업용 CLI + MCP stdio 서버입니다.
+SSM 우선(SSM-first) 방식의 AWS 운영 CLI + MCP stdio 서버입니다.
 
-이 패키지는 AWS 인벤토리/런타임/완화 작업을 정규화된 출력 스키마와 `ACTION_REQUIRED` 가이드로 제공합니다. 단순 AWS CLI 래퍼가 아니라, 에이전트 친화적인 운영 워크플로우를 목표로 합니다.
+이 패키지는 AWS 운영 작업(인벤토리/런타임/조치)을 정규화된 응답 스키마와 `ACTION_REQUIRED` 가이드로 제공합니다. 단순 AWS CLI 래퍼가 아니라, 에이전트 친화적인 운영 워크플로우 실행을 목표로 합니다.
 
 ## 빠른 시작
 
@@ -13,105 +13,939 @@ 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`로 표준화
+## 무엇을 제공하나요
+
+- 멀티 서비스 인벤토리: EC2, Lambda, ALB/NLB, ASG, RDS, ElastiCache, Route53, VPC/Subnet/SecurityGroup, ECS, S3, IAM, KMS, CloudWatch, CloudTrail, Config, Secrets Manager, ECR, DynamoDB, SNS, EventBridge, SQS, ACM, Kinesis, MSK, Budgets, Cost Anomaly, EBS, EFS, EKS, API Gateway (REST/v2), CloudFront, WAF, Shield, Step Functions, CloudWatch Logs, X-Ray, Inspector2, Redshift, OpenSearch, Organizations, ControlTower
+- SSM 상태 가시성: managed/online
+- 도메인 분석 파이프라인: IaC drift, CI/CD signals, backup/DR posture, security posture, FinOps cost signals, application layer health, incident severity recommendation
+- 선택적 런타임 스냅샷 및 SSM 자동 조치
+- 변경 표면 확장: EC2 + ECS + ASG + RDS + EKS 통제형 변경 도구
+- 정책 기반 라우팅: mode/surface/schema-tier 자동 선택
+- 대규모 운영 제어: Organizations AssumeRole fan-out + profile/region 샤딩
+- 인증 불가 시 수동 모드: JSON/CSV 서버 목록 + PEM SSH/ProxyJump/Bastion 런타임 스냅샷
+- `ACTION_REQUIRED` 기반 human-in-the-loop 재시도 루프
+- 내부 실행 경로 고정(AWS SDK + AWS CLI)
+- 출력 프레젠테이션 제어: output profile/sections/fields + client-aware 기본값
+- 거버넌스 로그 + topology/relationship JSON 산출물
+- incident webhook 연동 + incident payload artifact(선택)
+
+## 언제 쓰면 좋은가요
+
+`mcp-aws-manager`는 범용 AWS API 접근보다 운영 워크플로우 MCP가 필요할 때 적합합니다.
+
+- 인벤토리/런타임/조치 루프를 결정적으로 반복 실행하고 싶을 때
+- `ACTION_REQUIRED` 중심 운영 가이드와 산출물이 필요할 때
+- 단순 ad-hoc API 제어만 필요하면 범용 AWS MCP가 더 단순할 수 있습니다
+
+비교/경계는 아래 문서를 참고하세요.
+
+- `MCP_DIFFERENTIATION.md`
+
+## 빠른 비교 요약
+
+| 선택 포인트 | `mcp-aws-manager` | 범용 API형 AWS MCP |
+|---|---|---|
+| 1차 목적 | 운영 워크플로우(인벤토리/런타임/조치) 결정적 실행 | 광범위한 ad-hoc API/툴 접근 |
+| 도구 노출 모델 | 고정 gateway 3-tool (`capabilities_summary`, `capabilities_detail`, `gateway_execute`) | 서비스/액션별 다수 직접 툴 |
+| 변경 안전장치 | mutate 경로 확인/정책 게이트 내장 | 서버/툴별 정책 구현에 의존 |
+| 응답 계약 | 정규화(`ok/summary/records/requiredActions/meta`) | 구현마다 상이 |
+| 적합한 상황 | 반복 가능한 운영 루프 + 운영자 가이드 필요 | 탐색/실험 위주의 광범위 API 접근 |
+
+상세 근거와 경계는 `MCP_DIFFERENTIATION.md`, `MCP_DIFFERENTIATION_KO.md`를 참고하세요.
+
+## API 커버리지 스냅샷
+
+- AWS API 총량은 고정 숫자가 없으며(지속 증가), 전체 서비스 기준으로 매우 큽니다.
+- 현재 구현 범위는 "모든 AWS API"가 아닙니다.
+- 사용 중인 AWS SDK service clients: `49`
+- 사용 중인 AWS SDK operation calls: `95`
+- 사용 중인 AWS CLI commands: `1` (`aws sso login --profile <profile>`)
+- 참고: 엔터프라이즈 제어(정책 게이트/롤백/거버넌스 검증)를 유지하면서 인벤토리 커버리지를 확장했습니다.
+
+현재 사용 중인 95개 AWS SDK 작업:
+
+- STS: `GetCallerIdentity`
+- EC2: `DescribeRegions`, `DescribeInstances`, `DescribeVpcs`, `DescribeSubnets`, `DescribeSecurityGroups`, `StartInstances`, `StopInstances`, `RebootInstances`, `DescribeIamInstanceProfileAssociations`, `AssociateIamInstanceProfile`, `ReplaceIamInstanceProfileAssociation`
+- SSM: `DescribeInstanceInformation`, `DescribeParameters`, `SendCommand`, `GetCommandInvocation`
+- Lambda: `ListFunctions`
+- ELBv2: `DescribeLoadBalancers`, `DescribeTargetGroups`
+- Auto Scaling: `DescribeAutoScalingGroups`, `SetDesiredCapacity`
+- RDS: `DescribeDBInstances`, `StartDBInstance`, `StopDBInstance`, `RebootDBInstance`
+- ElastiCache: `DescribeCacheClusters`
+- Route53: `ListHostedZones`, `ListResourceRecordSets`
+- ECS: `ListClusters`, `DescribeClusters`, `ListServices`, `DescribeServices`, `UpdateService`
+- S3: `ListBuckets`, `GetBucketLocation`
+- IAM: `ListRoles`
+- KMS: `ListKeys`, `DescribeKey`
+- CloudWatch: `DescribeAlarms`
+- CloudTrail: `DescribeTrails`
+- AWS Config: `DescribeConfigurationRecorders`, `DescribeConfigurationRecorderStatus`, `DescribeDeliveryChannels`, `DescribeConfigRules`, `DescribeComplianceByConfigRule`
+- Secrets Manager: `ListSecrets`
+- ECR: `DescribeRepositories`
+- DynamoDB: `ListTables`, `DescribeTable`
+- SNS: `ListTopics`
+- EventBridge: `ListEventBuses`
+- SQS: `ListQueues`, `GetQueueAttributes`
+- ACM: `ListCertificates`, `DescribeCertificate`
+- Kinesis: `ListStreams`, `DescribeStreamSummary`
+- MSK: `ListClustersV2`
+- AWS Budgets: `DescribeBudgets`
+- EBS: `DescribeVolumes`
+- EFS: `DescribeFileSystems`
+- EKS: `ListClusters`, `DescribeCluster`, `DescribeNodegroup`, `UpdateNodegroupConfig`
+- API Gateway (REST): `GetRestApis`
+- API Gateway v2: `GetApis`
+- CloudFront: `ListDistributions`
+- WAFv2: `ListWebACLs`
+- Shield: `ListProtections`
+- Step Functions: `ListStateMachines`
+- CloudWatch Logs: `DescribeLogGroups`
+- X-Ray: `GetGroups`
+- Inspector2: `ListFindings`
+- Redshift: `DescribeClusters`
+- OpenSearch: `ListDomainNames`, `DescribeDomain`
+- Organizations: `ListAccounts`
+- ControlTower: `ListLandingZones`
+- CloudFormation: `DescribeStacks`
+- CodePipeline: `ListPipelines`, `ListPipelineExecutions`
+- CodeBuild: `ListProjects`, `ListBuildsForProject`, `BatchGetBuilds`
+- CodeDeploy: `ListApplications`, `ListDeploymentGroups`, `ListDeployments`, `BatchGetDeployments`
+- AWS Backup: `ListBackupPlans`, `ListProtectedResources`
+- SecurityHub: `GetFindings`
+- GuardDuty: `ListDetectors`, `ListFindings`
+- Cost Explorer: `GetCostAndUsage`, `GetAnomalies`, `GetSavingsPlansUtilization`, `GetReservationCoverage`
 
 ## 바이너리
 
 - CLI: `mcp-aws-manager`
-- MCP stdio server: `mcp-aws-manager-mcp`
+- MCP stdio server (single-entry, 기본값: `--surface all`): `mcp-aws-manager-mcp`
+
+`mcp-aws-manager-mcp`는 gateway 라우팅 기반으로 surface 범위만 선택합니다.
+
+```bash
+mcp-aws-manager-mcp --surface all
+mcp-aws-manager-mcp --surface readonly
+mcp-aws-manager-mcp --surface mutate
+```
 
-## 최초 설정(권장 흐름)
+## 에이전트 보조 최초 설정
 
-1. 설치 및 부트스트랩
+신규 사용자는 아래 순서를 권장합니다.
+
+1. 설치 및 bootstrap:
 
 ```bash
 npm.cmd install -g mcp-aws-manager@latest
 mcp-aws-manager
 ```
 
-2. 상태 확인
+bootstrap/setup 기본 동작은 단일 서버 1개를 등록합니다.
+
+- `mcp-aws-manager` (single-entry, `--surface all`)
+
+명시적 등록 예시:
+
+```bash
+mcp-aws-manager setup
+mcp-aws-manager setup --clients codex,claude
+mcp-aws-manager setup --clients cursor,windsurf,antigravity
+```
+
+2. 상태 점검:
 
 ```bash
 mcp-aws-manager doctor
 ```
 
-3. AWS 인증 설정(권장: SSO)
+3. AWS 인증 설정(권장: SSO):
 
 ```bash
 aws configure sso --profile default
 aws sso login --profile default
 ```
 
-4. 인증 확인
+4. 인증 확인:
 
 ```bash
 aws sts get-caller-identity --profile default
 ```
 
-5. 인벤토리 실행
+5. 인벤토리 실행:
 
 ```bash
 mcp-aws-manager discover --profiles default --no-progress
 ```
 
-## 인증 불가 시 수동 모드
+실패 시 `ACTION_REQUIRED`를 1건 처리한 뒤 동일 명령으로 재시도하세요.
+
+AWS 인증이 불가능하면 수동 모드를 사용하세요.
 
 ```bash
 mcp-aws-manager discover --manual-server-list ./servers.csv --pem-paths C:\keys\prod.pem --no-progress
 ```
 
-## GUI 리포트
+GUI 리포트는 기본 생성됩니다(자동 경로: workspace/home `aws-inventory.html`).
 
 ```bash
 mcp-aws-manager discover --profiles default --no-progress
 ```
 
-- 기본 경로: 워크스페이스/홈 자동 선택(`aws-inventory.html`)
-- `--html-out <path>`: 리포트 경로 변경
-- `--open-html`: 생성 후 브라우저 오픈 강제
-- `--no-open-html`: 자동 오픈 비활성화
-- GUI에서 현재 뷰 기준 CSV 다운로드 가능
+GUI 포함 항목:
+
+- 요약 카드(레코드/서비스/프로필/리전/EC2/SSM/공인 IP/이슈)
+- 탭 뷰(`Report`, `Diagrams`, `Evidence`, `Inventory`)
+- 리소스 유형별 섹션을 포함한 상세 markdown 리포트(`report.md`)
+- 토폴로지 다이어그램(Profile -> Region -> Type -> Resource)
+- 관계 다이어그램(DNS / TargetGroup-ALB / ASG 휴리스틱 링크)
+- 리소스 상세와 집중 관계 다이어그램(`focus.svg`)을 포함한 포커스 서버/리소스 선택기
+- 증적 보기 및 내보내기(`evidence.json`)
+- 다이어그램 내보내기(`diagram.drawio`, `topology.svg`, `relationship.svg`)
+- 다운로드 파일명에 생성 시각 자동 포함(예: `report-20260304-113000.md`)
+
+경로/오픈 제어:
+
+```bash
+mcp-aws-manager discover --profiles default --html-out ./inventory.html --open-html --no-progress
+```
+
+기본값은 `open-html=true`입니다. 자동 오픈을 끄려면 `--no-open-html`을 사용하세요.
+
+### 수동 MCP 클라이언트 설정(대체 경로)
+
+자동 `bootstrap/setup`이 불가능한 환경에서만 사용하세요.
+
+1) 로컬 저장소(개발):
+
+```json
+{
+  "mcpServers": {
+    "mcp-aws-manager": {
+      "command": "node",
+      "args": [
+        "<repo>/bin/mcp-aws-manager-mcp.js",
+        "--surface",
+        "all"
+      ],
+      "cwd": "<repo>"
+    }
+  }
+}
+```
+
+2) 전역 npm 설치:
+
+```json
+{
+  "mcpServers": {
+    "mcp-aws-manager": {
+      "command": "mcp-aws-manager-mcp",
+      "args": ["--surface", "all"]
+    }
+  }
+}
+```
+
+3) `npx`(전역 설치 없이):
+
+```json
+{
+  "mcpServers": {
+    "mcp-aws-manager": {
+      "command": "npx",
+      "args": ["-y", "-p", "mcp-aws-manager", "mcp-aws-manager-mcp", "--surface", "all"]
+    }
+  }
+}
+```
+
+## 사용자 확인이 필요한 단계
+
+대부분 아래 항목만 수동으로 처리하면 됩니다.
+
+- SSO 브라우저 로그인 및 MFA 확인
+- 조직 계정의 IAM 권한 승인
+- EC2 런타임 가시성을 위해 `AmazonSSMManagedInstanceCore` 부여 및 SSM Agent/네트워크 정상화
+
+에이전트 재시도 루프(권장):
+
+1. 먼저 도구를 실행합니다.
+2. `requiresUserAction=false`이면 결과를 요약하고 종료합니다.
+3. `requiresUserAction=true`이면 `requiredActions[]`에서 한 건만 안내합니다.
+4. 사용자가 완료를 알리면 `guidance.retryTool` + `guidance.retryArgs`로 즉시 재실행합니다.
+5. `requiresUserAction=false`가 될 때까지 반복합니다.
+
+## MCP 도구 사용
+
+단일 엔트리 MCP 서버 실행(기본: `--surface all`):
+
+```bash
+mcp-aws-manager-mcp
+```
+
+노출 프로필 선택:
+
+- `mcp-aws-manager-mcp --surface all|readonly|mutate` (gateway-only)
+
+Gateway 모델은 `tools/list`에 정확히 3개만 노출합니다.
+
+- `capabilities_summary`
+- `capabilities_detail`
+- `gateway_execute`
+
+Gateway 호출 흐름:
+
+1. `capabilities_summary`로 카테고리/`operationId` 목록을 조회합니다.
+2. `capabilities_detail`로 선택한 `operationId`의 실행 계약을 확인합니다.
+3. `gateway_execute`로 `{ "operationId": "...", "args": { ... } }`를 실행합니다.
+
+대표 `operationId` 계열:
+
+- 조회 계열: `discover.aws_inventory_basic`, `discover.aws_inventory_advanced`, `discover.aws_inventory_summary`, `discover.aws_inventory_detail`, `discover.list_bedrock_endpoints`, `discover.list_sagemaker_endpoints`
+- 변경 계열: `mutate.ec2_start_instances`, `mutate.ec2_stop_instances`, `mutate.ec2_reboot_instances`, `mutate.ec2_apply_instance_profile`, `mutate.ec2_rollback_last_change`, `mutate.ecs_update_service_desired_count`, `mutate.asg_set_desired_capacity`, `mutate.rds_start_instances`, `mutate.rds_stop_instances`, `mutate.rds_reboot_instances`, `mutate.eks_update_nodegroup_scaling`
+- 거버넌스/시스템 계열: `governance.verify_chain`, `system.get_server_runtime`, `system.cli_help`
+
+Gateway execute 예시:
+
+- Discovery summary: `{ "operationId": "discover.aws_inventory_summary", "args": { "profiles": ["default"], "regions": ["ap-southeast-1"] } }`
+- Discovery detail: `{ "operationId": "discover.aws_inventory_detail", "args": { "profiles": ["default"], "regions": ["ap-southeast-1"], "resourceTypes": ["ec2"], "limit": 50 } }`
+- AI/ML 조회: `{ "operationId": "discover.list_bedrock_endpoints", "args": { "profile": "default", "region": "us-east-1", "metricWindowMinutes": 60 } }`
+- Mutation: `{ "operationId": "mutate.ec2_start_instances", "args": { "profile": "default", "region": "ap-southeast-1", "instanceIds": ["i-123"], "userConfirmation": "yes" } }`
+
+Discover 연산 참고:
+
+- `discover.aws_inventory_basic`: compact 입력 스키마
+- `discover.aws_inventory_advanced`: full 입력 스키마
+- `discover.aws_inventory_summary`: summary-first + selector hint
+- `discover.aws_inventory_detail`: 선택자 기반 상세/페이지 조회 (`resourceTypes`, `resourceIds`, `offset`, `limit`)
+- 출력 레이아웃 옵션: `outputProfile`, `sections`, `includeFields`, `excludeFields`, `rendererTemplate`
+- 라우팅/제어 옵션: `mode`, `schemaTier`, `userConfirmation`, `profileShard`, `regionShard`, `orgRoleName`, `orgAccountIds`, `orgIncludeAllAccounts`, `orgMaxAccounts`, `enterprisePolicyPath`, `approvalTicket`, `changeReason`
+- 증적/산출물 옵션: `topologyOutPath`, `relationshipsOutPath`, `governanceLogPath`, `verifyGovernanceChain`, `incidentWebhookUrl`, `incidentWebhookTimeoutMs`, `incidentWebhookAuthHeader`, `incidentWebhookToken`, `incidentOutPath`
+- `workingDirectory`는 allowlist(`cwd`, home, `MCP_AWS_ALLOWED_WORKDIRS`)로 검증됩니다.
+- stderr로 구조화 JSON 로그를 출력하며, `LOG_LEVEL=error|warn|info|debug`(기본 `info`)로 상세도를 제어할 수 있습니다.
+
+런타임 introspection:
+
+- gateway 모델: `gateway_execute` + `operationId: "system.get_server_runtime"`
+- 응답에는 현재 surface, 노출 연산/도구, confirmation 정책, response contract 메타가 포함됩니다.
+
+예시 tool args:
+
+```json
+{
+  "profiles": ["default"],
+  "regions": ["ap-northeast-2"],
+  "profileShard": { "index": 1, "total": 2 },
+  "regionShard": { "index": 1, "total": 3 },
+  "orgRoleName": "OrganizationAccountAccessRole",
+  "orgIncludeAllAccounts": false,
+  "orgAccountIds": ["111111111111", "222222222222"],
+  "orgMaxAccounts": 25,
+  "includeLambda": true,
+  "includeIac": true,
+  "includeCicd": true,
+  "includeBackupDr": true,
+  "includeSecurity": true,
+  "includeFinops": true,
+  "includeApplication": true,
+  "includeIncident": true,
+  "mode": "observe",
+  "schemaTier": "advanced",
+  "publicOnly": true,
+  "runtimeSnapshot": true,
+  "outputProfile": "operator",
+  "sections": ["overview", "runtime", "application", "actions"],
+  "includeFields": ["resourceType", "resourceId", "state", "ssmOnline", "runtimeSnapshotStatus"],
+  "excludeFields": ["runtimeSnapshotOutput"],
+  "clientProfile": "codex",
+  "rendererTemplate": "compact",
+  "userConfirmation": "yes",
+  "topologyOutPath": "C:\\tmp\\topology.json",
+  "relationshipsOutPath": "C:\\tmp\\relationships.json",
+  "governanceLogPath": "C:\\tmp\\governance.jsonl",
+  "incidentWebhookUrl": "https://example.com/hooks/oncall",
+  "incidentWebhookAuthHeader": "Authorization",
+  "incidentWebhookToken": "Bearer ***",
+  "incidentOutPath": "C:\\tmp\\incident.json",
+  "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
+
+자주 등장하는 `ACTION_REQUIRED` 코드:
+
+- `SSO_LOGIN_NEEDED`
+- `AWS_CREDENTIALS_REQUIRED`
+- `IAM_PERMISSION_REQUIRED`
+- `AWS_OPERATION_FAILED`
+- `SSM_ROLE_OR_AGENT_REQUIRED`
+- `INSTANCE_HAS_PROFILE`
+- `IAM_PROFILE_ASSOCIATION_FAILED`
+- `CHANGE_CONFIRMATION_REQUIRED`
+- `CHANGE_NOT_CONFIRMED`
+- `APPROVAL_TICKET_REQUIRED`
+- `APPROVAL_TICKET_INVALID`
+- `CHANGE_REASON_REQUIRED`
+- `ENTERPRISE_POLICY_NOT_FOUND`
+- `ENTERPRISE_POLICY_INVALID`
+- `ENTERPRISE_POLICY_BLOCKED_ACTION`
+- `ENTERPRISE_POLICY_DISCOVER_REMEDIATION_BLOCKED`
+- `ENTERPRISE_POLICY_BLOCKED_PROFILE`
+- `ENTERPRISE_POLICY_BLOCKED_REGION`
+- `ENTERPRISE_POLICY_BATCH_TOO_LARGE`
+- `INCIDENT_WEBHOOK_DISPATCH_FAILED`
+- `GOVERNANCE_LOG_WRITE_FAILED`
+- `GOVERNANCE_CHAIN_BROKEN`
+- `GOVERNANCE_LOG_NOT_FOUND`
+- `GOVERNANCE_LOG_INVALID_JSON`
+- `GOVERNANCE_CHAIN_HASH_MISMATCH`
+- `GOVERNANCE_CHAIN_PREV_HASH_MISMATCH`
+- `IAC_CLOUDFORMATION_PERMISSION_REQUIRED`
+- `CICD_CODEPIPELINE_PERMISSION_REQUIRED`
+- `CICD_CODEBUILD_PERMISSION_REQUIRED`
+- `CICD_CODEDEPLOY_PERMISSION_REQUIRED`
+- `BACKUP_PERMISSION_REQUIRED`
+- `BACKUP_COVERAGE_REVIEW_REQUIRED`
+- `SECURITY_POSTURE_PERMISSION_REQUIRED`
+- `SECURITY_CONFIG_PERMISSION_REQUIRED`
+- `SECURITY_INSPECTOR2_PERMISSION_REQUIRED`
+- `SECURITY_ACM_PERMISSION_REQUIRED`
+- `SECURITY_ACM_CERT_EXPIRING`
+- `FINOPS_COST_EXPLORER_PERMISSION_REQUIRED`
+- `INCIDENT_ESCALATION_RECOMMENDED`
+- `WORKING_DIRECTORY_INVALID`
+- `WORKING_DIRECTORY_NOT_FOUND`
+- `WORKING_DIRECTORY_NOT_DIRECTORY`
+- `WORKING_DIRECTORY_NOT_ALLOWED`
+- `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`
+- `VPC_LIST_PERMISSION_REQUIRED`
+- `ECS_LIST_PERMISSION_REQUIRED`
+- `S3_LIST_PERMISSION_REQUIRED`
+- `IAM_LIST_PERMISSION_REQUIRED`
+- `KMS_LIST_PERMISSION_REQUIRED`
+- `SNS_LIST_PERMISSION_REQUIRED`
+- `EVENTBRIDGE_LIST_PERMISSION_REQUIRED`
+- `SQS_LIST_PERMISSION_REQUIRED`
+- `ACM_LIST_PERMISSION_REQUIRED`
+- `KINESIS_LIST_PERMISSION_REQUIRED`
+- `MSK_LIST_PERMISSION_REQUIRED`
+- `CLOUDWATCH_LIST_PERMISSION_REQUIRED`
+- `EBS_LIST_PERMISSION_REQUIRED`
+- `EFS_LIST_PERMISSION_REQUIRED`
+- `EKS_LIST_PERMISSION_REQUIRED`
+- `APIGATEWAY_LIST_PERMISSION_REQUIRED`
+- `APIGATEWAYV2_LIST_PERMISSION_REQUIRED`
+- `CLOUDFRONT_LIST_PERMISSION_REQUIRED`
+- `WAF_LIST_PERMISSION_REQUIRED`
+- `SHIELD_LIST_PERMISSION_REQUIRED`
+- `STEPFUNCTIONS_LIST_PERMISSION_REQUIRED`
+- `CLOUDWATCH_LOGS_LIST_PERMISSION_REQUIRED`
+- `XRAY_LIST_PERMISSION_REQUIRED`
+- `INSPECTOR2_LIST_PERMISSION_REQUIRED`
+- `REDSHIFT_LIST_PERMISSION_REQUIRED`
+- `OPENSEARCH_LIST_PERMISSION_REQUIRED`
+- `ORGANIZATIONS_LIST_PERMISSION_REQUIRED`
+- `CONTROLTOWER_LIST_PERMISSION_REQUIRED`
+- `MANUAL_SERVER_LIST_EMPTY`
+- `MANUAL_SERVER_HOST_REQUIRED`
+- `WEB_IDENTITY_CONFIG_REQUIRED`
+- `WEB_IDENTITY_TOKEN_FILE_NOT_FOUND`
+- `PEM_KEY_NOT_FOUND`
+- `BASTION_PEM_KEY_NOT_FOUND`
+- `PEM_MAPPING_REQUIRED`
+- `SSH_CLIENT_NOT_FOUND`
+- `SSH_AUTH_OR_CONNECT_FAILED`
+
+`ACTION_REQUIRED` 메타 필드:
+
+- `severity`
+- `owner`
+- `autoFixable`
+
+## 응답 계약(Response Contract)
+
+- 모든 도구 응답에 runtime contract 필드 포함:
+  - `meta.schemaVersion`
+  - `meta.compatibility`
+  - `meta.responseType`
+- View envelope( CLI JSON / MCP parsed payload ):
+  - `outputProfile`
+  - `sections`
+  - `fields`
+  - `view.records`
+  - `rawNormalized` (재처리 안정성을 위해 항상 포함)
+  - `schema` / `schemaVersion`
+- 계약 스키마: `schemas/mcp-tool-response.schema.json`
+- 호환성 정책: `RESPONSE_COMPATIBILITY_POLICY.md`
+
+<details>
+<summary>상세 AWS 인증 설정 (SSO vs Access Key)</summary>
+
+권장 방식:
+
+- 운영자(사람) 계정은 `SSO (IAM Identity Center)` 권장
+- `Access Key`는 SSO를 쓸 수 없는 예외 상황의 로컬 대체 수단
+- CI/CD 자동화는 장기 키보다 IAM Role/OIDC 권장
+
+SSO 권장 이유:
+
+- 장기 키를 로컬에 보관하지 않아 보안 리스크 감소
+- MFA/세션 만료 동작을 표준화하기 쉬움
+- 중앙 권한 회수(revoke) 및 감사(audit)에 유리
+
+사전 조건:
+
+- AWS CLI v2
+- 조직 계정에 IAM Identity Center 구성 완료
+- 대상 계정/Permission Set 할당 완료
+
+SSO 설정:
+
+```bash
+aws configure sso --profile default
+aws sso login --profile default
+aws sts get-caller-identity --profile default
+```
+
+Access key 설정(대체 경로):
+
+```bash
+aws configure --profile default
+aws sts get-caller-identity --profile default
+```
+
+OIDC/WebIdentity 설정(CI/CD 또는 Kubernetes):
+
+```bash
+export AWS_ROLE_ARN=arn:aws:iam::123456789012:role/oidc-workload-role
+export AWS_WEB_IDENTITY_TOKEN_FILE=/var/run/secrets/eks.amazonaws.com/serviceaccount/token
+aws sts get-caller-identity
+```
+
+CLI 옵션으로 동일하게 지정:
+
+```bash
+mcp-aws-manager discover \
+  --auth-mode web-identity \
+  --web-identity-role-arn arn:aws:iam::123456789012:role/oidc-workload-role \
+  --web-identity-token-file /var/run/secrets/eks.amazonaws.com/serviceaccount/token
+```
+
+빠른 점검:
+
+```bash
+aws configure list-profiles
+aws configure list --profile default
+aws ec2 describe-regions --profile default
+```
+
+자주 나는 오류:
 
-## MCP 도구
+- `Missing the following required SSO configuration values`
+  `aws configure sso --profile default`를 다시 실행해 필수 항목을 모두 입력하세요.
+- `Unable to locate credentials`
+  SSO 세션 만료 또는 인증정보 누락 상태입니다. `aws sso login --profile default`를 실행하거나 Access Key를 재설정하세요.
+- `AccessDenied` / `not authorized`
+  인증은 성공했지만 해당 API를 호출할 IAM 권한(Permission Set/Policy)이 부족합니다.
+
+</details>
+
+<details>
+<summary>AWS 접근 경로 설정 (Profile / SSO / OIDC WebIdentity)</summary>
+
+인증 모드:
+
+- `auto` (기본): 기본적으로 profile을 사용하되, WebIdentity(role+token)가 주어지면 해당 경로를 사용할 수 있습니다.
+- `profile`: AWS profile 자격증명(`fromIni`)을 고정 사용합니다.
+- `web-identity`: OIDC/WebIdentity 토큰 경로(`fromTokenFile`)를 고정 사용합니다.
+
+권장 선택:
+
+- 운영자 PC: `profile` + SSO 로그인
+- CI/CD 또는 Kubernetes 워크로드 아이덴티티: `web-identity`
+- 혼합 환경: `auto` 유지 + 필요 시 명시 옵션 전달
+
+Profile/SSO 경로:
+
+```bash
+aws configure sso --profile prod-admin
+aws sso login --profile prod-admin
+mcp-aws-manager discover --profiles prod-admin --regions us-east-1 --auth-mode profile
+```
+
+WebIdentity 경로:
+
+```bash
+export AWS_ROLE_ARN=arn:aws:iam::123456789012:role/oidc-workload-role
+export AWS_WEB_IDENTITY_TOKEN_FILE=/var/run/secrets/eks.amazonaws.com/serviceaccount/token
+mcp-aws-manager discover --auth-mode web-identity --regions us-east-1
+```
+
+Gateway/mutation 및 AI-read 입력 필드:
+
+- `authMode`
+- `webIdentityRoleArn`
+- `webIdentityTokenFile`
+- `webIdentitySessionName` (선택)
+
+입력 우선순위:
+
+- 명시적 tool 입력/CLI 옵션
+- `MCP_AWS_WEB_IDENTITY_*`
+- `AWS_ROLE_ARN` / `AWS_WEB_IDENTITY_TOKEN_FILE`
+
+인증 관련 주요 ACTION_REQUIRED:
+
+- `WEB_IDENTITY_CONFIG_REQUIRED`
+- `WEB_IDENTITY_TOKEN_FILE_NOT_FOUND`
+- `AWS_CREDENTIALS_REQUIRED`
+
+</details>
+
+<details>
+<summary>서버 내부 접근 경로 설정 (SSM / PEM SSH / ProxyJump / Bastion)</summary>
+
+런타임 스냅샷 경로 선택:
+
+- AWS 관리 EC2(`manualInput=false`): SSM RunCommand 경로 사용
+- 수동 서버 목록(`manualInput=true`): SSH 경로 사용
+- SSH 경로는 다음 중 하나:
+  - `ssh-pem` (직접 키 접속)
+  - `ssh-proxyjump` (`--ssh-proxy-jump`)
+  - `ssh-bastion` (`--ssh-bastion-*`, 내부적으로 ProxyCommand 사용)
+
+수동 목록 + 직접 PEM 예시:
+
+```bash
+mcp-aws-manager discover \
+  --manual-server-list ./servers.json \
+  --pem-paths ~/.ssh/target.pem \
+  --runtime-snapshot
+```
+
+수동 목록 + ProxyJump 예시:
+
+```bash
+mcp-aws-manager discover \
+  --manual-server-list ./servers.json \
+  --pem-paths ~/.ssh/target.pem \
+  --ssh-proxy-jump ec2-user@bastion.example.com \
+  --runtime-snapshot
+```
+
+수동 목록 + Bastion 키 분리 예시:
+
+```bash
+mcp-aws-manager discover \
+  --manual-server-list ./servers.json \
+  --pem-paths ~/.ssh/target.pem \
+  --ssh-bastion-host bastion.example.com \
+  --ssh-bastion-user ec2-user \
+  --ssh-bastion-port 22 \
+  --ssh-bastion-pem-path ~/.ssh/bastion.pem \
+  --runtime-snapshot
+```
+
+수동 서버 JSON 필드(호스트별 선택):
+
+- `host`/`publicIp`/`privateIp`/`publicDns`
+- `sshUser`, `sshPort`, `pemPath`
+- `proxyJump` 또는 `sshProxyJump`
+- `bastionHost`, `bastionUser`, `bastionPort`, `bastionPemPath`
+
+접근 경로 관련 주요 ACTION_REQUIRED:
+
+- `MANUAL_SERVER_HOST_REQUIRED`
+- `PEM_MAPPING_REQUIRED`
+- `BASTION_PEM_KEY_NOT_FOUND`
+- `SSH_AUTH_OR_CONNECT_FAILED`
+
+</details>
+
+<details>
+<summary>Integration Connector 관리 (No-Code)</summary>
+
+기본 상태 파일:
+
+- `~/.mcp-aws-manager/integrations.json`
 
 조회:
 
-- `discover_ec2_with_ssm`
-- `mcp_aws_discover_cli_help`
+```bash
+mcp-aws-manager integration list
+mcp-aws-manager integration show
+```
+
+설정 + 활성화:
+
+```bash
+mcp-aws-manager integration configure pagerduty --set routingKey=XXXX --enable
+```
+
+정책 팩:
+
+```bash
+mcp-aws-manager integration policy show
+mcp-aws-manager integration policy set strict_change
+```
+
+진단:
+
+```bash
+mcp-aws-manager integration doctor
+mcp-aws-manager integration doctor --check-live --timeout-ms 8000
+```
 
-변경:
+discover 시 오버라이드:
+
+- `--integration-config <path>`
+- `--integration-timeout-ms <n>`
+- `--policy-pack <balanced|strict_change|readonly_only>`
+- `--policy-override`
+
+</details>
+
+<details>
+<summary>Discover 옵션 레퍼런스</summary>
+
+- `--profiles <a,b,c>`
+- `--regions <a,b,c>`
+- `--profile-shard <index/total>`
+- `--region-shard <index/total>`
+- `--org-role-name <role-name>`
+- `--org-account-ids <a,b,c>`
+- `--org-include-all-accounts`
+- `--org-max-accounts <n>`
+- `--instance-ids <id1,id2>`
+- `--include-lambda`
+- `--include-ec2` / `--no-ec2`
+- `--include-alb` / `--no-include-alb`
+- `--include-asg` / `--no-include-asg`
+- `--include-rds` / `--no-include-rds`
+- `--include-elasticache` / `--no-include-elasticache`
+- `--include-route53` / `--no-include-route53`
+- `--include-vpc` / `--no-include-vpc`
+- `--include-ecs` / `--no-include-ecs`
+- `--include-s3` / `--no-include-s3`
+- `--include-iam` / `--no-include-iam`
+- `--include-kms` / `--no-include-kms`
+- `--include-cloudwatch` / `--no-include-cloudwatch`
+- `--include-cloudtrail` / `--no-include-cloudtrail`
+- `--include-config` / `--no-include-config`
+- `--include-secrets` / `--no-include-secrets`
+- `--include-parameter-store` / `--no-include-parameter-store`
+- `--include-ecr` / `--no-include-ecr`
+- `--include-dynamodb` / `--no-include-dynamodb`
+- `--include-sns` / `--no-include-sns`
+- `--include-eventbridge` / `--no-include-eventbridge`
+- `--include-sqs` / `--no-include-sqs`
+- `--include-acm` / `--no-include-acm`
+- `--include-kinesis` / `--no-include-kinesis`
+- `--include-msk` / `--no-include-msk`
+- `--include-budgets` / `--no-include-budgets`
+- `--include-cost-anomaly` / `--no-include-cost-anomaly`
+- `--include-ebs` / `--no-include-ebs`
+- `--include-efs` / `--no-include-efs`
+- `--include-eks` / `--no-include-eks`
+- `--include-apigateway` / `--no-include-apigateway`
+- `--include-apigatewayv2` / `--no-include-apigatewayv2`
+- `--include-cloudfront` / `--no-include-cloudfront`
+- `--include-waf` / `--no-include-waf`
+- `--include-shield` / `--no-include-shield`
+- `--include-step-functions` / `--no-include-step-functions`
+- `--include-cloudwatch-logs` / `--no-include-cloudwatch-logs`
+- `--include-xray` / `--no-include-xray`
+- `--include-inspector2` / `--no-include-inspector2`
+- `--include-redshift` / `--no-include-redshift`
+- `--include-opensearch` / `--no-include-opensearch`
+- `--include-organizations` / `--no-include-organizations`
+- `--include-controltower` / `--no-include-controltower`
+- `--include-iac` / `--no-include-iac`
+- `--include-cicd` / `--no-include-cicd`
+- `--include-backup-dr` / `--no-include-backup-dr`
+- `--include-security` / `--no-include-security`
+- `--include-finops` / `--no-include-finops`
+- `--include-application` / `--no-include-application`
+- `--include-incident` / `--no-include-incident`
+- `--incident-force-escalate`
+- `--mode <auto|observe|change|incident>`
+- `--schema-tier <auto|basic|advanced>`
+- `--auth-mode <auto|profile|web-identity>`
+- `--web-identity-role-arn <arn>`
+- `--web-identity-token-file <path>`
+- `--web-identity-session-name <name>`
+- `--user-confirmation <yes|no>`
+- `--enterprise-policy <path>`
+- `--approval-ticket <id>`
+- `--change-reason <text>`
+- `--policy-pack <balanced|strict_change|readonly_only>`
+- `--policy-override`
+- `--integration-config <path>`
+- `--integration-timeout-ms <n>`
+- `--public-only`
+- `--managed-only`
+- `--auto-remediate-ssm`
+- `--ssm-instance-profile-name <name>` / `--ssm-instance-profile-arn <arn>`
+- `--allow-replace-profile`
+- `--runtime-snapshot` / `--no-runtime-snapshot`
+- `--snapshot-profile <quick|standard|deep>`
+- `--output-profile <operator|audit|exec|finops|incident|compact|auditable>`
+- `--sections <overview,inventory,runtime,application,iac,cicd,backupDr,security,finops,incident,actions,governance>`
+- `--include-fields <a,b,c>`
+- `--exclude-fields <a,b,c>`
+- `--client-profile <codex|claude|cursor|operator>`
+- `--renderer-template <default|compact>`
+- `--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>`
+- `--ssh-proxy-jump <user@host[:port][,hop2...]>`
+- `--ssh-bastion-host <host>`
+- `--ssh-bastion-user <user>`
+- `--ssh-bastion-port <port>`
+- `--ssh-bastion-pem-path <path>`
+- `--html-out <path>` (기본: 자동 경로, workspace/home `aws-inventory.html`)
+- `--topology-out <path>` (기본: 자동 경로, workspace/home `aws-topology.json`)
+- `--relationships-out <path>` (기본: 자동 경로, workspace/home `aws-relationships.json`)
+- `--governance-log <path>` (기본: 자동 경로, workspace/home `mcp-aws-governance-log.jsonl`)
+- `--verify-governance-chain` / `--no-verify-governance-chain`
+- `--incident-webhook-url <url>`
+- `--incident-webhook-timeout-ms <n>`
+- `--incident-webhook-auth-header <name>`
+- `--incident-webhook-token <token>`
+- `--incident-out <path>`
+- `--open-html` (기본 on)
+- `--no-open-html` (자동 오픈 off)
+- `--auto-sso-login` / `--no-auto-sso-login`
+- `--format <json|csv|markdown|html>`
+- `--out <path>`
+
+</details>
+
+거버넌스 체인 검증 명령:
 
-- `ec2_start_instances`
-- `ec2_stop_instances`
-- `ec2_reboot_instances`
-- `ec2_apply_instance_profile`
+```bash
+mcp-aws-manager governance verify --governance-log ./mcp-aws-governance-log.jsonl --strict
+```
 
-예시:
+## 클라이언트 스모크 자동화
 
-- `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
+```bash
+npm run smoke:clients
+npm run smoke:clients:strict
+node scripts/smoke-clients.js --clients codex,claude --json-out ./smoke-report.json
+```
 
-- 인증: `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`
+- 기본 모드: 상태를 리포트하고 종료코드 `0`
+- `--strict`: 선택한 클라이언트 중 하나라도 비정상이면 non-zero 종료
 
-## 한국어 관련 문서
+## AWS E2E 시나리오 자동화
 
-- `MCP_CLIENT_SETUP_KO.md`
-- `AWS_SSO_SETUP_GUIDE_KO.md`
+실계정 시나리오(권한/리전/복구 경로) 점검:
 
-## 원문(영문) 문서
+```bash
+npm run e2e:aws -- --profile default --region us-east-1 --out-dir ./.e2e-aws
+npm run e2e:aws:strict -- --profile default --region us-east-1
+```
 
-- `README.md`
-- `MCP_CLIENT_SETUP.md`
-- `AWS_SSO_SETUP_GUIDE.md`
+E2E 러너 검증 항목:
+
+- 기본 관찰(observe) 흐름(JSON 계약 + `rawNormalized`)
+- 잘못된 리전 입력 처리 경로
+- mutable discover 확인 게이트(`CHANGE_CONFIRMATION_REQUIRED`)
+- 확인 승인 경로(`--user-confirmation yes`)
+- 강제 incident 에스컬레이션 페이로드 산출물(`INCIDENT_ESCALATION_RECOMMENDED`)
+- 엔터프라이즈 정책 승인 티켓 게이트(`APPROVAL_TICKET_REQUIRED`)
+- 거버넌스 해시 체인 검증(`governance verify --strict`)
+
+<details>
+<summary>권한 체크리스트</summary>
+
+활성화한 기능에 따라 최소 권한이 달라집니다.
+
+- 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`
+- VPC/Subnet/SecurityGroup: `ec2:DescribeVpcs`, `ec2:DescribeSubnets`, `ec2:DescribeSecurityGroups`
+- ECS: `ecs:ListClusters`, `ecs:DescribeClusters`, `ecs:ListServices`, `ecs:DescribeServices`
+- S3: `s3:ListAllMyBuckets`, `s3:GetBucketLocation`
+- IAM: `iam:ListRoles`
+- KMS: `kms:ListKeys`, `kms:DescribeKey`
+- ACM: `acm:ListCertificates`, `acm:DescribeCertificate`
+- Kinesis: `kinesis:ListStreams`, `kinesis:DescribeStreamSummary`
+- MSK: `kafka:ListClustersV2`
+- CloudWatch: `cloudwatch:DescribeAlarms`
+- EBS: `ec2:DescribeVolumes`
+- EFS: `elasticfilesystem:DescribeFileSystems`
+- EKS: `eks:ListClusters`, `eks:DescribeCluster`
+- API Gateway: `apigateway:GET`
+- CloudFront: `cloudfront:ListDistributions`
+- WAFv2: `wafv2:ListWebACLs`
+- Shield: `shield:ListProtections`
+- Step Functions: `states:ListStateMachines`
+- CloudWatch Logs: `logs:DescribeLogGroups`
+- X-Ray: `xray:GetGroups`
+- Inspector2: `inspector2:ListFindings`
+- Redshift: `redshift:DescribeClusters`
+- OpenSearch: `es:ListDomainNames`, `es:DescribeDomain`
+- Organizations: `organizations:ListAccounts`
+- ControlTower: `controltower:ListLandingZones`
+- CI/CD 분석 확장: `codepipeline:ListPipelines`, `codepipeline:ListPipelineExecutions`, `codebuild:ListProjects`, `codebuild:ListBuildsForProject`, `codebuild:BatchGetBuilds`, `codedeploy:ListApplications`, `codedeploy:ListDeploymentGroups`, `codedeploy:ListDeployments`, `codedeploy:BatchGetDeployments`
+- 보안 분석 확장: `config:DescribeConfigRules`, `config:DescribeComplianceByConfigRule`, `acm:ListCertificates`, `acm:DescribeCertificate`
+- FinOps 분석 확장: `ce:GetSavingsPlansUtilization`, `ce:GetReservationCoverage`
+- Runtime snapshot: `ssm:SendCommand`, `ssm:GetCommandInvocation`, `ssm:DescribeInstanceInformation`
+- Auto-remediation: `ec2:AssociateIamInstanceProfile`, optional `ec2:ReplaceIamInstanceProfileAssociation`, `iam:PassRole`
+- Mutate 도구 확장:
+  - ECS: `ecs:DescribeServices`, `ecs:UpdateService`
+  - ASG: `autoscaling:SetDesiredCapacity`
+  - RDS: `rds:StartDBInstance`, `rds:StopDBInstance`, `rds:RebootDBInstance`
+  - EKS: `eks:DescribeNodegroup`, `eks:UpdateNodegroupConfig`
+- Organizations fan-out(옵션): `organizations:ListAccounts`, `sts:AssumeRole`(대상 계정 role trust 필요)
+
+수동 모드:
+
+- 인벤토리는 사용자 제공 서버 목록 파일 사용(AWS API 불필요)
+- 런타임 스냅샷은 직접 PEM SSH와 ProxyJump/Bastion 라우팅(`--ssh-proxy-jump`, `--ssh-bastion-*`)을 지원
+
+</details>
+
+## 관련 문서
+
+문서 상태:
+- Canonical(구현과 동기화 필수): `README.md`, `RESPONSE_COMPATIBILITY_POLICY.md`
+- Reference(상세/비교 참고): `IMPLEMENTATION_INTEGRATIONS.md`, `MCP_DIFFERENTIATION.md`, `MCP_DIFFERENTIATION_KO.md`, `AGENT_WORKING_CONTEXT_KO.md`, `RECORDS_FIELD_REFERENCE_KO.md`
+
+- `README_KO.md`: 한국어 개요/빠른 시작
+- `IMPLEMENTATION_INTEGRATIONS.md`: API/CLI 연동 인벤토리
+- `MCP_DIFFERENTIATION.md`: AWS MCP 대안 대비 차별점
+- `MCP_DIFFERENTIATION_KO.md`: 한국어 차별화/선택 가이드
+- `AGENT_WORKING_CONTEXT_KO.md`: 에이전트 협업 시 불변 원칙/작업 루프/operationId 빠른 참조
+- `RECORDS_FIELD_REFERENCE_KO.md`: `records[]` 전수 필드(292개) 레퍼런스
+- `RESPONSE_COMPATIBILITY_POLICY.md`: 응답 스키마/버전 호환 정책
+- `schemas/mcp-tool-response.schema.json`: 표준 도구 응답 JSON 스키마
+
+