mcp-aws-manager 0.3.9 → 0.4.1

package/README.md

@@ -1,4 +1,4 @@
-# mcp-aws-manager
+# mcp-aws-manager
 
 AWS operations CLI + MCP stdio server (SSM-first).
 
@@ -15,37 +15,118 @@ mcp-aws-manager discover --profiles default --no-progress
 
 ## What It Does
 
-- Multi-service inventory: EC2, Lambda, ALB/NLB, ASG, RDS, ElastiCache, Route53
+- Multi-service inventory: 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 state visibility: managed/online status
+- Domain analysis pipeline: IaC drift, CI/CD signals, backup/DR posture, security posture, FinOps cost signals, application layer health, incident severity recommendation
 - Optional runtime snapshot and SSM remediation
-- Manual fallback mode: JSON/CSV server list + PEM SSH runtime snapshot (when AWS auth is unavailable)
+- Mutate surface extension: EC2 + ECS + ASG + RDS + EKS controlled change tools
+- Policy-aware routing: mode/surface/schema-tier selection for safer defaults
+- Multi-account scaling controls: Organizations AssumeRole fan-out + profile/region sharding
+- Manual fallback mode: JSON/CSV server list + PEM SSH/ProxyJump/Bastion runtime snapshot (when AWS auth is unavailable)
 - Human-in-the-loop retry flow via `ACTION_REQUIRED`
 - Internal-only execution path (AWS SDK + AWS CLI)
+- Presentation layer controls: output profile presets, section/field projection, and client-aware default layout
+- Persistent governance log + topology/relationship JSON artifacts
+- Optional incident escalation webhook dispatch with local incident payload artifact
+
+## When To Use This Project
+
+Use `mcp-aws-manager` when you need an operations workflow MCP, not just generic AWS API access.
+
+- Choose this project for deterministic inventory/runtime/remediation loops.
+- Choose this project when `ACTION_REQUIRED` guidance and operator artifacts are required.
+- For broad ad-hoc AWS API control only, an umbrella API-style AWS MCP may be enough.
+
+See detailed comparison and product boundaries in:
+
+- `docs/MCP_DIFFERENTIATION.md`
+
+## Quick Comparison
+
+| Selection Point | `mcp-aws-manager` | Umbrella API-style AWS MCP |
+|---|---|---|
+| Primary goal | Deterministic operations workflow (inventory/runtime/remediation) | Broad ad-hoc API/tool access |
+| Tool exposure model | Fixed gateway 3-tool (`capabilities_summary`, `capabilities_detail`, `gateway_execute`) | Many direct service/action tools |
+| Change safety | Built-in confirmation/policy gates for mutate paths | Depends on each tool/server policy |
+| Response contract | Normalized (`ok/summary/records/requiredActions/meta`) | Varies by implementation |
+| Best fit | Reproducible ops loops with operator guidance | Exploratory or wide API probing |
+
+For full rationale and boundaries, see `docs/MCP_DIFFERENTIATION.md` and `docs/MCP_DIFFERENTIATION_KO.md`.
 
 ## 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 SDK service clients used: `49`
+- AWS SDK operation calls used: `95`
 - AWS CLI commands used: `1` (`aws sso login --profile <profile>`)
+- Note: enterprise controls (policy gate/rollback/governance verification) remain in place while inventory coverage has been expanded.
 
-Current 20 AWS SDK operations:
+Current 95 AWS SDK operations:
 
 - STS: `GetCallerIdentity`
-- EC2: `DescribeRegions`, `DescribeInstances`, `StartInstances`, `StopInstances`, `RebootInstances`, `DescribeIamInstanceProfileAssociations`, `AssociateIamInstanceProfile`, `ReplaceIamInstanceProfileAssociation`
-- SSM: `DescribeInstanceInformation`, `SendCommand`, `GetCommandInvocation`
+- 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`
-- RDS: `DescribeDBInstances`
+- 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`
 
 ## Binaries
 
 - CLI: `mcp-aws-manager`
-- MCP stdio server: `mcp-aws-manager-mcp`
+- MCP stdio server (single-entry; default: `--surface all`): `mcp-aws-manager-mcp`
+
+`mcp-aws-manager-mcp` uses gateway routing with selectable surface scope:
+
+```bash
+mcp-aws-manager-mcp --surface all
+mcp-aws-manager-mcp --surface readonly
+mcp-aws-manager-mcp --surface mutate
+```
 
 ## Agent-Assisted First-Time Setup
 
@@ -58,6 +139,23 @@ npm.cmd install -g mcp-aws-manager@latest
 mcp-aws-manager
 ```
 
+Bootstrap registers the default single MCP server for detected clients:
+
+- `mcp-aws-manager` (single-entry, `--surface all`)
+- Runtime command is auto-resolved for host stability.
+- Windows priority: absolute `mcp-aws-manager-mcp.cmd`
+- macOS/Linux priority: absolute `mcp-aws-manager-mcp` binary
+- Fallback: `node <installed-package>/bin/mcp-aws-manager-mcp.js`
+- Last fallback (ephemeral npx context): pinned `npx -y -p mcp-aws-manager@<version> mcp-aws-manager-mcp`
+
+Optional explicit registration:
+
+```bash
+mcp-aws-manager setup
+mcp-aws-manager setup --clients codex,claude
+mcp-aws-manager setup --clients cursor,windsurf,antigravity
+```
+
 2. Health check:
 
 ```bash
@@ -97,6 +195,17 @@ GUI report is generated by default (auto path: workspace/home `aws-inventory.htm
 mcp-aws-manager discover --profiles default --no-progress
 ```
 
+GUI includes:
+- summary cards (records/services/profiles/regions/EC2/SSM/public-IP/issues)
+- tab view (`Report`, `Diagrams`, `Evidence`, `Inventory`)
+- detailed markdown report (`report.md`) with per-resource-type sections
+- topology diagram (Profile -> Region -> Type -> Resource)
+- relationship diagram (DNS / TargetGroup-ALB / ASG heuristic links)
+- focused server/resource selector with per-resource detail and focused relation diagram (`focus.svg`)
+- evidence view and export (`evidence.json`)
+- diagram export (`diagram.drawio`, `topology.svg`, `relationship.svg`)
+- downloaded artifacts include generation timestamp in filename (for example `report-20260304-113000.md`)
+
 Custom path / open behavior:
 
 ```bash
@@ -105,6 +214,69 @@ mcp-aws-manager discover --profiles default --html-out ./inventory.html --open-h
 
 By default, HTML open is enabled. Use `--no-open-html` to disable.
 
+### Manual MCP Client Configuration (Fallback)
+
+Use this only when automatic `bootstrap/setup` registration is unavailable.
+
+1) Local repository (development):
+
+```json
+{
+  "mcpServers": {
+    "mcp-aws-manager": {
+      "command": "node",
+      "args": [
+        "<repo>/bin/mcp-aws-manager-mcp.js",
+        "--surface",
+        "all"
+      ],
+      "cwd": "<repo>"
+    }
+  }
+}
+```
+
+2) Global npm install (manual fallback):
+
+Windows (recommended):
+
+```json
+{
+  "mcpServers": {
+    "mcp-aws-manager": {
+      "command": "C:\\Users\\<user>\\AppData\\Roaming\\npm\\mcp-aws-manager-mcp.cmd",
+      "args": ["--surface", "all"]
+    }
+  }
+}
+```
+
+macOS/Linux:
+
+```json
+{
+  "mcpServers": {
+    "mcp-aws-manager": {
+      "command": "mcp-aws-manager-mcp",
+      "args": ["--surface", "all"]
+    }
+  }
+}
+```
+
+3) `npx` (without global install):
+
+```json
+{
+  "mcpServers": {
+    "mcp-aws-manager": {
+      "command": "npx",
+      "args": ["-y", "-p", "mcp-aws-manager", "mcp-aws-manager-mcp", "--surface", "all"]
+    }
+  }
+}
+```
+
 ## User Confirmation Required
 
 These are normally the only manual steps (agent-guided):
@@ -113,29 +285,67 @@ These are normally the only manual steps (agent-guided):
 - IAM permission approval in organization account
 - For EC2 runtime visibility: attach `AmazonSSMManagedInstanceCore` and keep SSM Agent/network healthy
 
+Agent retry loop (recommended):
+
+1. Execute tool call.
+2. If `requiresUserAction=false`, summarize and finish.
+3. If `requiresUserAction=true`, present one `requiredActions[]` item and ask user to complete it.
+4. When user confirms completion, retry using `guidance.retryTool` + `guidance.retryArgs`.
+5. Repeat until `requiresUserAction=false`.
+
 ## MCP Tool Usage
 
-Run MCP server:
+Run single-entry MCP server (default: `--surface all`):
 
 ```bash
 mcp-aws-manager-mcp
 ```
 
-Exposed MCP tools:
+Choose exposure profile:
+
+- `mcp-aws-manager-mcp --surface all|readonly|mutate` (gateway-only)
+
+Gateway model (`tools/list`) exposes exactly 3 tools:
+
+- `capabilities_summary`
+- `capabilities_detail`
+- `gateway_execute`
+
+Gateway call flow:
+
+1. Call `capabilities_summary` to receive operation categories and `operationId` list.
+2. Call `capabilities_detail` with one `operationId` to inspect execution contract.
+3. Call `gateway_execute` with `{ "operationId": "...", "args": { ... } }`.
+
+Typical `operationId` families:
 
-- `discover_ec2_with_ssm`
-- `ec2_start_instances`
-- `ec2_stop_instances`
-- `ec2_reboot_instances`
-- `ec2_apply_instance_profile`
-- `mcp_aws_discover_cli_help`
+- Discovery: `discover.aws_inventory_basic`, `discover.aws_inventory_advanced`, `discover.aws_inventory_summary`, `discover.aws_inventory_detail`, `discover.list_bedrock_endpoints`, `discover.list_sagemaker_endpoints`.
+- Mutation: `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/System: `governance.verify_chain`, `system.get_server_runtime`, `system.cli_help`.
 
-Mutation tool examples:
+Gateway execute 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 }`
+- 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 read: `{ "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 operation notes:
+
+- `discover.aws_inventory_basic` uses a compact input schema.
+- `discover.aws_inventory_advanced` exposes full inventory/runtime options.
+- `discover.aws_inventory_summary` is summary-first and returns selector hints.
+- `discover.aws_inventory_detail` returns filtered/paged detailed records (`resourceTypes`, `resourceIds`, `offset`, `limit`).
+- Output layout options are supported: `outputProfile`, `sections`, `includeFields`, `excludeFields`, `rendererTemplate`.
+- Routing/control options are supported: `mode`, `schemaTier`, `userConfirmation`, `profileShard`, `regionShard`, `orgRoleName`, `orgAccountIds`, `orgIncludeAllAccounts`, `orgMaxAccounts`, `enterprisePolicyPath`, `approvalTicket`, `changeReason`.
+- Evidence/output artifact options are supported: `topologyOutPath`, `relationshipsOutPath`, `governanceLogPath`, `verifyGovernanceChain`, `incidentWebhookUrl`, `incidentWebhookTimeoutMs`, `incidentWebhookAuthHeader`, `incidentWebhookToken`, `incidentOutPath`.
+- `workingDirectory` is checked against allowlist roots (`cwd`, home, and optional `MCP_AWS_ALLOWED_WORKDIRS`).
+- Structured JSON logs are emitted to stderr; control verbosity with `LOG_LEVEL=error|warn|info|debug` (default: `info`).
+
+Runtime introspection:
+
+- In gateway mode, use `gateway_execute` with `operationId: "system.get_server_runtime"`.
+- Runtime payload includes current surface, exposed operations/tools, confirmation policy, and response contract metadata.
 
 Example tool args:
 
@@ -143,9 +353,38 @@ Example tool args:
 {
   "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",
@@ -169,6 +408,42 @@ Common `ACTION_REQUIRED` codes:
 - `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`
@@ -176,21 +451,86 @@ Common `ACTION_REQUIRED` codes:
 - `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` metadata includes:
+
+- `severity`
+- `owner`
+- `autoFixable`
+
+## Response Contract
+
+- Runtime contract fields are included in every tool response:
+  - `meta.schemaVersion`
+  - `meta.compatibility`
+  - `meta.responseType`
+- View envelope (CLI JSON / MCP parsed payload) includes:
+  - `outputProfile`
+  - `sections`
+  - `fields`
+  - `view.records`
+  - `rawNormalized` (always included for re-processing stability)
+  - `schema` / `schemaVersion`
+- Contract schema: `schemas/mcp-tool-response.schema.json`
+- Compatibility policy: `docs/RESPONSE_COMPATIBILITY_POLICY.md`
+
 <details>
 <summary>Detailed AWS Auth Setup (SSO vs Access Key)</summary>
 
-SSO is recommended because:
+Recommended approach:
+
+- `SSO (IAM Identity Center)` for human operators (recommended)
+- `Access Key` only as a local fallback when SSO is unavailable
+- For CI/CD automation, prefer IAM Role/OIDC over long-lived user keys
+
+Why SSO is preferred:
+
+- Avoids storing long-lived keys on local machines
+- Makes MFA/session-expiry behavior consistent
+- Improves centralized access revocation and auditability
 
-- Avoids long-lived access keys on user machines
-- Enforces session-based login and MFA more easily
-- Improves centralized revoke/audit handling
+Prerequisites:
+
+- AWS CLI v2
+- IAM Identity Center configured in the organization account
+- Target account + permission set assignment completed
 
 SSO setup:
 
@@ -200,13 +540,202 @@ aws sso login --profile default
 aws sts get-caller-identity --profile default
 ```
 
-Access key setup (optional):
+Access key setup (fallback):
 
 ```bash
 aws configure --profile default
 aws sts get-caller-identity --profile default
 ```
 
+OIDC/WebIdentity setup (CI/CD or 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 option equivalent:
+
+```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
+```
+
+Quick checks:
+
+```bash
+aws configure list-profiles
+aws configure list --profile default
+aws ec2 describe-regions --profile default
+```
+
+Frequent errors:
+
+- `Missing the following required SSO configuration values`
+  Re-run `aws configure sso --profile default` and complete all prompts.
+- `Unable to locate credentials`
+  SSO session expired or credentials are missing. Run `aws sso login --profile default` or reconfigure access keys.
+- `AccessDenied` / `not authorized`
+  The profile is valid, but IAM permission set/policy is insufficient for the requested API.
+
+</details>
+
+<details>
+<summary>AWS Access Path Setup (Profile / SSO / OIDC WebIdentity)</summary>
+
+Auth modes:
+
+- `auto` (default): uses profile by default, but can switch to WebIdentity when token+role are provided.
+- `profile`: always uses AWS profile credentials (`fromIni`).
+- `web-identity`: always uses OIDC/WebIdentity token path (`fromTokenFile`).
+
+Recommended selection:
+
+- Human operator workstation: `profile` + SSO login.
+- CI/CD or Kubernetes workload identity: `web-identity`.
+- Mixed environments: keep `auto` and pass explicit fields when needed.
+
+Profile/SSO path:
+
+```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 path:
+
+```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 and AI-read input fields:
+
+- `authMode`
+- `webIdentityRoleArn`
+- `webIdentityTokenFile`
+- `webIdentitySessionName` (optional)
+
+Input precedence:
+
+- explicit tool input/CLI option
+- `MCP_AWS_WEB_IDENTITY_*`
+- `AWS_ROLE_ARN` / `AWS_WEB_IDENTITY_TOKEN_FILE`
+
+Common auth-related ACTION_REQUIRED:
+
+- `WEB_IDENTITY_CONFIG_REQUIRED`
+- `WEB_IDENTITY_TOKEN_FILE_NOT_FOUND`
+- `AWS_CREDENTIALS_REQUIRED`
+
+</details>
+
+<details>
+<summary>Server Internal Access Path Setup (SSM / PEM SSH / ProxyJump / Bastion)</summary>
+
+Runtime snapshot route selection:
+
+- AWS-managed EC2 (`manualInput=false`): SSM RunCommand path.
+- Manual server list (`manualInput=true`): SSH path.
+- SSH path uses:
+  - `ssh-pem` (direct key)
+  - `ssh-proxyjump` (`--ssh-proxy-jump`)
+  - `ssh-bastion` (`--ssh-bastion-*`, internally via ProxyCommand)
+
+Manual list + direct PEM example:
+
+```bash
+mcp-aws-manager discover \
+  --manual-server-list ./servers.json \
+  --pem-paths ~/.ssh/target.pem \
+  --runtime-snapshot
+```
+
+Manual list + ProxyJump example:
+
+```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
+```
+
+Manual list + Bastion key split example:
+
+```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
+```
+
+Manual server JSON fields (optional per host):
+
+- `host`/`publicIp`/`privateIp`/`publicDns`
+- `sshUser`, `sshPort`, `pemPath`
+- `proxyJump` or `sshProxyJump`
+- `bastionHost`, `bastionUser`, `bastionPort`, `bastionPemPath`
+
+Common access-path ACTION_REQUIRED:
+
+- `MANUAL_SERVER_HOST_REQUIRED`
+- `PEM_MAPPING_REQUIRED`
+- `BASTION_PEM_KEY_NOT_FOUND`
+- `SSH_AUTH_OR_CONNECT_FAILED`
+
+</details>
+
+<details>
+<summary>Integration Connector Management (No-Code)</summary>
+
+State file default:
+
+- `~/.mcp-aws-manager/integrations.json`
+
+List/show:
+
+```bash
+mcp-aws-manager integration list
+mcp-aws-manager integration show
+```
+
+Configure + enable:
+
+```bash
+mcp-aws-manager integration configure pagerduty --set routingKey=XXXX --enable
+```
+
+Policy pack:
+
+```bash
+mcp-aws-manager integration policy show
+mcp-aws-manager integration policy set strict_change
+```
+
+Doctor:
+
+```bash
+mcp-aws-manager integration doctor
+mcp-aws-manager integration doctor --check-live --timeout-ms 8000
+```
+
+Discover-time overrides:
+
+- `--integration-config <path>`
+- `--integration-timeout-ms <n>`
+- `--policy-pack <balanced|strict_change|readonly_only>`
+- `--policy-override`
+
 </details>
 
 <details>
@@ -214,6 +743,12 @@ aws sts get-caller-identity --profile default
 
 - `--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`
@@ -222,12 +757,77 @@ aws sts get-caller-identity --profile default
 - `--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>`
@@ -236,15 +836,74 @@ aws sts get-caller-identity --profile default
 - `--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>` (default: auto path, workspace/home `aws-inventory.html`)
+- `--topology-out <path>` (default: auto path, workspace/home `aws-topology.json`)
+- `--relationships-out <path>` (default: auto path, workspace/home `aws-relationships.json`)
+- `--governance-log <path>` (default: auto 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` (open; default is on)
 - `--no-open-html` (disable auto-open)
 - `--auto-sso-login` / `--no-auto-sso-login`
-- `--format <json|csv>`
+- `--format <json|csv|markdown|html>`
 - `--out <path>`
 
 </details>
 
+Governance verification command:
+
+```bash
+mcp-aws-manager governance verify --governance-log ./mcp-aws-governance-log.jsonl --strict
+```
+
+## Client Smoke Automation
+
+Run cross-client smoke checks:
+
+```bash
+npm run smoke:clients
+npm run smoke:clients:strict
+node scripts/smoke-clients.js --clients codex,claude --json-out ./smoke-report.json
+```
+
+- Default mode reports status and exits `0`.
+- `--strict` exits non-zero when any selected client is not healthy.
+
+## AWS E2E Scenario Automation
+
+Run real-account scenario checks (permission/region/recovery path):
+
+```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
+```
+
+Current scenarios include:
+
+- baseline observe contract (`schema` + `rawNormalized`)
+- invalid region handling
+- mutable confirmation gate (`missing` / `yes`)
+- incident escalation artifact generation
+- enterprise policy approval-ticket enforcement
+- governance chain verification (`governance verify --strict`)
+
+The E2E runner validates:
+
+- baseline observe flow (JSON contract + `rawNormalized`)
+- invalid region handling path
+- mutable discover confirmation gate (`CHANGE_CONFIRMATION_REQUIRED`)
+- confirmation-approved path (`--user-confirmation yes`)
+- forced incident escalation payload artifact (`INCIDENT_ESCALATION_RECOMMENDED`)
+
 <details>
 <summary>Permission Checklist</summary>
 
@@ -257,22 +916,62 @@ Minimum permissions depend on enabled features.
 - 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 analysis: `codepipeline:ListPipelines`, `codepipeline:ListPipelineExecutions`, `codebuild:ListProjects`, `codebuild:ListBuildsForProject`, `codebuild:BatchGetBuilds`, `codedeploy:ListApplications`, `codedeploy:ListDeploymentGroups`, `codedeploy:ListDeployments`, `codedeploy:BatchGetDeployments`
+- Security analysis extension: `config:DescribeConfigRules`, `config:DescribeComplianceByConfigRule`, `acm:ListCertificates`, `acm:DescribeCertificate`
+- FinOps analysis extension: `ce:GetSavingsPlansUtilization`, `ce:GetReservationCoverage`
 - Runtime snapshot: `ssm:SendCommand`, `ssm:GetCommandInvocation`, `ssm:DescribeInstanceInformation`
 - Auto-remediation: `ec2:AssociateIamInstanceProfile`, optional `ec2:ReplaceIamInstanceProfileAssociation`, `iam:PassRole`
+- Mutate tool extension:
+  - ECS: `ecs:DescribeServices`, `ecs:UpdateService`
+  - ASG: `autoscaling:SetDesiredCapacity`
+  - RDS: `rds:StartDBInstance`, `rds:StopDBInstance`, `rds:RebootDBInstance`
+  - EKS: `eks:DescribeNodegroup`, `eks:UpdateNodegroupConfig`
+- Organizations fan-out (optional): `organizations:ListAccounts`, `sts:AssumeRole` (target account role trust required)
 
 Manual fallback mode:
 
 - Inventory uses user-provided server list file (no AWS API required)
-- Runtime snapshot uses local `ssh` client + PEM key access
+- Runtime snapshot supports direct PEM SSH and ProxyJump/Bastion routing (`--ssh-proxy-jump`, `--ssh-bastion-*`)
 
 </details>
 
 ## Related Docs
 
+Document status:
+- Canonical (keep synchronized with implementation): `README.md`, `docs/RESPONSE_COMPATIBILITY_POLICY.md`
+- Reference (detail/positioning): `docs/IMPLEMENTATION_INTEGRATIONS.md`, `docs/MCP_DIFFERENTIATION.md`, `docs/MCP_DIFFERENTIATION_KO.md`, `workflow/AGENT_WORKING_CONTEXT_KO.md`, `docs/RECORDS_FIELD_REFERENCE_KO.md`
+
 - `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
-- `MCP_DIFFERENTIATION.md`: differentiation from existing AWS MCP servers
+- `docs/IMPLEMENTATION_INTEGRATIONS.md`: API/CLI integration inventory
+- `docs/MCP_DIFFERENTIATION.md`: differentiation from existing AWS MCP servers
+- `docs/MCP_DIFFERENTIATION_KO.md`: Korean differentiation guide and selection criteria
+- `workflow/AGENT_WORKING_CONTEXT_KO.md`: agent-focused implementation invariants, gateway loop, and operation catalog quick reference
+- `docs/RECORDS_FIELD_REFERENCE_KO.md`: full `records[]` field reference (292 fields)
+- `docs/RESPONSE_COMPATIBILITY_POLICY.md`: response schema/version compatibility rules
+- `schemas/mcp-tool-response.schema.json`: canonical tool response JSON schema
+
+