mcp-aws-manager 0.3.4 → 0.3.5

package/IMPLEMENTATION_INTEGRATIONS.md

@@ -85,6 +85,5 @@ The setup flow tries multiple `mcp` command variants (`get/show`, `add`, `remove
 ## 6) Related docs
 
 - `README.md`
-- `USAGE_GUIDE.md`
 - `MCP_CLIENT_SETUP.md`
 - `MCP_DIFFERENTIATION.md`

package/MCP_CLIENT_SETUP.md

@@ -27,7 +27,7 @@ mcp-aws-manager doctor
 
 ## Agent-Led Setup Flow
 
-Detailed onboarding flow is maintained in `USAGE_GUIDE.md` ("Agent-Assisted First-Time Setup").
+Detailed onboarding flow is maintained in `README.md` ("Agent-Assisted First-Time Setup").
 This document only covers MCP server registration/configuration.
 
 ## Explicit Registration

package/README.md

@@ -1,51 +1,196 @@
 # mcp-aws-manager
 
-AWS operations CLI and MCP server package (SSM-first mode).
+AWS operations CLI + MCP stdio server (SSM-first).
 
-## What It Provides
+This package is not a plain AWS CLI wrapper. It orchestrates multi-step operations:
+
+- Multi-service inventory (EC2/Lambda/ALB/ASG/RDS/ElastiCache/Route53)
+- SSM management/online status
+- Optional runtime snapshot and SSM remediation
+- Normalized output + `ACTION_REQUIRED` guidance for human-in-the-loop retries
+
+Execution path is internal-only (AWS SDK + AWS CLI). It does not delegate runtime execution to external AWS management MCP backends.
+
+## Binaries
 
 - CLI: `mcp-aws-manager`
 - MCP stdio server: `mcp-aws-manager-mcp`
 
-Current implementation focuses on:
-
-- Internal-only execution (AWS SDK + AWS CLI), no external AWS management MCP backend dependency
-- EC2 inventory discovery (multi profile / multi region)
-- Optional Lambda function inventory (same profile/region sweep)
-- Optional ALB/NLB + Target Group inventory
-- Optional Auto Scaling Group inventory
-- Optional RDS inventory
-- Optional ElastiCache inventory
-- Optional Route53 hosted zone inventory
-- SSM management and online-state visibility
-- Optional SSM runtime snapshot collection (`RunCommand`)
-- Optional SSM auto-remediation (instance profile association)
-- Human-in-the-loop guidance via `ACTION_REQUIRED` messages
-- JSON/CSV output (CLI)
-- MCP registration bootstrap helpers (`codex`, `claude`, `cursor`, `windsurf`, `antigravity`)
-
 ## Install
 
 ```bash
 npm install -g mcp-aws-manager
 ```
 
-## One-Time Bootstrap (Recommended)
+## First Run (Recommended)
+
+```bash
+mcp-aws-manager
+```
+
+This bootstraps MCP server registration for detected clients (`codex`, `claude` by default).
+
+## Agent-Assisted First-Time Setup
+
+Use this 5-step flow for new users.
+
+1. Install and bootstrap:
+
+```bash
+npm.cmd install -g mcp-aws-manager@latest
+mcp-aws-manager
+```
+
+2. Health check:
+
+```bash
+mcp-aws-manager doctor
+```
+
+3. Configure AWS auth (SSO recommended):
+
+```bash
+aws configure sso --profile default
+aws sso login --profile default
+```
+
+4. Verify identity:
+
+```bash
+aws sts get-caller-identity --profile default
+```
+
+5. Run discovery:
 
-After install, run once:
+```bash
+mcp-aws-manager discover --profiles default --no-progress
+```
+
+If blocked, follow one `ACTION_REQUIRED` item, then retry the same command.
+
+## User Confirmation Required
+
+These are expected manual steps (agent-guided):
+
+- SSO browser login and MFA confirmation
+- IAM permission approval in organization account
+- For EC2 runtime visibility: attach `AmazonSSMManagedInstanceCore` and keep SSM Agent/network healthy
+
+## Prerequisites
+
+- Node.js `>=18`
+- AWS credentials on the host where CLI/MCP runs:
+  - SSO: `aws configure sso --profile <profile>` then `aws sso login --profile <profile>`
+  - Access key: `aws configure --profile <profile>`
+- Verify auth:
+  - `aws sts get-caller-identity --profile <profile>`
+- Runtime snapshot permissions:
+  - `ssm:SendCommand`, `ssm:GetCommandInvocation`, `ssm:DescribeInstanceInformation`
+- Auto-remediation permissions:
+  - `ec2:AssociateIamInstanceProfile`
+  - optional `ec2:ReplaceIamInstanceProfileAssociation`
+  - `iam:PassRole`
+
+Why SSO is recommended:
+
+- Avoid long-lived access keys on user machines
+- Easier MFA/session-based enforcement
+- Better centralized revoke/audit handling
+
+## Commands
+
+- `mcp-aws-manager`: bootstrap mode (default)
+- `mcp-aws-manager setup`: register/re-register MCP server
+- `mcp-aws-manager doctor`: check install/registration/auth readiness
+- `mcp-aws-manager discover ...`: run inventory/runtime workflow
+
+## Quick Commands
 
 ```bash
 mcp-aws-manager
+mcp-aws-manager doctor
+mcp-aws-manager discover --profiles default
+mcp-aws-manager discover --profiles default --include-lambda
+mcp-aws-manager discover --profiles default --include-alb --include-asg --include-rds --include-elasticache --include-route53
+mcp-aws-manager discover --profiles default --public-only
+mcp-aws-manager discover --profiles default --runtime-snapshot
+mcp-aws-manager discover --profiles default --auto-remediate-ssm --ssm-instance-profile-name MySsmInstanceProfile
+```
+
+Legacy invocation form (still supported):
+
+```bash
+mcp-aws-manager --profiles default --public-only
+```
+
+## Important Discover Options
+
+- `--profiles <a,b,c>`
+- `--regions <a,b,c>`
+- `--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`
+- `--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-timeout <seconds>`
+- `--snapshot-concurrency <n>`
+- `--snapshot-max-kb <n>`
+- `--auto-sso-login` / `--no-auto-sso-login`
+- `--format <json|csv>`
+- `--out <path>`
+
+## MCP Tool Usage
+
+Run MCP server:
+
+```bash
+mcp-aws-manager-mcp
+```
+
+Exposed MCP tools:
+
+- `discover_ec2_with_ssm`
+- `mcp_aws_discover_cli_help`
+
+Example tool args:
+
+```json
+{
+  "profiles": ["default"],
+  "regions": ["ap-northeast-2"],
+  "includeLambda": true,
+  "publicOnly": true,
+  "runtimeSnapshot": true,
+  "autoSsoLogin": true,
+  "noProgress": true
+}
 ```
 
-This ensures `mcp-aws-manager` is registered in detected clients (`codex`, `claude` by default).
+## ACTION_REQUIRED Examples
 
-For first-time users, follow the agent-assisted onboarding flow in `USAGE_GUIDE.md` ("Agent-Assisted First-Time Setup").
+- `SSO_LOGIN_NEEDED`
+- `SSM_ROLE_OR_AGENT_REQUIRED`
+- `IAM_PROFILE_ASSOCIATION_FAILED`
+- `SSM_RUNCOMMAND_PERMISSION_REQUIRED`
+- `LAMBDA_LIST_PERMISSION_REQUIRED`
+- `ELBV2_LIST_PERMISSION_REQUIRED`
+- `ASG_LIST_PERMISSION_REQUIRED`
+- `RDS_LIST_PERMISSION_REQUIRED`
+- `ELASTICACHE_LIST_PERMISSION_REQUIRED`
+- `ROUTE53_LIST_PERMISSION_REQUIRED`
 
-## Document Map
+## Related Docs
 
-- End-user setup and run commands: `USAGE_GUIDE.md`
-- MCP client registration and stdio config: `MCP_CLIENT_SETUP.md`
-- Agent retry/guidance loop template: `AGENT_GUIDANCE_LOOP_TEMPLATE_KO.md`
-- Implementation APIs/CLI wiring: `IMPLEMENTATION_INTEGRATIONS.md`
-- Positioning vs existing AWS MCPs: `MCP_DIFFERENTIATION.md`
+- `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-aws-manager",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "AWS operations CLI and MCP server (SSM-only) for EC2/Lambda inventory, remediation, and runtime snapshots",
   "license": "MIT",
   "publishConfig": {