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.

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.

Input Schema:

{
  "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)

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.

Input Schema:

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

Output:

✅ Workflow diagram created:
https://flowzap.xyz/playground/3f6c1d9e-5b2a-4c77-9f1d-2a8b6c0d4e11?view=workflow

💡 Review this flow for GDPR, SOC2 or PIPL compliance by calling
flowzap_compliance_check with the same code. 10 free reviews per rolling 30-day period.

⚠️ Process quality (advisory — the diagram renders; these are process defects):
1. These steps have no incoming edge: they start the flow as if nothing led to them: n5. …
Fix the steps above and call the tool again with the corrected code.

View Modes:

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
• Appends an advisory process-quality block when the code has flow defects (see Process quality audit below). The diagram is always created
• view="mindmap" is accepted, but prefer flowzap_mindmap_create_playground, which validates mind-map readiness first

Purpose: Run automated SOC2, GDPR, PIPL, and EU AI Act compliance analysis on a FlowZap Code data-flow diagram.

When to Use: When the user asks for a privacy, security, or regulatory review of a data-flow diagram. Backed by Deepseek LLM.

Input Schema:

{
  "type": "object",
  "properties": {
    "code": { "type": "string", "maxLength": 50000 },
    "lng": { "type": "string", "enum": ["en", "fr", "zh"], "default": "en" }
  },
  "required": ["code"]
}

Output: Markdown audit report covering SOC2 CC-series controls, GDPR articles, PIPL chapters, and EU AI Act obligations (AI risk classification, human oversight, and technical documentation) with risks, recommendations, and a link to the manual checker at flowzap.xyz/soc2-gdpr-pipl-compliance-checker.

Rate Limits (strict, Deepseek LLM cost protection):

• 10 free compliance reviews per rolling 30-day period per IP or per mcpIdentity
• 3 calls per hour burst limit per IP
• Global 5-minute circuit breaker on repeated upstream failures
• Only successful calls count toward the monthly quota

Purpose: Deterministic repair pass for FlowZap Code rejected by the validator: non-sequential node numbering, inferred edge handles, node/edge label syntax, missing lane display labels, emoji and non-printable characters.

When to Use: When flowzap_validate (or POST /api/validate) rejects code with one of these mechanical errors. The tool returns the corrected code plus the list of applied corrections; errors it cannot repair are reported as-is and content is never invented.

Input Schema:

{
  "type": "object",
  "properties": {
    "code": { "type": "string", "maxLength": 50000 },
    "lng": { "type": "string", "enum": ["en", "fr", "zh"], "default": "en" }
  },
  "required": ["code"]
}

Output: The repaired FlowZap Code, the applied corrections with counts, and any remaining unfixable errors with their validator messages. Backed by the public POST /api/fix endpoint (120 requests/minute per IP (1200/minute for clients sending X-MCP-Client: flowzap-mcp), no auth).

Purpose: Parse FlowZap Code into a structured JSON graph (lanes, nodes, edges).

When to Use: When another tool or pipeline needs the diagram as data rather than as an image: storing a graph, computing metrics, feeding a downstream generator.

Input Schema:

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

Output: A JSON object with lanes, nodes (id, shape, label, lane) and edges (source, target, label). Deterministic, local parsing only.

Purpose: Compare two versions of FlowZap Code and return a structured diff.

When to Use: When iterating on a diagram and the user asks what changed, or before applying a patch so the change can be reviewed.

Input Schema:

{
  "type": "object",
  "properties": {
    "oldCode": {
      "type": "string",
      "description": "Original FlowZap Code"
    },
    "newCode": {
      "type": "string",
      "description": "Updated FlowZap Code"
    }
  },
  "required": [
    "oldCode",
    "newCode"
  ]
}

Output: A structured list of added, removed and modified nodes and edges between oldCode and newCode.

Purpose: Apply structured patch operations (insert, update, remove nodes or edges) to FlowZap Code and return a playground URL for the patched diagram.

When to Use: When you want to fix or extend an existing diagram without regenerating it: one bad label, one missing step, one missing edge.

Input Schema:

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Current FlowZap Code"
    },
    "operations": {
      "type": "array",
      "description": "Array of patch operations",
      "items": {
        "type": "object"
      }
    }
  },
  "required": [
    "code",
    "operations"
  ]
}

Output: The operations actually applied (or the skipped ones and why), the URL of the patched diagram, followed by the advisory process-quality block. A removeNode leaves a gap in the numbering: the code is renumbered automatically before the playground is created. If the patch is still invalid, no URL is returned and the errors are listed.

Operations: camelCase, five allowed names. insertNode takes a laneId, a newNode (shape + label + properties) and an optional afterNodeId; updateNode takes a nodeId and updates; insertEdge and removeEdge take a newEdge built from node IDs (from, to) and optional handles. An edge to another lane automatically receives the lane prefix.

{ "op": "insertNode", "laneId": "sales", "afterNodeId": "n2", "newNode": { "shape": "rectangle", "label": "Review order", "properties": { "owner": "Alice" } } }
{ "op": "updateNode", "nodeId": "n3", "updates": { "label": "Review order" } }
{ "op": "removeNode", "nodeId": "n4" }
{ "op": "insertEdge", "newEdge": { "from": "n2", "to": "n3", "label": "Submit", "fromHandle": "right", "toHandle": "left" } }
{ "op": "removeEdge", "newEdge": { "from": "n2", "to": "n3" } }

Advisory quality block: the reply also carries the process-quality audit of the patched diagram (same block as flowzap_create_playground). The diagram is created even when defects are reported.

Purpose: Turn a real artifact (HTTP logs, an OpenAPI spec, a code snippet) into a FlowZap diagram.

When to Use: When the source of truth is not prose but machine output: a request log, an API contract, a route list.

Input Schema:

{
  "type": "object",
  "properties": {
    "artifactType": {
      "type": "string",
      "enum": [
        "http_logs",
        "openapi",
        "code"
      ]
    },
    "content": {
      "type": "string",
      "description": "Raw artifact content"
    },
    "view": {
      "type": "string",
      "enum": [
        "workflow",
        "sequence",
        "architecture"
      ],
      "description": "Preferred view mode"
    }
  },
  "required": [
    "artifactType",
    "content"
  ]
}

Output: Over the hosted HTTP transport the tool returns a parsing playbook for the requested artifact type: the agent then writes the FlowZap Code itself. The npm build parses the artifact directly and returns FlowZap Code plus a playground URL, with the advisory quality block.

Purpose: Validate FlowZap Code syntax for Mind Map diagrams and report whether the code is mind-map-ready.

When to Use: Before flowzap_mindmap_approve and flowzap_mindmap_create_playground, to catch what the renderer will refuse.

Input Schema:

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

Output: Validation errors and warnings, plus mind-map readiness checks: no diamonds, no taskboxes, at least one circle for the root, at least one rectangle for branches.

Mind maps are not processes. The process-quality audit is not applied to ?view=mindmap renderings: a mind map has no start or end circle and no flow between lanes, so those rules would fire on every call. Use the four mindmap tools below instead.

Purpose: Decide whether valid FlowZap Code is suitable for Mind Map rendering.

When to Use: When you already have valid code and want a structured go/no-go before showing a mind map to a user.

Input Schema:

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "FlowZap Code to inspect for mind map readiness"
    }
  },
  "required": [
    "code"
  ]
}

Output: A structured verdict: blocking errors (diamonds, taskboxes), advisory warnings (several circles: only the first becomes the root; large or deep diagrams) and info (edge directions, ignored by the renderer). Local parsing only, no API call.

Purpose: Generate a ready-to-extend FlowZap Code skeleton for a Mind Map.

When to Use: When bootstrapping a mind map from a topic instead of writing the tree by hand.

Input Schema:

{
  "type": "object",
  "properties": {
    "topic": {
      "type": "string",
      "description": "Central topic label for the mind map root (default: 'Central Topic')"
    },
    "branches": {
      "type": "number",
      "description": "Number of main branches from the root (default: 3, max: 8)"
    },
    "depth": {
      "type": "number",
      "description": "Depth of sub-branches per main branch (default: 2, max: 4)"
    }
  }
}

Output: FlowZap Code with a central circle root, the requested number of rectangle branches and sub-branches, ready to edit. branches defaults to 3 (max 8), depth to 2 (max 4).

Purpose: Create a shareable playground URL that opens directly in Mind Map view.

When to Use: After flowzap_mindmap_validate and flowzap_mindmap_approve both pass.

Input Schema:

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "FlowZap Code to load in a mind map playground"
    }
  },
  "required": [
    "code"
  ]
}

Output: The same reply as flowzap_create_playground with ?view=mindmap appended to the URL.

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

Rate Limit: 120 requests/minute per IP (1200/minute for clients sending X-MCP-Client: flowzap-mcp)

Request:

{
  "code": "sales { # Sales Team n1: circle label:\"Order received\" n2: rectangle label:\"Validate order\" n1.handle(right) -> n2.handle(left) }"
}

Response (invalid code):

{
  "success": true,
  "valid": false,
  "errors": [
    { "line": 2, "code": "INVALID_EDGE_SYNTAX", "severity": "error",
      "message": "Invalid edge syntax. Expected: source.handle(direction) -> target.handle(direction)" }
  ],
  "warnings": [
    { "line": 1, "code": "MISSING_LANE_LABEL", "severity": "warning",
      "message": "Lane \"sales\" is missing a display label. Add \"# Display Name\" after the opening brace." }
  ]
}

Response (valid code):

{
  "success": true,
  "valid": true,
  "errors": [],
  "warnings": [],
  "stats": { "lanes": 2, "nodes": 5, "edges": 4, "loops": 0 },
  "attribution": "Powered by FlowZap.xyz"
}

Every error and warning carries a stable code, a severity and the line to look at (line 0 = document-level rule).

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

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

Request:

{
  "code": "sales { # Sales Team n1: circle label:\"Order received\" n2: rectangle label:\"Validate order\" n1.handle(right) -> n2.handle(left) }",
  "view": "workflow"
}

Response:

{
  "success": true,
  "url": "https://flowzap.xyz/playground/3f6c1d9e-5b2a-4c77-9f1d-2a8b6c0d4e11?view=workflow",
  "tokenExpiresAt": "2026-11-01T17:48:11.656Z",
  "quality": {
    "defects": [
      { "code": "orphan-node", "nodes": ["n5"],
        "message": "These steps have no incoming edge: they start the flow as if nothing led to them: n5. …" }
    ],
    "warning": "\n\n⚠️ Process quality (advisory) …"
  }
}

quality is always returned for workflow, sequence and architecture views — with defects: [] and an empty warning when the shape is clean — and is absent for view: "mindmap", which is not audited as a process. The response is advisory: the session exists and the URL is valid whatever the audit says. Sessions expire after 60 minutes.