Animated architecture diagrams for agents and editors

"Follow the canonical Markdy specification (https://markdy.com/AGENT.md) and generate a .markdy scene:
Explain a Cache-Aside Architecture with a Web Client, API Gateway, URL Service, Redis Cluster, and PostgreSQL database. Include two animated storyboard beats: 1. Cache Hit Path and 2. Cache Miss & Async Warm."

(Tip: If you have the official Markdy MCP Server installed, just ask: "Create an animated Markdy architecture diagram for our cache-aside service.")

scene "Cache-Aside Architecture" theme=auto
layout LR

browser Client "Web Client"
gateway Gateway "API Gateway"
service Svc "URL Service"
cache Redis "Redis Cluster"
database Postgres "PostgreSQL 16"

beat cache_hit "1. Cache Hit Path":
  show $nodes stagger=60ms
  frame Client Gateway Svc Redis zoom=1.12
  Client -> Gateway "GET /link" -> Svc "resolve"
  Svc -> Redis "GET key:link"
  Svc <- Redis "200 Target URL"
  Client <- Gateway "301 Redirect"

beat cache_miss "2. Cache Miss & Async Warm":
  frame Svc Redis Postgres zoom=1.15
  Svc -> Postgres "SELECT destination WHERE key = 'link'"
  Svc <- Postgres "Row Found"
  Svc ~> Redis "SETEX key:link (Warm Cache)"
  glow Postgres color=#38bdf8 & glow Redis color=#22c55e

Static boxes and arrows fail to capture distributed systems in action. Markdy turns text into choreographed 60fps motion graphics directly in your browser.

• 🎬 Kinetic Storytelling: Choreograph requests (->), responses (<-), and events (~>) across sequential beat timelines with auto-zooms and glow cues.
• 📐 Dynamic Port Multiplexing: Automatically balances parallel connections across node boundaries with zero line congestion or overlapping paths.
• 🔗 Code Provenance & Git Grounding: Anchor high-level architecture nodes directly to verified source code (@src="src/auth.ts#L10-L50") with automated in-tree Git verification.
• 🔄 Architectural Evolution Matrix: Compare architecture states across Git commits and automatically synthesize animated migration storyboards.
• 🔬 Blast Radius & Route Pathfinder: Compute upstream dependency callers, downstream failure blast radius, and shortest message paths in real-time.
• 💎 Native Vector Symbol Registry: Embedded, zero-dependency SVG vector glyphs for AWS, GCP, Kubernetes, Docker, Postgres, Redis, Kafka, and 20+ stacks.
• ⚡ Zero-Dep & Web-Native: Powered by pure CSS/SVG transforms and the Web Animations API (WAAPI) — ~14 kB parser, no Canvas, no GSAP.
• 🔄 Universal Ingestion: 1-click migration from Mermaid, Draw.io, Docker Compose, Kubernetes manifests, and Terraform states.
• 🤖 AI-Native & MCP: Official Model Context Protocol (MCP) server for Claude, Cursor, Antigravity, and Cline with self-healing syntax diagnostics.
• 🛡️ Architecture Governance: Built-in rules prevent deadlock cycles and cross-layer bypasses.

Equip Claude, Cursor, Antigravity, VS Code, Cline, Windsurf, or Zed with self-healing syntax diagnostics, auto-repair, and transpilers:

# Claude Code / CLI
claude mcp add markdy -- npx -y @markdy/mcp-server

# Google Antigravity & Gemini CLI
agy mcp add markdy -- npx -y @markdy/mcp-server

👉 1-Click Install for Cursor ↗  •  1-Click Install for VS Code ↗  •  Full JSON Configs for 6 IDEs ↓  •  AI Agent Guide (AGENT.md) ↗

Live side-by-side animated preview (Cmd+K V), syntax highlighting, auto-completion, error squiggles, and SVG/PNG export:

# Visual Studio Code
code --install-extension hoangyell.markdy-vscode

# Cursor / VSCodium (Open VSX Registry)
cursor --install-extension hoangyell.markdy-vscode

👉 VS Code Marketplace ↗  •  Open VSX Registry ↗  •  Extension Docs ↗

Zero-CLS, SSR-placeholder islands with viewport-triggered lazy hydration for Astro documentation sites and blogs:

pnpm add @markdy/astro

---
import { Markdy } from "@markdy/astro";
import code from "./diagram.markdy?raw";
---

<Markdy code={code} client:visible />

👉 @markdy/astro Package Guide ↗

Render fenced ```markdy code blocks directly inside .mdx files with automatic lazy loading:

pnpm add @markdy/mdx react react-dom

// mdx.config.js
import { remarkMarkdy } from "@markdy/mdx";

export default {
  remarkPlugins: [[remarkMarkdy, { componentName: "MarkdyDiagram" }]],
};

👉 @markdy/mdx Package Guide ↗

Render standalone HTML diagrams or run architecture linting in CI/CD pipelines:

# Global install
npm install -g @markdy/cli

# Render diagram to animated HTML or SVG
markdy render system.markdy --out diagram.html

# Lint Markdy architecture scenes in CI/CD
markdy lint **/*.markdy

👉 CLI Package Guide ↗  •  Universal Ingestion Guide ↗

• @markdy/stdlib-systems: Standard library of semantic cloud and distributed systems node kinds.
• @markdy/language-server: Headless LSP for custom editor integrations (Neovim, Helix, Emacs).

Markdy is architected as a modular monorepo where each package fulfills a focused responsibility:

Markdy provides topological layout algorithms tailored to specific system patterns:

• Distributed Systems: architecture, flowchart, tree, state, sequence
• Security & Structure: layers, nested, swimlane, quadrant, pyramid
• Data & Product Loops: medallion, timeline, gantt, flywheel, constellation, radar, venn

Themes: midnight (dark modern), paper (light technical), blueprint (CAD cyan), editorial (serif publication), graphite (minimal dark), nebula (cosmic violet), terminal (CLI retro), sketchy (hand-drawn), ink (blue ballpoint & fountain pen ink), doodle (playful doodle).

👉 Explore all 17+ interactive scenes in the Live Gallery ↗

Convert existing diagrams and infrastructure configs into animated MarkdyScript scenes:

markdy import flow.mmd            --out flow.markdy        # Mermaid.js Flowcharts & Sequences
markdy import docker-compose.yml  --out compose.markdy     # Docker Compose Services & Networks
markdy import k8s-manifests/      --out cluster.markdy     # Kubernetes Ingress, Pods & Services
markdy import terraform.tfstate   --out infra.markdy       # Terraform Provisioned State
markdy import architecture.drawio --out diagram.markdy     # Draw.io / diagrams.net XML

Equip your favorite AI Coding Agent with native Markdy tools (validate_markdy_code, diagnose_markdy_syntax, fix_markdy_code, transpile_to_markdy) and live specification resources (markdy://spec/agent-reference).

⚡ Quick MCP Server Setup & Installation

AI Environment	Setup Action	Method
Cursor		1-Click Install ↗ or JSON Config
VS Code / Copilot		1-Click Install ↗ or JSON Config
Claude Code & Desktop		CLI (claude mcp add) & JSON
Google Antigravity		1-Command CLI (agy mcp add)
Cline / Roo Code		Config File (cline_mcp_settings.json)
Windsurf / Cascade		Config File (mcp_config.json)
Zed Editor		Config File (settings.json)

🛠️ Client Configuration Snippets

1. Claude Code & Claude Desktop

Claude Code (Anthropic CLI):

claude mcp add markdy -- npx -y @markdy/mcp-server

Claude Desktop GUI (claude_desktop_config.json):

{
  "mcpServers": {
    "markdy": {
      "command": "npx",
      "args": ["-y", "@markdy/mcp-server"]
    }
  }
}

2. Cursor & VS Code (.cursor/mcp.json or .vscode/mcp.json)

{
  "mcpServers": {
    "markdy": {
      "command": "npx",
      "args": ["-y", "@markdy/mcp-server"]
    }
  }
}

3. Google Antigravity & Gemini CLI

Via 1-Command CLI:

agy mcp add markdy -- npx -y @markdy/mcp-server

Or via Config File (~/.gemini/antigravity/mcp_config.json or .agents/mcp_config.json):

{
  "mcpServers": {
    "markdy": {
      "command": "npx",
      "args": ["-y", "@markdy/mcp-server"]
    }
  }
}

4. Cline & Roo Code (cline_mcp_settings.json)

{
  "mcpServers": {
    "markdy": {
      "command": "npx",
      "args": ["-y", "@markdy/mcp-server"]
    }
  }
}

5. Windsurf / Cascade (~/.codeium/windsurf/mcp_config.json)

{
  "mcpServers": {
    "markdy": {
      "command": "npx",
      "args": ["-y", "@markdy/mcp-server"]
    }
  }
}

6. Zed Editor (settings.json)

{
  "context_servers": {
    "markdy": {
      "command": {
        "path": "npx",
        "args": ["-y", "@markdy/mcp-server"]
      }
    }
  }
}

🧰 Available Agent Tools & Resources

• 🔍 validate_markdy_code: Check syntax, unresolved node references, and cycle rules.
• 💡 diagnose_markdy_syntax: Detailed diagnostics with exact line numbers and remediation steps.
• 🩹 fix_markdy_code: Self-healing code repair that fixes common syntax mistakes and formats AST.
• 🔄 transpile_to_markdy: Convert Mermaid, Docker Compose, Kubernetes, Terraform, or Draw.io into valid MarkdyScript.
• 📚 markdy://spec/agent-reference: Full AST grammar reference and token catalog.
• 🏛️ markdy://governance/rules: Architecture rules (Well-Architected, cycle bounds, layer separation).
• 📦 markdy://templates/catalog: 33 production-grade architecture blueprints.

👉 Read the Full AI Agent Reference Guide (AGENT.md) ↗