# skmahe1077/aws-wa-mcp-server architecture

> Architecture diagram of the GitHub repository skmahe1077/aws-wa-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/skmahe1077/aws-wa-mcp-server
- Repository: https://github.com/skmahe1077/aws-wa-mcp-server

## Overview

AWS Well-Architected MCP Server exposes read-only account scans through an MCP interface. A user selects a pillar scan or an account-wide scan; the server resolves the AWS session and region, runs pillar checks against AWS, and returns findings, severity-based health scores, skipped checks, compliance mappings, and audit metadata. Six distinct pillar modules preserve the product’s domain coverage; shared scan primitives provide the internal result, scoring, and compliance layer. The excerpts show the server, shared primitives, and some pillar checks; other pillar capabilities are documented in the README, so their internal details are not inferred.

Main entry points: [`aws_wa_mcp/server.py`](https://github.com/skmahe1077/aws-wa-mcp-server/blob/main/aws_wa_mcp/server.py) (MCP scan server), [`aws_wa_mcp/pillars/__init__.py`](https://github.com/skmahe1077/aws-wa-mcp-server/blob/main/aws_wa_mcp/pillars/__init__.py) (Pillar registry), [`aws_wa_mcp/pillars/common.py`](https://github.com/skmahe1077/aws-wa-mcp-server/blob/main/aws_wa_mcp/pillars/common.py) (Scan primitives), [`aws_wa_mcp/pillars/cost_optimization.py`](https://github.com/skmahe1077/aws-wa-mcp-server/blob/main/aws_wa_mcp/pillars/cost_optimization.py) (Cost optimization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["MCP interface"]
  node_server["MCP scan server<br/>[server.py]"]
  node_registry["Pillar registry<br/>[__init__.py]"]
end

subgraph group_scanners["Pillar scanners"]
  node_cost["Cost optimization"]
  node_reliability["Reliability<br/>[reliability.py]"]
  node_performance["Performance efficiency"]
  node_operations["Operational excellence"]
  node_security["Security<br/>[security.py]"]
  node_sustainability["Sustainability<br/>[sustainability.py]"]
end

subgraph group_analysis["Scan analysis"]
  node_common["Scan primitives<br/>[common.py]"]
end

subgraph group_external["External systems"]
  node_aws[("AWS account APIs")]
end

node_user(("Assistant user"))

node_user -->|"requests scans"| node_server
node_server -->|"loads tools"| node_registry
node_registry -->|"registers scanner"| node_cost
node_registry -->|"registers scanner"| node_reliability
node_registry -->|"registers scanner"| node_performance
node_registry -->|"registers scanner"| node_operations
node_registry -->|"registers scanner"| node_security
node_registry -->|"registers scanner"| node_sustainability
node_server -->|"runs selected scan"| node_cost
node_server -->|"runs selected scan"| node_reliability
node_server -->|"runs selected scan"| node_performance
node_server -->|"runs selected scan"| node_operations
node_server -->|"runs selected scan"| node_security
node_server -->|"runs selected scan"| node_sustainability
node_cost -->|"uses shared checks"| node_common
node_reliability -->|"uses shared checks"| node_common
node_performance -->|"uses shared checks"| node_common
node_operations -->|"uses shared checks"| node_common
node_security -->|"uses shared checks"| node_common
node_sustainability -->|"uses shared checks"| node_common
node_server -->|"builds scan response"| node_common
node_server -->|"reads caller identity"| node_aws
node_cost -->|"reads account resources"| node_aws
node_reliability -->|"reads account resources"| node_aws
node_performance -->|"reads account resources"| node_aws
node_operations -->|"reads account resources"| node_aws
node_security -->|"reads account resources"| node_aws
node_sustainability -->|"reads account resources"| node_aws

click node_server "https://github.com/skmahe1077/aws-wa-mcp-server/blob/main/aws_wa_mcp/server.py"
click node_registry "https://github.com/skmahe1077/aws-wa-mcp-server/blob/main/aws_wa_mcp/pillars/__init__.py"
click node_cost "https://github.com/skmahe1077/aws-wa-mcp-server/blob/main/aws_wa_mcp/pillars/cost_optimization.py"
click node_reliability "https://github.com/skmahe1077/aws-wa-mcp-server/blob/main/aws_wa_mcp/pillars/reliability.py"
click node_performance "https://github.com/skmahe1077/aws-wa-mcp-server/blob/main/aws_wa_mcp/pillars/performance_efficiency.py"
click node_operations "https://github.com/skmahe1077/aws-wa-mcp-server/blob/main/aws_wa_mcp/pillars/operational_excellence.py"
click node_security "https://github.com/skmahe1077/aws-wa-mcp-server/blob/main/aws_wa_mcp/pillars/security.py"
click node_sustainability "https://github.com/skmahe1077/aws-wa-mcp-server/blob/main/aws_wa_mcp/pillars/sustainability.py"
click node_common "https://github.com/skmahe1077/aws-wa-mcp-server/blob/main/aws_wa_mcp/pillars/common.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_registry,node_user toneBlue
class node_cost,node_reliability,node_performance,node_operations,node_security,node_sustainability toneAmber
class node_common toneMint
class node_aws toneRose
```

## Components

### MCP interface

- [MCP scan server](https://github.com/skmahe1077/aws-wa-mcp-server/blob/main/aws_wa_mcp/server.py): `aws_wa_mcp/server.py`
- [Pillar registry](https://github.com/skmahe1077/aws-wa-mcp-server/blob/main/aws_wa_mcp/pillars/__init__.py): `aws_wa_mcp/pillars/__init__.py`

### Pillar scanners

- [Cost optimization](https://github.com/skmahe1077/aws-wa-mcp-server/blob/main/aws_wa_mcp/pillars/cost_optimization.py): `aws_wa_mcp/pillars/cost_optimization.py`
- [Reliability](https://github.com/skmahe1077/aws-wa-mcp-server/blob/main/aws_wa_mcp/pillars/reliability.py): `aws_wa_mcp/pillars/reliability.py`
- [Performance efficiency](https://github.com/skmahe1077/aws-wa-mcp-server/blob/main/aws_wa_mcp/pillars/performance_efficiency.py): `aws_wa_mcp/pillars/performance_efficiency.py`
- [Operational excellence](https://github.com/skmahe1077/aws-wa-mcp-server/blob/main/aws_wa_mcp/pillars/operational_excellence.py): `aws_wa_mcp/pillars/operational_excellence.py`
- [Security](https://github.com/skmahe1077/aws-wa-mcp-server/blob/main/aws_wa_mcp/pillars/security.py): `aws_wa_mcp/pillars/security.py`
- [Sustainability](https://github.com/skmahe1077/aws-wa-mcp-server/blob/main/aws_wa_mcp/pillars/sustainability.py): `aws_wa_mcp/pillars/sustainability.py`

### Scan analysis

- [Scan primitives](https://github.com/skmahe1077/aws-wa-mcp-server/blob/main/aws_wa_mcp/pillars/common.py): `aws_wa_mcp/pillars/common.py`

### External systems

- **AWS account APIs**

### Other components

- **Assistant user**

## Connections

- Assistant user → MCP scan server: requests scans (evidence: `README.md`)
- MCP scan server → Pillar registry: loads tools (evidence: `aws_wa_mcp/server.py`)
- Pillar registry → Cost optimization: registers scanner (evidence: `aws_wa_mcp/pillars/__init__.py`)
- Pillar registry → Reliability: registers scanner (evidence: `aws_wa_mcp/pillars/__init__.py`)
- Pillar registry → Performance efficiency: registers scanner (evidence: `aws_wa_mcp/pillars/__init__.py`)
- Pillar registry → Operational excellence: registers scanner (evidence: `aws_wa_mcp/pillars/__init__.py`)
- Pillar registry → Security: registers scanner (evidence: `aws_wa_mcp/pillars/__init__.py`)
- Pillar registry → Sustainability: registers scanner (evidence: `aws_wa_mcp/pillars/__init__.py`)
- MCP scan server → Cost optimization: runs selected scan (evidence: `README.md`)
- MCP scan server → Reliability: runs selected scan (evidence: `README.md`)
- MCP scan server → Performance efficiency: runs selected scan (evidence: `README.md`)
- MCP scan server → Operational excellence: runs selected scan (evidence: `README.md`)
- MCP scan server → Security: runs selected scan (evidence: `README.md`)
- MCP scan server → Sustainability: runs selected scan (evidence: `README.md`)
- Cost optimization → Scan primitives: uses shared checks (evidence: `aws_wa_mcp/pillars/cost_optimization.py`)
- Reliability → Scan primitives: uses shared checks (evidence: `aws_wa_mcp/pillars/reliability.py`)
- Performance efficiency → Scan primitives: uses shared checks (evidence: `aws_wa_mcp/pillars/performance_efficiency.py`)
- Operational excellence → Scan primitives: uses shared checks (evidence: `aws_wa_mcp/pillars/operational_excellence.py`)
- Security → Scan primitives: uses shared checks (evidence: `aws_wa_mcp/pillars/security.py`)
- Sustainability → Scan primitives: uses shared checks (evidence: `aws_wa_mcp/pillars/sustainability.py`)
- MCP scan server → Scan primitives: builds scan response (evidence: `aws_wa_mcp/server.py`)
- MCP scan server → AWS account APIs: reads caller identity (evidence: `aws_wa_mcp/server.py`)
- Cost optimization → AWS account APIs: reads account resources (evidence: `README.md`)
- Reliability → AWS account APIs: reads account resources (evidence: `README.md`)
- Performance efficiency → AWS account APIs: reads account resources (evidence: `README.md`)
- Operational excellence → AWS account APIs: reads account resources (evidence: `README.md`)
- Security → AWS account APIs: reads account resources (evidence: `aws_wa_mcp/pillars/security.py`)
- Sustainability → AWS account APIs: reads account resources (evidence: `README.md`)
