Metadata-Version: 2.4
Name: aws-resiliency-mcp
Version: 1.0.0
Summary: MCP server that evaluates AWS account resiliency and DR gaps
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: boto3>=1.34.0
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-docx>=1.1.0
Requires-Dist: reportlab>=4.0.0
Provides-Extra: dev
Requires-Dist: boto3-stubs[essential]>=1.34.0; extra == 'dev'
Requires-Dist: mypy>=1.13.0; extra == 'dev'
Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Description-Content-Type: text/markdown

# aws-resiliency-mcp

[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI](https://img.shields.io/pypi/v/aws-resiliency-mcp.svg)](https://pypi.org/project/aws-resiliency-mcp/)

**MCP server that evaluates AWS account resiliency posture and identifies disaster recovery gaps across 12 service categories.**

## Features

- **17 MCP Tools** — granular per-category assessments plus discovery, cross-region, multi-AZ, and full-scan tools
- **12 Assessment Categories** — compute, data, networking, output, serverless, AI/ML, containers, security, analytics, storage, messaging, observability
- **Discovery-First Architecture** — auto-detects active services via Resource Explorer / Config before assessing
- **Multi-Region Scanning** — parallel cross-region DR gap analysis across 10+ regions
- **Environment Classification** — auto-tags resources as production/DR/non-prod from tags and naming patterns
- **Region Role Detection** — classifies regions as PRIMARY, DR/SECONDARY, or NOT_USED
- **4 Output Formats** — Markdown, HTML, DOCX, PDF
- **Cross-Account Access** — supports STS AssumeRole and temporary credentials
- **Severity Adjustment** — automatically bumps production findings up, non-prod findings down
- **Parallel Execution** — concurrent assessments and region scans via asyncio thread pool

## Installation

```bash
# Recommended: run directly with uvx
uvx aws-resiliency-mcp

# Or install via pip
pip install aws-resiliency-mcp

# Development install
pip install -e ".[dev]"
```

## Quick Start

### Claude Desktop / Amazon Quick

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "aws-resiliency-mcp": {
      "command": "uvx",
      "args": ["aws-resiliency-mcp"],
      "env": {
        "AWS_PROFILE": "default",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}
```

### With Docker

```json
{
  "mcpServers": {
    "aws-resiliency-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "AWS_ACCESS_KEY_ID",
        "-e", "AWS_SECRET_ACCESS_KEY",
        "-e", "AWS_SESSION_TOKEN",
        "aws-resiliency-mcp"
      ]
    }
  }
}
```

## Tool Reference

| Tool | Description |
|------|-------------|
| `discover_resources` | Auto-detect active AWS services in an account (Resource Explorer → Config → fallback) |
| `assess_compute_resiliency` | Evaluate EC2, ECS, Lambda, EKS — multi-AZ, auto-scaling, redundancy |
| `assess_data_resiliency` | Evaluate RDS, DynamoDB, S3, EBS, EFS — backups, replication, multi-AZ |
| `assess_networking_resiliency` | Evaluate VPC, ALB/NLB, Route53, CloudFront, Direct Connect — redundancy, failover |
| `assess_output_resiliency` | Evaluate SQS, SNS, Kinesis, API Gateway — DLQ, redundancy, throttling |
| `assess_serverless_resiliency` | Evaluate Step Functions, EventBridge, Cognito, AppSync — DLQ, retry, concurrency |
| `assess_ai_ml_resiliency` | Evaluate SageMaker, Bedrock — endpoint redundancy, model backups |
| `assess_containers_resiliency` | Evaluate ECS/EKS clusters, ECR — task placement, image replication |
| `assess_security_resiliency` | Evaluate KMS, IAM, Secrets Manager, WAF, GuardDuty — key rotation, MFA |
| `assess_analytics_resiliency` | Evaluate EMR, Glue, Athena, OpenSearch, Redshift — HA, backups |
| `assess_storage_resiliency` | Evaluate S3, EBS, EFS, FSx, Backup — versioning, replication, lifecycle |
| `assess_messaging_resiliency` | Evaluate SQS, SNS, EventBridge, MQ — DLQ, cross-region, HA |
| `assess_observability_resiliency` | Evaluate CloudWatch, CloudTrail, X-Ray — alarm coverage, log retention |
| `assess_multi_az_region` | Verify multi-AZ deployment within a single region |
| `assess_cross_region_dr` | Compare primary vs DR region resources across 10 regions |
| `classify_region_roles` | Detect PRIMARY/DR/NOT_USED region roles via tags or resource density |
| `full_resiliency_assessment` | Run all assessments with discovery, scoring, and formatted report |

## Architecture

```
┌─────────────┐     ┌──────────────┐     ┌────────────────┐     ┌────────────┐
│  Discovery  │────▶│   Assess     │────▶│   Classify     │────▶│   Format   │
│             │     │  (parallel)  │     │  (env + region)│     │ (md/html/  │
│ RE2/Config/ │     │  12 modules  │     │  severity adj  │     │  docx/pdf) │
│ describe    │     │  per-service │     │  region roles  │     │            │
└─────────────┘     └──────────────┘     └────────────────┘     └────────────┘
```

1. **Discover** — Identify which services have resources (skip empty categories)
2. **Assess** — Run category-specific checks in parallel threads
3. **Classify** — Tag each finding with environment context, adjust severity
4. **Format** — Generate report in requested format with prioritized recommendations

## Configuration

### Credentials

The server uses the standard AWS credential chain:

1. Environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`)
2. AWS profiles (`AWS_PROFILE`)
3. Instance metadata / container credentials
4. SSO credentials

### Cross-Account Access

Provide an `account_id` parameter to any tool — the server will `AssumeRole` to `arn:aws:iam::{account_id}:role/ReadOnlyAccess`.

Alternatively, pass temporary credentials directly:

```
assess_compute_resiliency(
    region="us-east-1",
    account_id="123456789012",
    access_key_id="ASIA...",
    secret_access_key="...",
    session_token="..."
)
```

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `AWS_REGION` | `us-east-1` | Default region for assessments |
| `AWS_PROFILE` | `default` | AWS CLI profile to use |
| `MCP_TRANSPORT` | `stdio` | MCP transport (`stdio` or `sse`) |

## Output Formats

| Format | Extension | Use Case |
|--------|-----------|----------|
| Markdown | `.md` | Quick terminal review, chat responses |
| HTML | `.html` | Shareable standalone dashboard with styling |
| DOCX | `.docx` | Formal reports for stakeholders |
| PDF | `.pdf` | Print-ready deliverables |

All formats include: summary metrics, DR readiness, tagging context, region strategy, per-category findings sorted by environment priority, and prioritized action items.

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run unit tests
pytest

# Run with coverage
pytest --cov=aws_resiliency_mcp --cov-report=term-missing

# Run integration tests (requires AWS credentials)
pytest -m integration

# Lint and format
ruff check src/ tests/
ruff format src/ tests/

# Type check
mypy src/

# Install pre-commit hooks
pre-commit install
```

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Install dev dependencies (`pip install -e ".[dev]"`)
4. Make changes and add tests
5. Ensure all checks pass (`pre-commit run --all-files`)
6. Commit (`git commit -m 'Add amazing feature'`)
7. Push and open a Pull Request

### Guidelines

- All new assessment modules must include unit tests with mocked boto3 calls
- Maintain 80%+ test coverage
- Follow existing patterns for Finding creation and environment enrichment
- Use `ruff` for formatting (enforced via pre-commit)

## License

This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.
