cloudwright-mcp

Design a cloud architecture from a natural-language description.

Primary entry point for greenfield architecture design. Returns a complete ArchSpec (YAML-serializable dict) with components, connections, tier assignments, and a cost estimate.

When to use: You have a requirement (prose) and need a concrete architecture with services, wiring, and cost. Use modify_architecture to iterate on an existing spec, or chat_create_session + chat_send for multi-turn refinement.

Behavior: Calls an LLM provider (Anthropic or OpenAI depending on configured keys) — incurs API costs per invocation. Deterministic post-processing layers (cost engine, catalog lookup) apply safe defaults like encryption-at-rest, multi-AZ on databases, and auto-scaling. Does not deploy or modify any cloud resources.

Modify an existing architecture with a natural-language instruction.

When to use: You already have an ArchSpec and want to evolve it (add a cache, swap a service, change a region). Returns the updated ArchSpec. For from-scratch design, use design_architecture. For iterative multi-turn editing with conversation memory, use chat_create_session.

Behavior: Calls an LLM provider — incurs API costs. Pure function: returns a new spec without mutating the input. Does not deploy.

Compare an architecture's service mapping across cloud providers.

Returns one translated ArchSpec per target provider, showing which services the original would become on each. Use this to understand architectural portability and equivalent services.

When to use vs compare_provider_costs: This tool returns full alternative architectures (with components, connections, tiers). compare_provider_costs returns only numeric cost totals per provider — use that when you only care about the bill, not the shape.

Behavior: Calls an LLM to resolve ambiguous service mappings where the static equivalence table is insufficient. Does not deploy.

Estimate the monthly cloud bill for an architecture spec.

Returns a structured estimate with per-component breakdown, total monthly cost, data-transfer costs, and currency. Deterministic: same spec + tier yields same result.

When to use: You need the numeric bill for one architecture on one provider+tier combination. For multi-provider comparison of just the costs, use compare_provider_costs. For side-by-side architecture + cost comparison across providers, use compare_providers + this tool.

Behavior: Pure computation — no LLM, no network, no API costs. Works offline. Does not deploy or touch cloud resources.

Compare the monthly cost totals of an architecture across cloud providers.

Returns one numeric cost summary per provider (monthly total, per-component breakdown, currency). Use this for cost-focused provider selection.

When to use vs compare_providers: This tool returns only cost numbers. compare_providers returns full alternative architectures (components, connections, tiers). If you want both the re-drawn architecture and its bill, call compare_providers first, then estimate_cost on each returned spec — or call both in parallel.

Behavior: Pure computation — no LLM, no network, no API costs. Uses the same offline catalog as estimate_cost. Does not deploy.

Validate an architecture against compliance frameworks.

Returns one result object per framework with pass/fail status per check, evidence (which components triggered the rule), and remediation hints.

When to use: You have a proposed architecture and need to know whether it satisfies HIPAA / PCI-DSS / SOC 2 / FedRAMP / GDPR before proceeding. Use security_scan for anti-pattern detection (weak auth, public buckets, etc.) which is framework-agnostic.

Behavior: Pure computation — no LLM, no network. Evaluates the spec statically against 30+ rules. Does not access or modify any cloud resources.

Scan an architecture for security anti-patterns and misconfigurations.

Returns a structured report with severity-graded findings (critical / high / medium / low / info), each tied to specific component IDs. Framework- agnostic — use validate_compliance for specific regulatory frameworks.

Checks include: unencrypted data stores, public-facing databases, missing WAF on public HTTP endpoints, weak auth on APIs, SPOFs, overly permissive connection protocols.

Behavior: Pure computation — no LLM, no network. Does not touch cloud.

Scan Terraform HCL source for security misconfigurations.

Returns findings (severity-graded) tied to specific resource blocks — e.g. aws_s3_bucket with acl = public-read, aws_security_group with cidr_blocks = 0.0.0.0/0 on sensitive ports, aws_rds_instance with storage_encrypted = false.

When to use: You have existing Terraform code (not an ArchSpec) and want an immediate security audit. For ArchSpec-level audit, use security_scan.

Behavior: Pure computation — no LLM, no network. Does not run Terraform or touch cloud. Safe for scanning untrusted HCL.

Lint an architecture for anti-patterns and best-practice violations.

Returns a list of warnings with rule name, severity (error / warning), component IDs involved, and a human-readable message.

Errors (production-blocking): unencrypted data stores, single-AZ databases, missing load balancer on public compute, public databases, single point of failure. Warnings (review-worthy): oversized instances (16xlarge+), missing WAF, missing monitoring, missing backups, missing auth.

When to use vs security_scan: lint is about architectural hygiene (is this a sane shape?). security_scan is about threat exposure (can an attacker reach X?). Use both for comprehensive review.

Behavior: Pure computation — no LLM, no network. Does not touch cloud.

Analyze blast radius and dependency structure of an architecture.

For each component (or just one, if component_id is set): returns direct dependents, transitive dependents, blast-radius size, SPOF status, and tier position. Use this to reason about failure modes — 'if component X dies, what else breaks?'

When to use: You have a spec and want to understand coupling and failure domains before production. Complementary to score_architecture (which gives a summary grade) and lint_architecture (which flags specific anti-patterns).

Behavior: Pure graph computation — no LLM, no network. Read-only. Does not touch cloud resources.

Score an architecture across reliability, security, cost, compliance, and complexity.

Returns the dimension scores, overall weighted score (0-100), letter grade, and per-dimension notes. Weights: Reliability 30% (load balancing, multi-AZ, auto-scaling, CDN, caching), Security 25% (WAF, auth, encryption, HTTPS, DNS), Cost Efficiency 20% (budget compliance, free- tier usage), Compliance 15% (framework validation), Complexity 10% (component count, connection density, tier separation).

When to use: You want a quick quality summary before a design review. For specific findings, use lint_architecture, security_scan, or validate_compliance.

Behavior: Pure computation — no LLM, no network. Read-only.

Diff two architecture specs and return a structured change report.

Returns a structured delta: components added / removed / modified, connections added / removed / modified, cost delta (USD/month), compliance-impact flags (e.g. WAF removal, encryption-at-rest turned off), and a human-readable summary.

When to use: You have two versions of a spec (before / after a proposed change) and need a reviewable diff for approval or ADR writing.

Behavior: Pure computation — no LLM, no network. Read-only. Does not modify either spec.

Export an architecture spec to Terraform, CloudFormation, Mermaid, D2, or other formats.

Returns {'format': str, 'content': str} where content is the ready-to-write payload. Terraform/CFN outputs use variables for sensitive values (no hardcoded credentials), include provider blocks with region configuration, and generate data sources for VPC/subnet discovery.

When to use: You have a finalized ArchSpec and need IaC code, a diagram, or an audit artifact. For multi-format export, call once per format.

Behavior: Pure computation — no LLM, no network. Does not write files or deploy; the caller is responsible for persisting or applying the returned content.

List all cloud services supported for a given provider.

Returns one entry per service with its slug, human-readable name, category (compute / database / storage / networking / etc.), and supported tiers. Use this to discover valid service: keys when hand-authoring ArchSpecs or mapping requirements to services.

Behavior: Pure lookup from the bundled service registry — no LLM, no network, no cloud access.

Search the cloud instance catalog by provider, specs, or text query.

Returns matching instance types with instance family, vCPU / memory / storage, hourly on-demand price, region availability, and architecture (x86 / arm). All filters combine with AND semantics.

When to use: Right-sizing workloads, finding the cheapest instance that meets a hardware bar, or discovering equivalents across families.

Behavior: Pure lookup from the bundled SQLite catalog — no LLM, no network. Prices reflect catalog snapshot date (see refresh CLI command to update).

Create a new stateful architecture-design conversation session.

Returns {'session_id': <12-char hex>}. The session_id is the handle for subsequent chat_send / chat_delete_session calls.

When to use: Multi-turn architecture design where each turn depends on the prior one (e.g. 'design it', 'now add a cache', 'now move to GCP'). For single-shot design use design_architecture; for one-shot edits of an existing spec use modify_architecture.

Behavior: Writes a new session file to the session store (persisted on disk). Does not call the LLM — the first LLM call happens on the first chat_send. Constraints are frozen at session creation and apply to every turn.

Send a message to an existing conversation session and get a response.

Returns {'response': str, 'spec': dict|None, 'usage': dict, 'cumulative_usage': dict}. spec is populated when the turn produced or modified an ArchSpec. usage reports LLM token counts for this turn; cumulative_usage totals across the whole session.

When to use: Every turn after chat_create_session. For zero-state single-shot calls use design_architecture / modify_architecture instead.

Behavior: Calls an LLM — incurs API costs proportional to the conversation history length (history grows each turn). Persists updated session state back to the session store.

List all saved conversation sessions.

Returns a list of session metadata: session_id, creation timestamp, last-activity timestamp, cumulative token usage, and whether the session currently owns a spec.

When to use: Resuming prior work, cleaning up abandoned sessions, or auditing session token spend.

Behavior: Pure disk read — no LLM, no network. Read-only.

Delete a conversation session.

Returns {'deleted': True} on success or {'error': ...} if the session did not exist. Destructive: the session's conversation history and any uncommitted spec are lost. There is no undo.

When to use: Clean-up after a completed design, or abandoning a dead-end conversation. Does not affect any deployed infrastructure — cloudwright never deploys anything.

Behavior: Removes the session file from the session store. No LLM, no network.