convez.ai
Agente
2menai

aws-fleet

2menai/aws-fleet

Ver no GitHub
InicialPluginScore · de 0 a 100

Generic multi-agent AWS diagnostic & remediation fleet for Claude Code — read-only scanning, Well-Architected assessment, and HTML intelligence reports.

Instalação

$npx convez-ai 2menai/aws-fleet

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
37%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

AWS Diagnostic & Remediation Fleet

A multi-agent project that scans AWS accounts, maps what's running, assesses it against the Well-Architected Framework, and produces a prioritized HTML intelligence report — using Claude Code + the AWS MCP Server (generally available since May 6, 2026, and part of the Agent Toolkit for AWS). With explicit approval, it also remediates findings.

What This Is

Open this folder in Claude Code and it becomes a fleet of AWS specialist agents that can:

  • Scan accounts (read-only) — Inventory and map live resources across one or more accounts
  • Assess — Score the environment against Well-Architected pillars; rank findings by severity × effort
  • Report — Render a styled HTML intelligence report (see report.template.html)
  • Remediate (opt-in) — Apply approved fixes; production changes confirmed per action
  • Use AWS Agent Skills — Curated, on-demand best-practice guidance from AWS service teams

The AWS MCP Server is a managed remote server — AWS hosts and maintains it, with IAM-based guardrails, CloudTrail logging, and CloudWatch metrics built in. You connect to it through a small local auth bridge (see Connection below).

Read-only by design. The default .mcp.json runs the MCP proxy with --read-only, so a normal session cannot mutate anything. Remediation is a deliberate opt-in (see Enabling remediation). This repo ships no real account data — every run discovers your environment live.

The Fleet

om orchestrates seven specialist lenses. Each scans read-only, assesses against the Well-Architected Framework, and surfaces prioritized findings (finding → pillar → severity → effort → recommendation). Remediation is opt-in and applied one approved change at a time; production is confirmed per action.

AgentLens — what it inspectsWell-Architected focusMutates?
omOrchestrator — discovers the environment, dispatches specialists in parallel, synthesizes the single HTML intelligence reportAll pillarsOnly via approved remediation
network-architectVPCs, subnets, route tables, NACLs, security groups, Internet/NAT/Transit gateways, peering, VPC endpoints, Flow LogsSecurity · ReliabilityOpt-in, 1 change at a time
compute-engineerEC2, ECS/Fargate, EKS, Lambda, Auto Scaling, AMIs, instance profiles — right-sizing, IMDSv2, Graviton/Spot, healthchecks, runtime currencyPerformance · Cost · ReliabilityOpt-in, 1 change at a time
security-hardenerIAM roles/policies/trust, OIDC scoping, security groups, KMS, public exposure (S3/ALB), GuardDuty, Secrets Manager, encryption, CloudTrailSecurityOpt-in, 1 change at a time
data-engineerRDS/Aurora, DynamoDB, S3, ElastiCache, queues — encryption, backups/PITR, versioning, public access, multi-AZReliability · Security · CostOpt-in, 1 change at a time
devops-specialistIaC footprint, CI/CD pipelines & OIDC roles, observability (CloudWatch alarms/dashboards/log retention), CloudTrail, tagging hygiene, driftOperational ExcellenceOpt-in, 1 change at a time
cost-optimizerCost/usage, right-sizing, Savings Plans/RIs, Spot/Graviton, idle & orphaned-resource waste (adds estimated monthly savings)Cost OptimizationOpt-in, 1 change at a time
pre-mortemFailure modes, blast radius, capacity/service limits, single points of failure — reasons backward from "what could go wrong"Reliability · SecurityNever — read-only

Quick Start

Prerequisites

# 1. Install AWS CLI v2.32.0+
brew install awscli

# 2. Install uv (runs the local mcp-proxy-for-aws auth bridge)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. Authenticate however your org does — the server uses your standard AWS credential chain:
aws login                                # simplified flow (auto-rotates creds)
#   or
aws sso login --profile <your-profile>   # IAM Identity Center / SSO
#   or set AWS_PROFILE / standard env vars / a [default] profile

# 4. Verify (add --profile <name> if you don't use a default profile)
aws sts get-caller-identity

Profile-agnostic by design: this repo's .mcp.json hardcodes no AWS profile. The proxy resolves credentials from the standard AWS chain (AWS_PROFILE, env vars, SSO, or a [default] profile), so each user supplies their own. If you only have named profiles (no [default]), set AWS_PROFILE before launching, e.g. export AWS_PROFILE=<your-profile>.

Note: uvx does not run the MCP server — AWS hosts that remotely. It runs mcp-proxy-for-aws, a thin local bridge that SigV4-signs each request with your AWS credentials and forwards it to the managed endpoint. See Connection.

Launch

# Open this folder in Claude Code
cd /path/to/aws-fleet
claude

Claude Code will automatically:

  1. Load CLAUDE.md (fleet instructions)
  2. Connect to the AWS MCP Server (read-only scanner) via .mcp.json
  3. Be ready to scan and report

Example Commands

> scan this account
> report                      # generate the full HTML intelligence report
> security audit
> cost check
> pre-mortem
> diagram                     # ASCII architecture from live state
> status
> remediate <finding>        # requires the write server (see Enabling remediation)

Connection

The AWS MCP Server is a single managed remote endpoint. Your MCP client reaches it through the local mcp-proxy-for-aws bridge (launched via uvx), which handles SigV4 authentication. This repo's .mcp.json is already wired for us-east-1:

{
  "mcpServers": {
    "aws-mcp": {
      "command": "uvx",
      "timeout": 100000,
      "transport": "stdio",
      "args": [
        "mcp-proxy-for-aws==1.6.0",
        "https://aws-mcp.us-east-1.api.aws/mcp",
        "--metadata", "AWS_REGION=us-east-1",
        "--read-only"
      ]
    }
  }
}

The endpoint Region selects which managed server you connect to; the AWS_REGION metadata sets the default Region for the operations it performs (these can differ, and you can always override per prompt, e.g. "…in us-west-2").

RegionEndpoint
US East (N. Virginia) — us-east-1 (default here)https://aws-mcp.us-east-1.api.aws/mcp
Europe (Frankfurt) — eu-central-1https://aws-mcp.eu-central-1.api.aws/mcp

No offline mode for the managed server — the proxy must reach the AWS endpoint. For fully air-gapped use, the separate open-source awslabs/mcp servers exist, but AWS recommends migrating to the managed server.

Multi-account (cross-account / cross-role)

Configure named profiles in ~/.aws/config, then the agent can target a profile per command — no session switching:

# ~/.aws/config
[profile lab]
sso_session = my-sso
sso_account_id = 111111111111
sso_role_name = LabAdmin

[profile prod-readonly]
sso_session = my-sso
sso_account_id = 222222222222
sso_role_name = ReadOnly
> using the prod-readonly profile, scan this account
> using the staging profile, report

Enabling remediation

Scanning is read-only. To let the fleet apply approved fixes, add a second, write-capable MCP server (the same proxy without --read-only) and use it only during an intentional remediation session:

{
  "mcpServers": {
    "aws-remediate": {
      "command": "uvx",
      "timeout": 100000,
      "transport": "stdio",
      "args": [
        "mcp-proxy-for-aws==1.6.0",
        "https://aws-mcp.us-east-1.api.aws/mcp",
        "--metadata", "AWS_REGION=us-east-1"
      ]
    }
  }
}

Even with the write server enabled, the fleet proposes each change and waits for your explicit approval before applying it; production changes are confirmed per action. For an even stronger guarantee, back this with an IAM role that only permits the specific mutations you intend (see IAM Guardrails & Observability).

GA Capabilities

CapabilityWhat it gives you
call_awsInvoke any of 15,000+ AWS API operations (incl. file uploads, long-running ops) via one tool
run_scriptRun Python server-side in a sandbox — inherits your IAM permissions, no network or local filesystem access
Agent SkillsCurated AWS best-practice guidance loaded on demand (retrieve_skill), low context-window cost
Doc discoverysearch_documentation / read_documentation retrieve current AWS docs — no credentials required
IAM guardrailsOrg-controlled access via IAM context keys (separate human vs. agent perms, read-only restrictions)
ObservabilityCloudWatch metrics under the AWS-MCP namespace + full CloudTrail records, built in

In the MCP client these tools surface with an aws___ prefix (e.g. aws___call_aws, aws___run_script, aws___retrieve_skill). File uploads and long-running operations are handled by companion tools (aws___get_presigned_url, aws___get_tasks). When the server runs with --read-only, the mutating tools (call_aws, run_script) are withheld.

Project Structure

aws-fleet/
├── CLAUDE.md              # Fleet instructions — roles, read-only directive, guardrails
├── .mcp.json             # AWS MCP Server connection (read-only scanner)
├── .claude/agents/       # 8 specialist lenses (network, compute, security, data, devops, cost, pre-mortem, om)
├── report.template.html  # HTML report schema (placeholder data only)
├── CHANGELOG.md          # Change history
├── README.md             # This file
└── reports/              # Generated reports (gitignored — contain live data)

Configuration

Change Default Region

Edit .mcp.json — change AWS_REGION=us-east-1 to your preferred region (and the endpoint, to scan from eu-central-1).

Set your profiles / accounts

This repo is profile-agnostic — nothing is hardcoded. Supply credentials via the standard AWS chain (AWS_PROFILE, SSO, or a [default] profile). Optionally fill in the profiles: / accounts: placeholders in CLAUDE.md for your own reference.

IAM Guardrails & Observability

Because the server runs on your IAM credentials, what the agent can do is governed by IAM — not by trusting the prompt. Scope an agent with a dedicated role and IAM context keys to, for example, allow read-only discovery while blocking mutations, or separate human vs. agent permissions. See Understanding IAM for managed AWS MCP servers.

Every call is auditable out of the box: CloudTrail records the API activity and CloudWatch publishes metrics under the AWS-MCP namespace (tracked separately from direct API calls).

Defaults

SettingValue
Regionus-east-1
Moderead-only scan (remediation is opt-in)
Profilesnone hardcoded — profile-agnostic
DeliverableHTML intelligence report (report.template.html schema)
Remediation IaCTerraform default, CDK TypeScript accepted
MCP proxymcp-proxy-for-aws==1.6.0 (version-pinned)
ObservabilityCloudTrail + CloudWatch (AWS-MCP namespace), on by default

Troubleshooting

ProblemFix
NoCredentials / server won't connectAuthenticate (aws login or aws sso login --profile <name>). If you have no [default] profile, export AWS_PROFILE=<name> before launching Claude Code.
ExpiredTokenExceptionRe-authenticate as above, then restart your MCP client to re-initialize.
Tools not loadingConfirm uvx is installed (which uvx) and creds resolve (aws sts get-caller-identity); restart Claude Code so .mcp.json reloads.
Wrong regionOverride per prompt ("...in us-west-2"), or change AWS_REGION in .mcp.json.

Cost Notes

Scanning is read-only and effectively free — describe/list/get calls and documentation lookups incur no resource charges, and there's no charge for the MCP server itself (you pay only for any resources remediation creates). Generated reports are local files (gitignored), not AWS resources.

Data Handling

This repo contains no real account data. Generated reports (report.html, reports/) and local Claude config (.claude/settings.local.json) are gitignored because they reflect your live environment — never commit them. report.template.html is placeholder-only and safe to share.

Ver o original no GitHub

Bom para

Relacionados