storepilot-mcp

StorePilot

一个 MCP 服务，覆盖 Google Play 和 App Store 上的整个应用组合。

向你的助手提问：

“我的哪些应用的崩溃率超过了 Google 的阈值？”

“上个月整个应用组合每个应用分别赚了多少钱？”

“列出两个商店中的所有应用：版本、评分、安装量、收入、崩溃情况。”

“德语描述在两个商店之间不一致——具体有哪些差异？”

“将 3.2.1 发布到 Play 内部测试轨道和 TestFlight。”

以上每个问题都只需调用一个工具，即可覆盖你拥有的所有应用，因为这些 工具面向整个应用组合，而不是单个端点。最后一个问题有意需要两次调用： 写入操作会先预览，并等待人工确认。

你需要自己的开发者账号——Google Play 服务账号、App Store Connect API 密钥，或两者都有。StorePilot 读取你的账号数据；它不会 抓取公开商店列表。

状态：早期阶段。 读取工具已在两个商店的真实账号上运行；营收和 崩溃阈值相关路径尚未返回真实数据，并且从未有写入操作在商店中执行。 在信任任何数字之前，请先阅读 状态与坦诚说明的限制。

---

实际上的不同之处

两个商店，一套工具。 Google Play 使用 Android Publisher API、Play Developer Reporting API 和私有 Cloud Storage 报告存储桶；App Store 使用 App Store Connect。总计 34 个工具，命名一致。

大多数工具无法获取的安装量和收入。 Play 安装量、评分和收入没有 REST API。它们只以 UTF-16 CSV 文件的形式存放在私有 Cloud Storage 存储桶中，因此大多数工具都会跳过这些数据，也就无法回答“这个应用赚了多少钱？”。StorePilot 会读取该存储桶，按列名而不是列位置解析 CSV，并按货币报告收入，绝不会跨货币求和。（这条路径已实现并通过固定数据测试，但尚未读取真实报告——请参阅状态。）

以整个应用组合为先。 portfolio_overview 会在一张表中呈现两个商店里的所有应用。play_portfolio_health 会扫描整个 Play 账号。这两个工具都不需要包名。专为独立开发者、应用工厂和代理机构打造。

跨商店工具。 parity_check 可查找两个商店之间的列表和版本差异。compare_reviews 会并排展示两个商店的评论。release_both 会将同一版本发布到两个商店。metadata_pull / metadata_push 使用 fastlane 自带的目录布局，因此采用 StorePilot 并不意味着要放弃 fastlane。

写入操作受控。 每项写入操作都会先预览，并返回一个确认令牌。该令牌通过 HMAC 与确切操作绑定，只能使用一次，并会在 10 分钟后过期。生产版本发布会强制采用分阶段推出，比例上限为 20%。

setup_doctor。 这里的凭据设置需要经过多个步骤，涉及 Google Cloud、Play Console 和 App Store Connect，过程中还有多种无提示失败情况。一个工具即可检查每个步骤，并打印出确切的修复方法。

---

安装

需要 Python 3.11+。

uvx storepilot          # no install; uv fetches it per run

也可以安装：

pipx install storepilot   # or: pip install storepilot

无论使用哪种方式，你都会获得一个 storepilot 二进制文件。下面的每项客户端配置都需要它的绝对路径——运行 which storepilot 即可查看。

Claude Code

claude mcp add storepilot -- storepilot

Claude Desktop / 任意 MCP 客户端

claude_desktop_config.json：

{
  "mcpServers": {
    "storepilot": {
      "command": "/absolute/path/to/storepilot",
      "env": {
        "STOREPILOT_GOOGLE_CREDENTIALS": "/path/to/service-account.json",
        "STOREPILOT_GOOGLE_REPORTS_BUCKET": "pubsite_prod_rev_0123456789",
        "STOREPILOT_ASC_KEY_PATH": "/path/to/AuthKey_XXXXXXXXXX.p8",
        "STOREPILOT_ASC_KEY_ID": "XXXXXXXXXX",
        "STOREPILOT_ASC_ISSUER_ID": "00000000-0000-0000-0000-000000000000",
        "STOREPILOT_ASC_VENDOR_NUMBER": "80000000"
      }
    }
  }
}

Cursor

Settings → MCP → Add new MCP server，或添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "storepilot": {
      "command": "/absolute/path/to/storepilot",
      "env": { "STOREPILOT_ASC_KEY_PATH": "/path/to/AuthKey_XXXXXXXXXX.p8" }
    }
  }
}

Codex CLI

添加到 ~/.codex/config.toml：

[mcp_servers.storepilot]
command = "/absolute/path/to/storepilot"
env = { STOREPILOT_ASC_KEY_PATH = "/path/to/AuthKey_XXXXXXXXXX.p8" }

只配置你使用的商店。每个适配器都会独立注册自己的工具；只要配置了任一商店，跨商店工具就会注册。.env.example 中列出了代码读取的所有变量。

.env 文件也可用，但它会从进程工作目录读取——也就是 MCP 客户端启动服务时所在的目录，而不是仓库目录。如果你在检出目录中自行运行 storepilot，请使用 .env；否则，请使用客户端的 env 区块。

StorePilot 从环境中读取凭据，绝不会将其写入任何位置。请将服务账号 JSON 和 .p8 文件保存在仓库外，并对两者运行 chmod 600——它们都是私钥。

---

从 setup_doctor 开始

不要一开始就调用数据工具，然后猜测为什么没有返回结果。先让你的助手运行 setup_doctor。它会分别检查每个凭据步骤，因此某项检查失败也不会掩盖其他问题，并且每项失败都会附带相应的修复方法。

尚未配置任何内容时：

StorePilot setup check
============================================================

-- Google Play ----------------------------------------------
[skip] Google Play: not configured
      Fix: Set STOREPILOT_GOOGLE_CREDENTIALS to the path of a service account JSON key. Full
      setup: create a Google Cloud project, enable the Android Publisher and Play Developer
      Reporting APIs, create a service account, download its JSON key, then invite the service
      account email in Play Console -> Users and permissions.
      Docs: https://developers.google.com/android-publisher/getting_started

-- App Store Connect ----------------------------------------
[fail] ASC credentials: App Store Connect is not configured: STOREPILOT_ASC_KEY_PATH,
      STOREPILOT_ASC_KEY_ID, STOREPILOT_ASC_ISSUER_ID unset.
      Fix: In App Store Connect go to Users and Access -> Integrations -> App Store Connect
      API, create a team key with the Admin or App Manager role, and download the .p8 file
      (Apple lets you download it exactly once). Then set STOREPILOT_ASC_KEY_PATH to that
      file, STOREPILOT_ASC_KEY_ID to the Key ID column, and STOREPILOT_ASC_ISSUER_ID to the
      Issuer ID shown above the key table. Sales reports additionally need
      STOREPILOT_ASC_VENDOR_NUMBER from Payments and Financial Reports.
      Docs: https://developer.apple.com/documentation/appstoreconnectapi/creating-api-keys-for-app-store-connect-api
[skip] ASC token: cannot test until the credentials load
      Fix: Fix the step above, then re-run setup_doctor.
[skip] ASC API reachable: cannot test until the credentials load
      Fix: Fix the step above, then re-run setup_doctor.
[skip] ASC sales access: cannot test until the credentials load
      Fix: Fix the step above, then re-run setup_doctor.

============================================================
Summary: 1 fail, 4 skip
Resolve the [fail] items above, then run setup_doctor again.

它还能捕获看似成功的失败情况：如果没有 回复评价 权限，Play 的评价 API 会返回 HTTP 200 和空列表，而不是报错；因此，“这个应用没有评价”和“你缺少权限”得到的是相同响应。setup_doctor 会将这种模糊情况作为单独的诊断结果报告，而不会自行猜测。

两家商店的完整操作指南：docs/SETUP.md。

---

工具

共 34 个工具。完整参数、返回格式和各工具的限制，请参阅 docs/TOOLS.md。

Google Play — 读取

工具	能回答的问题
play_list_apps	此安装可以访问哪些软件包？
play_get_vitals	崩溃和 ANR（应用无响应）率与 Google 的 1.09% / 0.47% 阈值相比如何？
play_get_anomalies	Google 自有的异常检测标记了哪些问题？
play_get_stats	一个月内的安装量和评分（GCS 存储桶）
play_get_earnings	一个月内按币种划分的收入（GCS 存储桶）
play_list_reviews	最近的正式版评价，可按星级筛选
play_portfolio_health	每个应用的运行状况指标、评分和安装量，汇总在一张表中

Google Play — 写入（均受限制）

工具	功能
play_upload_bundle	上传 .aab 并将其发布到某个轨道
play_create_release	发布已上传的版本代码
play_promote_release	在不同轨道间移动构建版本（beta → production）
play_expand_rollout	扩大分阶段发布的范围——这是达到 100% 的唯一途径
play_halt_rollout	立即停止发布，无需确认步骤
play_reply_review	发布公开的开发者回复
play_update_listing	覆盖一个区域设置的商店文案

App Store Connect

工具	功能
asc_list_apps	密钥可见的应用及其 Apple ID
asc_list_builds	TestFlight 构建版本及其三种审核状态
asc_list_reviews	客户评价，可筛选，包含完整历史记录
asc_list_versions	版本、审核状态和分阶段发布天数
asc_get_sales	销售额和收益，缓存时间较长
asc_get_analytics	通过 Apple 的异步报告流程获取 App Analytics
asc_upload_build	返回 Transporter 操作说明——没有 API 可用于上传
asc_reply_review	公开回复客户评价（受限制）
asc_update_metadata	可编辑版本的商店文案（受限制）
asc_submit_for_review	预检后提交给 App Review（受限制）

跨商店

工具	作用
portfolio_overview	在一张表中查看两个商店上的所有应用
compare_reviews	并排查看某个应用在两个商店的评论
parity_check	检查两个商店之间的版本和商品信息差异
release_both	使用一个令牌，将一个版本发布到 Play 和 TestFlight（需授权）
metadata_pull	将商店文案拉取到 fastlane-layout 本地目录树
metadata_push	将本地目录树推送到两个商店（需授权）
list_app_pairs	显示配对注册表
suggest_app_pairs	根据 bundle-id 和名称证据提出配对建议
pair_apps	将一个配对写入注册表

另有 setup_doctor。

两个 API 都不会说明某个 Play 包和 Apple ID 属于同一款产品， 因此配对信息保存在 ~/.storepilot/apps.toml 中。运行 suggest_app_pairs， 然后对你认可的建议运行 pair_apps。建议在写入前不会生效—— 错误配对会把某个应用的收入、评论和崩溃率归到另一个应用名下， 后续流程中也不会有任何异常提示。

---

安全模型

每次写入都需要调用两次。第一次返回预览和令牌；第二次则带上该令牌。

预览才是真正的安全机制：它会呈现在聊天中，供人查看，例如“这不是正确的应用”或“这是生产轨道”。 Play 预览不是估算结果——操作会在一次临时 Play 编辑中实际运行，该编辑经过验证后会被删除， 因此预览会报告 Google 实际分配的版本代码，以及 Google 实际会返回的任何错误。

令牌的唯一作用是防止预览和确认之间发生变动。它是对操作的规范指纹计算出的 HMAC， 使用每次安装独有的密钥进行签名；密钥不会出现在工具输出中。令牌只能使用一次，有效期为 10 分钟。 普通内容哈希可以由模型自行计算，让模型无需呈现人类需要查看的预览就能自行确认。 更改任何参数都会使令牌失效。

还有三条规则：

• 生产发布必须采用分阶段推出，第一步最多覆盖 20% 的用户（如果省略比例，则为 0.1）。play_expand_rollout 是唯一能达到 100% 的途径，并单独设置，因此绝不会作为副作用发生。
• play_halt_rollout 有意不设授权门槛。 停止有问题的发布始终是安全的做法；在事故期间还要让人再来回操作一轮，是设计上的失误。
• 所有操作都会记录审计日志——预览、确认、拒绝、执行和失败都会写入 ~/.storepilot/audit.log 中的只追加日志，并对凭据和长值进行脱敏。

release_both 会为两个商店签发一个令牌，因为批准双商店发布的一半，不等于批准整个发布。如果部分失败，它会明确说明哪些内容发布到了哪里，且不会回滚任何内容：因为另一家商店返回 API 错误，就从用户手中撤回可正常使用的构建版本，比两边出现差异更糟。

状态与明确的限制

StorePilot 已在两个商店的真实账户上以只读方式运行。首次运行发现了三个错误，现已全部修复：Apple 会拒绝在 appStoreVersions 端点上使用 sort，Play 报告存储桶并不总是命名为 pubsite_prod_rev_*，而存储桶访问权限属于账户级别的 Play Console 权限，并非错误消息建议的 Cloud Console IAM 授权。

已在线验证 —— 服务账号和 ES256 JWT 身份验证、速率限制节流、两个商店上的 setup_doctor、Play 和 App Store 读取工具，以及在同一张表格中呈现两个商店共六款应用的 portfolio_overview。

尚未验证，其中两项涉及核心宣传内容：

• 从未获取到任何 Vitals 数据点。 Android Vitals 会抑制低于每日最低用户数的指标，而测试账户中的应用用户数都未达到这一门槛。因此，阈值比较——也就是 play_get_vitals 的用途——从未基于真实数据运行，悬而未决的问题依然存在：Reporting API 返回的是 1.09 还是 0.0109？数值不匹配会导致每项判定都相差 100 倍。
• 从未读取过任何报告 CSV。 安装量、评分和收入都来自 GCS 存储桶，而解析器至今只处理过测试数据。Google 在2026 年 7 月更改了收入报告中的 Fee Description 列，因此真实的表头才是风险所在。

• 从未执行过任何写入操作。 所有防护措施、预览和发布策略都只通过模拟客户端和 503 测试验证过，从未在真实商店上验证。
• 使用 App Manager 密钥请求 Apple 销售报告会返回 403；读取这些报告需要具有财务权限的密钥。

完整列表见 docs/ROADMAP.md。如果你在真实账户上运行 StorePilot——尤其是账户中有应用规模足以生成 Vitals 报告——那么针对这些事项提交错误报告的价值最高。

商店施加的硬性限制

这些限制无法在此解决。StorePilot 会在使用相关功能时明确说明，而不会返回看似有效的答案：

• 在两个商店中，创建新应用记录都只能通过 Console 完成。 在 Play 上，首次上传也必须手动完成。
• 声明表单只能通过 Console 填写——数据安全、隐私营养标签、内容分级。
• 没有 REST 端点可以上传 iOS 二进制文件。 asc_upload_build 会返回 Transporter/altool 操作说明，而不会假装能够完成上传。
• Play 的评论 API 只返回正式版轨道的评论、仅包含评论内容的评论，并且大致只涵盖最近 7 天。
• Apple 的 API 完全不提供汇总评分。
• Play 报告数据会延迟 3–7 天，某月的收入通常要到次月 5 日左右才会出现。在此之前，报告尚不存在，StorePilot 会报告“尚未发布”，而不是返回 0。

配额

• Play Developer Reporting：每秒 10 个查询。StorePilot 将请求速率控制在每秒 8 个，以留出余量，因此扫描大型应用组合需要几秒钟。
• App Store Connect：每个密钥每小时约 3,600 个请求，限制会在 x-rate-limit 标头中报告；此外还有未公开的每分钟上限，达到约 300–350 个请求时会开始拒绝请求。客户端会同时遵循这两项限制，每分钟最多发送 240 个请求，并随着每小时配额逐渐耗尽而拉开调用间隔。
• Apple 的 salesReports 配额比 API 其余部分严格得多，因此结果会缓存——过去的周期永久缓存，因为 Apple 从不重写这些报告。

---

对比

StorePilot 并非唯一会调用这些 API 的 MCP 服务，也不是 fastlane 的替代品。docs/COMPARISON.md 列出了替代方案、说明了各自的优势，并明确指出 StorePilot 是唯一选择的具体小众场景。

文档

• docs/SETUP.md — 完整说明凭据迷宫
• docs/TOOLS.md — 每个工具、参数和限制
• docs/COMPARISON.md — 替代方案和 fastlane
• docs/ROADMAP.md — 当前状态和实时验证待办事项
• docs/SECURITY.md — 凭据处理和威胁模型
• CONTRIBUTING.md — 设置、基本规则以及真正有帮助的事项
• CHANGELOG.md — 已发布的内容，以及实时运行修复的问题

贡献

最有帮助的贡献是使用真实商店账号运行 StorePilot 并报告出现的问题——尤其是拥有足够大型应用、能让 Android Vitals 报告数据的账号；测试账号并非如此。请参阅 CONTRIBUTING.md。

MCP Registry

已发布为 io.github.sonlenef/storepilot-mcp。

mcp-name: io.github.sonlenef/storepilot-mcp

许可证

MIT