mcp-aws-manager 0.1.1 → 0.2.0

package/MCP_CLIENT_SETUP.md

@@ -1,19 +1,18 @@
-# MCP Client Setup (stdio)
+# 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)
-
-Use this when running directly from this repository.
+## 1) Local Repo (development)
 
 ```json
 {
@@ -31,14 +30,10 @@ 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:
-
 ```json
 {
   "mcpServers": {
@@ -49,9 +44,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 +64,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
+# 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,12 @@ 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)
 
 ## Install
 
@@ -21,65 +22,46 @@ 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.
-
-Run a CLI check (explicit PEM path(s) or auto-discovery from current folder):
-
-```bash
-# explicit PEM path
-mcp-aws-manager --pem-path /path/to/key.pem --profiles default
+## Prerequisites
 
-# multiple explicit PEM paths (comma-separated)
-mcp-aws-manager --pem-path /path/to/key1.pem,/path/to/key2.pem --profiles default
+- 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`)
 
-# no args: auto-uses all *.pem in current directory
-cd /path/that/contains/pem
-mcp-aws-manager
-```
+## Quick Start
 
-For LLM clients, register the MCP command:
+Basic discovery:
 
-```json
-{
-  "mcpServers": {
-    "mcp-aws-manager": {
-      "command": "mcp-aws-manager-mcp"
-    }
-  }
-}
+```bash
+mcp-aws-manager --profiles default
 ```
 
-## CLI Usage
+Only public IP instances:
 
 ```bash
-mcp-aws-manager --pem-path /path/to/key.pem --profiles default
-
-# if current directory contains .pem files, pemPath is optional
-mcp-aws-manager
+mcp-aws-manager --profiles default --public-only
 ```
 
-Windows PowerShell example:
+Collect runtime snapshots:
 
-```powershell
-mcp-aws-manager --pem-path C:\Users\<you>\.ssh\mykey.pem --profiles default
+```bash
+mcp-aws-manager --profiles default --runtime-snapshot
 ```
 
-Output format examples:
+Try automatic remediation for unmanaged instances:
 
 ```bash
-# JSON (default)
-mcp-aws-manager --pem-path /path/to/key.pem --profiles default
-
-# CSV
-mcp-aws-manager --pem-path /path/to/key.pem --profiles default --format csv
+mcp-aws-manager \
+  --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 --profiles default --format csv --out ./inventory.csv
 ```
 
 ## MCP (LLM Tool) Usage
@@ -90,43 +72,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.
+Exposed MCP tools:
 
-See `MCP_CLIENT_SETUP.md` for ready-to-copy config examples.
-
-### 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`
+- `mcp-aws-discover-mcp`