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:

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

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)

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

1. Identify the actors/systems (→ lanes) and steps (→ nodes) from the user's description.
2. Write FlowZap Code following all rules above.
3. Call flowzap_validate to verify syntax.
4. If valid, call flowzap_create_playground to get a shareable URL.
5. Return the FlowZap Code and the playground URL to the user.
6. 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:

Data flow scope

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

1. POST https://flowzap.xyz/api/validate — returns syntax validation result
2. 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

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)

Further resources

• FlowZap Code full spec
• LLM context file
• JSON syntax schema
• 200+ workflow templates
• MCP server docs
• npm package — flowzap-mcp v1.3.5
• GitHub