FlowZap Diagram Skill

Generate valid FlowZap Code (.fz) diagrams from natural-language descriptions, validate them, and return shareable playground URLs — all without leaving your coding agent.

When to use this skill

User asks for a workflow, flowchart, process diagram, sequence diagram, or achitecture diagram.
User pastes HTTP logs, OpenAPI specs, or code and wants them visualised.
User wants to compare two diagram versions (diff) or patch an existing diagram.

MCP server setup (one-time)

If the FlowZap MCP server is not already configured, install it:

# Claude Code
claude mcp add --transport stdio flowzap -- npx flowzap-mcp@1.3.5

# Or add to .mcp.json / claude_desktop_config.json / cursor / windsurf config:
{
  "mcpServers": {
    "flowzap": {
      "command": "npx",
      "args": ["flowzap-mcp@1.3.5"]
    }
  }
}

Package verification

The pinned version 1.3.5 can be verified against the npm registry:

Field	Value
npm	flowzap-mcp@1.3.5
Integrity (SHA-512)	`sha512-MjiOEHoG08UdLflnls6Ij07bXiJmuGbCrWSm5fycizZ70PecVeAb0DSrrFxAPOB8hQcZ0Y/WQtXbgRRQr/t/nA==`
Shasum	`374c7a966c1a1f350216c513df32383a772d360d`
Source	github.com/flowzap-xyz/flowzap-mcp
License	MIT

To verify locally before use:

npm view flowzap-mcp@1.3.5 dist.integrity dist.shasum

Compatible tools: Claude Desktop, Claude Code, Cursor, Windsurf, OpenAI Codex, Warp, Zed, Cline, Roo Code, Continue.dev, Sourcegraph Cody.

Not compatible: Replit, Lovable.dev.

Available MCP tools

Tool	Purpose
`flowzap_validate`	Check .fz syntax before sharing
`flowzap_create_playground`	Get a shareable playground URL
`flowzap_get_syntax`	Retrieve full DSL docs at runtime
`flowzap_export_graph`	Export diagram as structured JSON (lanes, nodes, edges)
`flowzap_artifact_to_diagram`	Parse HTTP logs / OpenAPI / code → diagram + playground URL
`flowzap_diff`	Structured diff between two .fz versions
`flowzap_apply_change`	Patch a diagram (insert/remove/update nodes/edges)

FlowZap Code DSL — quick reference

FlowZap Code is not Mermaid, not PlantUML. It is a unique DSL offering a simple syntax for a triple-view option to workflow, sequence and architecture diagrams.

Shapes (only 4)

Shape	Use for
`circle`	Start / End events
`rectangle`	Process steps / actions
`diamond`	Decisions (Yes/No branching)
`taskbox`	Assigned tasks (`owner`, `description`, `system`)

Syntax rules

Node IDs are globally unique, sequential, no gaps: n1, n2, n3 …
Node attributes use colon: label:"Text"
Edge labels use equals inside brackets: [label="Text"]
Handles are required on every edge: n1.handle(right) -> n2.handle(left)
Directions: left, right, top, bottom
Cross-lane edges: prefix target with lane name: sales.n5.handle(top)
Lane display label: one # Label comment right after opening brace
Loops: loop [condition] n1 n2 n3 — flat, inside a lane block
Layout: prefer horizontal left→right; use top/bottom only for cross-lane hops

Multi-lane sequence design

Ping-pong rule: For multi-participant processes, every cross-lane interaction must alternate back-and-forth between lanes. A request from Lane A → Lane B must be followed by a response from Lane B → Lane A before any new request from Lane A. This ensures the sequence view renders meaningful request-response message pairs rather than one-way broadcasts.

Gotchas — never do these

Do NOT use label="Text" on nodes (must be label:"Text").
Do NOT use label:"Text" on edges (must be [label="Text"]).
Do NOT skip node numbers (n1, n3 → invalid; must be n1, n2).
Do NOT omit lane prefix on cross-lane edges.
Do NOT output Mermaid, PlantUML, or any other syntax.
Do NOT add comments except the single # Display Label per lane.
Do NOT place loop outside a lane's braces.
Do NOT use a taskbox shape unless the user explicitly requests it.

Minimal templates

Single lane:

process { # Process
n1: circle label:"Start"
n2: rectangle label:"Step"
n3: circle label:"End"
n1.handle(right) -> n2.handle(left)
n2.handle(right) -> n3.handle(left)
}

Two lanes with cross-lane edge:

user { # User
n1: circle label:"Start"
n2: rectangle label:"Submit"
n1.handle(right) -> n2.handle(left)
n2.handle(bottom) -> app.n3.handle(top) [label="Send"]
}

app { # App
n3: rectangle label:"Process"
n4: circle label:"Done"
n3.handle(right) -> n4.handle(left)
}

Decision branch:

flow { # Flow
n1: rectangle label:"Check"
n2: diamond label:"OK?"
n3: rectangle label:"Fix"
n4: rectangle label:"Proceed"
n1.handle(right) -> n2.handle(left)
n2.handle(bottom) -> n3.handle(top) [label="No"]
n2.handle(right) -> n4.handle(left) [label="Yes"]
}

For the full DSL specification and advanced multi-lane examples: See references/syntax.md

Workflow: how to generate a diagram

Identify the actors/systems (→ lanes) and steps (→ nodes) from the user's description.
Write FlowZap Code following all rules above.
Call flowzap_validate to verify syntax.
If valid, call flowzap_create_playground to get a shareable URL.
Return the FlowZap Code and the playground URL to the user.
Always output only raw FlowZap Code when showing the diagram — no Markdown fences wrapping .fz content, no extra commentary mixed in.

Full MCP documentation: flowzap.xyz/docs/mcp

Security and data transparency

The flowzap-mcp server runs locally on the user's machine (stdio transport) and enforces the following safeguards:

Control	Detail
TLS only	All outbound requests require `https://` and are restricted to `flowzap.xyz` (SSRF protection)
No authentication	Uses only public FlowZap APIs; no API keys, tokens, or user credentials are stored or transmitted
No user-data access	Cannot read diagrams, accounts, or any data beyond what the agent explicitly passes in
Input validation	Code capped at 50 KB, total input at 100 KB; null bytes and control characters stripped
Rate limiting	Client-side 30 requests/minute sliding window
Request timeout	30-second hard timeout with `AbortController`
Response sanitization	Only expected fields are returned; playground URLs validated against allowlist
Audit logging	All tool calls and API requests logged to `stderr` (not exposed to the MCP client)

Data flow scope

The MCP server sends only the FlowZap Code provided by the agent to two public endpoints:

POST https://flowzap.xyz/api/validate — returns syntax validation result
POST https://flowzap.xyz/api/playground/create — returns an ephemeral playground URL (60-minute TTL, non-guessable token)

No other data (file paths, environment variables, user identity) is transmitted.

Playground URL access controls

Playground URLs are ephemeral, time-limited (60-minute TTL), and use non-guessable cryptographic tokens. They are read-only views of the diagram code submitted at creation time. No account or login is required to view them; no data persists beyond the TTL.

Data lifecycle

Endpoint	Data stored	Retention
`POST /api/validate`	None — stateless; code is parsed in memory and discarded after the response	0 (not persisted)
`POST /api/playground/create`	FlowZap Code only (in PostgreSQL)	60 minutes (database row + playground URL both expire)

The playground session is stored server-side with a cryptographic token (UUID v4). After the 60-minute TTL, the session is deleted — either on the next access attempt or during a periodic sweep. No user identity, file paths, environment variables, or host metadata are attached to the session.

What the MCP server does NOT do

No filesystem access — cannot read or write files on the host machine
No environment variable access — does not read or transmit process.env or shell variables
No code execution — does not evaluate, compile, or run any user code; it only transmits FlowZap DSL text
No network scanning — outbound connections are restricted to flowzap.xyz over TLS (SSRF-protected allowlist)
No long-term data persistence — playground sessions expire after 60 minutes; the validate endpoint stores nothing
No telemetry or tracking — no analytics, device fingerprinting, or usage data is collected by the MCP server; server-side API logs record only IP, user-agent, and code length (not code content)

flowzap-diagrams