FlowZap

FlowZap's MCP generates Workflow, Sequence and Architecture Diagrams from your App in seconds. Pretty ones.

造訪 flowzap.xyz

Welcome to FlowZap, the App to diagram with Speed, Clarity and Control.

FlowZap MCP Server Documentation

🤖 This documentation is optimized for LLM and AI Agent consumption

Version 1.3.6 | Last Updated: April 2026 | Stricter validation, ping-pong sequence enforcement, playground endpoint alignment

npm packageFlowZap Code SyntaxAgent APIOpenAPIPublic MCP Stats

Overview

The FlowZap MCP (Model Context Protocol) Server enables AI agents to create, validate, and share professional Workflow, Sequence and Architecture diagrams using FlowZap Code—a domain-specific language designed for machine-readable diagram generation.

Tip: Use it with the SKILL md file for optimal results!

What is FlowZap?

PurposeConvert text-based code into visual workflow diagrams
Optimized ForAI-first generation, agentic workflows (n8n, Make.com, Zapier)
Unique FeatureTriple-view rendering - same code renders as workflow, sequence, AND architecture diagrams
SharingInstant shareable URLs without authentication

Security Guarantees

The FlowZap MCP Server implements enterprise-grade security measures to protect users:

Network Security

ProtectionImplementation
SSRF PreventionOnly connects to flowzap.xyz and www.flowzap.xyz via HTTPS
URL ValidationAll returned URLs are verified to originate from FlowZap domains
Request Timeout30-second timeout prevents hanging connections

Input Validation

LimitValuePurpose
Max Code Length50,000 charactersPrevents memory exhaustion
Max Input Length100,000 charactersProtects against payload attacks
Null Byte RemovalAutomaticPrevents injection attacks
Control Character SanitizationAutomaticRemoves non-printable characters

Rate Limiting

ParameterValue
Max Requests30 per minute
Window Duration60 seconds
BehaviorReturns retry-after time when exceeded

Data Privacy

  • No Authentication Required - Public endpoints only
  • No User Data Stored - Playground sessions are ephemeral (60-minute TTL, non-guessable cryptographic tokens)
  • No Tracking - No cookies or persistent identifiers
  • Logs to stderr only - Security events never exposed to MCP clients

Available Tools

1. flowzap_get_syntax

Purpose: Retrieve complete FlowZap Code syntax documentation.

When to Use: Before generating any FlowZap Code, call this tool to learn the correct syntax.

Input Schema:

{
  "type": "object",
  "properties": {}
}

Output: Complete syntax guide including global constraints, shape types, node syntax, edge syntax, loop syntax, and common mistakes to avoid.

2. flowzap_validate

Purpose: Validate FlowZap Code syntax before creating a diagram.

When to Use: Always validate code before calling flowzap_create_playground. This prevents errors and provides actionable feedback.

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "FlowZap Code to validate"
    }
  },
  "required": ["code"]
}

Success Output:

✅ FlowZap Code is valid!

Stats:
- Lanes: 2
- Nodes: 5
- Edges: 4

Failure Output:

❌ Validation failed:
- Line 3: Unknown shape "oval". Valid shapes: circle, rectangle, diamond, taskbox
- Line 5: Edge missing handle syntax. Use: n1.handle(right) -> n2.handle(left)

3. flowzap_create_playground

Purpose: Create a shareable playground URL with the diagram.

When to Use: After validation passes, create a playground to give users an interactive diagram they can view and edit.

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "FlowZap Code to load in the playground"
    },
    "view": {
      "type": "string",
      "enum": ["workflow", "sequence", "architecture"],
      "description": "Initial view mode. Default: workflow"
    }
  },
  "required": ["code"]
}

Output:

✅ Playground created!

🔗 **View your diagram:** https://flowzap.xyz/playground/abc123?view=architecture

The diagram is ready to view and edit. Share this link with anyone!

View Modes:

ViewBest For
workflowStep-by-step process flows (default)
sequenceMessage exchanges between participants
architectureSystem-level overview showing lanes as systems

Important Notes:

  • Automatically validates code before creating playground
  • Returns validation errors if code is invalid
  • Playground URLs expire after 60 minutes
  • No authentication required to view
  • Use view="architecture" for system-level overview of multi-lane diagrams

Validation Rules Reference

The validator performs comprehensive validation checks across multiple categories. Understanding these helps generate valid code on the first attempt.

Error Codes (Block Diagram Creation)

CodeDescriptionFix
CONTAINS_EMOJIEmoji characters detectedUse UTF-8 plain text only
NESTED_LANELane defined inside another laneFlatten lane structure
UNMATCHED_BRACEClosing } without opening {Check brace balance
UNCLOSED_BRACEMissing closing }Add closing brace
DUPLICATE_NODE_IDSame node ID used twiceUse unique IDs: n1, n2, n3...
INVALID_SHAPEUnknown shape typeUse: circle, rectangle, diamond, taskbox
MISSING_LABELNode without label (except taskbox)Add label:"Text"
NODE_OUTSIDE_LANENode defined outside any laneMove inside a lane block
MISSING_HANDLESEdge without handle syntaxUse n1.handle(right) -> n2.handle(left)
INVALID_EDGE_SYNTAXMalformed edge definitionCheck arrow syntax ->
INVALID_DIRECTIONUnknown handle directionUse: left, right, top, bottom
EDGE_OUTSIDE_LANEEdge defined outside any laneMove inside a lane block
UNDEFINED_LANE_REFCross-lane ref to non-existent laneCheck lane name spelling
INVALID_LOOP_SYNTAXMalformed loop definitionUse loop [condition] n1 n2
LOOP_OUTSIDE_LANELoop defined outside any laneMove inside a lane block
MISPLACED_COMMENTComment in wrong locationPut the only allowed comment on the same line as the lane opening brace
COMMENT_OUTSIDE_LANEComment outside any laneRemove it or move the display label onto the lane opening line
UNDEFINED_NODEEdge references undefined nodeDefine node before referencing
NON_SEQUENTIAL_NUMBERINGNode numbering does not start at n1 or has a gapUse n1, n2, n3... sequentially across the whole diagram
WRONG_LABEL_SYNTAXNode label uses = instead of :Use label:"Text" for node attributes
WRONG_EDGE_LABEL_SYNTAXEdge label uses : instead of =Use [label="Text"] for edge labels
ORPHAN_NODENode is not connected to any edgeConnect it as a source or target edge, or remove it
MISSING_RETURN_EDGECross-lane request has no corresponding return edgeAdd a response edge from the target lane back to the source lane
MULTIPLE_OUTBOUND_REQUESTSA lane sends another cross-lane request before the prior one is answeredUse a strict request → response → next request rhythm
CHRONOLOGICAL_PAIRING_VIOLATIONA different cross-lane request appears before the previous return edgeReorder edges to match the true request/response timeline
EMPTY_DIAGRAMNo nodes definedAdd at least one node
WRONG_DSL_FORMATMermaid/PlantUML detectedUse FlowZap syntax only

Warning Codes (Best Practice Violations)

CodeDescriptionRecommendation
NON_PRINTABLE_CHARSControl characters detectedUse plain text only
DUPLICATE_LANESame lane defined twiceMerge into single block
MISSING_LANE_LABELLane without # Display NameAdd display label
NON_STANDARD_NODE_IDID not in n1, n2, n3 formatUse standard numbering
TASKBOX_MISSING_PROPSTaskbox without owner/descriptionAdd required properties
LOOP_TOO_FEW_NODESLoop with only 1 nodeInclude at least 2 nodes
UNKNOWN_ATTRIBUTENon-standard attribute usedUse: label, owner, description, system
LABEL_TOO_LONGLabel exceeds 50 charactersKeep labels concise

FlowZap Code Syntax Quick Reference

Global Constraints

✓ UTF-8 plain text only (no emojis)
✓ Node IDs: n1, n2, n3... (globally unique, sequential, no gaps)
✓ Shapes: circle, rectangle, diamond, taskbox
✓ Attributes: label, owner, description, system
✓ Comments: Only "# Display Label" on the same line as the lane opening brace
✓ Sequence view: alternate cross-lane request and response edges in real chronological order
✗ No Mermaid, PlantUML, or other DSL syntax

Basic Structure

laneName { # Lane Display Name
  n1: circle label:"Start"
  n2: rectangle label:"Process"
  n1.handle(right) -> n2.handle(left)
}

Shape Types

ShapePurposeExample
circleStart/End eventsn1: circle label:"Start"
rectangleTasks/Activitiesn2: rectangle label:"Process Order"
diamondDecision gatewaysn3: diamond label:"Valid?"
taskboxAssigned tasksn4: taskbox owner:"Alice" description:"Deploy"

Edge Syntax

# Basic edge
n1.handle(right) -> n2.handle(left)

# Edge with label
n2.handle(bottom) -> n3.handle(top) [label="Yes"]

# Cross-lane edge (prefix with lane name)
n3.handle(right) -> fulfillment.n4.handle(left) [label="Send"]

Handle Directions

DirectionPosition
leftLeft side of node
rightRight side of node
topTop of node
bottomBottom of node

Loop Syntax

loop [retry up to 3 times] n1 n2 n3
  • Must be inside a lane block
  • Cannot be nested
  • Should reference at least 2 nodes

Complete Example

sales { # Sales Team
  n1: circle label:"Order Received"
  n2: rectangle label:"Validate Order"
  n5: rectangle label:"Receive decision"
  n1.handle(right) -> n2.handle(left)
  n2.handle(bottom) -> fulfillment.n3.handle(top) [label="Submit"]
}

fulfillment { # Fulfillment
  n3: rectangle label:"Review Order"
  n4: rectangle label:"Return decision"
  n3.handle(right) -> n4.handle(left)
  n4.handle(top) -> sales.n5.handle(bottom) [label="Approved"]
}

Recommended Workflow for AI Agents

  1. Step 1: Learn Syntax
    {"name": "flowzap_get_syntax", "arguments": {}}}
  2. Step 2: Generate Code
    Based on user request, generate FlowZap Code following the syntax rules.
  3. Step 3: Validate
    {"name": "flowzap_validate", "arguments": {"code": "..."}}
  4. Step 4: Fix Errors (if any)
    Parse error messages and correct the code.
  5. Step 5: Create Playground
    {"name": "flowzap_create_playground", "arguments": {"code": "..."}}
  6. Step 6: Present to User
    Share the playground URL with the user.

Common Mistakes to Avoid

MistakeIncorrectCorrect
Lane comment on separate linelaneName { # LabellaneName { # Label
Abbreviated shapesn1: rectn1: rectangle
Missing handlesn1 -> n2n1.handle(right) -> n2.handle(left)
Wrong node attribute syntaxlabel="Text"label:"Text"
Wrong edge label syntax[label:"Text"][label="Text"]
Emojis in labelslabel:"Start 🚀"label:"Start"
Unknown attributespriority:"high"(remove - not supported)
Non-sequential IDsn1, n3, n5n1, n2, n3
Undefined lane refsundefined.n5Use actual lane name
Second request before responseA -> B, then A -> C, then B -> AA -> B, then B -> A, then next request

API Endpoints (Direct Access)

For agents that prefer direct HTTP calls instead of MCP:

POST /api/validate

URL: https://flowzap.xyz/api/validate

Rate Limit: 30 requests/minute per IP

Request:

{
  "code": "process { # P n1: circle label:\"Start\" }"
}

Response:

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "stats": {
    "lanes": 1,
    "nodes": 1,
    "edges": 0,
    "loops": 0
  }
}

POST /api/playground/create

URL: https://flowzap.xyz/api/playground/create

Rate Limit: 5 requests/minute, 50/day per IP

Request:

Response:

{
  "url": "https://flowzap.xyz/playground?session=abc123"
}

Installation

The FlowZap MCP Server works with any tool that supports the Model Context Protocol (MCP). Here is the complete list of compatible tools:

All Compatible Coding Tools

ToolHow to Configure
Claude DesktopAdd to claude_desktop_config.json:macOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonWindows: %APPDATA%\Claude\claude_desktop_config.json
Claude CodeRun: claude mcp add --transport stdio flowzap -- npx [email protected] add to .mcp.json in your project root.
CursorOpen Settings → Features → MCP Servers → Add Server. Use the same JSON config.
Windsurf IDEAdd to ~/.codeium/windsurf/mcp_config.json
OpenAI CodexAdd to ~/.codex/config.toml:[mcp_servers.flowzap]command = "npx"args = ["[email protected]"]Or run: codex mcp add flowzap -- npx [email protected]
Warp TerminalSettings → MCP Servers → Click "+ Add" → Paste the JSON config.
Zed EditorAdd to settings.json:{"context_servers": {"flowzap": {"command": "npx", "args": ["[email protected]"]}}}
Cline (VS Code)Open Cline sidebar → MCP Servers icon → Edit cline_mcp_settings.json
Roo Code (VS Code)Add to .roo/mcp.json in project or global settings.
Continue.devCreate .continue/mcpServers/flowzap.yaml with:name: FlowZapmcpServers: - name: flowzap command: npx args: ["[email protected]"]
Sourcegraph CodyAdd to VS Code settings.json via openctx.providers configuration.

Windows Users: If tools don't appear, use the absolute path: "command": "C:\\Program Files\\nodejs\\npx.cmd". Find your npx path with: where.exe npx

JSON Configuration

All tools use the same JSON configuration format:

{
  "mcpServers": {
    "flowzap": {
      "command": "npx",
      "args": ["[email protected]"]
    }
  }
}

Support & Resources

Install as Agent Skill (40+ agents)

npx skills add flowzap-xyz/flowzap-mcp

Compatible with: Claude Code, Cursor, Windsurf, Codex, Gemini CLI, GitHub Copilot, Cline, Roo Code, Augment, OpenCode, and more.

Version History

VersionDateChanges
1.3.6Apr 2026Stricter validation (numbering gaps, ping-pong sequence enforcement, same-line lane labels), playground endpoint alignment, updated docs
1.3.5Feb 2026Security fixes: MCP SDK ReDoS, hono JWT/XSS, ajv ReDoS, qs DoS vulnerabilities
1.3.3Feb 2026All 7 tools wired, Architecture view mode
1.3.0Feb 2026Added Architecture view mode, triple-view rendering
1.2.0Jan 2026Added new validation rules, comprehensive test coverage
1.1.0Dec 2025Security hardening, rate limiting
1.0.0Nov 2025Initial release

This documentation is optimized for LLM consumption. For human-readable guides, visit flowzap.xyz/flowzap-code

相關伺服器

NotebookLM 網頁匯入器

一鍵將網頁和 YouTube 影片匯入 NotebookLM。超過 200,000 位使用者信賴。

安裝 Chrome 擴充功能