pipefy-introspection

内省と GraphQL の直接実行

現在のサーフェスに対応するリファレンスのみをお読みください：MCP または CLI。以下のワークフローでは、共通の操作名と引数を使用します。

スキーマの検出、組織情報、フォールバック用の実行機能について説明します。

これは解決戦略のティア 2です。専用操作が失敗するか存在しない場合は、内省を使って API を理解し、その後 execute_graphql で操作を直接実行します。

専用の書き込み操作で失敗が報告された場合は、execute_graphql でミューテーションを試す前に、対象を再度読み取ってください。読み取り結果から書き込みが反映されていないことが確認できた場合のみ続行します。結果が不明確な場合は、その旨を報告して終了してください。作成を再度行うと、データが重複する可能性があります。

ティア 1： 専用操作が存在する — それを使用します。 ティア 2： 内省と execute_graphql を使用します（このスキル）。 ティア 3： curl/httpx による直接的なフォールバック — pipefy-api-fallback を参照してください。

---

ツール

操作	読み取り専用	目的
introspect_type	はい	型の構造：fields、inputFields、enumValues。max_depth は任意です。
introspect_query	はい	ルートクエリの引数と戻り値の型。max_depth は任意です。
introspect_mutation	はい	ルートミューテーションの引数と戻り値の型。max_depth は任意です。
search_schema	はい	型名と説明のキーワード検索。kind フィルターは任意です。
execute_graphql	いいえ	任意の GraphQL を実行します。
get_organization	はい	組織情報（名前、プラン、UUID、メンバー数、パイプ数）を読み込みます。
list_organizations	はい	呼び出し元がアクセスできる組織を一覧表示します — ID は不要です。組織を発見するための、事前情報なしで使えるエントリーポイントです。

---

max_depth（introspect_type / query / mutation）

max_depth のデフォルト値は 1 です。

• 1 — 型とフィールドの情報のみ（サブタイプはインライン展開されません）。
• 2+ — 参照されている入力型／出力型をインラインで解決します（resolvedType）。ミューテーションを内省してから各入力型を個別に内省する代わりに、1 回の呼び出しで確認できます。

例：

introspect_mutation mutation_name="createCard" max_depth=2

スカラー（ID、String、Int など）は展開されません。

search_schema の kind

任意のフィルター：OBJECT、INPUT_OBJECT、ENUM、SCALAR、INTERFACE、UNION。

search_schema keyword="automation" kind="INPUT_OBJECT"

---

内省を使う場面

• 専用ツールがエラーを返し、その原因を調べる必要がある場合 — 入力型を内省して、引数名と型を確認します。
• create_phase_field のフィールド型：ツールの入力スキーマに一覧表示されています。スキーマが見えない場合や、差異を確認する場合は、introspect_type('FieldTypeId') で一覧を確認します。
• extra_input を使う前 — 対応する入力型を内省し、任意のキーを確認します。
• ミューテーションのシグネチャが不明な場合 — execute_graphql の前に introspect_mutation('createSomething') を実行します。
• スキーマを調べる場合 — search_schema('automation') で関連する型と入力を探します。

execute_graphql を使う場面

• その操作に対応する専用操作が存在しない場合。
• 専用ツールが失敗し、内省を使って正しいペイロードを確認した場合。
• pipe(id: $id) { organization { uuid } } で組織の UUID を解決するなど、アドホックなクエリを実行する場合。
• どの単一のツールでも対応できない、複雑なネストされたクエリを実行する場合。

必ず専用操作を優先してください。 専用操作は入力を検証し、ページネーションを処理して、一貫した形式でエラーを返します。execute_graphql は、専用ツールでは問題を解決できない場合のフォールバックです。

---

手順 — ミューテーションのシグネチャを特定する

1. キーワードでミューテーションを検索します：

   search_schema keyword="label"
   

2. ミューテーションの完全なシグネチャを取得します：

   introspect_mutation mutation_name="createLabel"
   

3. 入力型のフィールドを確認します：

   introspect_type type_name="CreateLabelInput"
   

4. 確認したミューテーションとその変数を使って、execute_graphql を実行します。

---

よく使うフォールバックの例

専用ツールでは不十分な場合にすぐ使えるパターンです。

レシピ 1 — create_phase_field で有効なフィールド型を確認する

introspect_type('FieldTypeId')

CreatePhaseFieldInput.type は ID スカラーですが、API は有効な値を FieldTypeId enum として公開しています。create_phase_field の入力スキーマにも同じ値が一覧表示されています。

レシピ 2 — タイトルでカードを検索する（find_cards ではできません）

find_cards はカスタムフィールドの値のみを検索します。タイトルで検索するには、次のようにします。

execute_graphql query='query($pipeId: ID!, $first: Int) { cards(pipe_id: $pipeId, first: $first) { edges { node { id title current_phase { name } } } } }' variables='{"pipeId":"<pipe-id>","first":50}'

タイトルでクライアント側フィルタリングを行います。パイプが大きい場合は、after を使ってページネーションします。

レシピ 3 — 任意のミューテーションで extra_input が受け付ける内容を確認する

ツールが extra_input を受け付ける場合（例：create_automation、`update_label）、すべての任意キーを確認できます。

introspect_mutation('createAutomation')     # find the input type name
introspect_type('CreateAutomationInput')    # see all inputFields

ツールの主要な引数と比較すると、extra_input で追加できるキーが分かります。

レシピ 4 — 組織 ID を確認する

「アクセスできる組織はどれですか？」という質問に、手がかりが何もない状態で答えるには、list_organizations を呼び出します。ID は不要で、各組織の id、uuid、name と、自分のロールが返されます。ここが出発点です。すでにパイプがある場合に限り、以下の GraphQL フォールバックを使用します。

ユーザーがパイプ ID しか持っておらず、その organization_id が必要な場合：

execute_graphql query='query($id: ID!) { pipe(id: $id) { organization { id uuid name } } }' variables='{"id":"<pipe-id>"}'

レシピ 5 — 作成後にセレクトフィールドの選択肢を更新する

作成時に選択肢を設定するには、create_phase_field に options を渡します。後から変更するには、このレシピを使用します。

execute_graphql query='mutation($id: ID!, $options: [String!]) { updatePhaseField(input: { id: $id, options: $options }) { phase_field { id label options } } }' variables='{"id":"<field-id>","options":["High","Medium","Low"]}'

レシピ 6 — フェーズ遷移ルールを確認する

move_card_to_phase が「有効な遷移先フェーズではありません」というエラーで失敗した場合：

execute_graphql query='query($id: ID!) { phase(id: $id) { id name cards_can_be_moved_to_phases { id name } } }' variables='{"id":"<current-phase-id>"}'

現在のフェーズから遷移できる有効なフェーズが返されます。

---

成功条件

• introspect_type が、入力型のフィールド一覧をすべて返す。
• execute_graphql が、エラーなしで期待されるデータを返す。

失敗するケース

• introspect_type が null を返す：型名では大文字と小文字が区別されます。PascalCase を試してください（例：create_label_input ではなく CreateLabelInput）。
• search_schema が大量の結果を返す：大文字と小文字を区別しない部分文字列検索のため、"card" のような広範なキーワードでは結果が大量に返されます。"AiAgent" や "FieldCondition" のような具体的な名前を使ってください。
• introspect_mutation の処理が重い：すべてのルートミューテーションフィールドを取得し、クライアント側でフィルタリングします（大規模なクエリを 1 回実行します）。ミューテーション名がすでに分かっている場合は、対象の入力型に対して introspect_type を使ってください。
• execute_graphql が GraphQL エラーを返す：path と message を確認してください。
• 生の HTTP エンドポイント：ツールキットは、公開スキーマのイントロスペクションとオペレーションを同じエンドポイント <PIPEFY_BASE_URL>/graphql（デフォルトは https://app.pipefy.com/graphql）に送信します。直接呼び出す場合は、pipefy-api-fallback を参照してください。

関連項目

• docs/mcp/tools/introspection.md — MCP パラメーター、および execute_graphql のクエリとミューテーションの不一致に関するヒント。
• pipefy-api-fallback — Tier 3：ツールキットが利用できない場合の直接 HTTP フォールバック。
• pipefy-pipes-and-cards — 最もよく使われる専用ツール（execute_graphql より優先して使用してください）。