mcp-aws-manager 0.1.1 → 0.3.0

package/MCP_CLIENT_SETUP.md

@@ -1,19 +1,49 @@
 # MCP Client Setup (stdio)
 
-This project now includes an MCP stdio server wrapper.
+This project provides an MCP stdio wrapper around the SSM-only CLI.
 
 - Preferred CLI command: `mcp-aws-manager`
 - Preferred MCP server command: `mcp-aws-manager-mcp`
-- Compatibility aliases still available: `mcp-aws-discover`, `mcp-aws-discover-mcp`
+- Compatibility aliases: `mcp-aws-discover`, `mcp-aws-discover-mcp`
 
-The MCP server exposes these tools:
+Exposed MCP tools:
 
-- `discover_public_ec2_with_pem`
+- `discover_ec2_with_ssm` (primary)
+- `discover_public_ec2_with_pem` (compatibility alias, same behavior)
 - `mcp_aws_discover_cli_help`
 
-## 1) Local Repo (recommended for development)
+## Recommended (Install Once)
 
-Use this when running directly from this repository.
+```bash
+npm install -g mcp-aws-manager
+mcp-aws-manager
+```
+
+`mcp-aws-manager` (no args) runs bootstrap and registers the MCP server for detected clients (`codex`, `claude`).
+
+Verification:
+
+```bash
+mcp-aws-manager doctor
+```
+
+## Explicit Registration
+
+```bash
+mcp-aws-manager setup
+```
+
+Custom name/command:
+
+```bash
+mcp-aws-manager setup --name mcp-aws-manager --mcp-command mcp-aws-manager-mcp --clients codex,claude
+```
+
+## Manual Configuration (Fallback)
+
+Use only when automatic registration is unavailable in your environment.
+
+### 1) Local Repo (development)
 
 ```json
 {
@@ -29,15 +59,7 @@ Use this when running directly from this repository.
 }
 ```
 
-## 2) Global npm Install
-
-After publishing/installing globally:
-
-```bash
-npm install -g mcp-aws-manager
-```
-
-Client config:
+### 2) Global npm Install
 
 ```json
 {
@@ -49,9 +71,7 @@ Client config:
 }
 ```
 
-## 3) npx (without global install)
-
-This can be useful for clients that support `npx` commands.
+### 3) npx (no global install)
 
 ```json
 {
@@ -71,8 +91,7 @@ This can be useful for clients that support `npx` commands.
 
 ## Notes
 
-- The current discovery tool is PEM-based and accepts `pemPath` or `pemPaths` (array).
-- If neither is provided, it auto-discovers `.pem` files from the working directory.
-- AWS credentials/profiles must be available on the machine running the MCP server.
-- Do not pass PEM contents through chat; use a local file path in tool arguments.
-- For scoped public npm packages, publish with `npm publish --access public` (or set `publishConfig.access`).
+- Discovery is SSM-only; PEM path arguments are no longer required.
+- Keep AWS credentials/profiles available on the host running MCP.
+- When `requiresUserAction=true` is returned, surface `requiredActions` to the user and retry after intervention.
+- For auto remediation, pass `autoRemediateSsm` and an instance profile name/arn.

package/README.md

@@ -1,6 +1,6 @@
 # mcp-aws-manager
 
-AWS operations CLI and MCP server package (currently discovery-focused).
+AWS operations CLI and MCP server package (SSM-only mode).
 
 ## What It Provides
 
@@ -9,11 +9,13 @@ AWS operations CLI and MCP server package (currently discovery-focused).
 
 Current implementation focuses on:
 
-- EC2 public IPv4 inventory discovery
-- PEM fingerprint-based EC2 KeyPair matching
-- Optional SSH reachability checks
+- EC2 inventory discovery (multi profile / multi region)
+- 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 tool wrapper for AI clients (stdio)
+- Codex/Claude MCP registration bootstrap helpers
 
 ## Install
 
@@ -21,67 +23,71 @@ Current implementation focuses on:
 npm install -g mcp-aws-manager
 ```
 
-## Quick Start
-
-Ensure AWS credentials/profile and a PEM file are available on your machine.
+## One-Time Bootstrap (Recommended)
 
-Run a CLI check (explicit PEM path(s) or auto-discovery from current folder):
+After install, run once:
 
 ```bash
-# explicit PEM path
-mcp-aws-manager --pem-path /path/to/key.pem --profiles default
-
-# multiple explicit PEM paths (comma-separated)
-mcp-aws-manager --pem-path /path/to/key1.pem,/path/to/key2.pem --profiles default
-
-# no args: auto-uses all *.pem in current directory
-cd /path/that/contains/pem
 mcp-aws-manager
 ```
 
-For LLM clients, register the MCP command:
+This ensures `mcp-aws-manager` is registered in detected clients (`codex`, `claude`).
 
-```json
-{
-  "mcpServers": {
-    "mcp-aws-manager": {
-      "command": "mcp-aws-manager-mcp"
-    }
-  }
-}
-```
+## Prerequisites
+
+- Node.js `>=18`
+- AWS credentials/profile (or IAM role) on the machine running the CLI/MCP server
+- For runtime snapshots: SSM permissions (`ssm:SendCommand`, `ssm:GetCommandInvocation`)
+- For auto remediation: EC2/IAM permissions (`ec2:AssociateIamInstanceProfile`, optionally `ec2:ReplaceIamInstanceProfileAssociation`, `iam:PassRole`)
 
-## CLI Usage
+## Quick Start
+
+Bootstrap / setup / doctor:
 
 ```bash
-mcp-aws-manager --pem-path /path/to/key.pem --profiles default
+mcp-aws-manager                     # bootstrap (default command)
+mcp-aws-manager setup              # register/re-register MCP server
+mcp-aws-manager doctor             # verify install + registration
+```
 
-# if current directory contains .pem files, pemPath is optional
-mcp-aws-manager
+Basic discovery:
+
+```bash
+mcp-aws-manager discover --profiles default
 ```
 
-Windows PowerShell example:
+Only public IP instances:
 
-```powershell
-mcp-aws-manager --pem-path C:\Users\<you>\.ssh\mykey.pem --profiles default
+```bash
+mcp-aws-manager discover --profiles default --public-only
 ```
 
-Output format examples:
+Collect runtime snapshots:
 
 ```bash
-# JSON (default)
-mcp-aws-manager --pem-path /path/to/key.pem --profiles default
+mcp-aws-manager discover --profiles default --runtime-snapshot
+```
 
-# CSV
-mcp-aws-manager --pem-path /path/to/key.pem --profiles default --format csv
+Try automatic remediation for unmanaged instances:
+
+```bash
+mcp-aws-manager discover \
+  --profiles default \
+  --auto-remediate-ssm \
+  --ssm-instance-profile-name MySsmInstanceProfile
 ```
 
-Optional SSH reachability check:
+Output CSV file:
 
 ```bash
-mcp-aws-manager --pem-path /path/to/key.pem --profiles default --ssh-check
+mcp-aws-manager discover --profiles default --format csv --out ./inventory.csv
 ```
 
+Compatibility note:
+
+- Legacy invocation without subcommand still works for discovery when options are passed.
+- Example: `mcp-aws-manager --profiles default --public-only`
+
 ## MCP (LLM Tool) Usage
 
 Run as an MCP stdio server:
@@ -90,43 +96,43 @@ Run as an MCP stdio server:
 mcp-aws-manager-mcp
 ```
 
-Then configure your MCP-compatible client (Claude Desktop, Cursor, Cline, etc.) to launch that command.
-
-See `MCP_CLIENT_SETUP.md` for ready-to-copy config examples.
-
-### Exposed MCP Tools
+Exposed MCP tools:
 
-- `discover_public_ec2_with_pem`
+- `discover_ec2_with_ssm` (primary)
+- `discover_public_ec2_with_pem` (compatibility alias, same SSM-only behavior)
 - `mcp_aws_discover_cli_help`
 
 Example tool arguments:
 
 ```json
 {
-  "pemPaths": [
-    "C:\\Users\\<you>\\.ssh\\key1.pem",
-    "C:\\Users\\<you>\\.ssh\\key2.pem"
-  ],
   "profiles": ["default"],
+  "publicOnly": true,
+  "runtimeSnapshot": true,
+  "autoSsoLogin": true,
   "noProgress": true
 }
 ```
 
-## Requirements
+## Human-in-the-loop Behavior
 
-- Node.js `>=18`
-- AWS credentials/profile on the machine running the CLI/MCP server
-- Local PEM file path(s) (current discovery tool is PEM-based)
+When fully automatic execution is not possible, the CLI/MCP returns actionable guidance:
+
+- `ACTION_REQUIRED: [SSO_LOGIN_NEEDED] ...`
+- `ACTION_REQUIRED: [SSM_ROLE_OR_AGENT_REQUIRED] ...`
+- `ACTION_REQUIRED: [IAM_PROFILE_ASSOCIATION_FAILED] ...`
+
+The MCP wrapper surfaces these in a structured `requiredActions` list.
 
 ## Security Notes
 
-- Do not paste PEM contents into LLM chats.
-- Pass only local file paths (`pemPath` or `pemPaths`) to the MCP tool.
-- Keep AWS credentials and PEM keys on the machine running the tool.
+- Prefer IAM role + SSM over SSH key based access.
+- Restrict RunCommand scopes with IAM policies and resource conditions.
+- Review remediation permissions before enabling `--auto-remediate-ssm`.
 
 ## Compatibility Aliases
 
-These legacy commands are also available:
+These legacy commands are still available:
 
 - `mcp-aws-discover`
 - `mcp-aws-discover-mcp`