> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudx.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 工具参考

> 每个公共 CloudX MCP 工具的参考，包括参数、支持的过滤器与响应字段。

# 工具参考

CloudX MCP 当前公开 17 个工具：七个报表工具、四个竞价检查工具、五个配置工具与一个文档检索工具。已认证用户始终只能访问自己的 CloudX 账户。

## 工具汇总

| 工具                   | 用途            | 额外过滤器                                                         | 主要响应字段                                            |
| -------------------- | ------------- | ------------------------------------------------------------- | ------------------------------------------------- |
| `GetReportDashboard` | 汇总 KPI 与图表数据  | `test_mode`、`country`、`device_os`                             | `summary`、`chart_data`                            |
| `GetReportBreakdown` | 自定义分组报表行      | `by`、`metrics`、排名与指标过滤                                        | `dimensions`、`metrics`、`rows`、`row_count`         |
| `GetReportBidders`   | 竞价方级表现        | `test_mode`、`country`、`device_os`                             | `bidders`                                         |
| `GetReportApps`      | 应用级表现         | `test_mode`、`country`、`device_os`                             | `apps`                                            |
| `GetReportAdUnits`   | 广告单元级表现       | `test_mode`、`country`、`device_os`、`app_bundle`、`ad_unit_type` | `ad_units`                                        |
| `GetReportExport`    | JSON 形态的原始导出行 | `country`、`device_os`                                         | `columns`、`rows`、`row_count`                      |
| `GetReportABTest`    | 对照与测试变体表现     | `ab_test_id`                                                  | `control`、`test`、统计字段                             |
| `GetAuctionList`     | 按过滤条件列出近期竞价   | 应用、广告单元、流量、ILRD 与聚合平台过滤                                       | `auctions`                                        |
| `GetAuctionShow`     | 单次竞价及可选关联详情   | `with`                                                        | `auctions`、`rounds`、`bids`、`ilrd`、`external_ilrd` |
| `GetAuctionRounds`   | 竞价轮次或轮次聚合指标   | `auction_id`、`metric`、流量过滤                                    | `rounds`、`metrics`                                |
| `GetAuctionBids`     | 出价与未出价记录      | 流量过滤、`floor_source`                                           | `bids`                                            |
| `GetConfigShow`      | 线上、已发布或草稿配置   | `id`、`version`、`draft`                                        | 配置元数据、`data`、`yaml`                               |
| `GetConfigValidate`  | 服务端配置验证       | `id`、`version`                                                | `valid`、`issues`、计数、`source`                      |
| `GetConfigHistory`   | 近期配置历史        | `since`、`author`、`include_drafts`、`limit`                     | `entries`                                         |
| `PostConfigEdit`     | 类型化库存配置编辑     | `body.config_id`、`body.operations`、`body.summary`             | 草稿或已发布配置结果                                        |
| `PostConfigPublish`  | 验证并发布草稿       | `body.draft_id`、`body.version_label`                          | `config_id`、`version_number`、`validation`         |
| `SearchDocs`         | CloudX 文档检索   | 无                                                             | `results`                                         |

<Info>
  只读工具需要对应的 `reports:read`、`auctions:read` 或 `configuration:read` 权限。`PostConfigEdit` 与 `PostConfigPublish` 需要 `configuration:write`。
</Info>

## 报表工具参数

| 参数             | 必填 | 适用工具                                             | 说明                                                   |
| -------------- | -- | ------------------------------------------------ | ---------------------------------------------------- |
| `start_time`   | 是  | 报表工具                                             | UTC 的 Unix 秒时间戳                                      |
| `end_time`     | 是  | 报表工具                                             | UTC 的 Unix 秒时间戳                                      |
| `country`      | 否  | Dashboard、Breakdown、Bidders、Apps、Ad Units、Export | ISO-2 国家代码                                           |
| `device_os`    | 否  | Dashboard、Breakdown、Bidders、Apps、Ad Units、Export | `iOS` 或 `Android`                                    |
| `test_mode`    | 否  | Dashboard、Breakdown、Bidders、Apps、Ad Units        | `production`、`test` 或 `all`                          |
| `app_bundle`   | 否  | 仅 Ad Units                                       | Bundle ID，例如 `com.example.game`                      |
| `ad_unit_type` | 否  | 仅 Ad Units                                       | `BANNER`、`INTERSTITIAL`、`REWARDED`、`MREC` 或 `NATIVE` |

## `GetReportDashboard`

用于跨时间范围的总体报表。

### 适用场景

* 总收入与填充率检查
* 每日趋势分析
* 按国家或平台快速健康检查

### 参数

| 参数           | 类型      | 必填 |
| ------------ | ------- | -- |
| `start_time` | integer | 是  |
| `end_time`   | integer | 是  |
| `country`    | string  | 否  |
| `device_os`  | string  | 否  |
| `test_mode`  | string  | 否  |

### 响应结构

* `summary`
* `chart_data`

`summary` 包含 `total_requests`、`total_impressions`、`revenue`、`fill_rate`、`ecpm`、`total_clicks`、`ctr`、`total_users` 等字段。

## `GetReportBreakdown`

用于自行选择报表的分组维度与指标，而不是使用固定的 Dashboard 结构。

### 参数

| 参数            | 类型      | 必填 | 说明                                                                       |
| ------------- | ------- | -- | ------------------------------------------------------------------------ |
| `start_time`  | integer | 是  | Unix 秒；时间范围不得超过 31 天                                                     |
| `end_time`    | integer | 是  | Unix 秒；时间范围不得超过 31 天                                                     |
| `by`          | string  | 是  | 逗号分隔：`hour`、`day`、`week`、`month`、`country`、`os`、`app`、`ad_unit`、`format` |
| `metrics`     | string  | 是  | 逗号分隔的指标名                                                                 |
| `country`     | string  | 否  | ISO-2 国家代码                                                               |
| `device_os`   | string  | 否  | `iOS` 或 `Android`                                                        |
| `test_mode`   | string  | 否  | 默认为 `production`                                                         |
| `granularity` | string  | 否  | `daily` 或 `hourly`；默认为 `daily`                                           |
| `top`         | integer | 否  | 按第一个指标返回前 1–1000 行                                                       |
| `bottom`      | integer | 否  | 按第一个指标返回后 1–1000 行                                                       |
| `having`      | string  | 否  | 指标表达式，例如 `revenue > 10`                                                  |

### 响应结构

* `dimensions`：请求的维度名
* `metrics`：请求的指标名
* `rows`：包含 `dimensions` 与 `metrics` map 的对象
* `row_count`

## `GetReportBidders`

用于对比需求合作伙伴。

### 适用场景

* 找出收入最高的竞价方
* 按合作伙伴检查竞价率与胜出率
* 跨国家或平台比较供给质量

### 参数

| 参数           | 类型      | 必填 |
| ------------ | ------- | -- |
| `start_time` | integer | 是  |
| `end_time`   | integer | 是  |
| `country`    | string  | 否  |
| `device_os`  | string  | 否  |
| `test_mode`  | string  | 否  |

### 响应结构

* `bidders`

每个竞价方行可包含 `name`、`requests`、`bids`、`bid_rate`、`impressions`、`win_rate`、`revenue` 与 `ecpm`。

## `GetReportApps`

用于在账户内比较应用级表现。

### 适用场景

* 按收入对应用排序
* 比较 iOS 与 Android 投放组合表现
* 发现填充率较低的应用

### 参数

| 参数           | 类型      | 必填 |
| ------------ | ------- | -- |
| `start_time` | integer | 是  |
| `end_time`   | integer | 是  |
| `country`    | string  | 否  |
| `device_os`  | string  | 否  |
| `test_mode`  | string  | 否  |

### 响应结构

* `apps`

每个应用行可包含 `app_id`、`name`、`platform`、`impressions`、`fill_rate`、`revenue` 与 `ecpm`。

## `GetReportAdUnits`

用于广告位级别的深入分析。

### 适用场景

* 比较 banner、激励视频与插屏广告
* 限定到单个应用 bundle
* 找出表现较弱或价值较高的广告位

### 参数

| 参数             | 类型      | 必填 |
| -------------- | ------- | -- |
| `start_time`   | integer | 是  |
| `end_time`     | integer | 是  |
| `country`      | string  | 否  |
| `device_os`    | string  | 否  |
| `test_mode`    | string  | 否  |
| `app_bundle`   | string  | 否  |
| `ad_unit_type` | string  | 否  |

### 响应结构

* `ad_units`

每行可包含 `ad_unit_id`、`name`、`app_name`、`app_bundle`、`type`、`impressions`、`fill_rate`、`revenue` 与 `ecpm`。

## `GetReportExport`

需要表格化数据而非汇总报表时使用此工具。

### 适用场景

* 将数据传入电子表格
* 校验下游分析
* 将结构化行交给其他工具或代理

### 参数

| 参数           | 类型      | 必填 |
| ------------ | ------- | -- |
| `start_time` | integer | 是  |
| `end_time`   | integer | 是  |
| `country`    | string  | 否  |
| `device_os`  | string  | 否  |

### 响应结构

* `columns`
* `rows`
* `row_count`

## `GetReportABTest`

用于在指定时间范围内比较 A/B 测试的对照变体与测试变体。

| 参数           | 类型      | 必填 |
| ------------ | ------- | -- |
| `ab_test_id` | string  | 是  |
| `start_time` | integer | 是  |
| `end_time`   | integer | 是  |

时间范围不得超过 31 天。响应包含带累计指标与每日行的 `control` 和 `test`，以及可用时的 `lift`、`p_value`、`chi_squared_p`、置信区间、样本量和 `status`。

## 竞价检查工具

基于时间范围的竞价工具使用 Unix 秒时间戳，最大范围为 31 天。常用可选过滤器包括 `test_mode`、`app_bundle`、`ad_unit_id`、`country` 与 `device_os`。行数上限默认为 50，可设为 1–500。

### `GetAuctionList`

用于在深入查看单次竞价前查找近期竞价。

| 参数                  | 类型      | 必填 | 说明                               |
| ------------------- | ------- | -- | -------------------------------- |
| `start_time`        | integer | 是  | Unix 秒                           |
| `end_time`          | integer | 是  | Unix 秒                           |
| `test_mode`         | string  | 否  | `production`、`test` 或 `all`      |
| `app_bundle`        | string  | 否  | 应用 bundle 标识符                    |
| `ad_unit_id`        | string  | 否  | 广告单元 ID                          |
| `country`           | string  | 否  | ISO-2 国家代码                       |
| `device_os`         | string  | 否  | `iOS` 或 `Android`                |
| `has_ilrd`          | boolean | 否  | 仅包含有 CloudX 展示级收入数据的竞价           |
| `has_external_ilrd` | boolean | 否  | 仅包含有外部展示级收入数据的竞价                 |
| `mediator`          | string  | 否  | `applovin`、`admob` 或 `levelplay` |
| `limit`             | integer | 否  | 1–500；默认 50                      |

`has_ilrd` 与 `has_external_ilrd` 不能同时使用。`mediator` 只能与 `has_external_ilrd: true` 一起使用。

`auctions` 响应数组包含 ID、时间戳、应用与广告单元上下文、获胜详情、出价计数、耗时、A/B 测试上下文与 ILRD 可用性。

### `GetAuctionShow`

在已知竞价 ID 时使用。`auction_id` 必填；可选的 `with` 使用逗号分隔的 `rounds`、`bids`、`ilrd`、`external-ilrd`。响应中包含 `auction_id`、`auctions` 以及请求的关联数据。

### `GetAuctionRounds`

使用 `auction_id` 检查单次竞价的轮次，或使用 `start_time` 与 `end_time` 聚合分析轮次。可选的 `metric` 为 `distribution`、`duration`、`cleared-on` 或 `skip-reason`，还支持常用流量过滤器与 `limit`。响应包含 `rounds`、`metrics` 或两者。

### `GetAuctionBids`

用于检查指定时间范围内的出价与未出价行。`start_time` 与 `end_time` 必填，另支持常用流量过滤器、`limit` 以及 `floor_source`（`static`、`dynamic`、`publisher` 或 `configured`）。`bids` 数组包含竞价方、状态、价格、获胜、延迟、底价、拒绝原因与竞价上下文。

## 配置工具

<Warning>
  `PostConfigEdit` 与 `PostConfigPublish` 会更改账户配置。发布前请检查返回的草稿与验证结果。
</Warning>

### `GetConfigShow`

不传参数时获取线上配置，也可使用 `id`、`version` 或 `draft` 选择草稿或已发布版本。响应包含 `id`、`kind`、版本与作者元数据、已解析的 `data` 与 `yaml`。

### `GetConfigValidate`

不传参数时验证线上配置，也可使用 `id` 或 `version` 选择配置。响应包含 `valid`、`error_count`、`warning_count`、`issues`、`source` 与 `yaml`。

### `GetConfigHistory`

按时间倒序列出近期配置行，最多 200 条，不代表账户的完整历史。可选参数为 `since`（RFC3339 或 `YYYY-MM-DD`）、`author`、`include_drafts` 与 `limit`（1–200，默认 50）。`entries` 包含配置 ID、类型、版本、作者、创建时间、描述与发布时 diff 计数。

### `PostConfigEdit`

对应用、广告单元、广告单元组、账户竞价方、网络映射、列表、标签、测试设备、线项目或 A/B 测试应用类型化变更。

| 参数                | 类型     | 必填   | 说明                           |
| ----------------- | ------ | ---- | ---------------------------- |
| `body.config_id`  | string | 否    | 默认使用线上配置；草稿就地编辑，已发布配置会复制为新草稿 |
| `body.operations` | array  | 是    | 每个对象必须且只能包含一个受支持的操作          |
| `body.summary`    | string | 条件必填 | 普通草稿编辑必填；A/B 测试操作可选          |

支持的操作包括：

* 应用：`create_app`、`update_app`、`delete_app`
* 广告单元：`create_ad_unit`、`update_ad_unit`、`delete_ad_unit`
* 网络与竞价方：`upsert_network_mapping`、`delete_network_mapping`、`upsert_account_bidder`
* 广告单元组：`create_ad_unit_group`、`update_ad_unit_group`、`delete_ad_unit_group`、`remove_ad_unit_from_group`
* 列表与标签：`create_list`、`update_list`、`delete_list`、`create_tag`、`update_tag`、`delete_tag`
* 测试设备：`upsert_test_device`、`delete_test_device`
* A/B 测试：`create_ab_test`、`update_ab_test`、`start_ab_test`、`end_ab_test`、`promote_ab_test`、`delete_ab_test`
* 线项目：`create_line_item`、`update_line_item`、`delete_line_item`

普通编辑与 `create_ab_test` 返回草稿。A/B 测试的更新、启动、结束、提升与删除操作会立即发布，且在请求中必须是唯一操作。广告单元与线项目的 `bidfloor` 使用美元 CPM 小数。

### `PostConfigPublish`

将草稿发布为线上配置。`body.draft_id` 必填，`body.version_label` 可选。草稿上线前会执行与 CloudX 应用相同的服务端验证。响应包含 `config_id`、`version_number` 与 `validation`；阻断性验证失败会返回 MCP 错误，且不会发布。

## `SearchDocs`

在 MCP 客户端中检索 CloudX 文档，在回答关于安装、配置、SDK、CLI、Dashboard、网络或报表的问题前使用。

### 适用场景

* 为某个 CloudX 工作流找到对应的文档页
* 在解释功能前以最新文档作为依据
* 不离开 AI 客户端即可获取相关的安装或排错片段

### 参数

| 参数           | 类型     | 必填 | 说明       |
| ------------ | ------ | -- | -------- |
| `body.query` | string | 是  | 自然语言检索查询 |

### 工具调用结构

```json theme={null}
{
  "name": "SearchDocs",
  "arguments": {
    "body": {
      "query": "report filters"
    }
  }
}
```

### 响应结构

* `results`

每条结果包含：

* `content`：匹配到的文档片段
* `path`：文档路径，例如 `/en/cli/reporting`
* `url`：绝对文档 URL
* `metadata`：页面元数据（标题等，若可用）

## 错误行为

无法满足请求时，这些工具会返回 MCP 错误结果。常见原因：

* 缺少 `start_time` 或 `end_time`
* 枚举值无效，例如 `device_os: "ios"` 而非 `iOS`
* 时间范围超过 31 天
* 竞价或配置 ID 不存在
* 没有请求工具所需的权限
* 配置编辑或发布验证失败

对于 `SearchDocs`，空白或缺失的查询会返回 `query is required`。文档检索暂时不可用时，工具会返回 docs search error。

## 相关链接

* [安装](/zh/mcp/installation)
* [示例](/zh/mcp/examples)