appstore-api-mcp 1.16.4 → 1.18.0

package/.env.example

@@ -35,3 +35,13 @@ ASC_PRIVATE_KEY_PATH=/absolute/path/to/AuthKey_XXXXXXXXXX.p8
 # APPSTORE_MCP_SNAPSHOT_DIR=
 # Optional: auto-snapshot an app's text metadata before the first listing edit (a safety net for "revert")
 # APPSTORE_MCP_AUTO_SNAPSHOT=true
+
+# --- Retention Messaging API (optional; separate, access-gated StoreKit API) ---
+# Runs on api.storekit.apple.com, NOT the App Store Connect host. Needs the
+# Retention Messaging API entitlement (apply: developer.apple.com/contact/request/retention-messaging-api)
+# and typically an In-App Purchase key (Users and Access → Integrations → In-App Purchase).
+# If these are unset, the retention_* tools reuse the ASC_* key above.
+# RETENTION_KEY_ID=
+# RETENTION_ISSUER_ID=
+# RETENTION_PRIVATE_KEY_PATH=./secrets/RetentionKey_XXXXXXXXXX.p8
+# RETENTION_BUNDLE_ID=technology.fil.SpeakerMate   # default app; tools also take a per-call bundleId

package/CHANGELOG.md

@@ -4,6 +4,58 @@ 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.18.0] - 2026-11-05
+
+### Added — Retention Messaging (subscription cancellation flow)
+- Tools for Apple's new **Retention Messaging API** (announced 2026-11-04):
+  `retention_doctor`, `retention_upload_message`, `retention_list_messages`,
+  `retention_delete_message`, `retention_set_default_message`,
+  `retention_get_default_message`, `retention_delete_default_message`,
+  `retention_set_realtime_url`, `retention_get_realtime_url`,
+  `retention_delete_realtime_url`, and a `retention_request` escape hatch.
+- This is a **separate, access-gated API** on `api.storekit.apple.com` (not the
+  App Store Connect host), so it ships as a dedicated `StoreKitClient` (ES256
+  JWT, App Store Server API style, per-app `bid`). Configure with `RETENTION_*`
+  env (an In-App Purchase key) or it reuses the `ASC_*` key; every call takes a
+  `bundleId`, and `sandbox:true` targets the sandbox host. Writes respect
+  read-only mode. Message text is validated against Apple's limits (header ≤66,
+  body ≤144, ≤5 bullets ≤66) before upload.
+- **Access required:** the Retention Messaging API is entitlement-gated (apply at
+  developer.apple.com/contact/request/retention-messaging-api); without it Apple
+  returns `404`. The real-time per-subscriber callback is the developer's own
+  server, not a tool here. A couple of request-body field names and the exact
+  key type are pending live verification once access is granted; the hosts and
+  endpoint paths were confirmed to respond (401 without auth).
+
+## [1.17.0] - 2026-10-31
+
+### Added
+- **Preflight guideline review before every submission.** A new read-only
+  `preflight_review` tool checks a version against common App Store Review
+  Guidelines and App Store Connect requirements, citing the Apple rule for each
+  finding and returning a `PASS / FAIL / WARN / MANUAL / ASC / NA` verdict with
+  evidence and a fix.
+  - *App Store Connect checks* (need `appId` + `versionId`): privacy-policy URL,
+    description and support URL per locale, screenshots per locale, media still
+    processing, age rating, build attached & VALID, per-build export compliance,
+    IDFA declaration, and a review demo account / notes when the app has a login.
+  - *Local source checks* (pass `projectRoot`, the app's source tree on this
+    machine): purpose strings for permission APIs, required-reason APIs declared
+    in a privacy manifest, SDKs that need a manifest, App Tracking Transparency,
+    account creation without in-app account deletion, Sign in with Apple,
+    deprecated `UIWebView`, private-API hints, placeholder content, insecure
+    HTTP, external payment SDKs, Restore Purchases, and the export-compliance key.
+- `submit_for_review` and `release_pipeline` now run preflight automatically and
+  **refuse to submit when any finding is FAIL**. New `skipPreflight` (bypass the
+  guideline review; the opaque-409 diagnosis still runs) and `projectRoot`
+  (also scan local source) options on both.
+
+The local scanner is a zero-dependency JavaScript port of the scanner from the
+MIT-licensed [app-store-preflight](https://github.com/ilan-uzan/app-store-preflight)
+project by Ilan Uzan; the bundled required-reason / purpose-string / SDK data
+lists come from the same project (see `src/preflight-data/NOTICE.md`). The rules
+that turn facts into guideline-cited verdicts are original to this project.
+
 ## [1.16.4] - 2026-10-08
 
 ### Fixed

package/README.md

@@ -264,7 +264,8 @@ Full parameter reference: **[docs/TOOLS.md](docs/TOOLS.md)**.
 | `list_app_preview_sets` / `list_app_previews` / `get_app_preview` / `create_app_preview_set` / `upload_app_preview` / `delete_app_preview` | 🎬 **App preview videos** — list, inspect (incl. `videoUrl`), upload, delete |
 | `audit_apps` | 🩺 **Fleet ASO audit** — scan all apps for missing subtitle/keywords/description, under-used keyword field, single-locale listings, missing screenshots. Read-only |
 | `apps_review_status` | 🗂️ **Fleet review board** — every app's current version + state (waiting / in-review / rejected / ready) in one call |
-| `submit_for_review` / `release_version` / `set_phased_release` | 🚀 Submit a version to Apple review (full flow), release an approved build, and control phased rollout |
+| `submit_for_review` / `release_version` / `set_phased_release` | 🚀 Submit a version to Apple review (full flow, **gated by preflight**), release an approved build, and control phased rollout |
+| `preflight_review` | 🛫 **Pre-submission guideline review** — checks the version (and, with `projectRoot`, the local source) against App Store Review Guidelines + App Store Connect requirements, citing the Apple rule for each finding. `submit_for_review` blocks on any `FAIL`. Read-only |
 | `doctor` | 🩺 Diagnose setup: Node, creds, key works, role capabilities, vendor number, Mac build tools, write mode |
 | `snapshot_app_metadata` / `diff_app_metadata_snapshot` / `restore_app_metadata` / `restore_screenshots` / `restore_app_previews` | 💾 Back up / compare / restore an app's metadata. Text always saved; `includeScreenshots:true` and `includePreviews:true` also download the images/videos so **deleted screenshots and previews can be re-uploaded**. Set `APPSTORE_MCP_AUTO_SNAPSHOT=true` to auto-snapshot text before the first edit |
 | `release_readiness_check` | ✅ One-call **go/no-go report** — build, metadata, ASO, screenshots, compliance, TestFlight, reviews |
@@ -453,6 +454,11 @@ filling out a listing.
 
 Built by **Sviatoslav (Sviat) Fil** — [filsv.com](https://filsv.com) — indie iOS apps & developer tools.
 
+The `preflight_review` tool's local-project scanner and its required-reason /
+purpose-string / SDK data lists are derived from the MIT-licensed
+**[app-store-preflight](https://github.com/ilan-uzan/app-store-preflight)**
+project by Ilan Uzan (see [`src/preflight-data/NOTICE.md`](src/preflight-data/NOTICE.md)).
+
 ## License
 
 MIT © Sviatoslav Fil — see [LICENSE](LICENSE).

package/docs/RECIPES.md

@@ -35,6 +35,20 @@ blockers first.
 
 Uses: `release_readiness_check` (single call), or the individual tools.
 
+For a **guideline/metadata** review (not just completeness), add `preflight_review`
+— it cites the App Store Review Guideline for each finding and marks blocking
+`FAIL`s. Pass `projectRoot` to also scan the local source (purpose strings,
+privacy manifests, account deletion, ATT, UIWebView, …):
+
+```text
+Run a preflight review for AppName v1.4.0 against the App Store guidelines. My
+Xcode project is at /path/to/AppName. Show the status, every FAIL with its
+Apple rule and fix, then the warnings.
+```
+
+Uses: `preflight_review` (read-only). `submit_for_review` runs this automatically
+and refuses to submit on any `FAIL`.
+
 <details><summary>Example output (fake data)</summary>
 
 | Area | Status | Detail |
@@ -65,6 +79,11 @@ Uses: `list_builds`, `list_beta_groups`, `list_beta_testers`,
 `add_build_to_beta_group`, `submit_beta_review`, `submit_for_review`,
 `release_version`, `set_phased_release`. **Stops at each human gate.**
 
+> At gate (4), `submit_for_review` runs `diagnose_submission` **and**
+> `preflight_review` first and refuses to submit on any `FAIL`. Pass
+> `projectRoot` to also scan the local source, or `skipPreflight:true` to bypass
+> the guideline review (the opaque-409 diagnosis still runs).
+
 ## 4. Customer reviews → release notes loop
 
 ```text

package/docs/TOOLS.md

@@ -319,8 +319,11 @@ Fleet review-status board across all (or selected) apps. Read-only.
 
 ### submit_for_review
 Submits a version to Apple review (create submission → add version → submit).
-**Sends the app to review — confirm first.**
+Runs `diagnose_submission` **and** `preflight_review` first and refuses to submit
+if either finds a blocker. **Sends the app to review — confirm first.**
 - `appId` **(required)**, `versionId` **(required)**, `platform` (default IOS)
+- `skipPreflight` — bypass the guideline review (the 409 diagnosis still runs)
+- `projectRoot` — also scan the local source during preflight
 
 ### release_version
 Release an approved version waiting for manual release (PENDING_DEVELOPER_RELEASE).
@@ -593,11 +596,50 @@ already in review.
 
 ### Diagnostics & orchestrators
 - `diagnose_submission(appId, versionId)` — read-only: the exact blockers behind submit's 409.
+- `preflight_review(appId?, versionId?, projectRoot?, only?)` — read-only guideline/metadata review (see below).
 - `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.
+- `release_pipeline(appId, versionId, buildNumber?, submit?, skipPreflight?, projectRoot?)` — attach → diagnose → **preflight** → (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.
 
+## Preflight — App Store guideline review
+
+A pre-submission review that checks an app against common **App Store Review
+Guidelines** and **App Store Connect** requirements, citing the Apple rule for
+each finding. Inspired by (and partly ported from) the MIT-licensed
+[app-store-preflight](https://github.com/ilan-uzan/app-store-preflight) project.
+
+### `preflight_review`
+Read-only; writes nothing.
+- `appId`, `versionId` — the version to review (runs the App Store Connect checks).
+- `projectRoot` — absolute path to the app's local source tree (Xcode / React
+  Native / Flutter). When given, the code is scanned too; when omitted, only the
+  App Store Connect checks run. The path must be on the machine the server runs on.
+- `only` — array of substrings; keep only findings whose id or guideline ref matches
+  (e.g. `["privacy", "5.1.1", "purpose-string"]`).
+- **Returns:** `{ status, ready, summary, blocking, findings, meta }`. Each finding has
+  `{ id, verdict, ref, url, title, detail, evidence?, fix? }`.
+
+**Verdicts:** `PASS` · `FAIL` (blocks `submit_for_review`) · `WARN` · `MANUAL`
+(only the developer can confirm) · `ASC` · `NA`.
+
+**What it checks**
+
+- *Local source (needs `projectRoot`):* purpose strings for permission APIs
+  (camera, mic, location, contacts, calendar, HealthKit, …); required-reason APIs
+  declared in a privacy manifest; SDKs that need a manifest; App Tracking
+  Transparency; account creation without in-app account deletion; Sign in with
+  Apple; deprecated `UIWebView`; private-API hints; placeholder content; insecure
+  HTTP; external payment SDKs; Restore Purchases; export-compliance key.
+- *App Store Connect (needs `appId` + `versionId`):* privacy-policy URL,
+  description and support URL per locale, screenshots per locale, media still
+  processing, age rating, build attached & VALID, per-build export compliance,
+  IDFA declaration, and a review demo account / notes when the app has a login.
+
+`submit_for_review` and `release_pipeline` run this automatically and **refuse to
+submit when any finding is FAIL** — pass `skipPreflight:true` to bypass the
+guideline review (the opaque-409 diagnosis still runs).
+
 ## Build & ship (macOS + Xcode)
 
 These run local Xcode tooling, so they only work on a Mac with Xcode installed.
@@ -667,6 +709,27 @@ you to create the record in the web UI. Same options as `bootstrap_ios_cicd`.
 
 ---
 
+## Retention Messaging (subscription cancellation flow)
+
+Messages/offers shown when a subscriber moves to cancel. ⚠️ **This is a separate,
+access-gated API** on `api.storekit.apple.com` (not the App Store Connect host).
+It needs the **Retention Messaging API entitlement** (apply at
+[developer.apple.com/contact/request/retention-messaging-api](https://developer.apple.com/contact/request/retention-messaging-api))
+and typically an **In-App Purchase key** (`RETENTION_*` env; otherwise the `ASC_*`
+key is reused). Every call takes the app's **`bundleId`**. Without access, Apple
+returns `404`. The real-time per-subscriber callback is **your own server**, not a tool here.
+
+- `retention_doctor(bundleId?)` — **start here**: checks key config and probes whether your account has access.
+- `retention_upload_message(bundleId, header, body, bulletPoints?, image?, …)` — create a message (header ≤66, body ≤144, ≤5 bullets ≤66; PENDING until App Review).
+- `retention_list_messages(bundleId)`, `retention_delete_message(bundleId, messageId)`
+- `retention_set_default_message(bundleId, productId, locale, messageId)` — "assign" a default per product+locale; `retention_get_default_message`, `retention_delete_default_message`
+- `retention_set_realtime_url(bundleId, url)` — register your real-time endpoint (prod needs Apple's performance test first); `retention_get_realtime_url`, `retention_delete_realtime_url`
+- `retention_request(bundleId, method, path, body?)` — escape hatch for any `/inApps/v1/messaging/*` endpoint (image upload, performance test, etc.)
+
+All retention tools take an optional `sandbox: true` to use `api.storekit-sandbox.apple.com`.
+
+---
+
 ## 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.16.4",
+  "version": "1.18.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": {

package/src/guardrails.js

@@ -93,6 +93,13 @@ export const WRITE_TOOLS = new Set([
   // snapshots
   "restore_app_metadata",
   "restore_screenshots",
+  // retention messaging (StoreKit host)
+  "retention_upload_message",
+  "retention_delete_message",
+  "retention_set_default_message",
+  "retention_delete_default_message",
+  "retention_set_realtime_url",
+  "retention_delete_realtime_url",
 ]);
 
 // High-impact categories with their own opt-out env flags.
@@ -109,9 +116,9 @@ export function envBool(value, dflt = false) {
   return /^(1|true|yes|on)$/i.test(String(value).trim());
 }
 
-/** Is this tool call a write? raw_request is a write unless the method is GET. */
+/** Is this tool call a write? raw_request / retention_request are writes unless GET. */
 export function isWriteTool(name, args = {}) {
-  if (name === "raw_request") {
+  if (name === "raw_request" || name === "retention_request") {
     const m = (args.method || "GET").toUpperCase();
     return m !== "GET";
   }