flowzap-diagrams

Original：🇺🇸 English

Translated

Generate, validate and publish workflow, sequence and architecture diagrams, using FlowZap Code DSL. Use when the user asks to create a workflow, flowchart, sequence diagram, process map or architecture diagram. Produces .fz code and shareable playground URLs via the FlowZap MCP server or public API.

1installs

Sourceflowzap-xyz/flowzap-mcp

Added on2026-02-22

NPX Install

npx skill4agent add flowzap-xyz/flowzap-mcp flowzap-diagrams

SKILL.md Content

View Translation Comparison →

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, or sequence 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:

bash

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

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

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

Not compatible (use public API instead): 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.

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

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.

Fallback: public API (no MCP)

If the MCP server is unavailable, use the public REST API (no auth required):

Validate:
```
POST /api/validate
```
with
```
{"code": "..."}
```
body

Create playground:

POST /api/playground/create

with

{"code": "..."}

body (5/min, 50/day)

Privacy: The flowzap.xyz API does not store user data. Sessions expire after 15 minutes.

Full API documentation: flowzap.xyz/docs/mcp