# Cloud Architect

Cloud architecture analysis, recommendations, and artifacts for any project. Works as an **MCP server** for AI-powered coding tools (Claude Code, Cursor, Windsurf) or as a **standalone CLI**.

Scans your project, detects your stack, and provides architecture recommendations, diagrams, decision records, and deployment comparisons for AWS, GCP, or Azure.

## Install

```bash
npm install -g github:bmdietrich/agent-cloud-architect
```

## Usage

### CLI

```bash
# Analyze a project and get architecture recommendations
cloud-architect analyze --provider aws --dir /path/to/project

# Generate a Mermaid architecture diagram
cloud-architect diagram --provider gcp --style mermaid

# Review against well-architected framework
cloud-architect review --provider azure --checklist security reliability cost

# Compare deployment options
cloud-architect compare --provider aws --options ecs-fargate eks lambda

# Generate an Architecture Decision Record
cloud-architect adr "Use Fargate for backend services" --context "Migrating from EC2"

# Ask a question using the agentic loop (requires ANTHROPIC_API_KEY)
cloud-architect ask "What's the best way to handle background jobs?" --provider aws
```

All commands accept:
- `-p, --provider <aws|gcp|azure>` — cloud provider (default: `aws`)
- `-d, --dir <path>` — project directory to analyze (default: cwd)

### MCP Server

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "cloud-architect": {
      "command": "npx",
      "args": ["-y", "github:bmdietrich/agent-cloud-architect"],
      "env": {
        "PROJECT_DIR": ".",
        "CLOUD_PROVIDER": "aws"
      }
    }
  }
}
```

Or register via Claude Code CLI:

```bash
claude mcp add cloud-architect \
  -e PROJECT_DIR=. \
  -e CLOUD_PROVIDER=aws \
  -- npx -y github:bmdietrich/agent-cloud-architect
```

## Tools

| Tool | Description |
|------|-------------|
| `analyze_project` | Scan project structure, detect stack, recommend cloud architecture |
| `generate_adr` | Generate Architecture Decision Records with context, options, and trade-offs |
| `architecture_diagram` | Produce Mermaid or D2 diagrams of the target architecture |
| `review_architecture` | Review against well-architected framework pillars (security, reliability, cost, etc.) |
| `compare_deployments` | Compare deployment options (e.g., ECS vs EKS vs Lambda) with trade-off analysis |

## How It Works

### Project Scanner

The context scanner detects:

- **Languages** — JavaScript, TypeScript, Python, Go, Rust, Java, Kotlin
- **Frameworks** — React, Next.js, Express, NestJS, FastAPI, Django, Spring, and more
- **Databases** — MongoDB, PostgreSQL, MySQL, Redis, DynamoDB, RabbitMQ, Kafka
- **Infrastructure** — Terraform, Serverless Framework, CDK, CloudFormation
- **Containers** — Dockerfiles, Docker Compose, Kubernetes manifests
- **CI/CD** — GitHub Actions, GitLab CI, Jenkins, CircleCI, CodeBuild
- **Services** — Detects individual services in monorepos with type inference (frontend, backend, worker, lambda)

### Provider Parameterization

The `cloudProvider` setting shapes all output — service names, architecture patterns, and recommendations map to the target provider:

| Concept | AWS | GCP | Azure |
|---------|-----|-----|-------|
| Serverless containers | Fargate | Cloud Run | Container Apps |
| FaaS | Lambda | Cloud Functions | Azure Functions |
| Container orchestration | ECS/EKS | GKE | AKS |
| Document DB | DocumentDB | Firestore | Cosmos DB |
| Cache | ElastiCache | Memorystore | Azure Cache for Redis |
| Queue | SQS | Pub/Sub | Service Bus |

### MCP Mode vs CLI Mode

**MCP mode** — the host AI (Claude, Cursor, etc.) is the reasoning layer. Tools return structured analysis, the AI interprets and applies it. No API key needed.

**CLI mode** — tools run directly and return markdown output. The `ask` command and `--agent` flag use an agentic loop with Claude to provide interactive analysis (requires `ANTHROPIC_API_KEY`).

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `PROJECT_DIR` | MCP mode | Project directory to analyze |
| `CLOUD_PROVIDER` | No | `aws`, `gcp`, or `azure` (default: `aws`) |
| `ANTHROPIC_API_KEY` | CLI agent mode | Required for `ask` command and `--agent` flag |

## Development

```bash
git clone github:bmdietrich/agent-cloud-architect
cd cloud-architect
npm install
npm run dev          # watch mode
npm run build        # one-time build
```

## License

MIT