内容
# 应用商店运营商
<p align="center">
<a href="https://www.npmjs.com/package/app-store-operator"><img src="https://img.shields.io/npm/v/app-store-operator?color=6366f1&label=npm" alt="npm"></a>
<a href="https://www.npmjs.com/package/app-store-operator"><img src="https://img.shields.io/npm/dm/app-store-operator?color=818cf8&label=downloads" alt="downloads"></a>
<a href="#license"><img src="https://img.shields.io/badge/license-MIT-green" alt="license"></a>
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%E2%89%A518-brightgreen" alt="node"></a>
<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-6366f1" alt="MCP"></a>
</p>
一个MCP（模型上下文协议）服务器，为iOS应用开发者提供应用商店竞争性研究工具。
## 功能
搜索应用商店中与给定关键词竞争的应用，并从SensorTower提取详细的分析数据 - 下载量、收入、评分、热门市场、发布者信息等。
## 工具
### `research_rivals`
查找关键词的前3名应用，并为每个应用返回完整的指标报告。
| 参数 | 类型 | 描述 |
|-----------|------|-------------|
| `keyword` | 字符串 | 搜索词（例如 `冥想`、`心理学`） |
| `country` | 字符串 | 两位国家代码（例如 `us`、`tr`、`gb`） |
**返回每个竞争对手的信息：**
- 应用商店和SensorTower网址
- 全球和上个月的下载量和收入
- 评分
- 发布者、类别、热门市场
- 发布日期、最后更新时间、支持的语言
- 应用内购买和广告网络存在
---
### `search_app_store`
搜索应用商店中的关键词，并以markdown表格形式返回排名结果 - 无需SensorTower。
| 参数 | 类型 | 描述 |
|-----------|------|-------------|
| `keyword` | 字符串 | 搜索词 |
| `country` | 字符串 | 两位国家代码 |
| `limit` | 数字 | 返回结果数量（1-25，默认为3） |
使用此功能发现哪些应用排名靠前，然后再决定分析哪些应用。接着使用 `get_app_details` 获取特定应用的分析数据。
---
### `get_app_details`
获取一个或多个已有应用ID的SensorTower分析数据。
| 参数 | 类型 | 描述 |
|-----------|------|-------------|
| `app_ids` | 数组 | 数值应用商店ID（例如从 `search_app_store` 获取） |
| `country` | 字符串 | 两位国家代码 |
**返回每个应用的信息：**
- 下载量和收入（全球 + 上个月）
- 评分
- 发布者、类别、热门市场
- 发布日期、最后更新时间、支持的语言
- 应用内购买和广告网络存在
---
### `prepare_iae`
生成iOS应用商店应用内事件（IAE）文案 - 目标语言的3种变体，然后生成最终报告。
| 参数 | 类型 | 描述 |
|-----------|------|-------------|
| `keywords` | 数组 | 按优先级排序的关键词（索引0-2 = 优先级1，3-6 = 优先级2，7-9 = 优先级3） |
| `locale` | 字符串 | 目标语言环境（例如 `zh-cn`、`en-gb`、`de-de`、`tr`、`ja`、`ko`） |
| `event_purpose` | 字符串 | 事件目的和用户关心的内容 |
| `audience` | 字符串 | 目标受众（例如学生、专业人士、家长） |
| `event_context` | 字符串 | 将事件与某个时刻联系起来的现实世界钩子（例如节假日、季节） |
| `goal` | 字符串 | 主要转化目标（例如吸引新用户、提高参与度） |
| `tone` | 字符串 | 文案语气：`Engaging`、`Playful`、`Motivational`、`Authoritative`、`Calm` 或 `Urgent` |
**返回：** 用于生成3种文案变体的结构化简报，每种变体包含事件名称（≤30字符）、简短描述（≤50字符）和长描述（≤120字符）。
## 要求
- Node.js v18+
## 用法
### 作为MCP服务器（Claude Code / Claude Desktop / OpenAI Codex）
**Claude Code** - 运行此命令一次：
```bash
claude mcp add --transport stdio app-store-operator -- npx -y app-store-operator@latest
```
**Claude Desktop** - 添加到MCP配置：
```json
{
"mcpServers": {
"app-store-operator": {
"command": "npx",
"args": ["app-store-operator@latest"]
}
}
}
```
**OpenAI Codex** - 运行此命令一次：
```bash
codex mcp add app-store-operator -- npx -y app-store-operator@latest
```
Codex将MCP服务器存储在 `~/.codex/config.toml` 中。如果您更喜欢直接编辑它：
```toml
[mcp_servers.app-store-operator]
command = "npx"
args = ["-y", "app-store-operator@latest"]
# 可选但对SensorTower抓取流程有用的配置
startup_timeout_sec = 20
tool_timeout_sec = 180
```
然后重启Codex或启动新线程，并询问类似的问题：
- `在英国应用商店中搜索与“发型”竞争的应用`
- `在法国应用商店中搜索“胡须风格”`
- `为en-gb的夏季发型活动准备应用内事件`
无需安装步骤 - `npx` 自动获取并运行软件包。
服务器通过stdio通信，旨在由MCP客户端调用。在 `initialize` 期间，它会公布服务器范围的 `instructions`，以便客户端正确地在工具之间路由，并在需要SensorTower登录时返回MCP工具错误。
## 工作原理
1. 查询iTunes搜索API以获取与关键词和国家/地区匹配的前3个应用
2. 对于每个应用，驱动Chromium浏览器抓取SensorTower分析数据
3. 提取指标并返回编译后的纯文本报告
SensorTower数据通过Playwright抓取，因为它是在客户端渲染的。
**浏览器窗口将打开。** 这是故意的，而不是错误：SensorTower需要登录，因此第一次运行会打开一个可见的窗口供您登录。会话保存到 `~/.app-store-operator/profile` 并在每次后续调用时重用，因此您只需登录一次。如果工具报告 `not_logged_in`，请在该窗口中完成登录并再次运行工具。
`research_rivals` 的结果在 `~/.app-store-operator/cache.json` 中缓存24小时 - 可以使用 `ASO_CACHE_TTL_HOURS` 环境变量覆盖TTL。
## 项目结构
```
src/
├── index.js # MCP服务器设置和请求处理程序
├── shared.js # 应用商店查找 + SensorTower抓取
├── cache.js # 24小时本地缓存（仅限research_rivals）
└── tools/
├── research-rivals.js # research_rivals工具
├── search-app-store.js # search_app_store工具
├── get-app-details.js # get_app_details工具
└── prepare-iae.js # prepare_iae工具
scripts/postinstall.js # 安装Playwright Chromium
test/smoke-test-mcp.js # stdio烟雾测试
```
## 开发
运行烟雾测试以验证服务器启动并通过stdio公开每个工具 - 它检查 `initialize` （包括服务器指令）和 `tools/list`：
```bash
npm run smoke
```
