pipefy-pipes-and-cards

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pipes & Cards

管道与卡片

Read, create, update, and delete pipes, phases, phase fields, labels, cards, attachments, and field conditions. 40 MCP tools.

读取、创建、更新和删除管道、阶段、阶段字段、标签、卡片、附件及字段条件。涵盖40个MCP工具。

Cross-cutting patterns

通用模式

Field types are not validated locally — use
```
introspect_type
```
(e.g., on
```
CreatePhaseFieldInput
```
) for allowed values.
Most write tools support
```
debug=true
```
on errors (returns GraphQL codes +
```
correlation_id
```
).
```
extra_input
```
merges extra API keys (camelCase); keys that duplicate primary arguments are ignored.

字段类型不会在本地验证——请使用
```
introspect_type
```
（例如针对
```
CreatePhaseFieldInput
```
）获取允许的值。
大多数写入工具在出现错误时支持
```
debug=true
```
（返回GraphQL代码 +
```
correlation_id
```
）。
```
extra_input
```
会合并额外的API密钥（采用驼峰式命名camelCase）；与主参数重复的密钥将被忽略。

Pipe operations

管道操作

Tool (MCP)	CLI	Read-only	Purpose
`get_pipe`	`pipefy pipe get <id>`	Yes	Fetch pipe metadata including phases and fields.
`search_pipes`	`pipefy pipe list`	Yes	Search by name pattern.
`create_pipe`	`pipefy pipe create`	No	Create a new pipe in the org.
`update_pipe`	`pipefy pipe update <id>`	No	Rename or change pipe settings.
`delete_pipe`	`pipefy pipe delete <id>`	No	Two-step destructive.
`clone_pipe`	`pipefy pipe clone <id>`	No	Clone an existing pipe.
`get_pipe_members`	`pipefy member list --pipe <id>`	Yes	List members of a pipe.

工具（MCP）	CLI命令	只读	用途
`get_pipe`	`pipefy pipe get <id>`	是	获取包含阶段和字段的管道元数据。
`search_pipes`	`pipefy pipe list`	是	按名称模式搜索管道。
`create_pipe`	`pipefy pipe create`	否	在组织中创建新管道。
`update_pipe`	`pipefy pipe update <id>`	否	重命名或修改管道设置。
`delete_pipe`	`pipefy pipe delete <id>`	否	两步式破坏性操作。
`clone_pipe`	`pipefy pipe clone <id>`	否	克隆现有管道。
`get_pipe_members`	`pipefy member list --pipe <id>`	是	列出管道成员。

Steps — create a pipe with phases

步骤——创建带阶段的管道

Create the pipe:

MCP:

create_pipe name="Customer Onboarding" organization_id=123

CLI:

pipefy pipe create --name "Customer Onboarding" --org 123

Add phases — call
```
create_phase
```
for each phase (see Phase section below). Omit
```
index
```
to append after existing workflow phases, or pass a 1-based
```
index
```
to insert among phases returned by
```
get_pipe
```
. Prefer
```
1
```
or higher;
```
index: 0
```
creates a phase that does not appear in
```
get_pipe
```
's
```
phases
```
list.
```
index
```
only controls order — it does not wire Phase Connections /
```
allowed_phases
```
(configure those in the Pipefy UI; use
```
get_phase_allowed_move_targets
```
before moves).
Add start form fields — call
```
create_phase_field
```
on the start form phase.

创建管道：

MCP命令：

create_pipe name="Customer Onboarding" organization_id=123

CLI命令：

pipefy pipe create --name "Customer Onboarding" --org 123

添加阶段——为每个阶段调用
```
create_phase
```
（见下方阶段部分）。省略
```
index
```
会将阶段追加到现有工作流阶段之后，传入从1开始计数的
```
index
```
可插入到
```
get_pipe
```
返回的阶段列表中。建议使用
```
1
```
或更大的值；
```
index: 0
```
创建的阶段不会出现在
```
get_pipe
```
的
```
phases
```
列表中。
```
index
```
仅控制顺序——它不会配置阶段连接/
```
allowed_phases
```
（请在Pipefy UI中配置这些；在移动卡片前使用
```
get_phase_allowed_move_targets
```
）。
添加起始表单字段——在起始表单阶段调用
```
create_phase_field
```
。

Phase operations

阶段操作

Tool (MCP)	CLI	Read-only	Purpose
`get_pipe`	`pipefy phase get <id>`	Yes	Phase metadata: use `get_pipe` (phases in the response) via MCP, or `pipefy phase get` on the CLI for a single phase.
`create_phase`	`pipefy phase create`	No	Add a phase to a pipe.
`update_phase`	`pipefy phase update <id>`	No	Rename, reorder, set done flag.
`delete_phase`	`pipefy phase delete <id>`	No	Two-step destructive.
`get_phase_allowed_move_targets`	`pipefy phase targets <id>`	Yes	Valid destination phases before `move_card_to_phase` (UI-configured edges only).
`get_phase_cards_count`	`pipefy phase count <id>`	Yes	Native per-phase card count via `get_phase` .
`get_phase_cards`	`pipefy phase cards <id>`	Yes	Paginated cards in a phase ( `--first` , `--after` , optional `--include-fields` ).

工具（MCP）	CLI命令	只读	用途
`get_pipe`	`pipefy phase get <id>`	是	阶段元数据：通过MCP使用 `get_pipe` （响应中包含阶段），或在CLI上使用 `pipefy phase get` 获取单个阶段信息。
`create_phase`	`pipefy phase create`	否	为管道添加阶段。
`update_phase`	`pipefy phase update <id>`	否	重命名、重新排序、设置完成标记。
`delete_phase`	`pipefy phase delete <id>`	否	两步式破坏性操作。
`get_phase_allowed_move_targets`	`pipefy phase targets <id>`	是	在调用 `move_card_to_phase` 前获取有效的目标阶段（仅包含UI配置的连接）。
`get_phase_cards_count`	`pipefy phase count <id>`	是	通过 `get_phase` 获取原生的阶段卡片数量。
`get_phase_cards`	`pipefy phase cards <id>`	是	阶段中的分页卡片（支持 `--first` 、 `--after` ，可选 `--include-fields` ）。

Seed pipe across phases

跨阶段填充管道

Use this workflow to place at least one card in each workflow phase (demos, QA checklists, chaos pipes) without

execute_graphql

. Transition edges must already exist in the Pipefy UI.

使用此工作流可在每个工作流阶段中放置至少一张卡片（适用于演示、QA检查清单、混沌管道），无需使用

execute_graphql

。过渡连接必须已在Pipefy UI中存在。

Tools needed

所需工具

Tool (MCP)	CLI	Read-only
`get_pipe`	`pipefy pipe get <pipe_id>`	Yes
`get_phase_cards_count`	`pipefy phase count <phase_id>`	Yes
`create_card`	`pipefy card create <pipe_id> --phase-id <id>`	No
`get_phase_cards`	`pipefy phase cards <phase_id>`	Yes
`get_phase_allowed_move_targets`	`pipefy phase targets <phase_id>`	Yes
`move_card_to_phase`	`pipefy card move <card_id> --phase <id>`	No

工具（MCP）	CLI命令	只读
`get_pipe`	`pipefy pipe get <pipe_id>`	是
`get_phase_cards_count`	`pipefy phase count <phase_id>`	是
`create_card`	`pipefy card create <pipe_id> --phase-id <id>`	否
`get_phase_cards`	`pipefy phase cards <phase_id>`	是
`get_phase_allowed_move_targets`	`pipefy phase targets <phase_id>`	是
`move_card_to_phase`	`pipefy card move <card_id> --phase <id>`	否

Steps

步骤

Load phase IDs —

get_pipe(pipe_id)

→ collect

phases[].id

for workflow phases. Omit

phase_id

create_card

for start-form intake.

MCP:

get_pipe pipe_id="306996634"

CLI:

pipefy pipe get 306996634 --json

Find empty phases — for each candidate
```
phase_id
```
, call
```
get_phase_cards_count
```
. Target phases where
```
cards_count
```
is 0 (if the start form shows 0 but you suspect cards, call
```
get_phase_cards
```
before creating duplicates).
MCP:
```
get_phase_cards_count phase_id="340012345"
```
CLI:
```
pipefy phase count 340012345 --json
```

Create cards in empty phases — loop

create_card

with

phase_id

(and

skip_elicitation=true

for agent seeding). When

fields

is non-empty, keys are filtered via

get_phase_fields(phase_id)

and

get_start_form_fields(pipe_id)

MCP:

create_card pipe_id="306996634" phase_id="340012345" skip_elicitation=true title="Seeded"

CLI:

bash

pipefy card create 306996634 --phase-id 340012345 --title "Seeded"

Verify inventory —

get_phase_cards(phase_id, first=50)

and confirm expected card IDs/titles.

CLI:

pipefy phase cards 340012345 --json

Before moves — on the card's current phase,

get_phase_allowed_move_targets

then

move_card_to_phase

only to an

allowed_phases[].id

MCP:

get_phase_allowed_move_targets phase_id="<current_phase_id>"

CLI:

pipefy phase targets <current_phase_id> --json

加载阶段ID——调用
```
get_pipe(pipe_id)
```
→ 收集工作流阶段的
```
phases[].id
```
。在
```
create_card
```
上省略
```
phase_id
```
将使用起始表单入口。
MCP命令：
```
get_pipe pipe_id="306996634"
```
CLI命令：
```
pipefy pipe get 306996634 --json
```
查找空阶段——对每个候选
```
phase_id
```
，调用
```
get_phase_cards_count
```
。目标为
```
cards_count
```
为0的阶段（如果起始表单显示为0但你怀疑存在卡片，请在创建重复卡片前调用
```
get_phase_cards
```
）。
MCP命令：
```
get_phase_cards_count phase_id="340012345"
```
CLI命令：
```
pipefy phase count 340012345 --json
```

在空阶段创建卡片——循环调用

create_card

并传入

phase_id

（对于Agent填充，需设置

skip_elicitation=true

）。当

fields

非空时，将通过

get_phase_fields(phase_id)

和

get_start_form_fields(pipe_id)

过滤密钥。

MCP命令：

create_card pipe_id="306996634" phase_id="340012345" skip_elicitation=true title="Seeded"

CLI命令：

bash

pipefy card create 306996634 --phase-id 340012345 --title "Seeded"

验证库存——调用
```
get_phase_cards(phase_id, first=50)
```
并确认预期的卡片ID/标题。
CLI命令：
```
pipefy phase cards 340012345 --json
```

移动前准备——在卡片当前阶段，先调用

get_phase_allowed_move_targets

，然后仅将卡片移动到

allowed_phases[].id

指定的阶段。

MCP命令：

get_phase_allowed_move_targets phase_id="<current_phase_id>"

CLI命令：

pipefy phase targets <current_phase_id> --json

Success criteria

成功标准

Every targeted phase reports
```
cards_count >= 1
```
(or
```
get_phase_cards
```
lists the seeded cards).
Moves use only phases returned in
```
allowed_phases
```
.

每个目标阶段的
```
cards_count >= 1
```
（或
```
get_phase_cards
```
列出了填充的卡片）。
仅使用
```
allowed_phases
```
返回的阶段进行移动操作。

Failure modes

失败模式

Empty
allowed_phases
: configure Phase → Connections in the Pipefy UI; the API cannot add edges.
Unexpected empty count: use
```
get_phase_cards
```
to list cards before creating duplicates.

allowed_phases
为空：请在Pipefy UI中配置阶段→连接；API无法添加连接。
意外的空计数：在创建重复卡片前使用
```
get_phase_cards
```
列出卡片。

Phase field operations

阶段字段操作

Tool (MCP)	CLI	Read-only	Purpose
`get_phase_fields`	`pipefy field list --phase <id>`	Yes	List fields on a phase.
`get_start_form_fields`	`pipefy pipe start-form <pipe_id>`	Yes	List start-form fields for card creation.
`create_phase_field`	`pipefy field create --phase <id>`	No	Add field to a phase.
`update_phase_field`	`pipefy field update <id>`	No	Rename, reorder, change required flag.
`delete_phase_field`	`pipefy field delete <id>`	No	Two-step destructive.

Discover field types:

MCP:

introspect_type type_name="CreatePhaseFieldInput"

This returns valid

type

enum values and their descriptions.

工具（MCP）	CLI命令	只读	用途
`get_phase_fields`	`pipefy field list --phase <id>`	是	列出阶段中的字段。
`get_start_form_fields`	`pipefy pipe start-form <pipe_id>`	是	列出用于卡片创建的起始表单字段。
`create_phase_field`	`pipefy field create --phase <id>`	否	为阶段添加字段。
`update_phase_field`	`pipefy field update <id>`	否	重命名、重新排序、修改必填标记。
`delete_phase_field`	`pipefy field delete <id>`	否	两步式破坏性操作。

发现字段类型：

MCP命令：

introspect_type type_name="CreatePhaseFieldInput"

此命令会返回有效的

type

枚举值及其描述。

Card operations

卡片操作

Tool (MCP)	CLI	Read-only	Purpose
`get_card`	`pipefy card get <id>`	Yes	Card data, fields, and comments.
`get_cards`	`pipefy card list --pipe <id>`	Yes	Paginated card list by pipe.
`find_cards`	`pipefy card find --pipe <id>`	Yes	Filter by a single field value.
`create_card`	`pipefy card create <pipe_id>`	No	Default: start form. Optional `--phase-id` / `phase_id` creates in that phase; interactive clients may elicit start-form fields unless `skip_elicitation=true` .
`fill_card_phase_fields`	`pipefy card fill <id> --phase <id>`	No	Fill phase fields non-interactively; filters to editable IDs. Uses `--fields` JSON object; for ad-hoc updates use `card update --field-updates` (JSON array).
`update_card`	`pipefy card update <id>`	No	Update title, assignee, due date, fields.
`update_card_field`	`pipefy card update <id> --field-updates`	No	Single-field update ( `updateCardField` ); for several fields prefer `update_card` + `field_updates` .
`move_card_to_phase`	`pipefy card move <id> --phase <id>`	No	Call `get_phase_allowed_move_targets` on the source phase first.
`delete_card`	`pipefy card delete <id>`	No	Two-step destructive.
`add_card_comment`	`pipefy card comment add <id>`	No	Add a text comment to a card.
`update_comment`	`pipefy card comment update`	No	Update an existing card comment.
`delete_comment`	`pipefy card comment delete`	No	Two-step destructive.
`upload_attachment_to_card`	`pipefy attachment upload --card`	No	Attach a file to an attachment field ( `field_id` = slug). Exactly one source: `file_path` (local; local profile only) or `file_url` (downloaded, SSRF-guarded; any profile — required on the hosted server). See `pipefy-attachments` .

工具（MCP）	CLI命令	只读	用途
`get_card`	`pipefy card get <id>`	是	获取卡片数据、字段和评论。
`get_cards`	`pipefy card list --pipe <id>`	是	按管道分页列出卡片。
`find_cards`	`pipefy card find --pipe <id>`	是	按单个字段值过滤卡片。
`create_card`	`pipefy card create <pipe_id>`	否	默认：使用起始表单。可选的 `--phase-id` / `phase_id` 会在指定阶段创建卡片；交互式客户端可能会要求填写起始表单字段，除非设置 `skip_elicitation=true` 。
`fill_card_phase_fields`	`pipefy card fill <id> --phase <id>`	否	非交互式填充阶段字段；仅过滤可编辑的ID。使用 `--fields` JSON对象；临时更新请使用 `card update --field-updates` （JSON数组）。
`update_card`	`pipefy card update <id>`	否	更新标题、经办人、截止日期、字段。
`update_card_field`	`pipefy card update <id> --field-updates`	否	单字段更新（ `updateCardField` ）；如需更新多个字段，建议使用 `update_card` + `field_updates` 。
`move_card_to_phase`	`pipefy card move <id> --phase <id>`	否	请先在源阶段调用 `get_phase_allowed_move_targets` 。
`delete_card`	`pipefy card delete <id>`	否	两步式破坏性操作。
`add_card_comment`	`pipefy card comment add <id>`	否	为卡片添加文本评论。
`update_comment`	`pipefy card comment update`	否	更新现有卡片评论。
`delete_comment`	`pipefy card comment delete`	否	两步式破坏性操作。
`upload_attachment_to_card`	`pipefy attachment upload --card`	否	将文件附加到附件字段（ `field_id` = 别名slug）。仅支持一种来源： `file_path` （本地文件；仅本地配置文件可用）或 `file_url` （下载文件，受SSRF防护；任何配置文件可用——托管服务器上必填）。详见 `pipefy-attachments` 。

Steps — create a card

步骤——创建卡片

Get start form fields (required — never skip):

MCP:

get_start_form_fields pipe_id=67890

CLI:

pipefy pipe start-form 67890 --json

Create the card with fields:

MCP:

create_card pipe_id=67890 title="My Card" fields_attributes='[{"field_id":"field_slug","field_value":"value"}]'

CLI:

bash

pipefy card create 67890 --title "My Card" --fields '{"field_slug":"value"}'

Report result with card ID and link:

https://app.pipefy.com/open-cards/<CARD_ID>

获取起始表单字段（必填——切勿跳过）：
MCP命令：
```
get_start_form_fields pipe_id=67890
```
CLI命令：
```
pipefy pipe start-form 67890 --json
```

创建带字段的卡片：

MCP命令：

create_card pipe_id=67890 title="My Card" fields_attributes='[{"field_id":"field_slug","field_value":"value"}]'

CLI命令：

bash

pipefy card create 67890 --title "My Card" --fields '{"field_slug":"value"}'

返回结果，包含卡片ID和链接：

https://app.pipefy.com/open-cards/<CARD_ID>

Pagination for get_cards

get_cards

分页示例

get_cards pipe_id=67890 first=50 after=<endCursor>

Read

pageInfo.hasNextPage

and

pageInfo.endCursor

from the response; pass

after=<endCursor>

for the next page.

get_cards pipe_id=67890 first=50 after=<endCursor>

从响应中读取

pageInfo.hasNextPage

和

pageInfo.endCursor

；在下一页请求中传入

after=<endCursor>

。

Label operations

标签操作

Tool (MCP)	CLI	Read-only	Purpose
`get_labels`	`pipefy label list --pipe <id>`	Yes	List pipe labels.
`create_label`	`pipefy label create`	No	Create a label with a color.
`update_label`	`pipefy label update <id>`	No	Rename or recolor.
`delete_label`	`pipefy label delete <id>`	No	Two-step destructive.

工具（MCP）	CLI命令	只读	用途
`get_labels`	`pipefy label list --pipe <id>`	是	列出管道标签。
`create_label`	`pipefy label create`	否	创建带颜色的标签。
`update_label`	`pipefy label update <id>`	否	重命名或修改颜色。
`delete_label`	`pipefy label delete <id>`	否	两步式破坏性操作。

Field condition operations

字段条件操作

Tool (MCP)	CLI	Purpose
`get_field_conditions`	`pipefy field-condition list --phase <id>`	List all field conditions on a phase.
`get_field_condition`	`pipefy field-condition get`	Load one field condition by ID.
`create_field_condition`	`pipefy field-condition create`	Create show/hide rule.
`update_field_condition`	`pipefy field-condition update`	Update condition action or rule.
`delete_field_condition`	`pipefy field-condition delete`	Two-step destructive.

工具（MCP）	CLI命令	用途
`get_field_conditions`	`pipefy field-condition list --phase <id>`	列出阶段中的所有字段条件。
`get_field_condition`	`pipefy field-condition get`	通过ID加载单个字段条件。
`create_field_condition`	`pipefy field-condition create`	创建显示/隐藏规则。
`update_field_condition`	`pipefy field-condition update`	更新条件操作或规则。
`delete_field_condition`	`pipefy field-condition delete`	两步式破坏性操作。

Success criteria

成功标准

Pipe and phases visible in Pipefy UI.
```
get_pipe
```
returns the new pipe ID and phases.
Cards created via
```
create_card
```
appear in the pipe's first phase.

管道和阶段在Pipefy UI中可见。
```
get_pipe
```
返回新管道ID和阶段信息。
通过
```
create_card
```
创建的卡片出现在管道的第一个阶段中。

Failure modes

失败模式

create_card
fails with missing required fields: call
```
get_start_form_fields
```
first to discover required
```
field_id
```
values.

create_phase_field
rejects type: call

introspect_type type_name="CreatePhaseFieldInput"

to get valid values.

Delete fails with preview error: expected — call without
```
confirm=true
```
first, show user the preview, then call with
```
confirm=true
```
.

create_card
因缺少必填字段失败：请先调用
```
get_start_form_fields
```
发现必填的
```
field_id
```
值。

create_phase_field
拒绝字段类型：调用

introspect_type type_name="CreatePhaseFieldInput"

获取有效值。

删除操作因预览错误失败：此为预期情况——先不带
```
confirm=true
```
调用，向用户展示预览，再带
```
confirm=true
```
调用。

另请参阅

```
skills/relations/
```
— link pipes and cards across workflows.
```
skills/automations/
```
— add automation rules to a pipe.
```
skills/introspection/
```
— discover field types and mutation signatures.
```
docs/mcp/tools/identifiers.md#field-references-slug-vs-internal_id
```
— canonical map of which tool/argument expects slug vs
```
internal_id
```
vs uuid vs numeric id (e.g.
```
update_card_field
```
uses a field slug).

```
skills/relations/
```
——跨工作流链接管道和卡片。
```
skills/automations/
```
——为管道添加自动化规则。
```
skills/introspection/
```
——发现字段类型和突变签名。
```
docs/mcp/tools/identifiers.md#field-references-slug-vs-internal_id
```
——规范说明哪些工具/参数需要使用别名slug、
```
internal_id
```
、uuid或数字ID（例如
```
update_card_field
```
使用字段别名slug）。

pipefy-pipes-and-cards

Original

Translation

Pipes & Cards

管道与卡片

Cross-cutting patterns

通用模式

Pipe operations

管道操作

Steps — create a pipe with phases

步骤——创建带阶段的管道

Phase operations

阶段操作

Seed pipe across phases

跨阶段填充管道

Tools needed

所需工具

Steps

步骤

Success criteria

成功标准

Failure modes

失败模式

Phase field operations

阶段字段操作

Card operations

卡片操作

Steps — create a card

步骤——创建卡片

Pagination for get_cards

get_cards分页示例

Label operations

标签操作

Field condition operations

字段条件操作

Success criteria

成功标准

Failure modes

失败模式

See also

另请参阅

`get_cards`
分页示例