@pofky/asc-mcp 1.3.0 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (103) hide show
  1. package/LIMITATIONS.md +41 -0
  2. package/README.md +80 -10
  3. package/USER_GUIDE.md +185 -0
  4. package/dist/client.d.ts +5 -0
  5. package/dist/client.d.ts.map +1 -1
  6. package/dist/client.js +58 -1
  7. package/dist/client.js.map +1 -1
  8. package/dist/doctor.d.ts +28 -0
  9. package/dist/doctor.d.ts.map +1 -0
  10. package/dist/doctor.js +178 -0
  11. package/dist/doctor.js.map +1 -0
  12. package/dist/editable.d.ts +9 -0
  13. package/dist/editable.d.ts.map +1 -0
  14. package/dist/editable.js +20 -0
  15. package/dist/editable.js.map +1 -0
  16. package/dist/gate.d.ts +8 -0
  17. package/dist/gate.d.ts.map +1 -0
  18. package/dist/gate.js +17 -0
  19. package/dist/gate.js.map +1 -0
  20. package/dist/index.js +254 -16
  21. package/dist/index.js.map +1 -1
  22. package/dist/license.js +1 -1
  23. package/dist/prompts.d.ts.map +1 -1
  24. package/dist/prompts.js +101 -0
  25. package/dist/prompts.js.map +1 -1
  26. package/dist/setup.d.ts +19 -0
  27. package/dist/setup.d.ts.map +1 -0
  28. package/dist/setup.js +153 -0
  29. package/dist/setup.js.map +1 -0
  30. package/dist/tools/age-rating.d.ts +14 -0
  31. package/dist/tools/age-rating.d.ts.map +1 -0
  32. package/dist/tools/age-rating.js +125 -0
  33. package/dist/tools/age-rating.js.map +1 -0
  34. package/dist/tools/app-details.js +2 -2
  35. package/dist/tools/availability.d.ts +20 -0
  36. package/dist/tools/availability.d.ts.map +1 -0
  37. package/dist/tools/availability.js +96 -0
  38. package/dist/tools/availability.js.map +1 -0
  39. package/dist/tools/builds.d.ts +26 -0
  40. package/dist/tools/builds.d.ts.map +1 -0
  41. package/dist/tools/builds.js +108 -0
  42. package/dist/tools/builds.js.map +1 -0
  43. package/dist/tools/eu-trader.d.ts +12 -0
  44. package/dist/tools/eu-trader.d.ts.map +1 -0
  45. package/dist/tools/eu-trader.js +25 -0
  46. package/dist/tools/eu-trader.js.map +1 -0
  47. package/dist/tools/guide.d.ts +38 -0
  48. package/dist/tools/guide.d.ts.map +1 -0
  49. package/dist/tools/guide.js +273 -0
  50. package/dist/tools/guide.js.map +1 -0
  51. package/dist/tools/iap.d.ts +43 -0
  52. package/dist/tools/iap.d.ts.map +1 -0
  53. package/dist/tools/iap.js +360 -0
  54. package/dist/tools/iap.js.map +1 -0
  55. package/dist/tools/list-apps.js +1 -1
  56. package/dist/tools/list-reviews.js +2 -2
  57. package/dist/tools/local-build.d.ts +26 -0
  58. package/dist/tools/local-build.d.ts.map +1 -0
  59. package/dist/tools/local-build.js +100 -0
  60. package/dist/tools/local-build.js.map +1 -0
  61. package/dist/tools/privacy.d.ts +15 -0
  62. package/dist/tools/privacy.d.ts.map +1 -0
  63. package/dist/tools/privacy.js +32 -0
  64. package/dist/tools/privacy.js.map +1 -0
  65. package/dist/tools/release-control.d.ts +22 -0
  66. package/dist/tools/release-control.d.ts.map +1 -0
  67. package/dist/tools/release-control.js +85 -0
  68. package/dist/tools/release-control.js.map +1 -0
  69. package/dist/tools/release-preflight.d.ts.map +1 -1
  70. package/dist/tools/release-preflight.js +139 -0
  71. package/dist/tools/release-preflight.js.map +1 -1
  72. package/dist/tools/review-screenshot.d.ts +14 -0
  73. package/dist/tools/review-screenshot.d.ts.map +1 -0
  74. package/dist/tools/review-screenshot.js +72 -0
  75. package/dist/tools/review-screenshot.js.map +1 -0
  76. package/dist/tools/review-status.js +2 -2
  77. package/dist/tools/sales-report.js +3 -3
  78. package/dist/tools/sales-report.js.map +1 -1
  79. package/dist/tools/screenshots.d.ts +15 -0
  80. package/dist/tools/screenshots.d.ts.map +1 -0
  81. package/dist/tools/screenshots.js +106 -0
  82. package/dist/tools/screenshots.js.map +1 -0
  83. package/dist/tools/signing.d.ts +21 -0
  84. package/dist/tools/signing.d.ts.map +1 -0
  85. package/dist/tools/signing.js +101 -0
  86. package/dist/tools/signing.js.map +1 -0
  87. package/dist/tools/submission.d.ts +47 -0
  88. package/dist/tools/submission.d.ts.map +1 -0
  89. package/dist/tools/submission.js +199 -0
  90. package/dist/tools/submission.js.map +1 -0
  91. package/dist/tools/testflight.d.ts +20 -0
  92. package/dist/tools/testflight.d.ts.map +1 -0
  93. package/dist/tools/testflight.js +75 -0
  94. package/dist/tools/testflight.js.map +1 -0
  95. package/dist/tools/update-version-metadata.d.ts +17 -0
  96. package/dist/tools/update-version-metadata.d.ts.map +1 -0
  97. package/dist/tools/update-version-metadata.js +148 -0
  98. package/dist/tools/update-version-metadata.js.map +1 -0
  99. package/dist/tools/version-control.d.ts +21 -0
  100. package/dist/tools/version-control.d.ts.map +1 -0
  101. package/dist/tools/version-control.js +144 -0
  102. package/dist/tools/version-control.js.map +1 -0
  103. package/package.json +5 -2
package/LIMITATIONS.md ADDED
@@ -0,0 +1,41 @@
1
+ <!-- GENERATED from src/tools/guide.ts by scripts/gen-docs.mjs. Do not edit by hand. -->
2
+
3
+ # Limitations and manual interruptions
4
+
5
+ Everything here is impossible via the App Store Connect API and must be done by hand. The MCP either returns the exact steps (privacy, trader) or detects and aborts (first IAPs) so nothing is left half-done.
6
+
7
+ ### Create an app record
8
+ Why: POST /v1/apps is forbidden for API keys.
9
+ Do instead: ASC website > Apps > + (one time).
10
+
11
+ ### Create an App Group
12
+ Why: Portal-only; no API.
13
+ Do instead: Apple Developer portal > Identifiers.
14
+
15
+ ### App Privacy nutrition label
16
+ Why: appDataUsages is not in the public API.
17
+ Do instead: ASC website. Run `set_privacy_nutrition` for the exact checklist + deep link.
18
+
19
+ ### EU DSA trader status
20
+ Why: No public API attribute/resource.
21
+ Do instead: ASC website. Run `set_eu_trader_status` for steps + deep link. Legal decision.
22
+
23
+ ### Submit an app's FIRST in-app purchases / subscriptions
24
+ Why: First products return FIRST_NON_CONSUMABLE_MUST_BE_SUBMITTED_ON_VERSION; only the website bundles them with the version.
25
+ Do instead: ASC website: open the version, Add for Review, tick the products, submit together. `submit_for_review` aborts to avoid orphaning. Later products submit via API.
26
+
27
+ ### Create a signing certificate / use cloud signing
28
+ Why: Least-privilege API keys lack certificate rights; cloud signing fails with a permission error.
29
+ Do instead: Have an Apple Distribution cert in the keychain, then `setup_app_store_signing` for manual-signing profiles + ExportOptions.plist.
30
+
31
+ ### Compile the binary
32
+ Why: Building an .ipa needs the Xcode toolchain.
33
+ Do instead: `build_and_archive` + `upload_binary` run locally on a Mac with Xcode.
34
+
35
+ ### Post a public response to a review
36
+ Why: API exposes reading reviews, not posting public replies.
37
+ Do instead: `draft_review_response` writes the reply; paste it in the ASC website.
38
+
39
+ ### Capture simulator screenshots
40
+ Why: Not yet implemented (roadmap).
41
+ Do instead: Produce PNGs yourself, then `upload_screenshots`.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # App Store Connect MCP Server
2
2
 
3
- > **The App Store Connect intelligence layer for your coding agent.** 11 tools that think, 3 slash-command workflows, and a bundled Claude Skill. Not another API wrapper.
3
+ > **Full control of App Store Connect from your coding agent.** 36 tools: read intelligence that thinks, plus write/control that ships your app end to end (edit metadata, upload screenshots, attach builds, TestFlight, submit, release, even build and upload the binary locally). 4 slash-command workflows and a bundled Claude Skill. Not another API wrapper.
4
4
 
5
5
  Maintained successor to [JoshuaRileyDev/app-store-connect-mcp-server](https://github.com/JoshuaRileyDev/app-store-connect-mcp-server) (archived Feb 2026). Different angle, same API surface plus more.
6
6
 
@@ -11,7 +11,9 @@ asc-mcp install-skill # one-line, optional, for auto-routed review questions
11
11
 
12
12
  ## What Makes This Different
13
13
 
14
- Other ASC MCP servers wrap the API and give you 80 to 293 raw endpoints. This one gives you 13 opinionated tools, 3 slash-command Prompts, and a Claude Skill that all think. Two of the tools use MCP Sampling: your own client's model does the LLM work, so there is no extra cost from this server.
14
+ Other ASC MCP servers wrap the API and give you 80 to 293 raw endpoints. This one gives you 36 opinionated tools, 4 slash-command Prompts, and a Claude Skill that all think. The read tools summarize and audit; the Pro control tools actually drive App Store Connect, from editing metadata to submitting and releasing, with the same API key. Two tools use MCP Sampling: your own client's model does the LLM work, so there is no extra cost from this server.
15
+
16
+ **Why full control is possible without fastlane:** fastlane's `deliver` and `pilot` are just calls to the same App Store Connect REST API this server authenticates against with your `.p8`. So nearly everything you would script with fastlane is a tool here, no Ruby toolchain required. The only step that needs your Mac is building and signing the binary, which `build_and_archive` and `upload_binary` drive via Xcode.
15
17
 
16
18
  | You say | What happens |
17
19
  |---------|-------------|
@@ -27,7 +29,11 @@ No context switching. No portal. Just ask.
27
29
 
28
30
  ## Setup (3 minutes)
29
31
 
30
- **Step 1.** Create an API key in [App Store Connect > Keys](https://appstoreconnect.apple.com/access/integrations/api) (Admin or App Manager role). Download the `.p8` file.
32
+ **Step 1.** Create an API key in [App Store Connect > Integrations > App Store Connect API](https://appstoreconnect.apple.com/access/integrations/api) (Admin or App Manager role), then grab three things from that same page:
33
+
34
+ - **Issuer ID** (`ASC_ISSUER_ID`): the UUID shown at the top of the page, with a copy button next to it.
35
+ - **Key ID** (`ASC_KEY_ID`): the 10-character ID next to your key, also in the filename `AuthKey_XXXXXXXXXX.p8`.
36
+ - **`.p8` file** (`ASC_PRIVATE_KEY_PATH`): click **Download** and point this at the saved file. Apple lets you download it only once, so keep it safe.
31
37
 
32
38
  **Step 2.** Install:
33
39
 
@@ -35,23 +41,37 @@ No context switching. No portal. Just ask.
35
41
  npm install -g @pofky/asc-mcp
36
42
  ```
37
43
 
38
- Add to `~/.claude/settings.json` (Claude Code) or your agent's MCP config:
44
+ No global install needed if you prefer `npx` (see the manual config below).
45
+
46
+ **Fastest setup (recommended).** Drop your `.p8` into Apple's standard path `~/.appstoreconnect/private_keys/` (the file is named `AuthKey_XXXXXXXXXX.p8`, and the Key ID is in the filename). Then run:
47
+
48
+ ```bash
49
+ asc-mcp init --write # auto-detects the key, asks for your Issuer ID, and writes the config for you
50
+ # or: asc-mcp init # same, but prints the block to paste yourself
51
+ ```
52
+
53
+ `init --write` finds your Claude Desktop / Claude Code config, backs it up, and merges in the server block, so there's no JSON editing. The server also auto-discovers the `.p8` path at runtime, so you only ever need `ASC_ISSUER_ID` (and `ASC_LICENSE_KEY` for Pro).
54
+
55
+ **Stuck?** Run `asc-mcp doctor` (or ask your agent to call `asc_setup_check`). It checks your key, Issuer ID, a live connection to App Store Connect, and your license, and prints the exact fix for anything wrong. In your agent, the `/asc-start` command walks a first-time user through all of this.
56
+
57
+ **Manual setup.** Add to your agent's MCP config (Claude Desktop config, or `~/.claude.json` for Claude Code). Use `npx` for zero-install, or `asc-mcp` if you installed globally:
39
58
 
40
59
  ```json
41
60
  {
42
61
  "mcpServers": {
43
62
  "appstore-connect": {
44
- "command": "asc-mcp",
63
+ "command": "npx",
64
+ "args": ["-y", "@pofky/asc-mcp"],
45
65
  "env": {
46
- "ASC_KEY_ID": "YOUR_KEY_ID",
47
- "ASC_ISSUER_ID": "YOUR_ISSUER_ID",
48
- "ASC_PRIVATE_KEY_PATH": "~/.appstore/AuthKey_XXXX.p8"
66
+ "ASC_ISSUER_ID": "YOUR_ISSUER_ID"
49
67
  }
50
68
  }
51
69
  }
52
70
  }
53
71
  ```
54
72
 
73
+ With the `.p8` in `~/.appstoreconnect/private_keys/`, `ASC_ISSUER_ID` is the only required env var (Key ID and key path are auto-detected). Add `ASC_LICENSE_KEY` to unlock Pro.
74
+
55
75
  **Step 3.** Ask your agent: "List my App Store Connect apps"
56
76
 
57
77
  Works with **Claude Code**, **Cursor**, **Windsurf**, **Cline**, and any MCP-compatible client.
@@ -62,6 +82,8 @@ Works with **Claude Code**, **Cursor**, **Windsurf**, **Cline**, and any MCP-com
62
82
 
63
83
  | Tool | What it does |
64
84
  |------|-------------|
85
+ | `asc_setup_check` | **Run first if anything's off.** Checks your key, Issuer ID, a live App Store Connect connection, and license tier, and prints the exact fix for each failure. |
86
+ | `asc_guide` | **Start here.** The in-agent playbook for every flow (first release, update, IAP, subscriptions, reviews, TestFlight, binary), with each manual App Store Connect website step flagged inline. See also [USER_GUIDE.md](USER_GUIDE.md) and [LIMITATIONS.md](LIMITATIONS.md). |
65
87
  | `list_apps` | List all your apps with name, bundle ID, SKU, platform |
66
88
  | `app_details` | Version history, build status, release state, dates |
67
89
  | `review_status` | Current review state with human-readable context |
@@ -81,10 +103,55 @@ Works with **Claude Code**, **Cursor**, **Windsurf**, **Cline**, and any MCP-com
81
103
  | `triage_reviews` | Pulls recent reviews and clusters them into 3 to 5 themes with counts, action buckets, and quotes, using MCP Sampling | Zero extra cost: your client's model does the clustering |
82
104
  | `draft_review_response` | Drafts a public reply to a single review in the review's locale, via Sampling. Elicits tone if your client supports it. Never auto-posts. | Apple guideline 1.2 respected; you paste into ASC yourself |
83
105
 
84
- **Coming next (Week 3):** rejection-risk scoring against the 2026 corpus (guideline 2.3 metadata, 4.0 design, privacy-AI 5.1.2).
106
+ ### Control & Ship (Pro)
107
+
108
+ These tools write to App Store Connect. Every outward-facing action (submit, release, upload binary) requires an explicit `confirm: true`, so nothing leaves your machine by accident.
109
+
110
+ | Tool | What it does |
111
+ |------|-------------|
112
+ | `create_version` | Create a new editable App Store version for your next release |
113
+ | `update_version_metadata` | Edit description, keywords, what's-new, promo text, URLs, app name, subtitle. Validates Apple's character limits and refuses over-limit writes |
114
+ | `upload_screenshots` | Upload screenshots for a device display type (reserve, upload, commit, with checksum) |
115
+ | `list_builds` | List recent builds and their processing state (VALID = ready) |
116
+ | `attach_build` | Attach a build to the editable version (defaults to newest processed build) |
117
+ | `submit_for_review` | Submit the version to App Review (modern reviewSubmissions flow). `confirm: true` required |
118
+ | `release_version` | Release an approved version to the public App Store. `confirm: true` required |
119
+ | `manage_phased_release` | Start, pause, resume, or complete the 7-day phased rollout |
120
+ | `list_beta_groups` | List your TestFlight beta groups |
121
+ | `assign_build_to_group` | Push a build to a beta group so testers can install it |
122
+ | `invite_beta_tester` | Invite an external tester by email and add them to a group |
123
+ | `set_app_metadata` | Set primary/secondary category, copyright, content-rights, and export-compliance (encryption) in one call |
124
+ | `set_app_price` | Set the base price by creating the price schedule (`price_usd: 0` for free), auto-equalized to all territories |
125
+ | `set_app_availability` | Make the app available in all App Store territories (or a subset), with auto-include for future ones |
126
+ | `set_review_contact` | Set the App Review contact and optional demo account on the version |
127
+ | `set_age_rating` | Set the v2 age-rating declaration (full content-descriptor set) |
128
+ | `set_privacy_nutrition` | Guidance + deep link for the App Privacy nutrition labels (not API-addressable) |
129
+ | `set_eu_trader_status` | Guidance + deep link for the EU DSA trader status (not API-addressable) |
130
+ | `create_iap` | Create a non-consumable/consumable IAP with localization, availability, and an auto-equalized price |
131
+ | `create_subscription` | Create a subscription group, sub, localization, availability, price, and free trial |
132
+ | `set_iap_review_screenshot` | Attach the App Review screenshot to a subscription or IAP |
133
+ | `setup_app_store_signing` | Download the app's App Store provisioning profiles and write a manual-signing `ExportOptions.plist` (works with a least-privilege API key) |
134
+ | `build_and_archive` | Build, archive, and export a signed `.ipa` via xcodebuild (needs Xcode on your Mac) |
135
+ | `upload_binary` | Upload the `.ipa` to App Store Connect via altool, using your API key. `confirm: true` required |
136
+
137
+ The whole flow chains: `setup_app_store_signing` to `build_and_archive` to `upload_binary` to `list_builds` (wait for VALID) to `attach_build` to `update_version_metadata` to `upload_screenshots` to `set_app_metadata`/`set_app_price`/`set_app_availability`/`set_age_rating`/`set_review_contact` to `release_preflight` to `submit_for_review` to `release_version`. The `/asc-ship-release` slash command drives it for you.
138
+
139
+ `release_preflight` is the single source of truth for "is this submittable": it checks every API-addressable field and ends with a tailored "Manual steps to finish" list for the few things Apple only allows in the website (first-IAP bundling, App Privacy nutrition labels, EU trader status).
85
140
 
86
141
  [Get Pro](https://buy.polar.sh/polar_cl_Ta3OxEA1EbRyYNPFtSsRXgYWBCCtjwMxlbAeW35RLuu) | [Retrieve your license key](https://asc-mcp-license.remewdy.workers.dev/key)
87
142
 
143
+ ## What stays manual (and why)
144
+
145
+ A handful of things Apple does not expose to API keys. The MCP never pretends otherwise: it either returns the exact website steps plus a deep link, or detects the case and aborts so nothing is half-done. Full detail in [LIMITATIONS.md](LIMITATIONS.md) (and `asc_guide topic:limitations`):
146
+
147
+ - **Create an app record / App Group.** `POST /v1/apps` is forbidden for API keys; do it once in the website.
148
+ - **App Privacy nutrition label.** Not in the API. `set_privacy_nutrition` returns the checklist plus a deep link.
149
+ - **EU DSA trader status.** Not in the API. `set_eu_trader_status` returns the steps. Legal decision.
150
+ - **An app's first IAPs/subscriptions.** Must be submitted with the version in the website; `submit_for_review` aborts rather than orphan the version. Later products submit via the API.
151
+ - **Certificate creation / cloud signing.** Least-privilege keys can't; `setup_app_store_signing` uses manual-signing profiles instead.
152
+ - **Compiling the binary.** Needs Xcode on your Mac (`build_and_archive` runs it locally).
153
+ - **Posting a public review reply.** `draft_review_response` writes it; you paste it in the website.
154
+
88
155
  ## How Sampling works (zero extra cost)
89
156
 
90
157
  `triage_reviews` and `draft_review_response` use the MCP Sampling primitive. When you call one of these tools, this server sends a `sampling/createMessage` request back to your own MCP client. Your client runs the LLM locally (Claude Desktop uses your account; Claude Code uses its session). We never call Anthropic from our side.
@@ -99,9 +166,12 @@ Type these in Claude Desktop or Claude Code and the agent runs a pre-built multi
99
166
 
100
167
  | Slash command | What it does |
101
168
  |---------------|--------------|
169
+ | `/asc-start` | New here? Verifies the connection, lists your apps, explains free vs Pro in plain language, and recommends your next step. No App Store Connect knowledge assumed. |
102
170
  | `/asc-weekly-review` | Calls `daily_briefing` then `list_reviews` (low-rating, last 7 days) for every app, clusters themes, returns a single digest with 3-bullet action list. |
103
171
  | `/asc-rejection-audit` | Given an `app_id`, calls `release_preflight` + `metadata_diff` + `review_status`, reads the result against the top 2026 rejection drivers (guideline 2.3 metadata, 4.0 design, privacy-AI 5.1.2). Produces Blocking / Likely-flagged / Safe sections. |
104
172
  | `/asc-release-go-no-go` | Given an `app_id`, combines preflight + review queue + metadata diff + top competitors in the same category. Returns a direct GO or NO-GO with three supporting reasons. |
173
+ | `/asc-ship-release` | Given an `app_id`, drives the full release: locate or create the editable version, push metadata, attach the newest build, upload screenshots, run preflight, then submit. Stops to confirm before every outward-facing step. |
174
+ | `/asc-first-app` | Given an `app_id`, drives a brand-new app's first 1.0 from existing app record to submitted, handling every first-time-only constraint and stopping at each manual website step (privacy label, trader status, first-IAP bundling). |
105
175
 
106
176
  These are MCP Prompts per the [spec](https://modelcontextprotocol.io/docs/concepts/prompts/). Zero other App Store Connect MCP ships with them.
107
177
 
@@ -181,7 +251,7 @@ Lead with the most impactful change. Keep under 4000 chars.
181
251
 
182
252
  | | Raw API wrappers (free) | This server |
183
253
  |---|---|---|
184
- | **Tool count** | 80 to 293 | 13 opinionated tools |
254
+ | **Tool count** | 80 to 293 | 36 opinionated tools (read + control) |
185
255
  | **MCP Prompts (slash commands)** | No | Yes, 3 pre-built workflows |
186
256
  | **MCP Sampling (zero server-side LLM cost)** | No | Yes, review triage + response drafts |
187
257
  | **Claude Skill bundled** | No | Yes, one-line install |
package/USER_GUIDE.md ADDED
@@ -0,0 +1,185 @@
1
+ <!-- GENERATED from src/tools/guide.ts by scripts/gen-docs.mjs. Do not edit by hand. -->
2
+
3
+ # App Store Connect MCP - Guide
4
+
5
+ Call `asc_guide` with a `topic` for the exact playbook. Manual steps (things no API can do) are flagged inline so you never get blocked mid-flow.
6
+
7
+ Topics:
8
+ - setup - one-time machine setup (.p8, init, config)
9
+ - first-app - ship a brand-new app's 1.0 (the hardest flow)
10
+ - update - ship an update to a live app
11
+ - screenshots - upload App Store screenshots
12
+ - iap - create a one-time in-app purchase
13
+ - subscriptions - create an auto-renewable subscription
14
+ - reviews - triage and reply to customer reviews
15
+ - testflight - distribute a beta
16
+ - binary - build, sign, upload the binary (needs Xcode)
17
+ - limitations - everything the API can't do + the manual workaround
18
+
19
+ Golden rule: when a step says MANUAL, stop and do it in the App Store Connect website (or Xcode). The agent should hand the user the deep link and exact steps, not pretend the API can do it.
20
+
21
+ Outward-facing tools (submit_for_review, release_version, upload_binary) require confirm:true. Always confirm with the human first.
22
+
23
+ ---
24
+
25
+ ## One-time setup
26
+
27
+ When: Before anything else, once per machine.
28
+
29
+ Steps:
30
+ 1. Create an API key: App Store Connect > Users and Access > Integrations > App Store Connect API > generate a key with the App Manager role. Download the .p8 (one time only).
31
+ 2. Drop the .p8 into ~/.appstoreconnect/private_keys/ (Apple's standard path). The 10-char Key ID is read from the filename, so that one file is enough.
32
+ 3. Run `asc-mcp init` in a terminal. It auto-detects the key, asks for your Issuer ID (the UUID at the top of the Integrations page) and an optional Pro license key, and prints a paste-ready MCP config block.
33
+ 4. Paste the block into your client config (~/.claude/settings.json, Claude Desktop config, Cursor, etc.) and restart the client.
34
+ 5. Verify with `list_apps`. If it returns your apps, you are connected.
35
+
36
+ Manual interruptions you must do yourself:
37
+ - MANUAL: generating the API key and downloading the .p8 is a one-time App Store Connect website action. The .p8 cannot be re-downloaded; if lost, revoke and make a new one.
38
+ - Free tier is read/intelligence only. Set ASC_LICENSE_KEY to unlock all write/control tools ($9/mo).
39
+
40
+ ---
41
+
42
+ ## Ship an app's FIRST release (1.0)
43
+
44
+ When: Brand-new app, never been on the store. The hardest flow because of first-time-only Apple constraints.
45
+
46
+ Steps:
47
+ MANUAL: the app RECORD must already exist. `POST /v1/apps` is forbidden for API keys, so create the app (name, bundle ID, SKU, primary language) once in App Store Connect > Apps > +. App Groups are portal-only too.
48
+ 1. `list_apps` to get the numeric app_id.
49
+ 2. Build + upload a binary so a build exists to attach (see topic:binary), or upload via Xcode/Transporter. Then `wait_for_build` until VALID.
50
+ 3. `set_app_metadata` - primary/secondary category, copyright, content rights, export compliance (most apps: uses_non_exempt_encryption=false).
51
+ 4. `set_app_price` - price_usd:0 for free, or a tier. Required before submit.
52
+ 5. `update_version_metadata` - description, keywords, what's-new (note: what's-new is NOT editable on a first 1.0 with no prior release; the tool drops it and reports it skipped), promo text, marketing/support/privacy-policy URLs, name, subtitle. Char limits validated.
53
+ 6. `set_app_availability` - defaults to all ~175 territories; pass a subset to restrict.
54
+ 7. `set_age_rating` - pass only the declarations that apply; the tool fetches, merges the full V2 set, and submits (it is NOT a partial PATCH).
55
+ 8. `set_review_contact` - name, phone, email, demo account if the app needs login. Required before submit.
56
+ 9. `attach_build` - newest VALID build by default.
57
+ 10. `upload_screenshots` per display type (at minimum APP_IPHONE_67; APP_IPHONE_65 + APP_IPAD recommended). See topic:screenshots.
58
+ MANUAL: App Privacy nutrition label. Not in the API. Run `set_privacy_nutrition` for the exact checklist + deep link, then set it in the ASC website.
59
+ MANUAL: EU DSA trader status. Not in the API. Run `set_eu_trader_status` for steps + deep link; it's a legal decision, set it in the website.
60
+ 11. If the app has in-app purchases or subscriptions, create them now (topic:iap / topic:subscriptions). The FIRST ones must be submitted WITH the version (next step).
61
+ 12. `release_preflight` - fix every FAIL it reports. It tailors a 'manual steps to finish' list to this app's state.
62
+ 13. MANUAL (if first IAPs exist): the app's very first in-app purchases CANNOT be bundled with the version via the API. In the ASC website, open the version, Add for Review, tick the products, and submit them together. `submit_for_review` detects this and ABORTS rather than orphaning the version. After the first release is live, later IAPs submit via the API fine.
63
+ 14. `submit_for_review` with confirm:true (only if there are no first-IAPs blocking; otherwise submit in the website per the step above).
64
+ 15. After approval: `release_version` (confirm:true) to go live now, or `manage_phased_release` start for a 7-day rollout.
65
+
66
+ Manual interruptions you must do yourself:
67
+ - App record + App Group creation - ASC website / Developer portal only.
68
+ - App Privacy nutrition label - ASC website only (`set_privacy_nutrition` gives the checklist).
69
+ - EU trader status - ASC website only, legal decision (`set_eu_trader_status` gives steps).
70
+ - First in-app purchases - must be submitted with the version in the ASC website; API cannot bundle them.
71
+ - Building the binary needs Xcode on a Mac (the API can't compile).
72
+
73
+ ---
74
+
75
+ ## Ship an UPDATE to an existing app
76
+
77
+ When: App is already live; you're releasing a new version. Much simpler than 1.0.
78
+
79
+ Steps:
80
+ 1. `app_details` to read current version + state.
81
+ 2. `create_version` with the next version number (e.g. 2.5.0) if there's no editable version yet.
82
+ 3. `update_version_metadata` - what's-new is editable now; update description/keywords/promo as needed.
83
+ 4. Upload the new build (`upload_binary` confirm:true, or Xcode/Transporter; see topic:binary), `wait_for_build` to VALID, then `attach_build`.
84
+ 5. `upload_screenshots` only if they changed.
85
+ 6. Later IAPs/subscriptions (not the first ever) can be created and will submit via the API.
86
+ 7. `release_preflight` - fix FAILs.
87
+ 8. `submit_for_review` confirm:true.
88
+ 9. After approval: `release_version` confirm:true, or `manage_phased_release` start.
89
+ 10. Use `metadata_diff` any time to see exactly what changed between live and pending across locales.
90
+
91
+ Manual interruptions you must do yourself:
92
+ - Still no API for nutrition label or trader status, but these persist from the first release; only revisit if your data practices changed.
93
+ - Building the binary still needs Xcode.
94
+
95
+ ---
96
+
97
+ ## Upload screenshots
98
+
99
+ When: Adding or replacing App Store screenshots.
100
+
101
+ Steps:
102
+ 1. Prepare PNG/JPEG files at the exact pixel size for the display type.
103
+ 2. `upload_screenshots` with display_type, an ordered files array, and locale. It runs Apple's 3-step reserve/PUT-chunks/commit flow for you.
104
+ 3. Common display types: APP_IPHONE_67 (6.7in, required), APP_IPHONE_65 (6.5in), APP_IPAD_PRO_129 (12.9in iPad).
105
+
106
+ Manual interruptions you must do yourself:
107
+ - Capturing the screenshots from a simulator is not yet automated (capture_screenshots is on the roadmap). Produce the PNGs yourself, then upload via the tool.
108
+ - Apple requires correct exact dimensions per display type or the commit fails.
109
+
110
+ ---
111
+
112
+ ## Create a one-time in-app purchase (non-consumable / consumable)
113
+
114
+ When: Selling a lifetime unlock, consumable credits, etc.
115
+
116
+ Steps:
117
+ 1. `create_iap` - product_id, reference name, display name (max 30), description (max 45), type, price_usd. It's idempotent: USA base price, auto-equalized across all territories, availability set. IAP state recomputes immediately on availability (unlike subscriptions, which need a nudge), so once price + availability + a review screenshot are set the product is READY_TO_SUBMIT.
118
+ 2. `set_iap_review_screenshot` - IAPs need an App Review screenshot to leave MISSING_METADATA. Upload one showing the paywall.
119
+ 3. For the FIRST IAP ever on the app: it must be submitted WITH the app version in the ASC website (see topic:first-app). After the first release is live, later IAPs submit via `submit_for_review`.
120
+
121
+ Manual interruptions you must do yourself:
122
+ - First non-consumable / first IAP on a brand-new app: submit it together with the version in the ASC website. API can't bundle the first one.
123
+ - IAP localization description is capped at 45 chars.
124
+
125
+ ---
126
+
127
+ ## Create an auto-renewable subscription
128
+
129
+ When: Recurring billing (monthly/yearly plans, free trials).
130
+
131
+ Steps:
132
+ 1. `create_subscription` - group ref + display name, product_id, names, description (max 45), period, price_usd, optional free_trial, review_note. It is idempotent and handles the gnarly order Apple requires: availability FIRST, then USA base price, then equalize across ~175 territories, then per-territory free-trial intro offers, then a final no-op PATCH to force the state to recompute to READY_TO_SUBMIT.
133
+ 2. `set_iap_review_screenshot` - subscriptions also need a review screenshot of the paywall.
134
+ 3. First subscriptions on a brand-new app submit WITH the version in the website; later ones via the API.
135
+
136
+ Manual interruptions you must do yourself:
137
+ - First subscriptions on a new app: submit with the version in the ASC website.
138
+ - Subscription state only recomputes on a subscription-level edit; create_subscription nudges it for you, but if you edit sub-resources by hand, expect a lag until a subscription PATCH.
139
+
140
+ ---
141
+
142
+ ## Triage and respond to customer reviews
143
+
144
+ When: Managing your App Store reputation.
145
+
146
+ Steps:
147
+ 1. `list_reviews` - filter by rating, sort, limit.
148
+ 2. `triage_reviews` - clusters recent reviews into 3-5 themes with counts and action buckets, using your own client's model via MCP Sampling (no extra cost from this server).
149
+ 3. `draft_review_response` - drafts a public reply in the review's locale. It NEVER auto-posts.
150
+ MANUAL: post the approved reply text in App Store Connect yourself (the API does not expose posting public responses).
151
+
152
+ Manual interruptions you must do yourself:
153
+ - Posting the public response is manual in the ASC website; the tool only drafts it.
154
+
155
+ ---
156
+
157
+ ## Distribute a TestFlight beta
158
+
159
+ When: Getting a build to testers before App Review.
160
+
161
+ Steps:
162
+ 1. Upload a build (topic:binary), `wait_for_build` to VALID.
163
+ 2. `list_beta_groups` to find or confirm a group.
164
+ 3. `assign_build_to_group` - newest VALID build by default.
165
+ 4. `invite_beta_tester` - email + name; Apple sends the TestFlight invite.
166
+
167
+ Manual interruptions you must do yourself:
168
+ - Beta App Review (for external groups' first build) and the test-information form may need a one-time touch in the ASC website.
169
+
170
+ ---
171
+
172
+ ## Build, sign, and upload the binary
173
+
174
+ When: You need a build on App Store Connect and want to do it from the agent.
175
+
176
+ Steps:
177
+ MANUAL: an Apple Distribution certificate must already exist in your login keychain. Certificate creation and cloud signing are not available to least-privilege API keys.
178
+ 1. `setup_app_store_signing` - downloads the app's IOS_APP_STORE provisioning profiles (app + extensions), installs them, and writes a manual-signing ExportOptions.plist. This sidesteps the cloud-signing permission most API keys lack.
179
+ 2. `build_and_archive` - xcodebuild archive + export using that ExportOptions.plist. Requires Xcode on this Mac. Give it the .xcodeproj/.xcworkspace, scheme, and the generated plist.
180
+ 3. `upload_binary` confirm:true - uploads the .ipa via altool with your API key.
181
+ 4. `wait_for_build` until the build is VALID, then `attach_build`.
182
+
183
+ Manual interruptions you must do yourself:
184
+ - Building requires the local Xcode toolchain; the API cannot compile.
185
+ - Distribution certificate must pre-exist in the keychain; API keys can't create certs or use cloud signing.
package/dist/client.d.ts CHANGED
@@ -8,6 +8,11 @@ export declare class ASCClient {
8
8
  constructor(config: ASCConfig);
9
9
  /** Make an authenticated GET request to the ASC API. */
10
10
  get<T>(path: string, params?: Record<string, string>): Promise<ASCResponse<T>>;
11
+ /** Make an authenticated write request (POST/PATCH/DELETE) to the ASC API. */
12
+ write<T>(method: "POST" | "PATCH" | "DELETE", path: string, body?: unknown): Promise<ASCResponse<T> | null>;
13
+ post<T>(path: string, body: unknown): Promise<ASCResponse<T> | null>;
14
+ patch<T>(path: string, body: unknown): Promise<ASCResponse<T> | null>;
15
+ del<T>(path: string): Promise<ASCResponse<T> | null>;
11
16
  /** Fetch all pages of a paginated response. */
12
17
  getAll<T>(path: string, params?: Record<string, string>, maxPages?: number): Promise<ASCResponse<T>>;
13
18
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAIzD;;;GAGG;AACH,qBAAa,SAAS;IACR,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAErC,wDAAwD;IAClD,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IA6BpF,+CAA+C;IACzC,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,SAAK,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAsCtG;;;OAGG;IACG,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;CAiCjE;AAED,qBAAa,WAAY,SAAQ,KAAK;IAE3B,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;gBAFZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM;CAMtB"}
1
+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAIzD;;;GAGG;AACH,qBAAa,SAAS;IACR,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAErC,wDAAwD;IAClD,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IA6BpF,8EAA8E;IACxE,KAAK,CAAC,CAAC,EACX,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,EACnC,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,OAAO,GACb,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IA4BjC,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO;IAGnC,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO;IAGpC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM;IAInB,+CAA+C;IACzC,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,SAAK,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAsCtG;;;OAGG;IACG,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;CAiCjE;AAED,qBAAa,WAAY,SAAQ,KAAK;IAE3B,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;gBAFZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM;CAUtB"}
package/dist/client.js CHANGED
@@ -33,6 +33,38 @@ class ASCClient {
33
33
  }
34
34
  return (await response.json());
35
35
  }
36
+ /** Make an authenticated write request (POST/PATCH/DELETE) to the ASC API. */
37
+ async write(method, path, body) {
38
+ const token = await (0, auth_js_1.getToken)(this.config.keyId, this.config.issuerId, this.config.privateKeyPath);
39
+ const response = await fetch(`${BASE_URL}${path}`, {
40
+ method,
41
+ headers: {
42
+ Authorization: `Bearer ${token}`,
43
+ "Content-Type": "application/json",
44
+ },
45
+ body: body === undefined ? undefined : JSON.stringify(body),
46
+ });
47
+ if (!response.ok) {
48
+ const errBody = await response.text();
49
+ throw new ASCAPIError(response.status, path, errBody);
50
+ }
51
+ // 204 No Content (typical for DELETE / some PATCH) has no JSON body.
52
+ if (response.status === 204)
53
+ return null;
54
+ const text = await response.text();
55
+ if (!text)
56
+ return null;
57
+ return JSON.parse(text);
58
+ }
59
+ post(path, body) {
60
+ return this.write("POST", path, body);
61
+ }
62
+ patch(path, body) {
63
+ return this.write("PATCH", path, body);
64
+ }
65
+ del(path) {
66
+ return this.write("DELETE", path);
67
+ }
36
68
  /** Fetch all pages of a paginated response. */
37
69
  async getAll(path, params, maxPages = 10) {
38
70
  const firstPage = await this.get(path, params);
@@ -98,7 +130,9 @@ class ASCAPIError extends Error {
98
130
  body;
99
131
  constructor(status, path, body) {
100
132
  const detail = tryParseErrorDetail(body);
101
- super(`ASC API error ${status} on ${path}: ${detail}`);
133
+ const hint = friendlyHint(status, body);
134
+ super(`ASC API error ${status} on ${path}: ${detail}` +
135
+ (hint ? `\n\nWhat this usually means: ${hint}` : ""));
102
136
  this.status = status;
103
137
  this.path = path;
104
138
  this.body = body;
@@ -106,6 +140,29 @@ class ASCAPIError extends Error {
106
140
  }
107
141
  }
108
142
  exports.ASCAPIError = ASCAPIError;
143
+ /**
144
+ * Translate Apple's terse HTTP errors into something a newcomer can act on.
145
+ * Returns "" when the raw detail is already clear enough (e.g. validation 422s
146
+ * carry their own message).
147
+ */
148
+ function friendlyHint(status, body) {
149
+ switch (status) {
150
+ case 401:
151
+ return "Authentication failed. Your Issuer ID, Key ID, or .p8 likely don't match. Re-check the Issuer ID (UUID on the Integrations page) and that the .p8 matches the Key ID. Run `asc-mcp doctor` to pinpoint it.";
152
+ case 403:
153
+ return "Your API key authenticated but lacks permission for this action. Its role is probably too low (needs App Manager or higher), or this specific capability (e.g. cloud signing, creating an app record) is not available to API keys at all. See `asc_guide topic:limitations`.";
154
+ case 404:
155
+ return "The resource wasn't found. Double-check the app_id / product_id (use `list_apps`), or the resource may not exist yet for this app.";
156
+ case 409:
157
+ return "State conflict: the version/product isn't in a state that allows this. For example, you can only edit/submit a version in PREPARE_FOR_SUBMISSION or a rejected state. Check current state with `app_details` or `review_status`.";
158
+ case 429:
159
+ return "Rate limited by Apple. Wait a minute and retry.";
160
+ default:
161
+ if (status >= 500)
162
+ return "App Store Connect had a server-side error. This is on Apple's end; retry shortly.";
163
+ return "";
164
+ }
165
+ }
109
166
  function tryParseErrorDetail(body) {
110
167
  try {
111
168
  const parsed = JSON.parse(body);
@@ -1 +1 @@
1
- {"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,28 @@
1
+ /**
2
+ * Self-diagnosis for setup. The #1 newbie failure mode is "it doesn't work" with
3
+ * no idea why: missing .p8, wrong Issuer ID, a key without the right role, or an
4
+ * unset license. `runDoctor` checks each link in the chain and, for every
5
+ * failure, prints the exact next step. Powers both `asc-mcp doctor` (CLI, runs
6
+ * before the server is even configured) and the free `asc_setup_check` MCP tool.
7
+ */
8
+ export type CheckStatus = "ok" | "warn" | "fail";
9
+ export interface DoctorCheck {
10
+ name: string;
11
+ status: CheckStatus;
12
+ detail: string;
13
+ fix?: string;
14
+ }
15
+ export interface DoctorReport {
16
+ checks: DoctorCheck[];
17
+ /** true when no check failed (warnings are allowed). */
18
+ healthy: boolean;
19
+ }
20
+ /**
21
+ * Run the full setup diagnosis. Reads env + the standard .p8 path, then attempts
22
+ * a real authenticated API call so "looks configured" and "actually works" are
23
+ * never confused.
24
+ */
25
+ export declare function runDoctor(): Promise<DoctorReport>;
26
+ /** Human-readable report for the CLI and the MCP tool. */
27
+ export declare function formatDoctor(report: DoctorReport): string;
28
+ //# sourceMappingURL=doctor.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAEjD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,wDAAwD;IACxD,OAAO,EAAE,OAAO,CAAC;CAClB;AASD;;;;GAIG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,YAAY,CAAC,CAqIvD;AAID,0DAA0D;AAC1D,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAazD"}