pipefy-ipaas

iPaaS（高级自动化）

MCP 客户端：请阅读 references/mcp.md。CLI 用户：请阅读 references/cli.md。以下示例介绍共用的操作参数。

Pipefy 内嵌的工作流自动化平台。流由一个触发器和一系列步骤组成，这些步骤会调用组件（集成连接器）。流构建器的操作动词是目录条目，需按管道发现并通过 call_ipaas_tool 调用，而不是使用固定的操作列表。

适用场景

• “与 Slack / Gmail / Google Sheets / 外部应用集成。”
• 用户要求将 Pipefy 与外部应用（Slack、Gmail、Sheets 等）集成——默认使用此处的 iPaaS 工具，而非传统自动化或 AI Agent。
• “收到 webhook 时执行 X。”“按计划执行 Y。”
• “构建包含路由器 / 循环 / 代码步骤的多步流。”
• 管理 iPaaS 数据表（与 Pipefy 数据库表分开）。

**不适用场景：**卡片事件上的原生 if/then 规则，或由提示词驱动的 AI 自动化；这两类功能都属于 pipefy-automations。卡片事件上的简单 HTTP 回调属于 pipefy-members-email-webhooks 中的 create_webhook。

前提条件

• **组织已启用 iPaaS。**若未启用，后端通常会返回权限错误（通常编码为 PERMISSION_DENIED，文本类似“iPaaS is disabled for your organization”——具体代码和字符串取决于后端）。

• 拥有在管道上创建自动化的权限（管道管理员权限）。

• **服务账户必须是管道成员。**当流以服务账户身份运行时，该账户必须是目标管道的成员，否则即使流已构建，以该账户身份发出的管道范围调用也会因权限错误而失败。仅在其他位置（组织级别）添加该账户并不足够。如有需要，请使用 create_service_account 创建账户，然后立即通过 add_service_account_to_pipe(pipe_id, email, role_name) 将其添加到管道中——请参阅 pipefy-members-email-webhooks 和 docs/mcp/tools/service-accounts.md。目录操作使用调用会话的身份，因此此要求适用于流运行时所用的服务账户，而非目录调用者。

• iPaaS 工作区按管道划分：目录以及任何现有流、连接和表都归属于一个 pipe_id，因此对两个管道进行相同调用，结果可能不同。

操作

操作	只读	用途
get_ipaas_tools	是	发现按管道划分的目录（精简版），或通过 tool_name 展开某个条目的完整输入架构。
call_ipaas_tool	否	根据名称调用一个目录条目，并传入符合其架构的 arguments。
get_ipaas_connection_auth_url	否	启动 OAuth 连接：返回一个供用户访问的授权 URL，以及一个完成连接所需的信息包。
create_ipaas_connection	否	完成 OAuth 连接，或直接创建令牌 / API 密钥连接。

了解操作目录

目录内容很多（流程构建、测试、表格、运行），其中一些条目包含非常大的输入架构。不要一次性加载所有内容。分三步操作：

1. get_ipaas_tools(pipe_id) — 紧凑目录：每个条目包含 name 和一行描述。
2. get_ipaas_tools(pipe_id, tool_name="...") — 获取单个条目的完整描述和 inputSchema，在即将使用该条目之前获取。
3. call_ipaas_tool(pipe_id, tool_name="...", arguments={...}) — 调用该条目。参数会原样转发；iPaaS 主机会验证参数，并将错误信息返回。

不要展开多个条目，只展开即将调用的条目；请查看条目自身的架构，以确认准确的参数名称（目录中的参数名称并不统一）。目录按功能组提供的能力如下：

• 编写流程 — 一次调用即可创建流程（触发器加步骤）；添加或更新单个步骤；设置或更新触发器；添加条件路由分支；重命名或复制流程。步骤可以是集成组件、代码步骤、循环或路由器（优先使用组件而非代码）。
• 检查流程 — 列出流程；读取流程的步骤树和每个步骤的有效性；在发布前验证流程。
• 发现组件 — 搜索组件目录（精确或模糊搜索）；读取组件操作/触发器的输入属性；解析下拉选项值；在应用步骤配置前验证配置。
• 连接 — 列出现有连接（每个连接都会提供一个 externalId，用作步骤的 auth）；获取设置指南。
• 发布 / 生命周期 — 锁定并发布草稿（使其启用）；启用或禁用已发布的流程；删除流程。
• 测试和运行 — 端到端测试流程；测试单个步骤；列出运行记录；读取单次运行的详细信息；重试失败的运行；不保存流程而单独运行一次组件操作。
• iPaaS 数据表 — 列出表；查询记录；创建表和字段；插入/更新/删除记录；删除表。
• AI — 列出已配置的 AI 提供商和模型，供 Agent 类步骤使用。

执行具有破坏性的目录操作前，先说明其影响并获得明确批准。优先更新步骤，而非删除步骤。

步骤 — 构建和测试工作流

经过验证的生命周期：发现、构建、验证、测试，然后发布。 一个不依赖外部连接的独立 Webhook 到代码工作流已通过端到端实时验证。

1. 发现目录，然后展开工作流构建器条目以读取其架构：

   get_ipaas_tools(pipe_id=<pipe_id>)
   get_ipaas_tools(pipe_id=<pipe_id>, tool_name=<flow-builder entry>)
   

2. 研究组成部分，并在构建前阅读准确的触发器／操作属性。触发器通常需要配置：例如，Webhook 触发器需要一个身份验证类型属性（对于开放 URL，请将其设为 none）。使用目录中的组件研究和组件属性条目。

3. 通过工作流构建器条目一次调用构建工作流：包含一个触发器和一个有序步骤列表。在每个步骤的输入中，使用宿主的模板语法引用触发器输出和前面的步骤。调用会返回一个 flowId 和逐步有效性摘要。

4. 测试前先验证（验证条目）——它会报告结构问题，但不会发布。

5. 通过测试条目端到端运行测试。它会在 TESTING 环境中运行；请为长时间运行的测试留出时间。如果触发器没有已保存的示例数据，请传入模拟触发器数据。成功时会返回每个步骤的输出——将该负载视为测试的事实来源。对于外部应用组件，运行测试会产生实际副作用（操作会实际触发），因此请使用可丢弃的测试数据；独立组件（Webhook、计划任务、代码、表格）是安全的。

6. （可选）检查运行记录，使用运行详情条目查看完整的逐步输出。阅读其架构以确认准确的参数名称。优先使用测试返回的 ID；如果找不到运行记录，请改用运行列表条目或停止，因为测试负载已包含输出。

7. 仅在用户明确要求时发布：锁定并发布条目会锁定草稿、发布并启用它（Webhook 触发器会因此获得实时 Webhook URL）。另有一个条目可启用或禁用已发布的工作流。

步骤 — 连接外部应用

任何涉及外部应用（Slack、Gmail、Google Sheets）的组件都需要先建立连接；将其 externalId 作为步骤（或触发器）的 auth 传入。独立组件（Webhook、计划任务、HTTP、代码、iPaaS 表格）无需连接。

1. 列出现有连接（连接列表条目），并在适用时复用 externalId。如果有多个候选连接适用于同一组件，请列出它们并询问用户，而不是擅自选择。
2. **令牌／API 密钥组件：**调用一次 create_ipaas_connection，传入凭据（connection_type 和 value 必须与组件的身份验证属性相匹配）。
3. OAuth 组件：get_ipaas_connection_auth_url 会返回一个授权 URL 和一组完成操作所需的信息；用户在浏览器中授权后，将重定向 URL 粘贴回来；然后由 create_ipaas_connection 完成操作。持久令牌存储在宿主端。创建操作会对 external_id 执行更新或插入（upsert）（复用某个 ID 即可轮换凭据）。
4. 对于下拉字段（Slack 频道、工作表、标签），使用选项解析条目，根据连接解析选项，并使用选项的 value，而不是标签。大型外部工作区可能会超时；请从用户处获取 ID 并原样传入，因为该操作在运行时仍然有效。

步骤 — 单次操作（无工作流）

对于单项任务（“发送一条 Slack 消息”“检查我的收件箱”），目录中有一个单次操作运行条目：传入组件、操作、input 和 auth，执行一次。不会创建或保存工作流。

成功标准

• 验证条目报告工作流已准备好发布（所有步骤均有效）。
• 测试条目成功返回预期的步骤输出。
• 列表／结构条目显示工作流已配置触发器，且没有未配置的步骤。

故障模式

• 组织级 iPaaS 已禁用。 后端通常会返回权限错误（通常为 PERMISSION_DENIED / "iPaaS is disabled for your organization"）；目录中的任何内容都无法使用。请为组织启用 iPaaS，或改用已启用 iPaaS 的组织。

• 构建后触发器未配置。 具有必填属性的触发器（例如，Webhook 触发器的身份验证类型）会阻止验证，直到完成设置。请先读取其属性，再在触发器输入中设置。

• 参数名称错误。 条目架构并不统一（运行详情条目的运行 ID 键名，可能与测试条目返回的键名不同）。请始终使用 get_ipaas_tools(pipe_id, tool_name=…) 展开条目，并根据该架构构建参数。

• 测试运行会产生实际副作用。 对于外部应用组件，即使处于草稿状态，测试也会执行实际操作。请使用可随时丢弃的测试数据；独立组件则不会产生此问题。

• 外部步骤因身份验证错误而失败。 该组件需要连接。请创建连接，并将其 externalId 作为步骤的 auth 传入；对于 Slack，机器人必须是目标频道的成员。

• 在服务账号下对流程操作时出现 PERMISSION_DENIED。 运行该流程的服务账号不是流程成员。请使用 add_service_account_to_pipe(pipe_id, email, role_name) 将其添加，并通过 get_pipe_members 确认。

• 下拉选项解析超时。 大型外部工作区可能导致超时。请向用户索取 ID，并按原样传入。

另请参阅

• pipefy-automations — 原生 if/then 规则和 AI 自动化（不是 iPaaS）。
• pipefy-members-email-webhooks — 用于卡片事件 HTTP 回调的 create_webhook；用于授予流程服务账号流程成员资格的 add_service_account_to_pipe。
• docs/mcp/tools/ipaas.md 和 docs/ipaas.md — 元工具语义和流程词汇。