appstore-api-mcp 1.12.0 → 1.15.0

package/CHANGELOG.md

@@ -4,6 +4,91 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/) and the project uses
 [Semantic Versioning](https://semver.org/).
 
+## [1.15.0] - 2026-10-05
+
+### Added — submission flow (from 5 field reports of real submissions)
+- **Build ↔ version ↔ review loop** (the biggest gap; previously `raw_request`):
+  `attach_build_to_version`, `get_app_store_version` (incl. attached build),
+  `update_app_store_version` (`usesIdfa`, releaseType…), `update_build`
+  (per-build `usesNonExemptEncryption` export compliance; `expired`),
+  `expire_build`, `get_build`, `wait_for_build_processing`, `next_build_number`.
+- **Review submissions:** `list_review_submissions`, `get_review_submission`,
+  `add_review_submission_item`, `cancel_review_submission` (surfaces Apple's
+  "can't cancel empty/non-cancellable" cleanly), `get_app_store_review_detail`.
+- **TestFlight:** `get_beta_review_status`, `set_beta_build_notes` ("What to Test").
+- **Screenshots:** `find_incomplete_screenshots` (assets stuck != COMPLETE that
+  silently block submission), `reorder_screenshots`, `replace_screenshots` (bulk
+  delete + re-upload in order).
+- **Subscriptions:** `list_subscription_groups`, `list_subscriptions`,
+  `list_subscription_offers` (**flags overlapping offer date ranges** — the
+  sandbox `countMismatch` cause), `create_subscription_group`,
+  `create_subscription`, `create_in_app_purchase`.
+- **Territories:** `list_app_territories` (compact appAvailabilityV2 summary).
+- **Diagnostics & orchestrators:** `diagnose_submission` (the exact blockers
+  behind submit's opaque 409), `swap_build` (wait→cancel→attach), `release_pipeline`
+  (attach→diagnose→submit), `bulk_upsert_localizations` (version + app-info, all
+  locales, creates missing ones, whitespace preserved verbatim).
+
+### Fixed
+- `list_builds` ignored `limit` (it paged via `getAll`). Now returns a single
+  page capped to `limit`; added `version` / `processingState` filters.
+- `submit_for_review` now pre-flights and, on failure, surfaces the real blockers
+  (no attached build, build not VALID, unset export compliance / IDFA, assets
+  still processing) instead of Apple's opaque `409 ENTITY_STATE_INVALID`; cleans
+  up the half-created empty submission.
+- `create_app_info_localization` upserts instead of failing "already exists"
+  (Apple auto-creates the name/subtitle row with the version localization).
+- `release_readiness_check` now verifies a build is attached + VALID, checks
+  description/screenshots across **all** locales, and flags assets still processing.
+- `upload_screenshot` returns a compact result (dropped ~700 tokens of signed
+  upload URLs per image).
+- `list_app_store_version_localizations` gains `omitLongFields` (return lengths
+  instead of full description/promotionalText/whatsNew).
+- `list_analytics_reports` accepts `appId` (uses the app's newest report request)
+  instead of crashing on a missing `requestId`.
+
+## [1.14.0] - 2026-10-05
+
+### Added
+- **PPP regional pricing for IAPs & subscriptions.** Bulk-set in-app purchase and
+  subscription prices across ~174 territories from a US base price, scaled by
+  purchasing-power parity. Logic + the 175-country dataset are ported from the
+  MIT-licensed [appstore-ppp-prices](https://github.com/duceum/appstore-ppp-pricing-agent-skill).
+  - `list_purchasable_products` — IAPs (v2) + subscriptions with current US prices.
+  - `preview_ppp_prices` — read-only dry run: per-territory target table, scaled in
+    local currency via Apple's equalizations and snapped to each territory's real
+    price grid (ratio-preserving floors of 0.99 / 0.49).
+  - `apply_ppp_prices` — applies the prices (IAP = one atomic price-schedule POST;
+    subscriptions = per-territory with `preserveCurrentPrice` + future `startDate`,
+    clearing pending prices first). **Irreversible**: requires `confirm:true`, is
+    gated by `APPSTORE_MCP_ALLOW_PRICE_CHANGES` and read-only mode, and the docs
+    mandate previewing first.
+  - Per-tier coefficients use embedded defaults; override any tier (premium,
+    high_income, upper_middle, lower_middle, emerging) by passing a `coefficients`
+    map — the agent reasons about elasticity, no server-side LLM or extra key.
+  - New `client.getAllPages()` helper returns side-loaded `included` resources.
+
+## [1.13.0] - 2026-06-13
+
+### Added
+- **iOS CI/CD → TestFlight bootstrap.** Turn a new iOS app into a fastlane +
+  GitHub Actions → TestFlight pipeline in one call:
+  - `ensure_asc_app` — find the App Store Connect app record for a bundle id
+    (find-only; the public API has no `POST /apps`, so it returns guidance when
+    the record doesn't exist yet).
+  - `bootstrap_ios_cicd` — scaffold the 7 pipeline files (Gemfile, fastlane
+    Appfile/Fastfile/.gitignore/SETUP.md, two GitHub Actions workflows) into the
+    app's repo, auto-detecting `appDir`/`bundleId`/`teamId`/`scheme`/`target`
+    from the `.xcodeproj`. Commits to a branch or opens a PR. Xcode automatic
+    ("cloud") signing via `-allowProvisioningUpdates` — no `match` repo.
+  - `set_repo_ci_secrets` — push `ASC_KEY_ID` / `ASC_ISSUER_ID` / `ASC_KEY_P8`
+    (base64) to the repo's Actions secrets. The API key is read from this
+    server's own config, never passed as an argument or returned in output;
+    values are piped to `gh secret set` over stdin.
+  - `bootstrap_testflight` — one-call orchestrator running all three.
+  - GitHub operations shell out to the `gh` CLI (no extra token, no new
+    dependency). The bootstrap writers respect read-only / safe mode.
+
 ## [1.12.0] - 2026-06-03
 
 ### Added

package/README.md

@@ -422,6 +422,7 @@ More: **[docs/SECURITY.md](docs/SECURITY.md)**.
 | `401`/`403` errors | Wrong issuer/key id, wrong `.p8`, or the key's role lacks permission. |
 | `409` on metadata update | The version isn't in an editable state — create/select a `PREPARE_FOR_SUBMISSION` version. |
 | `npx` can't find the package | Ensure Node ≥ 18 and that the package name is published/correct. |
+| `SyntaxError: Unexpected token '&&='` or `npm … not to run on Node.js v14` at startup | `npx` is using an **old Node** still on your `PATH`, not your Node ≥ 18. Check with `npx node --version`. Fix: point `command` at an absolute modern npx (e.g. `/opt/homebrew/opt/node@22/bin/npx`) or add a `PATH` to the server's `env`. See [SETUP.md → multiple Node versions](docs/SETUP.md#multiple-node-versions-the-most-common-startup-crash). |
 | Tools don't appear | MCP servers load at client startup — restart the client / start a new session. |
 
 ---

package/docs/SETUP.md

@@ -112,3 +112,58 @@ Then set `ASC_PRIVATE_KEY_BASE64` instead of `ASC_PRIVATE_KEY_PATH`.
   Create or select a version in `PREPARE_FOR_SUBMISSION` state.
 - **Token/clock errors** — JWTs are time-based; make sure your system clock is correct.
 - **`npx` fails to resolve the package** — verify Node ≥ 18 and the published package name.
+
+### Multiple Node versions (the most common startup crash)
+
+> **Symptom:** the server fails to connect, and its logs show one of:
+> ```
+> npm v10.x is known not to run on Node.js v14.x
+> SyntaxError: Unexpected token '&&='
+> ```
+
+Having Node ≥ 18 *installed* isn't enough — `npx` has to actually **run on it**.
+If you have more than one Node on your machine (nvm, Homebrew, system Node, Xcode's
+bundled Node…), `npx` may resolve to an **old** one earlier on your `PATH`. Modern
+npm then crashes before the server ever reads your credentials, so it looks like an
+auth/config problem when it isn't.
+
+**Diagnose** — ask which Node `npx` actually uses (not just `node --version`):
+
+```bash
+npx node --version   # if this prints v14.x / anything < 18, that's the bug
+which -a node npx     # shows every node/npx on your PATH, in resolution order
+```
+
+**Fix — option A (recommended): pin an absolute, modern npx as the `command`.**
+Find it with `which npx` under your good Node (e.g. `/opt/homebrew/opt/node@22/bin/npx`),
+then use that full path instead of bare `npx`:
+
+```json
+{
+  "mcpServers": {
+    "appstore-api": {
+      "command": "/opt/homebrew/opt/node@22/bin/npx",
+      "args": ["-y", "appstore-api-mcp"],
+      "env": {
+        "ASC_KEY_ID": "YOUR_KEY_ID",
+        "ASC_ISSUER_ID": "YOUR_ISSUER_ID",
+        "ASC_PRIVATE_KEY_PATH": "/Users/you/.appstoreconnect/AuthKey_XXXXXXXXXX.p8"
+      }
+    }
+  }
+}
+```
+
+**Fix — option B: add a `PATH` to the server's `env`** so its child process resolves
+the right Node first (handy when `command` must stay as bare `npx`):
+
+```json
+"env": {
+  "ASC_KEY_ID": "YOUR_KEY_ID",
+  "ASC_ISSUER_ID": "YOUR_ISSUER_ID",
+  "ASC_PRIVATE_KEY_PATH": "/Users/you/.appstoreconnect/AuthKey_XXXXXXXXXX.p8",
+  "PATH": "/opt/homebrew/opt/node@22/bin:/opt/homebrew/bin:/usr/bin:/bin"
+}
+```
+
+After either fix, restart the client (or start a new session) so the server relaunches.

package/docs/TOOLS.md

@@ -352,6 +352,46 @@ The agent does the translating; this writes them.
 Creates a new price schedule from a price point. **Changes live pricing — confirm first.**
 - `appId` **(required)**, `baseTerritory` **(required)**, `pricePointId` **(required)**, `startDate` (YYYY-MM-DD, optional)
 
+## PPP regional pricing (IAP & subscriptions)
+
+Bulk-set **in-app purchase / subscription** prices across ~174 territories from a
+US base price, scaled by purchasing-power-parity (PPP). Distinct from
+`set_app_price` (which sets the paid-*app* price). The target price is scaled in
+each territory's **local currency** (via Apple's equalizations) and snapped to a
+real price-point on that territory's grid — not a dollar figure equalized to a
+coarse subset. Ported from the MIT-licensed
+[appstore-ppp-prices](https://github.com/duceum/appstore-ppp-pricing-agent-skill).
+
+> **Always `preview_ppp_prices` → show the user the table → `apply_ppp_prices`.**
+> Prices are customer-facing across ~174 territories and **cannot be undone.**
+
+Coefficients come from an embedded 175-country table (tiers: `premium`,
+`high_income`, `upper_middle`, `lower_middle`, `emerging`; USA is always the 1.00
+base). There is **no server-side LLM** — reason about the app's elasticity (games =
+high → discount poorer markets more; AI/productivity = low → discount less) and
+pass per-tier overrides. Floors: 0.99 (premium/high_income), 0.49 (others), with
+ratio preservation across multiple products.
+
+### list_purchasable_products
+Every IAP + subscription with its current US price, tagged `IAP`/`SUB`.
+- `appId` **(required)** — use the returned `productId` with the tools below.
+
+### preview_ppp_prices
+Dry run (read-only): the full per-territory price table without writing.
+- `appId`, `productId` **(required)**
+- `usPrice` (override the US base), `coefficients` (per-tier overrides, each 0.1–2.0),
+  `exclude` (territory codes, e.g. `["RUS","BLR"]`)
+
+### apply_ppp_prices
+Applies the prices. **Irreversible.** Requires `confirm:true`; blocked in read-only
+mode and when `APPSTORE_MCP_ALLOW_PRICE_CHANGES=false`.
+- `appId`, `productId`, `confirm:true` **(required)**
+- `usPrice`, `coefficients`, `exclude` (same as preview)
+- `preserveCurrentPrice` (subscriptions; default **true** — existing subscribers keep
+  their price), `startDate` (subscriptions; `YYYY-MM-DD`, default 2 days out)
+- IAPs are set in one atomic request; subscriptions per-territory (pending price
+  changes are cleared first).
+
 ## Product Page Optimization
 
 ### list_app_store_version_experiments
@@ -451,7 +491,7 @@ clear error):
 | --- | --- |
 | `APPSTORE_MCP_READ_ONLY=true` | block all writes |
 | `APPSTORE_MCP_ALLOW_RELEASE=false` | block `release_version` / `set_phased_release` |
-| `APPSTORE_MCP_ALLOW_PRICE_CHANGES=false` | block `set_app_price` |
+| `APPSTORE_MCP_ALLOW_PRICE_CHANGES=false` | block `set_app_price` / `apply_ppp_prices` |
 | `APPSTORE_MCP_ALLOW_REVIEW_REPLIES=false` | block public review replies |
 | `APPSTORE_MCP_ALLOW_EXTERNAL_TESTFLIGHT=false` | block `submit_beta_review` |
 
@@ -477,6 +517,46 @@ clear error):
 > See **[RECIPES.md](RECIPES.md)** for copy-paste prompts that chain these into
 > workflows (prepare-version, release-train-with-gates, review→notes, portfolio audit).
 
+## Submission flow (build ↔ version ↔ review)
+
+The steps a real submission needs beyond `submit_for_review` — attaching a build,
+fixing the silent blockers behind Apple's opaque `409`, and swapping a build that's
+already in review.
+
+### Build & version
+- `attach_build_to_version` — `versionId` + (`buildId` or `buildNumber`+`appId`). The mandatory pre-submit link.
+- `get_app_store_version(versionId)` — state, releaseType, `usesIdfa`, and the **attached build** (or null).
+- `update_app_store_version(versionId, …)` — `usesIdfa`, `releaseType`, `earliestReleaseDate`, `versionString`, `downloadable`.
+- `update_build` — `usesNonExemptEncryption` (export compliance, **per-build, doesn't carry over**), `expired`. By `buildId` or `buildNumber`+`appId`.
+- `expire_build`, `get_build`, `next_build_number(appId)`.
+- `wait_for_build_processing(appId, buildNumber, timeoutSeconds?)` — polls to VALID/INVALID/FAILED.
+
+### Review submissions
+- `list_review_submissions(appId, state?)`, `get_review_submission(id)`.
+- `add_review_submission_item(reviewSubmissionId, versionId)`.
+- `cancel_review_submission` — by `submissionId` or `appId` (current in-flight); optional `waitSeconds`. Surfaces Apple's refusal on empty/non-cancellable submissions.
+- `get_app_store_review_detail(versionId)` — contact info, demo account, notes.
+
+### TestFlight
+- `get_beta_review_status` (build's `betaReviewState`), `set_beta_build_notes(whatsNew, locale?)` ("What to Test", upsert).
+
+### Screenshots
+- `find_incomplete_screenshots(versionId)` — assets whose `assetDeliveryState != COMPLETE` (silent submit blockers).
+- `reorder_screenshots(screenshotSetId, orderedIds)` — new uploads append last, so re-order after re-upload.
+- `replace_screenshots(screenshotSetId, filePaths[])` — delete all + upload in order, one call.
+
+### Subscriptions
+- `list_subscription_groups(appId)`, `list_subscriptions(groupId)`.
+- `list_subscription_offers(subscriptionId)` — **flags overlapping offer date ranges** (the sandbox `countMismatch` cause).
+- `create_subscription_group`, `create_subscription`, `create_in_app_purchase`. (First-time products still need ticking for review on the version page — the API can't submit them.)
+
+### Diagnostics & orchestrators
+- `diagnose_submission(appId, versionId)` — read-only: the exact blockers behind submit's 409.
+- `swap_build(appId, versionId, buildNumber|buildId)` — wait for processing → cancel in-flight review → attach.
+- `release_pipeline(appId, versionId, buildNumber?, submit?)` — attach → diagnose → (if clean and `submit:true`) submit.
+- `bulk_upsert_localizations(versionId, { locale: {…} })` — version + app-info fields across all locales, creates missing ones; `dryRun` supported.
+- `list_app_territories(appId)` — compact availability summary.
+
 ## Build & ship (macOS + Xcode)
 
 These run local Xcode tooling, so they only work on a Mac with Xcode installed.
@@ -503,6 +583,49 @@ in `list_builds` and can be submitted with `submit_for_review`.
 
 ---
 
+## iOS CI/CD → TestFlight bootstrap
+
+Turn a new iOS app into a fastlane + GitHub Actions → TestFlight pipeline in one
+call. Signing is Xcode automatic ("cloud") signing via `-allowProvisioningUpdates`
+— no `match` repo. The GitHub side shells out to the `gh` CLI (install + `gh auth
+login` required; reuses your existing auth, no extra token). The App Store Connect
+API key lives only in this server's environment and is exposed only through these
+high-level actions — never as an argument, never in output.
+
+> Create the App Store Connect API key **once at the TEAM level** (App Store
+> Connect → Users and Access → Integrations) so the same three secret values work
+> for every app/repo.
+
+### ensure_asc_app
+Find the App Store Connect app record for a bundle id. **Find-only:** the public
+API cannot create app records (there is no `POST /apps`), so `created` is always
+`false`. If missing, returns `found:false` plus guidance (register the bundle id,
+create the record once in the web UI).
+- `bundleId` **(required)**, `name`, `sku`, `platform`, `primaryLocale`
+- **Returns:** `{ app_id, created, found, bundleId, name }`
+
+### bootstrap_ios_cicd
+Scaffold the 7 pipeline files (`Gemfile`, `fastlane/{Appfile,Fastfile,.gitignore,
+SETUP.md}`, `.github/workflows/{ios-ci.yml,ios-testflight.yml}`). Auto-detects
+`appDir`/`bundleId`/`teamId`/`scheme`/`target` from the repo's `.xcodeproj`.
+- `repoDir` (local clone, default `.`), `repo` (`owner/name` for the PR), `owner`
+- overrides: `appDir`, `bundleId`, `teamId`, `scheme`, `target`
+- `mode`: `pr` (default — branch + push + open PR), `branch`, `commit`, `files`
+- `branch`, `baseBranch`, `dryRun` (preview detected values + rendered files)
+
+### set_repo_ci_secrets
+Push `ASC_KEY_ID`, `ASC_ISSUER_ID`, `ASC_KEY_P8` (base64) to the repo's Actions
+secrets via `gh secret set` (values piped over stdin; `gh` does the libsodium
+sealed-box encryption). Key material is read from this server's env, never echoed.
+- `repo` (`owner/name`), `owner`, `repoDir` (derive `owner/name` from `origin`)
+
+### bootstrap_testflight
+One-call orchestrator: `ensure_asc_app` → `bootstrap_ios_cicd` → `set_repo_ci_secrets`.
+If the app record doesn't exist yet, it still scaffolds + sets secrets and tells
+you to create the record in the web UI. Same options as `bootstrap_ios_cicd`.
+
+---
+
 ## Rate limits
 
 App Store Connect allows ~3,500 requests/hour and returns `429` when exceeded.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appstore-api-mcp",
-  "version": "1.12.0",
+  "version": "1.15.0",
   "description": "MCP server for Apple App Store Connect — edit listings (keywords, descriptions, titles, screenshots), track analytics (downloads, proceeds, subscriptions, retention), run a fleet-wide ASO audit, preview changes with dry-run, and reach the full API. Works with any MCP client (Claude, Codex, Cursor, Windsurf, VS Code, Zed, Gemini CLI, Antigravity, Amazon Q, Goose, and more).",
   "type": "module",
   "bin": {