# MCP 工具参考

每个 MCP 工具对应一项组织范围能力。工具默认为拒绝：API key 必须包含匹配的 [MCP scope](/zh/api/mcp/#mcp-scopes)，且调用者必须满足最低组织角色。

## Templates

**Scope：** `mcp:templates:read` · **Min role：** viewer

| Tool | Description |
| --- | --- |
| `list_templates` | 列出已批准的游戏模板及其素材模式（`name`、尺寸、`transparent`、`promptWrapper`）与 `baseGameConfig` |
| `get_template` | 按 id 获取一个模板，包括控件与 config 接线提示 |

`list_templates` 上的可选输入：`category`（不区分大小写的子字符串筛选）。

## Games & Prizes

**Read scope：** `mcp:games:read` · **Write scope：** `mcp:games:write` · **Min role：** viewer（读） / editor（写）

| Tool | Scope | Description |
| --- | --- | --- |
| `list_games` | read | 列出组织游戏；可选 `status` 筛选（`draft`、`published`、`archived`） |
| `get_game` | read | 获取带完整扁平 `config` 与有效奖品的游戏 |
| `list_game_prizes` | read | 列出游戏的有效奖品 |
| `create_game` | write | 从模板创建草稿游戏；扁平 `config` + 可选奖品 |
| `update_game` | write | 更新字段；`config` 为浅合并 |
| `set_game_status` | write | 将状态设为 `draft`、`published` 或 `archived` |
| `set_game_prizes` | write | 同步奖品表（省略 `id` 以创建；缺失的奖品被删除；空数组清除全部） |

每个 `min_score` 档位的奖品概率百分比合计必须**恰好为 100%**。

## Streams

**Read scope：** `mcp:streams:read` · **Write scope：** `mcp:streams:write` · **Min role：** viewer（读） / editor（写）

| Tool | Scope | Description |
| --- | --- | --- |
| `list_streams` | read | 列出组织的 streams |
| `get_stream` | read | 获取 stream；可选 `include_games` / `include_connections` |
| `create_stream` | write | 创建活动旅程（stream） |
| `update_stream` | write | 更新 stream 字段 |

## Connections

**Read scope：** `mcp:connections:read` · **Write scope：** `mcp:connections:write` · **Min role：** admin

| Tool | Scope | Description |
| --- | --- | --- |
| `list_connections` | read | 列出组织集成（Braze、Zapier、webhooks 等）；无原始凭据 |
| `get_connection` | read | 连接详情，仅含 `has_credentials` / `credential_keys` |
| `create_connection` | write | 创建集成（例如 Braze `{ api_key, rest_endpoint }`、Zapier `{ webhook_url }`） |
| `update_connection` | write | 在支持处更新名称、描述或凭据 |
| `delete_connection` | write | 删除组织连接 |
| `list_stream_connections` | read | 列出链接到 stream 的集成 |
| `link_stream_connection` | write | 将连接附加到 stream |
| `update_stream_connection` | write | 更新 stream–connection 链接 |
| `unlink_stream_connection` | write | 移除 stream–connection 链接 |

:::note
MCP 不支持 `voucher_webhook`。读取响应中从不返回提供方密钥。
:::

## Analytics Providers

**Read scope：** `mcp:analytics_providers:read` · **Write scope：** `mcp:analytics_providers:write` · **Min role：** admin

| Tool | Scope | Description |
| --- | --- | --- |
| `list_analytics_providers` | read | 列出组织分析提供商配置（仅公开 ID） |
| `get_analytics_provider` | read | 获取单个组织分析提供商 |
| `create_analytics_provider` | write | 创建可复用提供商（`google_analytics`、`mixpanel`、`posthog`、`amplitude`、`google_tag_manager`、`meta_pixel`） |
| `update_analytics_provider` | write | 更新名称、config 或 `is_active` |
| `delete_analytics_provider` | write | 删除提供商（级联删除 stream 链接） |
| `list_stream_analytics_providers` | read | 列出链接到 stream 的提供商 |
| `link_stream_analytics_provider` | write | 将组织提供商附加到 stream |
| `update_stream_analytics_provider` | write | 更新 stream 链接（`is_active`、`config_override`） |
| `unlink_stream_analytics_provider` | write | 移除 stream 链接（组织提供商保留） |

配置仅接受**公开**测量 ID / 项目令牌 — 切勿使用密钥 API key。见[分析提供商](/zh/connections/analytics-providers/)。

## Gallery

**Read scope：** `mcp:gallery:read` · **Write scope：** `mcp:gallery:write` · **Min role：** editor

| Tool | Scope | Description |
| --- | --- | --- |
| `list_gallery_media` | read | 分页的组织图库媒体与存储用量；可选 `source` 筛选（`upload`、`generated`） |
| `delete_gallery_media` | write | 按 id 删除图库项；若仍用作缩略图、徽标、游戏素材或奖品图片则返回 `409` 失败 |

删除前先列出媒体并检查存储用量。面板工作流见 [Gallery](/zh/gallery/overview/)。

## Vouchers

**Read scope：** `mcp:vouchers:read` · **Write scope：** `mcp:vouchers:write` · **Min role：** viewer（读） / editor（写）

| Tool | Scope | Description |
| --- | --- | --- |
| `list_voucher_sets` | read | 列出带代码统计与关联游戏的兑换码集 |
| `get_voucher_set` | read | 获取一个集合；可选 `include_vouchers` 获取单个代码 |
| `create_voucher_set` | write | 创建空兑换码集 |
| `add_vouchers_to_set` | write | 批量添加代码（转大写；跳过重复；每次调用最多 5,000） |
| `update_org_voucher_status` | write | 将代码设为 `available` 或 `claimed` |
| `delete_org_voucher` | write | 删除单个 **available** 代码（已领取/已使用代码不可删除） |
| `delete_voucher_set` | write | 删除集合并级联删除其代码 |

创建集合并导入代码后，使用 `set_game_prizes` 以 `prize_type: voucher_set` 与 `voucher_set_id` 将其链接到奖品。见[兑换码系统](/zh/rewards/vouchers/)。

## Reports

**Scope：** `mcp:reports:read` · **Min role：** analyst

| Tool | Description |
| --- | --- |
| `get_org_analytics_summary` | 轻量面板汇总（每日游玩、总计、顶尖游戏）；最多 **90** 天 |
| `get_org_report` | 详细报告 JSON（与无 CSV 的 Reports API 形状相同）；最多 **365** 天；表格报告最多返回 100 行 |

`get_org_report` 接受 `report`、`start_date`、`end_date`（`YYYY-MM-DD`），以及可选的 `game_id` / `stream_id`。报告类型：`overview`、`games`、`streams`、`prizes`、`sessions`、`highscores`、`streamScoreboard`、`ctaLeads`。

:::caution[CTA 线索中的 PII]
`ctaLeads` 报告包含玩家姓名、邮箱、电话与自定义字段。请优先使用最小权限范围，并相应对待 API key 访问。
:::

## AI

**Scope：** `mcp:ai` · **Min role：** editor

| Tool | Description |
| --- | --- |
| `extract_brand` | 从网站 URL 提取品牌标识（颜色、字体、语气、徽标线索） |
| `generate_funnel` | 从品牌 URL 或简报建议漏斗阶段 / stream 结构 |
| `generate_image` | 用 Gemini 生成**单个**游戏素材；可选透明 PNG；存入组织图库 |
| `generate_images` | 并行生成**最多 8** 个素材；多素材模板优先使用此工具 |

对于美术生成，从模板素材模式传递 `width`、`height`、`transparent` 与 `prompt_wrapper`。对于 `generate_images`，将每项的 `asset_key` 设为模板 `asset.name`，然后用这些扁平键通过 `update_game` 将返回的 URL 写入 `game.config`。当模板有超过 8 个提示图片素材时，先用占位符创建游戏，再分批生成。

## Sessions

**Scope：** `mcp:sessions:write` · **Min role：** editor

| Tool | Description |
| --- | --- |
| `create_play_session` | 为 `game_id` 或 `stream_id` 生成一次性游玩会话令牌（与 REST create-session API 相同） |

可选输入：`external_ref`、`metadata`、`expires_in_minutes`（最多 7 天）。

玩家 URL 模式与生命周期见 [Session Tokens](/zh/api/session-tokens/)。

## 角色要求摘要

| Min role | Tools |
| --- | --- |
| **viewer** | 模板、游戏/stream 与兑换码读取工具 |
| **analyst** | 报告工具 |
| **editor** | 游戏/stream 写入、图库、兑换码写入、AI、会话生成 |
| **admin** | 所有连接与分析提供商工具 |

API keys 在通过 MCP 使用时继承组织的成员模型进行角色检查。密钥上的资源白名单仍然适用。

这些相同能力为应用内 [Assistant](/zh/assistant/overview/) 提供支持（以您已登录用户身份认证，而非 API key）。