🤖 本文档针对 LLM 和 AI 代理的使用进行了优化

版本 1.3.6 | 最后更新：2026 年 4 月 | 更严格的验证、乒乓时序强制、Playground端点对齐

概述

FlowZap MCP（模型上下文协议）服务器使 AI 代理能够使用 FlowZap Code 创建、验证并分享专业的工作流、时序和架构图——这是一种专为机器可读图表生成而设计的领域特定语言。

FlowZap 是什么？

用途	将基于文本的代码转换为可视化工作流图表
优化方向	AI 优先生成、代理工作流（n8n、Make.com、Zapier）
独特功能	三视图渲染——同一代码可渲染为工作流、时序和架构图
分享	无需身份验证即可即时分享 URL

安全保障

FlowZap MCP 服务器实施企业级安全措施：

网络安全

防护	实现方式
SSRF 防护	仅通过 HTTPS 连接 flowzap.xyz
URL 验证	所有返回的 URL 均验证为来自 FlowZap 域名
请求超时	30 秒超时防止连接挂起

输入验证

限制	值	目的
最大代码长度	50,000 字符	防止内存耗尽
最大输入长度	100,000 字符	防止载荷攻击
空字节删除	自动	防止注入攻击
控制字符净化	自动	删除不可打印字符

速率限制

参数	值
最大请求数	每分钟 30 次
窗口时长	60 秒
超限行为	返回 retry-after 时间

数据隐私

无需身份验证——仅公开端点
不存储用户数据——Playground 会话是临时的（60 分钟 TTL，不可猜测的加密令牌）
无追踪——无 cookie 或持久标识符
仅记录到 stderr——安全事件永远不会暴露给 MCP 客户端

可用工具

1. flowzap_get_syntax

用途：获取完整的 FlowZap Code 语法文档。

何时使用：在生成任何 FlowZap Code 之前，调用此工具学习正确的语法。

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

2. flowzap_validate

用途：在创建图表之前验证 FlowZap Code 语法。

何时使用：始终在调用 flowzap_create_playground 之前进行验证。

✅ FlowZap Code 有效！

统计：
- Lanes：2
- 节点：5
- 边：4

❌ 验证失败：
- 第 3 行：未知形状 "oval"。有效形状：circle, rectangle, diamond, taskbox
- 第 5 行：边缺少 handle 语法。使用：n1.handle(right) -> n2.handle(left)

3. flowzap_create_playground

用途：创建包含图表的可分享 Playground URL。

视图模式：

视图	最适合
workflow	分步流程（默认）
sequence	参与者之间的消息交换
architecture	将 lanes 显示为系统的系统级概览

验证规则参考

错误代码（阻止图表创建）

代码	描述	修复方法
CONTAINS_EMOJI	检测到 emoji 字符	仅使用 UTF-8 纯文本
DUPLICATE_NODE_ID	相同节点 ID 使用了两次	使用唯一 ID：n1, n2, n3...
INVALID_SHAPE	未知形状类型	circle, rectangle, diamond, taskbox
MISSING_LABEL	节点无标签（taskbox 除外）	添加 label:"文本"
MISSING_HANDLES	边缺少 handle 语法	n1.handle(right) -> n2.handle(left)
INVALID_DIRECTION	未知 handle 方向	left, right, top, bottom
NON_SEQUENTIAL_NUMBERING	编号不是从 n1 开始或存在间隔	在整个图中使用连续的 n1, n2, n3...
WRONG_LABEL_SYNTAX	节点标签使用了 = 而不是 :	使用 label:"文本"
WRONG_EDGE_LABEL_SYNTAX	边标签使用了 : 而不是 =	使用 [label="文本"]
MISPLACED_COMMENT	注释放在错误位置	把唯一允许的注释放在左大括号同一行
MISSING_RETURN_EDGE	跨泳道请求缺少返回边	从目标泳道加一条返回到源泳道的响应边
UNDEFINED_NODE	边引用了未定义的节点	在引用前定义节点
EMPTY_DIAGRAM	未定义任何节点	至少添加一个节点
WRONG_DSL_FORMAT	检测到 Mermaid/PlantUML	仅使用 FlowZap 语法

语法快速参考

laneName { # 显示名称
  n1: circle label:"开始"
  n2: rectangle label:"处理"
  n1.handle(right) -> n2.handle(left)
}

AI 代理推荐工作流

第 1 步：学习语法 — 调用 flowzap_get_syntax
第 2 步：生成代码 — 根据用户请求生成 FlowZap Code
第 3 步：验证 — 调用 flowzap_validate
第 4 步：修复错误 — 解析错误消息并修正代码
第 5 步：创建 Playground — 调用 flowzap_create_playground
第 6 步：展示给用户 — 分享 Playground URL

安装

FlowZap MCP 服务器适用于所有支持模型上下文协议（MCP）的工具。

JSON 配置（所有工具通用）

{
  "mcpServers": {
    "flowzap": {
      "command": "npx",
      "args": ["flowzap-mcp@1.3.6"]
    }
  }
}

工具	配置方法
Claude Desktop	添加到 `claude_desktop_config.json`
Claude Code	`claude mcp add --transport stdio flowzap -- npx flowzap-mcp@1.3.6`
Cursor	设置 → 功能 → MCP 服务器 → 添加服务器
Windsurf IDE	添加到 `~/.codeium/windsurf/mcp_config.json`
Zed Editor	通过 `context_servers` 添加到 `settings.json`
Cline / Roo Code	编辑 `cline_mcp_settings.json` 或 `.roo/mcp.json`

Windows 用户：如果工具未显示，请使用绝对路径："command": "C:\\Program Files\\nodejs\\npx.cmd"。使用 where.exe npx 查找路径。

支持与资源

• 语法文档： flowzap.xyz/zh/flowzap-code
• 交互式 Playground： flowzap.xyz/zh/playground
• 模板库： flowzap.xyz/zh/templates
• Agent API： flowzap.xyz/zh/docs/agent-api
• npm 包： npmjs.com/package/flowzap-mcp

作为 Agent Skill 安装（支持 40+ 代理）

npx skills add flowzap-xyz/flowzap-mcp

版本历史

版本	日期	变更内容
1.3.6	2026 年 4 月	更严格的验证（编号间隔、乒乓时序强制、同行车道标签）、Playground端点对齐、文档更新
1.3.5	2026 年 2 月	安全修复：MCP SDK ReDoS、hono JWT/XSS、ajv ReDoS、qs DoS
1.3.3	2026 年 2 月	全部 7 个工具就绪，架构视图模式
1.3.0	2026 年 2 月	新增架构视图模式，三视图渲染
1.2.0	2026 年 1 月	新增验证规则，全面测试覆盖
1.1.0	2025 年 12 月	安全加固，速率限制
1.0.0	2025 年 11 月	初始版本

本文档针对 LLM 使用进行了优化。如需人类可读指南，请访问 flowzap.xyz/zh/flowzap-code

FlowZap MCP 服务器文档

概述