axiom-asc-mcp

App Store Connect MCP 集成

核心原则：配置 asc-mcp 后，无需离开 Claude Code 即可管理整个 App Store Connect 工作流——以编程方式提交构建版本、分发到 TestFlight、回复评价并监控指标。

设置

安装

brew install mint
mint install zelentsov-dev/[email protected]

创建 API 密钥

1. 打开 App Store Connect → Users and Access → Integrations → API
2. 使用 Admin 或 App Manager 角色生成密钥
3. 下载 .p8 文件（仅可下载一次，请妥善保存）
4. 记下 Key ID 和 Issuer ID

添加到 Claude Code

claude mcp add asc-mcp \
  -e ASC_KEY_ID=YOUR_KEY_ID \
  -e ASC_ISSUER_ID=YOUR_ISSUER_ID \
  -e ASC_PRIVATE_KEY_PATH=/path/to/AuthKey.p8 \
  -- ~/.mint/bin/asc-mcp

验证

让 Claude 调用 company_current。如果返回你的团队名称，说明已连接。

---

Worker 筛选

asc-mcp 有 25 个 worker（约 208 个工具）。加载全部 worker 会浪费上下文。使用 --workers 仅加载所需内容。

预设

预设	Workers	工具	用例
TestFlight	apps,builds,beta_groups,beta_testers	约 34	Beta 分发
Release	apps,builds,versions,reviews	约 40	App Store 提交
Monetization	apps,iap,subscriptions,offer_codes,pricing	约 55	IAP 和订阅
Full	（默认，所有 worker）	约 208	全部功能

使用预设时，注册服务时添加 --workers：

claude mcp add asc-mcp \
  -e ASC_KEY_ID=... \
  -e ASC_ISSUER_ID=... \
  -e ASC_PRIVATE_KEY_PATH=... \
  -- ~/.mint/bin/asc-mcp --workers apps,builds,versions,reviews

注意：无论 --workers 设置如何，company 和 auth worker 始终会加载。启用 builds 时，会自动包含 build_processing 和 build_beta。

Worker 选择决策树

digraph workers {
    "What are you doing?" [shape=diamond];
    "TestFlight preset" [shape=box, label="--workers apps,builds,\nbeta_groups,beta_testers"];
    "Release preset" [shape=box, label="--workers apps,builds,\nversions,reviews"];
    "Monetization preset" [shape=box, label="--workers apps,iap,\nsubscriptions,offer_codes,pricing"];
    "Full (no flag)" [shape=box, label="No --workers flag\n(all 208 tools)"];

    "What are you doing?" -> "TestFlight preset" [label="distributing beta builds"];
    "What are you doing?" -> "Release preset" [label="submitting to App Store"];
    "What are you doing?" -> "Monetization preset" [label="managing IAP/subscriptions"];
    "What are you doing?" -> "Full (no flag)" [label="multiple tasks or unsure"];
}

---

工作流：发布流水线

向 App Store 提交新版本。

1. apps_search(query: "MyApp")           → get app ID
2. builds_list(appId, limit: 5)          → find latest processed build
3. app_versions_create(appId, platform: "IOS", versionString: "2.1.0")
4. app_versions_attach_build(versionId, buildId)
5. app_versions_set_review_details(versionId, { contactEmail, notes, ... })
6. app_versions_submit_for_review(versionId)
7. (After approval) app_versions_create_phased_release(versionId)

第 3 步之前：版本字符串不得已存在。使用 app_versions_list 检查。

第 4 步之前：构建版本必须处于 VALID 处理状态。使用 builds_get_processing_state 检查。

第 6 步之前：版本必须处于 PREPARE_FOR_SUBMISSION 状态。附加构建版本并设置审核详情是前置条件。

---

工作流：TestFlight 分发

向 Beta 测试人员分发构建版本。

1. apps_search(query: "MyApp")           → get app ID
2. builds_list(appId, limit: 5)          → find latest build
3. builds_set_beta_localization(buildId, locale: "en-US", whatsNew: "Bug fixes")
4. beta_groups_list(appId)               → find or create group
   OR beta_groups_create(appId, name: "Internal Testers", isInternal: true)
5. beta_groups_add_builds(groupId, [buildId])
6. builds_send_beta_notification(buildId) → notify testers (optional)

提示：内部测试人员（最多 100 人）可立即获得构建版本。外部测试人员（最多 10,000 人）需要对每个版本的首个构建版本进行 Beta App Review。

---

工作流：评价管理

监控并回复 App Store 评价。

1. apps_search(query: "MyApp")           → get app ID
2. reviews_list(appId, sort: "-createdDate", limit: 20)
   OR reviews_list(appId, filterRating: "1,2")  → negative reviews only
3. reviews_stats(appId)                  → rating distribution summary
4. reviews_create_response(reviewId, responseBody: "Thank you for...")

回复指南：

• 在 24-48 小时内回复负面评价
• 保持专业，并提供具体帮助
• 更新回复会替换之前的回复（用户会看到“Developer Response”）

---

工作流：反馈分类

将 TestFlight 反馈与构建诊断信息关联起来。

1. builds_list(appId, limit: 10)         → recent builds
2. builds_get_beta_testers(buildId)      → who tested this build
3. metrics_build_diagnostics(buildId)    → crash signatures for this build
4. metrics_get_diagnostic_logs(signatureId) → individual crash logs

限制：App Store Connect API 无法获取 TestFlight 文本反馈和屏幕截图。请使用 Xcode Organizer 或 ASC 网页控制面板查看反馈内容。

---

工作流：多公司

在 App Store Connect 团队之间切换。

1. company_list                          → see configured accounts
2. company_switch(companyId: "client-a") → switch active account
3. (All subsequent calls use client-a's credentials)

多公司设置

添加到 ~/.config/asc-mcp/companies.json：

{
  "companies": [
    {
      "id": "my-company",
      "name": "My Company",
      "key_id": "KEY_ID_1",
      "issuer_id": "ISSUER_1",
      "key_path": "/Users/you/.keys/AuthKey1.p8"
    },
    {
      "id": "client-a",
      "name": "Client A",
      "key_id": "KEY_ID_2",
      "issuer_id": "ISSUER_2",
      "key_path": "/Users/you/.keys/AuthKey2.p8"
    }
  ]
}

也可以使用编号环境变量：ASC_COMPANY_1_NAME、ASC_COMPANY_1_KEY_ID 等。

---

关键工具速查

App 和构建版本

工具	参数	返回内容
apps_search	query	App ID、名称、bundleId、平台
apps_list	limit	账户中的所有 App
builds_list	appId、limit、sort	构建编号、版本、处理状态
builds_find_by_number	appId、buildNumber	特定构建版本的详情
builds_get_processing_state	buildId	PROCESSING、VALID、INVALID 等
builds_check_readiness	buildId	构建版本是否已准备好进行分发

版本与提交

工具	参数	返回值
app_versions_create	appId, platform, versionString	状态为 PREPARE_FOR_SUBMISSION 的新版本
app_versions_attach_build	versionId, buildId	已关联的构建版本
app_versions_set_review_details	versionId, contactEmail, notes 等	审核详情
app_versions_submit_for_review	versionId	已提交审核
app_versions_cancel_review	versionId	已取消审核
app_versions_release	versionId	手动发布
app_versions_create_phased_release	versionId	为期 7 天的分阶段发布

TestFlight

工具	参数	返回值
beta_groups_create	appId, name, isInternal	新群组
beta_groups_add_testers	groupId, testerIds	已更新的群组
beta_groups_add_builds	groupId, buildIds	已分发的构建版本
builds_set_beta_localization	buildId, locale, whatsNew	“测试内容”文本
builds_send_beta_notification	buildId	已通知测试人员

评价与指标

工具	参数	返回值
reviews_list	appId, sort, filterRating, limit	评价条目
reviews_stats	appId	评分分布
reviews_create_response	reviewId, responseBody	开发者回复
metrics_app_perf	appId	应用级性能指标
metrics_build_diagnostics	buildId	每个构建版本的崩溃特征

---

API 限制

限制	详情
元数据中不得使用表情符号	版本“更新内容”、描述、关键词——使用文字，不要使用表情符号
版本状态	只有处于 PREPARE_FOR_SUBMISSION 状态的版本可以编辑。提交后，如需更改，请创建新版本。
JWT 有效期	令牌有效期为 20 分钟，asc-mcp 会自动续期
速率限制	Apple 会对每个账户实施限制。遇到 429 错误时，asc-mcp 会采用指数退避方式重试。
区域设置格式	标准代码：en-US、ja、de-DE、zh-Hans、ru
构建处理	新上传的构建版本需要 15-30 分钟处理。关联前请轮询 builds_get_processing_state。
分阶段发布	仅在审核通过后可用。可使用 app_versions_update_phased_release 暂停或恢复。

---

注意事项

注意事项	详情
找不到构建版本	构建版本可能仍在处理中。检查 builds_get_processing_state——状态必须为 VALID。
“版本已存在”	不能创建重复的版本字符串。请先使用 app_versions_list 检查。
关联失败	构建版本必须已处理完成，并且版本必须处于 PREPARE_FOR_SUBMISSION 状态。
审核详情被拒绝	联系信息字段有格式要求。电子邮件地址必须有效，电话号码必须包含国家/地区代码。
应用不匹配	apps_search 使用模糊搜索。请确认返回的 bundleId 与目标应用相符。
多公司账户混淆	更改前务必先调用 company_current，确认当前启用的账户。
Beta App Review	每个版本的首个外部 TestFlight 构建版本需要审核。同一版本后续的构建版本会自动批准。
缺少分析数据	analytics_* 工具需要在公司配置中设置 vendor_number。未设置时，销售和财务报告会静默失败。

---

反合理化

想法	实际情况
“我直接用 ASC 网页控制面板就好”	对于重复性任务，MCP 工具更快——回复 20 条评论、分发到 5 个群组，或在多个应用中创建版本。
“我不需要筛选工作器”	208 个工具会占用约 30K 个上下文 token。筛选出你需要的工具。
“我不提供审核详情也能提交”	提交会失败。必须先调用 app_versions_set_review_details，再调用 app_versions_submit_for_review。
“我跳过 company_current 就行——我只有一个账户”	多公司配置会在会话之间保留。务必确认。
“通过 API 进行反馈分类也一样”	ASC API 中没有文本反馈和截图。要查看反馈内容，请使用 Organizer；要诊断崩溃，请使用 MCP。

---

asc-mcp 不可用时

如果未配置 asc-mcp，请改用手动工作流：

• 崩溃分析：使用 Xcode Organizer（参见 axiom-testflight-triage）或 App Store Connect 网页控制面板（参见 axiom-app-store-connect-ref）
• TestFlight 分发：使用 Xcode → Product → Archive → Distribute，或 xcodebuild + altool
• 审核管理：使用 App Store Connect 网页控制面板
• 提交：使用 Xcode → Product → Archive → Distribute to App Store

---

资源

技能：axiom-app-store-submission、axiom-app-store-ref、axiom-app-store-connect-ref、axiom-testflight-triage

Agent：crash-analyzer、security-privacy-scanner、iap-auditor