pipefy-pipes-and-cards

Pipes & Cards

アクティブなサーフェスのリファレンスのみを参照してください：MCP または CLI。以下のワークフローでは、共通の操作名と引数を使用します。

パイプ、フェーズ、フェーズフィールド、ラベル、カード、添付ファイル、フィールド条件を読み取り、作成、更新、削除します。

---

共通パターン

• フィールドタイプ：create_phase_field では、API の FieldTypeId enum 値（小文字。例：short_text。SHORT_TEXT ではありません）を指定します。ツールの入力スキーマに値の一覧があります。

• extra_input は追加の API キー（camelCase）をマージします。主要な引数と重複するキーは無視されます。

• フェーズ接続は UI 専用です。 フェーズを作成または並べ替えても、Phase Connections / allowed_phases は接続されません。Pipefy の UI でエッジを設定し、カードを移動する前に get_phase_allowed_move_targets を使用してください。API では遷移エッジを追加できません。

• 書き込み後に確認します。 作成または更新後は、一致する get ツール（get_pipe、get_card、get_phase_fields など）で再読み込みしてから、成功を報告してください。書き込み応答だけを成功の証拠と見なさないでください。

---

パイプ操作

操作	読み取り専用	目的
get_pipe	はい	フェーズとフィールドを含むパイプのメタデータを取得します。
search_pipes	はい	名前のパターンで検索します。
create_pipe	いいえ	組織に新しいパイプを作成します。
update_pipe	いいえ	パイプの名前を変更するか、設定を変更します。
delete_pipe	いいえ	破壊的操作です。事前に確認し、承認を得てください。
clone_pipe	いいえ	既存のパイプを複製します。
get_pipe_members	はい	パイプのメンバー一覧を取得します。

手順 — フェーズを含むパイプの作成

1. パイプを作成します：

   create_pipe name="Customer Onboarding" organization_id=300123456

2. フェーズを構成します。 create_pipe はすでに、キー 1、2、3 の Inbox、Doing、Done を追加します。これら 3 つに加えて、要求された名前ごとに create_phase を呼び出さないでください。

   パイプに 3 つ以上のフェーズが必要で、最後のフェーズが最終フェーズの場合は、update_phase で Inbox、Doing、Done の名前を変更します。Done を最終フェーズのままにするため、done は設定しないでください。2 番目のフェーズと最後のフェーズの間に配置するフェーズのみを、2.01、2.02 などのキーで作成します。パイプに 3 つ未満のフェーズが必要な場合は、残さない空のデフォルトフェーズをそれぞれ削除します。delete_phase は破壊的操作です。事前に確認し、承認を得てください。

   index は浮動小数点数のソートキーです。既存の 2 つのキーの間の値を指定すると、そのフェーズ間に挿入されます。同じキーには固定の順序がないため、他のフェーズでは使われていないキーを使用してください。新しいパイプの Inbox、Doing、Done のキーは 1、2、3 です。また、0 を指定すると、そのフェーズは get_pipe のフェーズ一覧から除外されます。get_pipe は各キーを phases[].index として昇順で返します。2 と 3 の間には、小数点以下 2 桁の値（2.01、2.02、...、2.99）を使用してください。2.10 は 2.1 と同じ浮動小数点数のため、10 番目の値は最初の値と同じになります。index は Phase Connections / allowed_phases を接続しません（Pipefy の UI で設定し、カードを移動する前に get_phase_allowed_move_targets を使用してください）。

   get_pipe を呼び出し、フェーズ名が意図した順序になっていることを確認してください。

3. 開始フォームのフィールドを追加します — 開始フォームのフェーズで create_phase_field を呼び出します。

---

フェーズ操作

操作	読み取り専用	目的
get_pipe	はい	パイプの応答からフェーズのメタデータを読み取ります。
create_phase	いいえ	パイプにフェーズを追加します。
update_phase	いいえ	名前を変更し、完了フラグを設定します。update_phase には index フィールドがありません。カードのないフェーズを移動するには、そのフェーズを削除し、ソートキーを指定して再作成してください。
delete_phase	いいえ	破壊的操作です。事前に確認し、承認を得てください。
get_phase_allowed_move_targets	はい	move_card_to_phase の前に、有効な移動先フェーズを取得します（UI で設定されたエッジのみ）。
get_phase_cards_count	はい	get_phase を通じて、フェーズごとのネイティブなカード数を取得します。
get_phase_cards	はい	フェーズ内のカードをページネーションで取得します。

フェーズをまたいでパイプにカードを追加する

このワークフローを使用すると、execute_graphql を使わずに、各ワークフローフェーズ（デモ、QA チェックリスト、カオスパイプ）に少なくとも 1 枚のカードを配置できます。遷移エッジは、あらかじめ Pipefy の UI で設定しておく必要があります。

必要なツール

操作	読み取り専用
get_pipe	はい
get_phase_cards_count	はい
create_card	いいえ
get_phase_cards	はい
get_phase_allowed_move_targets	はい
move_card_to_phase	いいえ

move_card_to_phase の前に、get_phase_allowed_move_targets を呼び出してください。必須フィールドが空の場合、移動できないことがあります。

手順

1. フェーズ ID を読み込む — get_pipe(pipe_id) を呼び出し、ワークフローフェーズの phases[].id を収集します。開始フォームからカードを受け付ける場合は、create_card の phase_id を省略してください。

   get_pipe pipe_id="301234567"

2. 空のフェーズを探す — 対象候補の各 phase_id に対して get_phase_cards_count を呼び出します。cards_count が 0 のフェーズを対象にします（開始フォームに 0 と表示されていても、カードがあると思われる場合は、重複して作成する前に get_phase_cards を呼び出してください）。

   get_phase_cards_count phase_id="341234567"

3. 空のフェーズにカードを作成する — phase_id を指定して create_card を繰り返し呼び出します。fields が空でない場合、キーは get_phase_fields(phase_id) と get_start_form_fields(pipe_id) を使ってフィルタリングされます。

   create_card pipe_id="301234567" phase_id="341234567" title="Seeded" fields={}
   

4. 一覧を確認する — get_phase_cards(phase_id, first=50) を呼び出し、想定したカード ID／タイトルがあることを確認します。

5. 移動する前に確認する — カードの現在のフェーズに対して get_phase_allowed_move_targets を呼び出し、その後、allowed_phases[].id に含まれるフェーズにのみ move_card_to_phase を呼び出します。

   get_phase_allowed_move_targets phase_id="<current_phase_id>"

成功条件

• 対象のすべてのフェーズで cards_count >= 1 と報告されるか、get_phase_cards に追加したカードが表示されます。
• 移動先には、allowed_phases で返されたフェーズのみを使用します。

失敗する場合

• allowed_phases が空の場合： Pipefy の UI で Phase → Connections を設定してください。API ではエッジを追加できません。
• 予期せず件数が 0 の場合： 重複して作成する前に get_phase_cards を使ってカードを一覧表示してください。

---

フェーズフィールドの操作

操作	読み取り専用	目的
get_phase_fields	はい	フェーズのフィールドを一覧表示します。
get_start_form_fields	はい	カード作成用の開始フォームフィールドを一覧表示します。
create_phase_field	いいえ	フェーズにフィールドを追加します。
update_phase_field	いいえ	名前の変更、並べ替え、必須フラグの変更を行います。
delete_phase_field	いいえ	破壊的な操作です。先に確認して承認してください。

フィールドタイプ： field_type には FieldTypeId の値を指定します。値は create_phase_field の入力スキーマに記載されています（または introspect_type type_name="FieldTypeId" を呼び出します）。選択式、ラジオボタン、チェックリストのフィールドタイプには options を設定します。connector フィールドには、パイプ ID またはテーブル ID を指定した extra_input.connectedRepoId も必要です。

---

カード操作

操作	読み取り専用	目的
get_card	はい	タイトル、フェーズ、パイプ、任意のフィールドを取得します。ラベルや担当者は返しません。
get_cards	はい	パイプごとにページ分割されたカード一覧を取得します。
get_records	はい	日付、フェーズ、ラベル、担当者、作成者、タイトル、カスタムフィールドでパイプ内のカードを一覧表示、件数取得、絞り込みします。正確な totalCount を返します。
find_cards	はい	単一のフィールド値で絞り込みます。
create_card	いいえ	デフォルトでは開始フォームを使用します。phase_id を指定すると、そのフェーズに作成します。
fill_card_phase_fields	いいえ	フェーズのフィールドに入力します。編集可能な ID のみに絞り込みます。
update_card	いいえ	タイトル、担当者、ラベル、期限、またはフィールドを更新します。リスト型のフィールド（接続、添付ファイル、チェックリスト）には、operation に ADD/REMOVE を指定した field_updates を使用してください。パイプのラベルと担当者はカード属性（label_ids / assignee_ids、すべて置き換え）であり、フィールドではありません。「ラベル操作」を参照してください。field_updates が設定されている場合、属性の引数は破棄されます。接続には、関連するカード IDを指定してください。
update_card_field	いいえ	単一フィールドの updateCardField を実行します。リスト型フィールドはすべて置き換えになります。接続には、表示タイトルではなく、関連するカード IDを値として指定してください。get_card の value（タイトルのみ）から再構築しないでください。get_card_relations で ID を読み取ってください。フィールドには update_card と ADD/REMOVE の組み合わせを推奨します。パイプのラベルには、このツールではなく label_ids を使用してください。
move_card_to_phase	いいえ	最初に get_phase_allowed_move_targets を呼び出してください。必須フィールドが未入力の場合、移動できないことがあります。
delete_card	いいえ	破壊的な操作です。事前に内容を確認し、承認してください。
add_card_comment	いいえ	カードにテキストコメントを追加します。
update_comment	いいえ	既存のカードコメントを更新します。
delete_comment	いいえ	破壊的な操作です。事前に内容を確認し、承認してください。

手順 — カードを作成する

1. 開始フォームのフィールドを取得します（必須 — 省略しないでください）。

   get_start_form_fields pipe_id=301234567

2. フィールドを指定してカードを作成します。

   create_card pipe_id=301234567 title="My Card" fields={"field_slug":"value"}
   

3. 結果を報告します。 カード ID とリンクを記載してください：https://app.pipefy.com/open-cards/<CARD_ID>

カードの件数取得と絞り込み

get_records を使うと、「件数はいくつか」という質問に1回の呼び出しで回答できます。first=1 を設定し、ページの長さではなく records.totalCount を読み取ってください。グループごと（担当者ごと、ラベルごと）の件数取得には、グループごとに1回の呼び出しが必要です。 where と order_by では、field に get_phase_fields のカスタムフィールド UUID を指定する必要があります。開始フォームのフィールドの場合は、phase_id に get_pipe の startFormPhaseId を設定して get_phase_fields を呼び出してください。slug は拒否されます。 日付は ISO 8601 形式です。CREATED_AT や FINISHED_AT などの日付時刻属性にはオフセットを指定しますが、date カスタムフィールドには日付のみ（"2026-07-03"）を指定してください。UTC 以外のオフセットを指定すると、eq が 0 を返し、between の範囲がずれるためです。between には {"min": ..., "max": ...} を指定します。 like と ilike はどちらも大文字と小文字を区別せず、値に含まれる各単語を部分文字列として、順不同で照合します。% と _ は通常の文字として扱われるため、"%acme%" ではなく ilike: "acme" と指定してください。ID でカードを検索するには、where={"attribute": "ID", "eq": "<id>"} を使用してください。 where または search_term を指定すると、ページ取得は 10,000 件で停止します。 すべてのカードを一覧表示するには、前のページの pageInfo.endCursor を after に設定してページを取得し、hasNextPage が false になるまで繰り返してください。また、行数の合計が totalCount と一致することを確認してください。

get_records pipe_id=67890 where={"attribute":"FINISHED_AT","between":{"min":"2026-01-01T00:00:00-03:00","max":"2026-01-31T23:59:59-03:00"}}

get_cards のページネーション

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

レスポンスから pageInfo.hasNextPage と pageInfo.endCursor を読み取り、次のページでは after=<endCursor> を設定してください。

---

ラベル操作

操作	読み取り専用	目的
get_pipe	はい	パイプのレスポンスに含まれる labels からラベルを一覧表示します。
create_label	いいえ	色を指定してラベルを作成します。
update_label	いいえ	名前または色を変更します。
delete_label	いいえ	破壊的な操作です。事前に確認して承認してください。

これらのツールは、パイプ上のラベル定義を管理します。パイプのラベルをカードに適用するには update_card(label_ids=[...]) を使用します。この操作はカードのラベルリスト全体を置き換えます。残すラベルのすべての ID を含め、新しいラベルの ID だけを送らないでください。get_card はラベルを返しません。execute_graphql（card(id: ...) { labels { id } }）で現在の ID を読み取り、マージしてから書き込んでください。operation ADD/REMOVE を指定する field_updates は、リスト型のフィールド用であり、カード属性のラベルには使用できません。ユーザーがラベルの自動適用（「期日を過ぎたら遅延のラベルを付ける」など）を求めている場合は、pipefy-automations を読み、そこで処理を止めてください（ラベルの適用に対応する自動化アクションはありません）。自動化アクションでは実現できず、カードの集合に対して update_card を実行すると、プロセスではなくエージェントがランタイムになってしまいます。

---

フィールド条件の操作

操作	目的
get_field_conditions	フェーズ上のすべてのフィールド条件を一覧表示します。
get_field_condition	ID を指定して1つのフィールド条件を読み込みます。
create_field_condition	表示／非表示ルールを作成します。成功を報告する前に、ルールが指定されたフェーズに設定されていることを確認してください。
update_field_condition	条件のアクションまたはルールを更新します。
delete_field_condition	破壊的な操作です。事前に確認して承認してください。

必須フィールドは非表示にしないでください。先に required をクリアしてください。

---

成功の基準

• Pipefy の UI でパイプとフェーズを確認できます。
• get_pipe が新しいパイプ ID とフェーズを返します。
• create_card で作成したカードが、パイプの最初のフェーズに表示されます。

失敗モード

• create_field_condition がフェーズの不足または誤りで失敗する場合： 返された条件を削除してから作り直してください。指定したフェーズに対して、確認せずに作成を再試行しないでください。
• create_card が必須フィールドの不足で失敗する場合： 先に get_start_form_fields を呼び出し、必須の field_id 値を確認してください。
• create_card／書き込みが失敗を報告する場合（メッセージが空、または不明瞭）： 確認せずに再試行しないでください。再試行する前に get_cards／get_phase_cards_count（またはパイプの cards_count）で再確認してください。pipefy-api-fallback（書き込みの失敗が不明瞭な場合は再試行前に読み直す）を参照してください。
• コネクターフィールドの更新後に関連付けが失われる場合： update_card_field は全置換です。関連カード ID を1つ書き込むと、残りがすべて削除されます（添付ファイルやチェックリストなど、他のリスト型フィールドも同じく全置換です）。関連するカード ID を使い、operation ADD/REMOVE を指定した update_card を優先してください。get_card の value（表示用のタイトルのみ）からリスト全体を再構築しないでください。REMOVE または安全な全置換を行うには、get_card_relations（または GraphQL の array_value）で現在の関連カード ID を取得してください。コネクターフィールドではなくパイプのリレーション経由で書き込む場合は、create_card_relation／delete_card_relation を使用してください。pipefy-relations を参照してください。パイプのラベルと担当者はフィールドではありません。update_card(label_ids=)／assignee_ids（全置換）を使用してください。field_updates ADD ではこれらを指定できません。
• create_phase_field が型を拒否する場合（Field type not found with id: ...）：小文字の FieldTypeId 値を使用してください（SHORT_TEXT ではなく short_text）。introspect_type type_name="FieldTypeId" で一覧を確認できます。

関連項目

• pipefy-relations — ワークフロー間でパイプとカードをリンクします。
• pipefy-automations — パイプに自動化ルールを追加します。
• pipefy-introspection — フィールド型とミューテーションのシグネチャを確認します。
• docs/mcp/tools/identifiers.md#field-references-slug-vs-internal_id — 各ツール／引数で slug、internal_id、uuid、数値 ID のどれを指定するかを示す正式な対応表です（例：update_card_field はフィールドの slug を使用します）。