AGENTS.md

Guidance for AI agents driving this MCP server. The primary consumer is an agent that turns a described architecture into a diagram.

Pick the right tool

• generate_html_diagram — the default. Self-contained interactive HTML (open in a browser or attach to an email). Use for almost everything.
• auto_generate_diagram — when the user explicitly wants an editable .drawio file laid out automatically. (The HTML also exports .drawio from a button, so prefer generate_html_diagram unless a file is required.)
• generate_diagram — only when you need manual x/y control.
• export_diagram — rasterize an existing .drawio to PNG/SVG/PDF (needs the draw.io CLI installed).
• render_diagram_media — turn an interactive diagram HTML (from generate_html_diagram/diagram_render) into a PNG figure, an animated GIF, and/or an animated SVG, for embedding where JS can't run (blog/WordPress, PDF, email, slide). Two GIF modes: flow (dots looping along the edges) and walkthrough (one animated segment per steps beat, concatenated into a looping tour). The SVG is vector + still animated (flow-dot SMIL kept) — sharp/tiny, but the AWS Blog/WordPress blocks SVG upload, so use SVG for your OWN site and GIF for WordPress. Needs Playwright (npx playwright install chromium) and, for GIF, a full ffmpeg. For a seamless flow loop, pass the SAME seconds value as flowPeriod to generate_html_diagram and as period to render_diagram_media.
• resolve_icon — check/lookup the icon filename for a service name.
• list_service_configs — a service's IaC config fields.
• export_iac_json — hand the diagram's architecture off to the official AWS IaC MCP (resources + dependencies + per-node config.iac).
• export_diagram_json — extract the diagram's elements as neutral JSON (title, services[], connections[], groups[], per-node config). Every generated diagram also writes this as a sidecar .json next to the HTML.
• Pricing / cost: this server does NOT price. Hand the diagram off — the sidecar .json (or export_diagram_json) — to a cost app such as aws-cost-app-mcp (a separate MCP), which resolves calculator keys and prices via calculator.aws (no AWS credentials).

Making a diagram into media (GIF / PNG / SVG)

1. generate_html_diagram(..., flowPeriod: 4) for a flow GIF, or add steps (with stepZoom: true) for a walkthrough GIF.
2. render_diagram_media({ htmlPath, gifPath, mode: 'flow'|'walkthrough', period: 4 }). Add pngPath and/or svgPath for more formats in one call.
3. flow → one seamless loop of the animated data flow. walkthrough → a tour that holds beatDuration on each beat (with its zoom/highlight/card) and loops back to the first.
4. Pick the format by destination:
   • AWS Blog / WordPress → GIF (animated) or PNG (static). SVG upload is blocked there.
   • Your own site / embed → SVG — vector, tiny, and still animated.

Authoring a good generate_html_diagram call

1. Name services canonically. Use the official AWS name (e.g. "Amazon Simple Storage Service" or "Amazon S3"). The icon is auto-resolved from the name — do NOT guess an icon filename. If unsure a name resolves, call resolve_icon.
2. Set category (compute/storage/database/networking/security/integration/ analytics/ai/management/general) — it drives the node color.
3. Add role to every service — one line on what it does. This is what makes the diagram documentation, not just boxes.
4. Type the connections (network/iam/event/data) so relationships read correctly (auth vs. async vs. data flow).
5. Place things:
   • Single VPC → just set subnet: "public" | "private" per service.
   • Anything else (multi-VPC, multi-account, AZs, on-prem) → declare groups (with parent for nesting) and point each service at one via parentId.
   • Third-party / on-prem actors → external: true.
6. Capture the WHY — add adr (context/decision/consequences) and wellArchitected pillar notes when the user gave rationale. These flow into the IaC handoff so generated infra honors the intent.
7. Do NOT ask this server to generate IaC. The IaC button emits a spec for the official awslabs.aws-iac-mcp-server; hand off to that.

8. Add a caption when the file will be read without you. The diagram's title/subtitle only live in the small floating dock, so a diagram opened cold — an email attachment, a wiki link, a PDF page — starts as boxes with no framing. caption renders a header band above the canvas:

   "caption": {
     "eyebrow": "Arquitetura alvo",              // small uppercase label, AWS orange
     "title": "Portal do Cidadão — camada pública",
     "text": "One paragraph: what this shows and for whom.",
     "meta": ["Versão: v2", "Data: 28/09/2026", "Ambiente: produção"]
   }

   A plain string (or a { en, pt } map) is shorthand for just text. Each meta entry written as "Label: value" renders as a labelled stat; anything else renders as a bare value. In a tabbed document the band sits above the tab rail, so it frames every view. Omit caption for the classic bare canvas (a slide, or a diagram whose surrounding page already has the title).

When the flow matters: add a sequence tab

If the user's ask is about an order of operations (a vend/provisioning flow, an auth handshake, a CI/CD pipeline, a saga), the architecture alone under-serves it. Pass sequence to generate_html_diagram (or diagram_add_sequence on a draft) and the SAME file gains a tab rail: Architecture + the animated UML sequence player. It is the SAME schema and renderer as the standalone generate_sequence_diagram output — author it once, embed it either way.

• participants[]: { id, label, sub?, service?, icon?, actor?, stereotype? } — give service (canonical AWS name) and the icon resolves itself; use icon: 'tech-icons/<x>.svg' for non-AWS lifelines; actor: true for a human.
• events[] in order, each with a required id and an explicit kind:
  • { kind: 'message', id, from, to, label, arrow?, tone?, badge?, … } — arrow: 'sync'|'async'|'reply' (reply = dashed return), badge: 'gate' for a blocking check, plus activate/deactivate/create/destroy/found/lost.
  • { kind: 'note', id, over: [a, b], label } for a band of explanation.
• fragments[] is a SEPARATE array anchored by event id — never inline begin/else/end events: { kind: 'alt'|'opt'|'loop'|'par'|'break'|'critical'|'ref'| 'neg'|'assert', label, startId, endId, dividers?: [{ beforeId, label }] }.
• groups[] boxes participant columns: { label, participants: [ids], tone? }.
• Narrate the important beats: title, flow, desc (inline markdown), code + codeLabel, and proof (free text or {repo, path, ref, lines} → clickable link).
• Add tabs[] yourself only when you need more than the two default tabs (e.g. a kind: 'doc' tab with sections[] for runbook/decision prose). Tab labels default per kind, so { id, kind } is enough.
• Keep the two views CONSISTENT: every sequence participant should exist as a node (or group) in the architecture, using the same wording.

Typed diagrams in the same document

A kind: 'typed' tab carries one typed diagram: { id, kind: 'typed', label?, diagram: { kind, title?, … } } with diagram.kind one of er, gantt, swimlane, tree, timeline, kanban, journey, quadrant, venn, layers, fishbone, wardley, flywheel, class, workflow. Each kind's fields follow its spec in packages/diagram-core/src/typed/<kind>.js (the same specs a downstream app validates with); an invalid body fails the render with the spec's messages, so fix it and render again.

• Use a typed tab for what the architecture canvas is not: a migration plan (gantt), a data model (er), a cross-team process (swimlane), a decision tree (workflow — decisions, branches that converge, narrated steps).
• A workflow tab is the same document generate_workflow_diagram takes (nodes, edges, steps); node icons resolve from service.

Group variants

aws-cloud, region, vpc, public-subnet, private-subnet, availability-zone, account, organization, auto-scaling-group, group (generic logical), corporate-data-center, on-premises.

Gotchas

• Icons are not bundled. If a render result warns that the icon set is missing (or a diagram comes out as letters), call setup_icons — it finds the icon package zip (Icon-package_<date>.zip) in ~/Downloads on its own and installs into the shared ~/.aws-architecture-icons, so it is needed once per machine, not once per install. If it finds no zip it returns the download link: relay that to the user, then call it again.
• Layouts: TB (default), LR, RADIAL. Radial is for flat hub-and-spoke and ignores groups.
• Keep process/step detail in connections[].label and adr, not as extra floating text — the canvas stays clean (AWS diagram guideline).