工具参考

Activepieces 中所有 MCP 工具的完整目录

发现

这些工具始终可用（固定）且为只读。它们帮助 AI 代理在进行更改前了解项目内容。

ap_list_flows

列出当前项目中的工作流，包含状态、触发器类型和发布状态。

ap_flow_structure

获取工作流的完整结构：步骤树、配置状态、步骤输入值、路由分支条件和有效的插入位置。显示每个步骤的实际配置输入（URL、请求体、请求头等），以便 AI 读取和编辑现有配置。

ap_read_step_code

读取 CODE 步骤的完整源代码、package.json 和输入映射。返回未截断的内容 —— 与 ap_flow_structure 不同，后者将代码截断为 300 个字符。

ap_validate_flow

验证工作流的结构问题，无需发布。检查步骤有效性、模板引用和空分支。

ap_research_pieces

研究可用的 Pieces。使用 pieceNames 进行批量精确查找（始终返回动作和触发器）。使用 searchQuery 进行模糊发现。

ap_get_piece_props

获取特定 Piece 动作或触发器的详细输入属性模式。返回字段名称、类型、必需/可选、描述、默认值和下拉选项。当需要认证但未提供时，自动列出可用连接。在调用 ap_update_step 或 ap_update_trigger 之前使用此工具，以了解需要设置哪些字段。

ap_resolve_property_options

解析单个 Piece 属性的下拉选项。返回带标签和内部 ID 的可用选择。在配置步骤前使用此工具发现动态下拉字段（例如 Slack 频道、Google Sheets、邮件标签）的有效值。

ap_resolve_property_chain

一次调用解析一系列依赖的下拉属性。对于具有级联字段的动作（例如 Spreadsheet → Sheet → Columns），此工具按顺序解析每个属性，将每个选定值馈入下一个解析。为已知值的属性传递 selectedValue；当遇到没有 selectedValue 的属性时，工具停止并返回选项。

ap_validate_step_config

在应用前验证步骤配置。返回字段级错误，不修改任何工作流。

ap_list_connections

列出项目中的 OAuth/应用连接。在添加需要认证的步骤前必需。

ap_list_ai_models

列出已配置的 AI 提供商及其可用模型。使用此工具发现配置运行 Agent 步骤的有效 aiProviderModel 值。

ap_list_tables

列出项目中的所有表格及其字段（名称、类型、ID）和行数。

ap_find_records

从表中查询记录，支持可选筛选。

筛选运算符： eq、neq、gt、gte、lt、lte、co（包含）、exists、not_exists

ap_list_runs

列出最近的工作流运行，支持可选筛选。

ap_get_run

获取工作流运行的详细信息，包括各步骤输出、错误和耗时。

ap_setup_guide

获取设置连接或 AI 提供商的分步说明。返回供用户在 UI 中遵循的说明 —— 凭据从不通过 MCP 处理。

ap_set_project_context

设置或清除当前项目上下文。所有工具都需要项目上下文才能运行。使用 projectId 选择项目，或不传参以清除选择。始终返回可用项目列表。

工作流管理

创建和管理工作流。

ap_create_flow

创建新的空工作流。

ap_duplicate_flow

复制现有工作流。创建包含所有步骤、配置和画布笔记的新副本。连接和样本数据不会被复制。

ap_rename_flow

重命名现有工作流。

ap_change_flow_status

启用或禁用工作流。

ap_delete_flow

永久删除工作流及其所有版本。此操作不可撤销。

ap_lock_and_publish

发布工作流的当前草稿。验证所有步骤已配置。

工作流构建

在工作流中添加、配置和删除步骤。

ap_build_flow

一次调用创建完整工作流 —— 触发器加任意数量的步骤。步骤按顺序添加（trigger → step_1 → step_2 → …）。所有步骤在创建时即验证。使用细粒度工具（ap_add_step、ap_update_step）修改现有工作流或添加嵌套结构（循环内容、路由分支）。

返回工作流 ID、指向编辑器中工作流的直接 flowUrl 链接、步骤数和验证状态。

数组中的步骤类型：

• PIECE：pieceName、actionName、input、auth、continueOnFailure、retryOnFailure
• CODE：sourceCode、input、continueOnFailure、retryOnFailure
• LOOP_ON_ITEMS：loopItems
• ROUTER：创建包含分支 1 + 其他分支的路由器

ap_update_trigger

设置或更新工作流的触发器。

ap_add_step

向工作流添加新步骤。可选择在同一调用中通过提供 input、auth、sourceCode 或 loopItems 进行配置。

ap_update_step

更新现有步骤的设置。可选属性自动填充默认值。

ap_delete_step

从工作流中删除步骤。

路由与分支

管理路由器步骤中的条件分支。使用 ap_flow_structure 查看现有分支条件和索引。

ap_add_branch

向路由器步骤添加条件分支。该分支在回退（Otherwise）分支之前插入。

条件格式： 外层数组 = OR 组，内层数组 = AND 条件。每个条件包含：

• firstValue（string）—— 左侧值，可使用 {{step_1.field}} 模板语法
• operator（string）—— 例如 TEXT_CONTAINS、NUMBER_IS_GREATER_THAN、EXISTS、BOOLEAN_IS_TRUE
• secondValue（string，可选）—— 右侧值（单值运算符不需要）
• caseSensitive（boolean，可选）—— 用于文本运算符

ap_update_branch

更新现有路由器分支的条件和/或名称，不影响其中的步骤。

ap_delete_branch

从路由器步骤中删除分支。不能删除回退（最后一个）分支。

标注

ap_manage_notes

在工作流中添加、更新或删除画布笔记。

表格

内置表格功能的完整 CRUD 操作。插入或更新记录时使用字段名称（而非 ID）。

ap_create_table

使用初始字段集创建新表格。

字段类型： TEXT、NUMBER、DATE、STATIC_DROPDOWN（需要 options 数组）

ap_delete_table

永久删除表格及其所有数据。

ap_manage_fields

在表格中添加、重命名或删除字段。

ap_insert_records

向表格中插入一条或多条记录。

ap_update_record

更新记录中的特定单元格。仅更改指定的字段。

ap_delete_records

永久删除一条或多条记录。

测试与运行

测试工作流、检查结果和重试失败项。测试工具最长轮询 120 秒并返回分步结果。

ap_test_flow

在测试环境中端到端测试工作流。当没有样本数据时（例如 webhook 触发器），传递 triggerTestData 以提供模拟触发器输出。

ap_test_step

测试工作流中的单个步骤。运行直到并包括目标步骤的所有步骤。当没有样本数据时传递 triggerTestData。

ap_retry_run

重试失败的工作流运行。

• FROM_FAILED_STEP：从失败处继续，保留前序步骤输出
• ON_LATEST_VERSION：使用当前发布版本重新运行整个工作流

ap_run_action

执行一次单个 Piece 动作，无需构建或保存工作流。专为一次性任务设计，例如”查看我的收件箱”或”发送一条 Slack 消息”，这些场景构建完整的自动化显得有些大材小用。底层上，该工具创建一个一次性工作流、运行动作、返回输出，然后清理工作流 —— 用户不会在其工作流列表中看到它。