# FlowZap MCP - 面向 AI 代理的完整文档

**版本：** 1.4.3  
**最近更新：** 2026 年 5 月  
**目标读者：** 大语言模型、AI 代理与 Agent 系统  
**官方文档：** https://flowzap.xyz/zh/flowzap-code

---

## 概览

FlowZap MCP（Model Context Protocol）让 AI 代理能够通过 **FlowZap Code** 创建、校验并分享工作流图、时序图和架构图。FlowZap Code 是一套面向机器生成的严格 DSL。

### FlowZap 是什么

FlowZap 是一个把文本代码转换为可视化图表的平台。
与 Mermaid 或 PlantUML 不同，FlowZap Code 专门为以下场景设计：

- **AI-first 生成** — 语法针对 LLM 输出进行了优化
- **Agent 工作流** — 适用于 n8n、Make.com、Zapier 与自动化场景
- **三视图渲染** — 同一份代码可渲染为 workflow、sequence 和 architecture
- **即时分享** — 无需认证即可创建可分享链接

---

## 安全保障

FlowZap MCP 服务器默认具备多层安全保护。

### 网络安全

| 保护项 | 实现方式 |
|--------|----------|
| **SSRF 防护** | 仅允许通过 HTTPS 连接 `flowzap.xyz` 和 `www.flowzap.xyz` |
| **URL 校验** | 所有返回 URL 都会验证其属于 FlowZap 域名 |
| **请求超时** | 30 秒，避免长时间挂起 |

### 输入校验

| 限制 | 数值 | 目的 |
|------|------|------|
| **最大代码长度** | 50,000 字符 | 防止内存耗尽 |
| **最大输入长度** | 100,000 字符 | 降低超大 payload 风险 |
| **Null 字节移除** | 自动 | 降低注入风险 |
| **控制字符清理** | 自动 | 移除不可打印字符 |

### 限流

| 参数 | 值 |
|------|----|
| **最大请求数** | 每分钟 30 次 |
| **时间窗口** | 60 秒 |
| **超限行为** | 返回重试等待信息 |

### 隐私

- **公共端点无需认证**
- **不持久化用户数据**
- **无额外追踪**
- **公共 MCP 场景不依赖 Cookie**

---

## 可用工具

### 1. `flowzap_get_syntax`

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

**何时使用：** 在生成任何 FlowZap Code 之前，先学习 DSL 规则。

**输入：**

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

**输出：** 完整语法指南，包括全局约束、形状、节点语法、边语法、循环和常见错误。

---

### 2. `flowzap_validate`

**用途：** 在创建图表前校验 FlowZap Code 语法。

**何时使用：** 调用 `flowzap_create_playground` 前始终应先校验。

**输入：**

```json
{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "待校验的 FlowZap Code"
    }
  },
  "required": ["code"]
}
```

**返回内容：**

- 代码是否有效
- 逐行错误详情
- 最佳实践 warning
- 统计信息（`lanes`、`nodes`、`edges`、`loops`）

---

### 3. `flowzap_create_playground`

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

**何时使用：** 校验通过后，为用户生成可打开、可编辑的交互式链接。

**输入：**

```json
{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "要加载到 playground 的 FlowZap Code"
    },
    "view": {
      "type": "string",
      "enum": ["workflow", "sequence", "architecture"]
    }
  },
  "required": ["code"]
}
```

**说明：**

- 创建前会自动校验代码
- 若代码非法，会返回校验错误
- 返回的 URL 可分享
- 多系统图建议使用 `architecture` 视图

---

### 4. `flowzap_export_graph`

**用途：** 将 FlowZap Code 导出为结构化 JSON 图。

**适用场景：** 代理需要以结构化方式理解 lanes、节点和边。

### 5. `flowzap_artifact_to_diagram`

**用途：** 将 HTTP 日志、OpenAPI 规范或代码转换为 FlowZap 图表。

**适用场景：** 将原始技术制品转换为可视化图。

### 6. `flowzap_diff`

**用途：** 比较两份 FlowZap Code。

**适用场景：** 解释差异或输出结构化变更。

### 7. `flowzap_apply_change`

**用途：** 对现有图表应用结构化补丁操作。

**适用场景：** 增量编辑，而不是整体重生成。

---

### 8. `flowzap_compliance_check`

**用途：** 对 FlowZap Code 数据流图执行自动化的 SOC2、GDPR 和 PIPL 合规分析。

**适用场景：** 当用户请求对数据流图进行隐私、安全或合规性审查时。由 Deepseek LLM 提供支持。

**速率限制（严格 — 保护 LLM 成本）：**
- **每个 IP 或 mcpIdentity 每天 3 次成功调用**
- **每个 IP 每小时 1 次**突发限制
- 上游连续失败时触发**全局 5 分钟熔断器**
- 仅成功的调用计入每日配额

**输出：** Markdown 审计报告 + 可分享的临时结果 URL（60 分钟 TTL）。

---

## 校验参考

### 阻断性错误

- `CONTAINS_EMOJI`
- `NESTED_LANE`
- `UNMATCHED_BRACE`
- `UNCLOSED_BRACE`
- `DUPLICATE_NODE_ID`
- `INVALID_SHAPE`
- `MISSING_LABEL`
- `NODE_OUTSIDE_LANE`
- `MISSING_HANDLES`
- `INVALID_EDGE_SYNTAX`
- `INVALID_DIRECTION`
- `EDGE_OUTSIDE_LANE`
- `UNDEFINED_LANE_REF`
- `INVALID_LOOP_SYNTAX`
- `LOOP_OUTSIDE_LANE`
- `MISPLACED_COMMENT`
- `COMMENT_OUTSIDE_LANE`
- `UNDEFINED_NODE`
- `NON_SEQUENTIAL_NUMBERING`
- `WRONG_LABEL_SYNTAX`
- `WRONG_EDGE_LABEL_SYNTAX`
- `ORPHAN_NODE`
- `MISSING_RETURN_EDGE`
- `MULTIPLE_OUTBOUND_REQUESTS`
- `CHRONOLOGICAL_PAIRING_VIOLATION`
- `EMPTY_DIAGRAM`
- `WRONG_DSL_FORMAT`

### Warning

- `NON_PRINTABLE_CHARS`
- `DUPLICATE_LANE`
- `MISSING_LANE_LABEL`
- `NON_STANDARD_NODE_ID`
- `TASKBOX_MISSING_PROPS`
- `LOOP_TOO_FEW_NODES`
- `UNKNOWN_ATTRIBUTE`
- `LABEL_TOO_LONG`

---

## FlowZap Code 核心规则

- 仅允许 UTF-8 纯文本
- 节点 ID 使用全局连续编号 `n1`、`n2`、`n3`
- 只允许 4 种形状：`circle`、`rectangle`、`diamond`、`taskbox`
- 只允许 4 个属性：`label`、`owner`、`description`、`system`
- 节点属性使用 `:`
- 边标签使用 `[]` 内的 `=`
- handle 方向只能是 `left`、`right`、`top`、`bottom`
- 跨 lane 引用格式是 `laneName.nX.handle(direction)`
- lane 注释必须与左大括号在同一行：`laneName { # Label`
- 在序列视图中必须严格保持 请求 → 响应 → 下一次请求 的顺序

### 简单示例

```plaintext
process { # 流程
  n1: circle label:"开始"
  n2: rectangle label:"步骤"
  n3: circle label:"结束"
  n1.handle(right) -> n2.handle(left)
  n2.handle(right) -> n3.handle(left)
}
```

### 多 lane 示例

```plaintext
sales { # 销售团队
  n1: circle label:"收到订单"
  n2: rectangle label:"提交订单"
  n5: rectangle label:"接收决定"
  n1.handle(right) -> n2.handle(left)
  n2.handle(bottom) -> fulfillment.n3.handle(top) [label="提交"]
}

fulfillment { # 履约
  n3: rectangle label:"审核订单"
  n4: rectangle label:"返回决定"
  n3.handle(right) -> n4.handle(left)
  n4.handle(top) -> sales.n5.handle(bottom) [label="已批准"]
}
```

---

## 代理推荐工作流

1. 调用 `flowzap_get_syntax`
2. 生成 FlowZap Code
3. 调用 `flowzap_validate`
4. 如有错误则修复
5. 调用 `flowzap_create_playground`
6. 将 URL 返回给用户

---

## 有用的公共端点

| Endpoint | 方法 | 限制 | 用途 |
|----------|------|------|------|
| `/api/validate` | POST | 30次/分钟 | 校验 FlowZap Code 语法 |
| `/api/playground/create` | POST | 5次/分钟，50次/天 | 创建 playground URL（15 分钟 TTL） |
| `/api/compliance-check` | POST | 5次/分钟，30次/天 | SOC2/GDPR/PIPL 合规分析。返回框架结果 + 可分享的结果 URL（60 分钟 TTL）。基于 Deepseek LLM。 |

**OpenAPI：** https://flowzap.xyz/.well-known/openapi.json

---

## 相关链接

- 人类可读文档：https://flowzap.xyz/zh/docs/mcp
- JSON 文档：https://flowzap.xyz/zh/docs/mcp.json
- 原始 Markdown：https://flowzap.xyz/zh/docs/mcp.md
- capabilities 清单：https://flowzap.xyz/zh/.well-known/capabilities.json
- npm 包：https://www.npmjs.com/package/flowzap-mcp
- FlowZap skill：https://skills.sh/flowzap-xyz/flowzap-mcp/flowzap-diagrams

---

## 人工支持

遇到以下情况时应升级到人工支持：

- 多次修复后仍无法通过校验
- playground URL 返回 404 或 500
- 限流阻断了合法使用
- 所需图表超出 DSL 支持范围

**支持页面：** https://flowzap.xyz/zh/feedback  
**邮箱：** hello@flowzap.xyz