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

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

Usage

CLI

# 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:

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

Or register via Claude Code CLI:

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

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