# AppGrowing MCP 安装说明

通过 MCP（Model Context Protocol）over HTTP 将 AppGrowing Global 广告情报接入你的 Agent。本页涵盖连接信息、21 个工具速览、关键调用参数与常见问题（FAQ, Frequently Asked Questions）。

## 1. 连接信息

通过 MCP over HTTP 接入 AppGrowing Global 广告情报服务。以下为连接所需的核心参数、API Key 的获取方式，以及一份可直接交给 Agent 的配置示例。

| 项目 | 值 |
| --- | --- |
| 端点 URL | `https://api-appgrowing-global.youcloud.com/mcp` |
| 协议 | MCP over HTTP（Streamable HTTP），JSON-RPC 2.0 |
| 认证 | `Authorization: Bearer <API_KEY>` |
| API Key | 由 AppGrowing 服务方提供，接入时替换 `<API_KEY>` [点击获取 API Key](https://appgrowing-global.youcloud.com/dashboard?finance=/team/info) |
| 请求头 | `Content-Type: application/json` + `Accept: application/json, text/event-stream` + `accept-language: zh` |
| 响应格式 | SSE（逐行返回，`data:` 前缀后是 JSON） |

### 1.1 API Key 获取方式

API Key 以 `sk_` 开头，在 AppGrowing Global 的「个人中心 → 企业信息」中复制。

[获取 API Key](https://appgrowing-global.youcloud.com/dashboard?finance=/team/info)

![AppGrowing Global 控制台：点击右上角头像进入个人中心，在左侧选择企业信息，复制 API Key](https://docs.appgrowing.net/mcp/installation/assets/api-key-zh.png)

### 1.2 配置示例

**方式一：手动写入配置**

标准 MCP 客户端配置（`mcpServers`）：

```json
{
  "mcpServers": {
    "AppGrowing-Global-MCP": {
      "url": "https://api-appgrowing-global.youcloud.com/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>",
        "accept-language": "zh"
      }
    }
  }
}
```

**方式二：交给 Agent 安装**

把下面这段话整段发给你的 Agent（先将 `<API_KEY>` 替换为你的 API Key），由它写入对应客户端的配置文件并完成安装：

```text
安装这个 MCP：
{
  "mcpServers": {
    "AppGrowing-Global-MCP": {
      "url": "https://api-appgrowing-global.youcloud.com/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>",
        "accept-language": "zh"
      }
    }
  }
}
```

> 🔒 API Key 是登录凭证，不要提交到 git；写进脚本或配置文件前，确认该文件已被 .gitignore 覆盖。

## 2. 21 个工具速览

MCP 现已开放 21 个工具，按用途分为四个模块：素材检索与创意卖点（4 个）、榜单情报（3 个）、App 投放分析（11 个）、发行商与开发者情报（2 个），外加基础工具（1 个）。

### 2.1 素材检索与创意卖点（4 个）

| 工具 | 用途 | 单次调用分析点数 |
| --- | --- | --- |
| `searchAdCreatives` | 素材搜索：按媒体、地区、卖点、受众、变现方式等多维度筛选广告素材。 | 10,000 |
| `creativeSellingPointTrends` | 创意卖点趋势：基于 30 万+ 动态创意卖点词库，可按素材数、广告数或热度排序，洞察各品类当前主打的卖点方向。 | 10,000 |
| `creativeAIAnalysisData` | 创意 AI 解读：拉取素材的旁白、创意卖点与 AI 解读，单次最多 100 条。 | 50,000 |
| `creativeResourceUrl` | 素材资源链接：获取素材原片与封面的下载直链（链接带时效期），用于拿到原始图片或视频文件。 | 10,000 |

### 2.2 榜单情报（3 个）

| 工具 | 用途 | 单次调用分析点数 |
| --- | --- | --- |
| `appAdRankings` | App 投放排行榜：按品牌维度排名，含在投广告数、素材数、受众画像及发行商/开发者信息。 | 10,000 |
| `appStoreDownloadRankings` | iOS App Store 下载榜：查看各品类在 App Store 的下载排名。 | 10,000 |
| `googlePlayDownloadRankings` | Google Play 下载榜：查看 Android 端各品类的下载排名。 | 10,000 |

### 2.3 App 投放分析（11 个）

| 工具 | 用途 | 单次调用分析点数 |
| --- | --- | --- |
| `adVolumeTrends` | 投放量级趋势：提供广告数与素材数随时间的趋势。 | 10,000 |
| `regionOverview` | 地区投放概览：各国家/地区的投放量级与占比。 | 10,000 |
| `regionTimeline` | 地区投放时间线：各地区投放量级随时间的变化。 | 10,000 |
| `mediaOverview` | 媒体投放概览：各媒体的投放量级与占比。 | 10,000 |
| `mediaTimeline` | 媒体投放时间线：各媒体投放量级随时间的变化。 | 10,000 |
| `adFormatOverview` | 广告形式概览：试玩、激励视频、信息流等广告形式的分布。 | 10,000 |
| `creativeTypeOverview` | 素材类型概览：图片、视频、竖版视频等素材类型的分布。 | 10,000 |
| `creativeFormatRatio` | 素材比例概览：横版/竖版与不同尺寸比例的分布。 | 10,000 |
| `audienceBreakdown` | 受众分布：广告受众的年龄 × 性别分布。 | 10,000 |
| `appLifecycle` | 产品生命周期：产品生命周期、版本节点与节日节点的时间线。 | 10,000 |
| `similarApps` | 相似应用推荐：按相似度或累计下载量排序推荐相似/相关产品。 | 10,000 |

### 2.4 发行商与开发者情报（2 个）

| 工具 | 用途 | 单次调用分析点数 |
| --- | --- | --- |
| `developerAppOverview` | 开发者产品列表：列出某开发者旗下的产品。 | 10,000 |
| `publisherAppOverview` | 发行商产品总览：汇总发行商旗下产品的在投广告数、素材数、在投时长、版本数与覆盖地区数。 | 10,000 |

### 2.5 基础工具（1 个）

| 工具 | 用途 | 单次调用分析点数 |
| --- | --- | --- |
| `filterOptions` | 筛选选项：返回全部可选筛选值（媒体、地区、类别、风格、卖点分类等）。 | 10,000 |

> 点数按每次调用计，与返回条数、翻页无关。

## 3. 关键调用参数

`searchAdCreatives` 是最常用的素材检索工具，以下为其关键入参与返回字段。

### 3.1 必填

- `purpose`：1=游戏 / 2=应用 / 3=网站
- `order`：排序（`impression_inc_2y_desc` 按曝光降序 / `max_dt_desc` 按最近投放）

### 3.2 常用筛选

| 参数 | 类型 | 示例 |
| --- | --- | --- |
| `startDate` / `endDate` | string | `2026-07-10` ~ `2026-08-10` |
| `category` | int 数组 | `[2001]` 角色扮演 / `[2009]` 卡牌 |
| `appStyle` | int 数组 | `[20304]` 卡牌-战斗 / `[21204]` 二次元 |
| `area` | string 数组 | `["JP"]` 日本 / `["US"]` 美国 |
| `media` | int 数组 | `[13]` TikTok / `[2]` Facebook |
| `keyword` + `accurateSearch` | string / int | keyword 传关键词，`accurateSearch=1` 精准匹配 |
| `searchDsl` | array | `[{"key":"campaign_name","type":"contain","value":"应用名"}]` 字段级检索（key 可选 campaign_name/slogan/asr/developer_name 等，type 可选 contain/exclude/equal/notEqual） |
| `language` | string 数组 | `["ja"]` 日语 |
| `videoTime` | int | 视频时长筛选 |

### 3.3 返回字段要点

- 素材在 `data.materialList` 的 `data` 数组里，每条核心在 `material` 字段
- `material.campaign[0].name` = 游戏名
- `material.creative.slogan` = 广告文案
- `material.creative.type` = 素材类型（102图片 / 201横版视频 / 202纵向视频 / 203全屏视频）
- `material.creative.resource[0].path` = **素材直链**（带 auth_key，可直接下载）；同节点还有 poster/width/height/duration
- `material.creative.resource[0].id` = 资源 ID（传给 creativeResourceUrl / creativeAIAnalysisData）
- `material.format` = 广告形式列表（对象数组，每项含 id 与 name，如 `[{"id":301,"name":"视频贴片"},{"id":302,"name":"激励广告"}]`，表示同时投视频贴片+激励广告）。一条素材可挂多个形式；调用 `creativeAIAnalysisData` 时取任意一个（建议第一个）的 id 与 ids 按位对应即可
- `material.media` = 媒体名（字符串数组，多个媒体以逗号拼接）
- 返回不含投放地区字段，地区只能通过入参 `area` 筛选
- `material.impression_inc_2y` = 曝光（">10M" 字符串格式）
- `material.cnt_ad_id` = 关联广告数

## 4. 返回数据截断的解决方案

**问题**

数据拉取受两层限制叠加：

- **单次调用最多返回 `100` 条**：分页大小固定为 `100`，取全量数据必须多次翻页调用。
- **部分 tool 的返回会被截断**：内容较多的 tool（如素材搜索，单页 `100` 条），返回体可能超过 MCP 工具层对 Agent 上下文的 **约 100KB 截断保护阈值** —— 这类返回一旦回流到 Agent 上下文，就会同时出现数据不完整和大 JSON 大量占用 token 两个问题（返回体较小的调用不受影响）。

**解决思路**（可把这段描述交给 Agent，由它自行生成脚本，无需手写）：

1. **脚本直连端点**
   不经过 MCP 客户端，由脚本直接向端点发起 JSON-RPC 请求（端点、请求头与 SSE 响应格式见[第 1 节](#connection)；响应取 `data:` 前缀行的 JSON）。直连拿到的是服务端完整响应，不受客户端截断保护影响。
2. **循环翻页**
   用 `page` 参数从 `1` 开始依次翻页，每页固定 `100` 条，直到取满 `total` 或某页返回不足 `100` 条。
3. **原始响应直接落盘**
   每页写一个本地文件（如 `./mcp_dumps/search_p1.json`），数据不经过终端、不进入 Agent 上下文。
4. **终端只打印摘要**
   仅输出 `total`、本页条数、落盘路径等统计信息。
5. **分析读文件**
   后续处理直接读取落盘文件，按需筛出少量样本后再交给 Agent 解读。

**环境提示**

端点使用 HTTPS，若脚本报 `CERTIFICATE_VERIFY_FAILED`（证书链校验失败），安装 `certifi`（`pip3 install certifi`）并指定其证书即可。

## 5. 常见问题与注意事项

| 问题 | 对策 |
| --- | --- |
| 认证使用 `Bearer` | 使用 `Authorization: Bearer` 头，请求头需包含 `Content-Type` 与 `Accept` |
| `searchDsl` 的 `equal` 可能不生效 | 会返回全量（`total` 巨大），改用 `contain`，或 `keyword + accurateSearch=1` |
| `appAdRankings` 日期参数易报 401001 | 用短日期范围（如近17天）或重试 |
| `publisherAppOverview` 要 `publisher.id` | 传 `developer.id` 返回空 |
| `adVolumeTrends` 必须传 `brandId` | `brandId` 与 `id` 不能同时为空，缺省返回空 trend |
| `searchAdCreatives` 无 `creativeType` 参数 | 筛选视频靠返回后按 `material.creative.type` 手动过滤 |
| 返回的 `media` 字段是字符串数组 | `material.media` 元素为媒体名（多个逗号拼接），返回中无 `area` 字段 |
| `creativeAIAnalysisData` 的 `format` 怎么传 | 取该素材 `material.format` 逗号拆分后的任意一个（建议第一个）与 `ids` 按位对应；多形式素材传哪一个均可 |
| 返回数据大 | 脚本直连落盘，避免大 JSON 进入上下文 |
| 429 / 500 偶发 | 增加重试机制（3次+2-3s backoff） |
| `creativeAIAnalysisData` 返回的 `id` 是什么，怎么回填 | 就是入参传的 `material.creative.resource[0].id`（资源 ID），不是 `material.id`；返回数组与 `ids` 顺序一一对应、返回 `id` 与入参原样相等，按返回 `id` 关联对应素材即可。资源 ID 为 base64 形态（`==` 结尾），`material.id` 为 32 位纯十六进制；若 `material.creative.resource` 有多个元素，每个资源 ID 单独对应一条分析结果。 |

接入问题可联系 AppGrowing Global 服务支持获取协助。