pipefy-introspection

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Introspection & Raw GraphQL

内省与原始GraphQL

Schema discovery, organization info, and a fallback executor. 7 MCP tools.

This is Tier 2 in the resolution strategy: when a dedicated MCP tool fails or doesn't exist, use introspection to understand the API, then

execute_graphql

to run the operation directly.

Tier 1: dedicated MCP tool exists — use it. Tier 2: use introspection +

execute_graphql

(this skill). Tier 3: direct curl/httpx fallback — see skills/api-troubleshoot/pipefy-api-fallback/SKILL.md.

用于Schema探索、组织信息查询，以及作为备用执行器。包含7个MCP工具。

这是解决方案策略中的Tier 2：当专用MCP工具执行失败或不存在对应操作工具时，使用内省功能了解API，然后通过

execute_graphql

直接运行操作。

Tier 1： 存在专用MCP工具 —— 使用该工具。 Tier 2： 使用内省 +

execute_graphql

（即本技能）。 Tier 3： 直接使用curl/httpx作为备用方案 —— 详见skills/api-troubleshoot/pipefy-api-fallback/SKILL.md。

Tools

工具

Tool (MCP)	CLI	Read-only	Purpose
`introspect_type`	`pipefy introspect type`	Yes	Type shape: `fields` , `inputFields` , `enumValues` . Optional `max_depth` .
`introspect_query`	`pipefy introspect query`	Yes	Root query arguments and return type. Optional `max_depth` .
`introspect_mutation`	`pipefy introspect mutation`	Yes	Root mutation arguments and return type. Optional `max_depth` .
`search_schema`	`pipefy introspect schema search`	Yes	Keyword search on type names/descriptions. Optional `kind` filter.
`execute_graphql`	`pipefy graphql exec`	No	Execute arbitrary GraphQL ( `--yes` required for mutations).
`get_organization`	`pipefy org get`	Yes	Load organization info (name, plan, UUID, member count, pipe count).
`list_organizations`	`pipefy org list`	Yes	List organizations the caller can access — no id required. The zero-knowledge entry point for org discovery.

工具（MCP）	CLI命令	只读	用途
`introspect_type`	`pipefy introspect type`	是	查看类型结构： `fields` 、 `inputFields` 、 `enumValues` 。可选参数 `max_depth` 。
`introspect_query`	`pipefy introspect query`	是	查看根查询的参数和返回类型。可选参数 `max_depth` 。
`introspect_mutation`	`pipefy introspect mutation`	是	查看根mutation的参数和返回类型。可选参数 `max_depth` 。
`search_schema`	`pipefy introspect schema search`	是	按关键词搜索类型名称/描述。可选参数 `kind` 进行过滤。
`execute_graphql`	`pipefy graphql exec`	否	执行任意GraphQL操作（执行mutation需添加 `--yes` 参数）。
`get_organization`	`pipefy org get`	是	加载组织信息（名称、套餐、UUID、成员数量、管道数量）。
`list_organizations`	`pipefy org list`	是	列出调用者可访问的所有组织 —— 无需ID。这是组织探索的零知识入口。

The

include_parsed

flag

include_parsed

标志

execute_graphql

introspect_type

introspect_mutation

introspect_query

, and

get_organization

all accept an optional

include_parsed: bool

(default

false

Default (
false
): response is
```
{ success, result }
```
where
```
result
```
is the raw GraphQL JSON as a string.
true
: response includes both
```
result
```
(the raw JSON string) AND
```
data
```
(the parsed dict). Drill into
```
data
```
programmatically; keep
```
result
```
to forward verbatim.

Use

include_parsed=true

whenever you plan to read nested fields (e.g. iterating over

phases[].fields[]

). Leave it off for one-shot reads where the raw string is sufficient.

execute_graphql

、

introspect_type

、

introspect_mutation

、

introspect_query

和

get_organization

均支持可选参数

include_parsed: bool

（默认值为

false

）。

默认值（
false
）：响应格式为
```
{ success, result }
```
，其中
```
result
```
是原始GraphQL JSON的字符串形式。
设置为
true
：响应同时包含
```
result
```
（原始JSON字符串）和
```
data
```
（解析后的字典）。可通过
```
data
```
以编程方式深入访问嵌套字段；保留
```
result
```
可直接转发原始内容。

当你需要读取嵌套字段时（例如遍历

phases[].fields[]

），请设置

include_parsed=true

。如果仅需一次性读取原始字符串内容，则无需开启此参数。

max_depth

(introspect_type / query / mutation)

max_depth

（适用于introspect_type / query / mutation）

MCP tools accept

max_depth

(default

). CLI:

--max-depth

1
— type/field info only (no inlined sub-types).
2+
— resolves referenced input/output types inline (
```
resolvedType
```
), so one call can replace introspecting the mutation then each input type separately.

Example (CLI):

bash

pipefy introspect mutation createCard --max-depth 2 --json

Example (MCP):

introspect_mutation mutation_name="createCard" max_depth=2 include_parsed=true

Scalars (

ID

String

Int

, …) are never expanded.

MCP工具支持

max_depth

参数（默认值为1）。CLI中使用

--max-depth

。

1
—— 仅返回类型/字段信息（不内联子类型）。
2+
—— 内联解析引用的输入/输出类型（
```
resolvedType
```
），因此一次调用即可替代先内省mutation再分别内省每个输入类型的操作。

示例（CLI）：

bash

pipefy introspect mutation createCard --max-depth 2 --json

示例（MCP）：

introspect_mutation mutation_name="createCard" max_depth=2 include_parsed=true

标量类型（

ID

、

String

、

Int

等）永远不会被展开。

kind

search_schema

search_schema

中的

kind

参数

Optional filter:

OBJECT

INPUT_OBJECT

ENUM

SCALAR

INTERFACE

UNION

search_schema keyword="automation" kind="INPUT_OBJECT"

bash

pipefy introspect schema search automation --kind INPUT_OBJECT --json

可选过滤参数：

OBJECT

、

INPUT_OBJECT

、

ENUM

、

SCALAR

、

INTERFACE

、

UNION

。

search_schema keyword="automation" kind="INPUT_OBJECT"

bash

pipefy introspect schema search automation --kind INPUT_OBJECT --json

When to use introspection

何时使用内省功能

A dedicated tool returned an error and you need to understand why — introspect the input type to check argument names/types.
Before creating fields:
```
introspect_type('CreatePhaseFieldInput')
```
to discover valid
```
type
```
enum values.
Before using
```
extra_input
```
: introspect the corresponding input type to find optional keys.

Unknown mutation signature:

introspect_mutation('createSomething')

before

execute_graphql

Schema exploration:
```
search_schema('automation')
```
to find related types and inputs.

专用工具返回错误，你需要了解原因 —— 内省输入类型以检查参数名称/类型。
创建字段前：调用
```
introspect_type('CreatePhaseFieldInput')
```
探索有效的
```
type
```
枚举值。
使用
```
extra_input
```
前：内省对应的输入类型以查找可选键。

未知mutation签名：在调用

execute_graphql

前先执行

introspect_mutation('createSomething')

。

Schema探索：调用
```
search_schema('automation')
```
查找相关类型和输入。

When to use

execute_graphql

何时使用

execute_graphql

No dedicated MCP tool exists for the operation.
A dedicated tool failed and you've used introspection to understand the correct payload.
Ad-hoc queries like resolving an org UUID via
```
pipe(id: $id) { organization { uuid } }
```
.
Complex nested queries that no single tool covers.

Always prefer dedicated MCP tools — they validate inputs, handle pagination, and format errors consistently.

execute_graphql

is the fallback when dedicated tools can't solve the problem.

该操作不存在专用MCP工具。
专用工具执行失败，且你已通过内省了解正确的请求 payload。
临时查询，例如通过
```
pipe(id: $id) { organization { uuid } }
```
解析组织UUID。
复杂的嵌套查询，没有单个工具可以覆盖。

优先使用专用MCP工具 —— 它们会验证输入、处理分页，并统一格式化错误信息。只有当专用工具无法解决问题时，才使用

execute_graphql

作为备用方案。

Steps — discover a mutation signature

步骤 —— 探索mutation签名

Search for the mutation by keyword:
```
search_schema keyword="label"
```

Get the full mutation signature:

introspect_mutation mutation_name="createLabel"

Discover input type fields:

introspect_type type_name="CreateLabelInput"

Execute the mutation (CLI):
bash
```
pipefy graphql exec --query "mutation …" --vars '{"input":{…}}' --yes --json
```
Mutations: the CLI exits with code 2 unless
```
--yes
```
is passed (guardrail for agents and scripts).

Execute the mutation (MCP):

execute_graphql query="mutation CreateLabel($input: CreateLabelInput!) { createLabel(input: $input) { label { id name } } }" variables='{"input": {"pipe_id": 67890, "name": "Urgent", "color": "#FF0000"}}'

按关键词搜索mutation：
```
search_schema keyword="label"
```

获取完整的mutation签名：

introspect_mutation mutation_name="createLabel"

探索输入类型的字段：

introspect_type type_name="CreateLabelInput"

执行mutation（CLI）：
bash
```
pipefy graphql exec --query "mutation …" --vars '{"input":{…}}' --yes --json
```
注意： 执行mutation时，CLI会返回退出码2，除非添加
```
--yes
```
参数（这是为Agent和脚本设置的防护机制）。

执行mutation（MCP）：

execute_graphql query="mutation CreateLabel($input: CreateLabelInput!) { createLabel(input: $input) { label { id name } } }" variables='{"input": {"pipe_id": 67890, "name": "Urgent", "color": "#FF0000"}}'

Common fallback recipes

常见备用方案示例

Ready-to-use patterns for situations where dedicated tools are insufficient.

以下是专用工具无法满足需求时的即用型方案。

Recipe 1 — Discover valid field types for

create_phase_field

方案1 —— 探索

create_phase_field

的有效字段类型

introspect_type('CreatePhaseFieldInput')

Look for the

type

field; it references an enum. Introspect the enum to get all valid values.

introspect_type('CreatePhaseFieldInput')

找到

type

字段，它引用了一个枚举类型。内省该枚举类型以获取所有有效值。

Recipe 2 — Get full behavior config of an AI agent

方案2 —— 获取AI Agent的完整行为配置

get_ai_agent

returns behavior headers only. To inspect the full config (

event_params

actionParams

actionsAttributes

execute_graphql query='query($uuid: ID!) { aiAgent(uuid: $uuid) { uuid name instruction behaviors { id name active event_id event_params { to_phase_id triggerFieldIds fromPhaseId } action_params { aiBehaviorParams { instruction referencedFieldIds actionsAttributes { name actionType referenceId metadata { destinationPhaseId pipeId fieldsAttributes { fieldId inputMode value } } } } } } } }' variables='{"uuid":"<agent-uuid>"}'

get_ai_agent

仅返回行为头部信息。要查看完整配置（

event_params

、

actionParams

、

actionsAttributes

）：

execute_graphql query='query($uuid: ID!) { aiAgent(uuid: $uuid) { uuid name instruction behaviors { id name active event_id event_params { to_phase_id triggerFieldIds fromPhaseId } action_params { aiBehaviorParams { instruction referencedFieldIds actionsAttributes { name actionType referenceId metadata { destinationPhaseId pipeId fieldsAttributes { fieldId inputMode value } } } } } } } }' variables='{"uuid":"<agent-uuid>"}'

Recipe 3 — Find a card by title (not possible with

find_cards

)

方案3 —— 按标题查找卡片（

find_cards

无法实现）

find_cards

only searches custom field values. To search by title:

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}'

Filter by title client-side. For large pipes, paginate with

after

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

参数进行分页。

Recipe 4 — Discover what

extra_input

accepts for any mutation

方案4 —— 探索任意mutation的

extra_input

支持的参数

When a tool accepts

extra_input

(e.g.

create_automation

update_label

), discover all optional keys:

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

Compare with the tool's primary arguments to know which keys are additive via

extra_input

当某个工具支持

extra_input

时（例如

create_automation

、

update_label

），探索所有可选键：

introspect_mutation('createAutomation')     # 查找输入类型名称
introspect_type('CreateAutomationInput')    # 查看所有inputFields

将结果与工具的主要参数进行对比，即可知道哪些键可通过

extra_input

添加。

Recipe 5 — Discover organization IDs

方案5 —— 探索组织ID

To answer "which organizations do I have access to?" with nothing in hand, call

list_organizations

— it needs no id and returns each org's

id

uuid

name

, and your role. That is the entry point; reach for the GraphQL fallbacks below only when you already have a pipe.

When the user only has a pipe ID and needs its

organization_id

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

如果要回答“我可以访问哪些组织？”且没有任何前置信息，调用

list_organizations

即可 —— 无需ID，它会返回每个组织的

id

、

uuid

、

name

以及你的角色。这是入口点；只有当你已经拥有管道ID时，才需要使用下面的GraphQL备用方案。

当用户仅拥有管道ID，需要获取对应的

organization_id

时：

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

Recipe 6 — Update a select field's options after creation

方案6 —— 创建后更新选择字段的选项

create_phase_field

does not accept options. Create first, then update:

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"]}'

create_phase_field

不支持选项参数。先创建字段，再进行更新：

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"]}'

Recipe 7 — Check phase transition rules

方案7 —— 检查阶段转换规则

When

move_card_to_phase

fails with "not a valid target 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>"}'

Returns the valid destination phases from the current phase.

当

move_card_to_phase

返回错误“not a valid target 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>"}'

返回当前阶段可跳转的有效目标阶段。

Optional schema cache

可选Schema缓存

For long-running agent sessions, the MCP can reuse the fetched GraphQL schema across requests instead of re-introspecting on every call. Enable via the

gql_reuse_fetched_graphql_schema

setting (env or settings file). Off by default. After a breaking Pipefy schema change, the process must be restarted to pick up the new schema. Single-session agents rarely benefit — leave it off unless you measure real improvement.

对于长时间运行的Agent会话，MCP可以在多个请求之间复用已获取的GraphQL Schema，而无需每次调用都重新内省。可通过

gql_reuse_fetched_graphql_schema

设置（环境变量或配置文件）开启该功能，默认关闭。当Pipefy Schema发生破坏性变更后，必须重启进程才能获取新的Schema。单会话Agent很少能从中获益，除非你能衡量到实际性能提升，否则建议保持关闭状态。

Success criteria

成功标准

```
introspect_type
```
returns the complete field list for the input type.
```
execute_graphql
```
returns the expected data without errors.

```
introspect_type
```
返回输入类型的完整字段列表。
```
execute_graphql
```
返回预期数据且无错误。

Failure modes

失败场景

introspect_type
returns
null
— type name is case-sensitive; try PascalCase (e.g.,
```
CreateLabelInput
```
, not
```
create_label_input
```
).
search_schema
returns many hits — case-insensitive substring matching; broad keywords like
```
"card"
```
flood results. Prefer specific names like
```
"AiAgent"
```
,
```
"FieldCondition"
```
.
introspect_mutation
is expensive — fetches all root mutation fields and filters client-side (single large query). Prefer
```
introspect_type
```
on the specific input type when you already know the mutation name.
execute_graphql
returns GraphQL errors — check
```
path
```
and
```
message
```
; pass
```
debug=true
```
on the next call to surface the
```
correlation_id
```
.
Endpoint confusion — introspection uses
```
app.pipefy.com/graphql
```
; real operations use
```
api.pipefy.com/graphql
```
. The MCP server handles this automatically; raw-API users must distinguish (see api-fallback).

introspect_type
返回
null
—— 类型名称区分大小写；尝试使用帕斯卡命名法（例如
```
CreateLabelInput
```
，而非
```
create_label_input
```
）。
search_schema
返回大量结果 —— 采用不区分大小写的子串匹配；像
```
"card"
```
这样宽泛的关键词会导致结果泛滥。建议使用更具体的名称，例如
```
"AiAgent"
```
、
```
"FieldCondition"
```
。
introspect_mutation
性能开销大 —— 会获取所有根mutation字段并在客户端过滤（单次大型查询）。如果已经知道mutation名称，优先使用
```
introspect_type
```
查询对应的输入类型。
execute_graphql
返回GraphQL错误 —— 检查
```
path
```
和
```
message
```
；下次调用时添加
```
debug=true
```
参数以显示
```
correlation_id
```
。
端点混淆 —— 内省使用
```
app.pipefy.com/graphql
```
；实际操作使用
```
api.pipefy.com/graphql
```
。MCP服务器会自动处理这一差异；直接调用API的用户必须区分两者（详见api-fallback）。

另请参阅

docs/mcp/tools/introspection.md — MCP parameters, query/mutation mismatch hints on
```
execute_graphql
```
.
skills/api-troubleshoot/pipefy-api-fallback/SKILL.md — Tier 3: direct HTTP fallback when MCP is unavailable.
skills/pipes-and-cards/pipefy-pipes-and-cards/SKILL.md — most common dedicated tools (prefer over
```
execute_graphql
```
).

docs/mcp/tools/introspection.md —— MCP参数说明、
```
execute_graphql
```
的查询/mutation不匹配提示。
skills/api-troubleshoot/pipefy-api-fallback/SKILL.md —— Tier 3：当MCP不可用时的直接HTTP备用方案。
skills/pipes-and-cards/pipefy-pipes-and-cards/SKILL.md —— 最常用的专用工具（优先于
```
execute_graphql
```
使用）。

pipefy-introspection

Original

Translation

Introspection & Raw GraphQL

内省与原始GraphQL

Tools

工具

The include_parsed flag

include_parsed 标志

max_depth (introspect_type / query / mutation)

max_depth（适用于introspect_type / query / mutation）

kind on search_schema

search_schema中的kind参数

When to use introspection

何时使用内省功能

When to use execute_graphql

何时使用execute_graphql

Steps — discover a mutation signature

步骤 —— 探索mutation签名

Common fallback recipes

常见备用方案示例

Recipe 1 — Discover valid field types for create_phase_field

方案1 —— 探索create_phase_field的有效字段类型

Recipe 2 — Get full behavior config of an AI agent

方案2 —— 获取AI Agent的完整行为配置

Recipe 3 — Find a card by title (not possible with find_cards)

方案3 —— 按标题查找卡片（find_cards无法实现）

Recipe 4 — Discover what extra_input accepts for any mutation

方案4 —— 探索任意mutation的extra_input支持的参数

Recipe 5 — Discover organization IDs

方案5 —— 探索组织ID

Recipe 6 — Update a select field's options after creation

方案6 —— 创建后更新选择字段的选项

Recipe 7 — Check phase transition rules

方案7 —— 检查阶段转换规则

Optional schema cache

可选Schema缓存

Success criteria

成功标准

Failure modes

失败场景

See also

另请参阅

The
`include_parsed`
flag

`include_parsed`
标志

`max_depth`
(introspect_type / query / mutation)

`max_depth`
（适用于introspect_type / query / mutation）

`kind`
on
`search_schema`

`search_schema`
中的
`kind`
参数

When to use
`execute_graphql`

何时使用
`execute_graphql`

Recipe 1 — Discover valid field types for
`create_phase_field`

方案1 —— 探索
`create_phase_field`
的有效字段类型

Recipe 3 — Find a card by title (not possible with
`find_cards`
)

方案3 —— 按标题查找卡片（
`find_cards`
无法实现）

Recipe 4 — Discover what
`extra_input`
accepts for any mutation

方案4 —— 探索任意mutation的
`extra_input`
支持的参数