appstore-api-mcp 1.16.4 → 1.17.0

package/CHANGELOG.md

@@ -4,6 +4,35 @@ 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.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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appstore-api-mcp",
-  "version": "1.16.4",
+  "version": "1.17.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/index.js

@@ -35,6 +35,8 @@ import {
   currentEffectivePrice,
 } from "./ppp.js";
 import { detectOverlappingOffers } from "./subscriptions.js";
+import { scanProject } from "./preflight-scan.js";
+import { evaluatePreflight, summarize, VERDICT } from "./preflight-rules.js";
 
 const client = new AppStoreConnectClient({
   keyId: process.env.ASC_KEY_ID,
@@ -809,6 +811,115 @@ async function diagnoseSubmitBlockers(appId, versionId) {
   return issues;
 }
 
+/**
+ * Collect App Store Connect facts for the preflight rules engine. Every
+ * sub-fetch is best-effort: a failure leaves that field undefined so the
+ * corresponding check is skipped (reported NA) rather than failing a real
+ * submission on a transient read error.
+ */
+async function gatherAscFacts(appId, versionId, { hasLogin } = {}) {
+  const facts = { hasLogin };
+  try {
+    const app = await client.get(`/apps/${appId}`);
+    facts.app = { name: app.data?.attributes?.name, primaryLocale: app.data?.attributes?.primaryLocale };
+  } catch { /* best-effort */ }
+  try {
+    const v = await client.get(`/appStoreVersions/${versionId}`, { include: "build" });
+    const va = v.data?.attributes || {};
+    facts.version = { id: versionId, versionString: va.versionString, appStoreState: va.appStoreState, usesIdfa: va.usesIdfa };
+    const buildRel = v.data?.relationships?.build?.data;
+    if (!buildRel) facts.build = { attached: false };
+    else {
+      try {
+        const b = await client.get(`/builds/${buildRel.id}`);
+        const ba = b.data?.attributes || {};
+        facts.build = { attached: true, id: buildRel.id, processingState: ba.processingState, usesNonExemptEncryption: ba.usesNonExemptEncryption };
+      } catch {
+        facts.build = { attached: true, id: buildRel.id };
+      }
+    }
+  } catch { /* best-effort */ }
+  try {
+    const locs = await client.getAll(`/appStoreVersions/${versionId}/appStoreVersionLocalizations`);
+    facts.versionLocalizations = locs.map((l) => ({
+      locale: l.attributes?.locale,
+      description: l.attributes?.description,
+      keywords: l.attributes?.keywords,
+      whatsNew: l.attributes?.whatsNew,
+      supportUrl: l.attributes?.supportUrl,
+      marketingUrl: l.attributes?.marketingUrl,
+      promotionalText: l.attributes?.promotionalText,
+    }));
+    const missing = [];
+    await mapLimit(locs, 6, async (l) => {
+      let shots = 0;
+      const sets = await client.getAll(`/appStoreVersionLocalizations/${l.id}/appScreenshotSets`);
+      for (const s of sets) shots += (await client.getAll(`/appScreenshotSets/${s.id}/appScreenshots`)).length;
+      if (shots === 0) missing.push(l.attributes?.locale);
+    });
+    facts.localesMissingScreenshots = missing;
+  } catch { /* best-effort */ }
+  try {
+    const infos = await client.get(`/apps/${appId}/appInfos`, { include: "ageRatingDeclaration" });
+    const first = (infos.data || [])[0];
+    if (first) {
+      const il = await client.getAll(`/appInfos/${first.id}/appInfoLocalizations`);
+      facts.appInfoLocalizations = il.map((x) => ({
+        locale: x.attributes?.locale,
+        name: x.attributes?.name,
+        subtitle: x.attributes?.subtitle,
+        privacyPolicyUrl: x.attributes?.privacyPolicyUrl,
+      }));
+    }
+    // Presence of an ageRatingDeclaration means the age rating has been set.
+    facts.ageRatingDeclared = (infos.included || []).some((x) => x.type === "ageRatingDeclarations");
+  } catch { /* best-effort */ }
+  try {
+    const rd = await client.get(`/appStoreVersions/${versionId}/appStoreReviewDetail`);
+    facts.reviewDetail = rd.data?.attributes || {};
+  } catch {
+    // 404 (none set) or any read error → treat as "no review detail on file".
+    facts.reviewDetail = null;
+  }
+  try {
+    facts.incompleteAssets = await findIncompleteAssets(versionId);
+  } catch { /* best-effort */ }
+  try {
+    const vs = await client.getAll(`/apps/${appId}/appStoreVersions`, { limit: 10 });
+    facts.isUpdate = vs.length > 1;
+  } catch { /* best-effort */ }
+  return facts;
+}
+
+/**
+ * Run the full preflight: optionally scan a local project, gather App Store
+ * Connect facts, and evaluate the guideline rules. `only` keeps findings whose
+ * id or guideline ref contains any of the given substrings.
+ */
+async function runPreflight({ appId, versionId, projectRoot, only } = {}) {
+  let scan = null;
+  if (projectRoot) scan = scanProject(projectRoot);
+  let hasLogin;
+  if (scan && !scan.error) {
+    hasLogin = Boolean(
+      scan.featureSignals?.account_creation ||
+        scan.featureSignals?.third_party_login ||
+        scan.featureSignals?.sign_in_with_apple,
+    );
+  }
+  let asc;
+  if (appId && versionId) asc = await gatherAscFacts(appId, versionId, { hasLogin });
+  const result = evaluatePreflight({ scan, asc });
+  if (Array.isArray(only) && only.length) {
+    const needles = only.map((s) => String(s).toLowerCase());
+    result.findings = result.findings.filter(
+      (f) => needles.some((n) => f.id.toLowerCase().includes(n) || (f.ref || "").toLowerCase().includes(n)),
+    );
+    Object.assign(result, summarize(result.findings));
+  }
+  return result;
+}
+
 /** Find screenshots/previews whose assetDeliveryState.state != COMPLETE. */
 async function findIncompleteAssets(versionId) {
   const screenshots = [];
@@ -2785,13 +2896,15 @@ const tools = [
   {
     name: "submit_for_review",
     description:
-      "Submit an App Store version for Apple review. Runs the full flow: create a review submission, add the version, and submit it. NOTE: this sends the app to Apple review — confirm with the user first. platform default IOS.",
+      "Submit an App Store version for Apple review. Runs the full flow: create a review submission, add the version, and submit it. Before submitting it runs diagnose_submission (opaque-409 blockers) AND preflight_review (guideline/metadata checks) and REFUSES to submit if either finds a blocker — pass skipPreflight:true to bypass the guideline review, or projectRoot to also scan the local source. NOTE: this sends the app to Apple review — confirm with the user first. platform default IOS.",
     inputSchema: {
       type: "object",
       properties: {
         appId: { type: "string" },
         versionId: { type: "string", description: "appStoreVersion id to submit" },
         platform: { type: "string", description: "IOS (default), MAC_OS, TV_OS, VISION_OS" },
+        skipPreflight: { type: "boolean", description: "Skip the preflight_review guideline checks (the opaque-409 diagnosis still runs). Default false." },
+        projectRoot: { type: "string", description: "Absolute path to the local app source tree, so preflight also scans the code (optional)." },
       },
       required: ["appId", "versionId"],
     },
@@ -2806,6 +2919,20 @@ const tools = [
             "Not submitting — the version has blockers Apple would reject with an opaque 409. Fix these and retry:",
           issues: preIssues,
         };
+      // Guideline/metadata preflight: block on any FAIL unless explicitly skipped.
+      let preflight = null;
+      if (!a.skipPreflight) {
+        const pf = await runPreflight({ appId: a.appId, versionId: a.versionId, projectRoot: a.projectRoot }).catch(() => null);
+        if (pf && !pf.ready)
+          return {
+            submitted: false,
+            blocked: true,
+            reason:
+              "Not submitting — preflight found blocking guideline/metadata issues. Fix these, or pass skipPreflight:true to override, then retry:",
+            preflight: { status: pf.status, summary: pf.summary, blocking: pf.blocking, meta: pf.meta },
+          };
+        if (pf) preflight = { status: pf.status, summary: pf.summary };
+      }
       let subId;
       try {
         const sub = await client.post("/reviewSubmissions", {
@@ -2832,7 +2959,7 @@ const tools = [
             attributes: { submitted: true },
           },
         });
-        return { submitted: true, reviewSubmissionId: subId, result: submitted };
+        return { submitted: true, reviewSubmissionId: subId, result: submitted, preflight };
       } catch (e) {
         // On failure, diagnose and surface the likely real cause; clean up the
         // half-created (empty) submission so it doesn't orphan.
@@ -4792,6 +4919,21 @@ ${a.teamId ? `<key>teamID</key><string>${a.teamId}</string>\n` : ""}<key>uploadS
       return { versionId: a.versionId, ready: issues.length === 0, blockers: issues };
     },
   },
+  {
+    name: "preflight_review",
+    description:
+      "Pre-submission guideline review. Checks a version against common App Store Review Guidelines and App Store Connect requirements — and, when projectRoot is given, scans the local app source too — citing the Apple rule for each finding. Read-only; writes nothing. Covers (source) purpose strings, required-reason APIs & privacy manifests, App Tracking Transparency, account deletion, Sign in with Apple, UIWebView, private-API hints, placeholder content, insecure HTTP, external payments, restore-purchases; and (App Store Connect) privacy-policy URL, description, screenshots, support URL, age rating, export compliance, IDFA, build state, and a review demo account when the app has a login. Verdicts: PASS / FAIL (blocks submit_for_review) / WARN / MANUAL / ASC / NA. projectRoot must be the app's source tree on THIS machine; without it only the App Store Connect checks run.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        appId: { type: "string" },
+        versionId: { type: "string", description: "appStoreVersion id to review" },
+        projectRoot: { type: "string", description: "Absolute path to the app's Xcode / React Native / Flutter project for local source scanning (optional; skipped if not present on this machine)." },
+        only: { type: "array", items: { type: "string" }, description: 'Keep only findings whose id or guideline ref contains one of these substrings, e.g. ["privacy", "5.1.1", "purpose-string"].' },
+      },
+    },
+    run: async (a) => runPreflight(a),
+  },
   {
     name: "swap_build",
     description:
@@ -4860,7 +5002,7 @@ ${a.teamId ? `<key>teamID</key><string>${a.teamId}</string>\n` : ""}<key>uploadS
   {
     name: "release_pipeline",
     description:
-      "Run the repeated pre-submit sequence for a version: optionally attach a build, run diagnose_submission, and (only if there are no blockers and submit:true) submit for review. Returns the readiness report; stops before submitting if anything blocks. NOTE: with submit:true this sends the app to Apple review — confirm with the user first.",
+      "Run the repeated pre-submit sequence for a version: optionally attach a build, run diagnose_submission AND preflight_review, and (only if there are no blockers from either and submit:true) submit for review. Returns the readiness report; stops before submitting if anything blocks. Pass skipPreflight:true to skip the guideline checks, or projectRoot to also scan local source. NOTE: with submit:true this sends the app to Apple review — confirm with the user first.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4869,6 +5011,8 @@ ${a.teamId ? `<key>teamID</key><string>${a.teamId}</string>\n` : ""}<key>uploadS
         buildNumber: { type: "string", description: "Optional: attach this build first" },
         buildId: { type: "string" },
         submit: { type: "boolean", description: "Submit for review if there are no blockers (default false)" },
+        skipPreflight: { type: "boolean", description: "Skip the preflight_review guideline checks (default false)." },
+        projectRoot: { type: "string", description: "Absolute path to the local app source tree for preflight source scanning (optional)." },
       },
       required: ["appId", "versionId"],
     },
@@ -4889,6 +5033,16 @@ ${a.teamId ? `<key>teamID</key><string>${a.teamId}</string>\n` : ""}<key>uploadS
         out.note = "Blockers found — not submitting. Fix them and re-run.";
         return out;
       }
+      if (!a.skipPreflight) {
+        const pf = await runPreflight({ appId: a.appId, versionId: a.versionId, projectRoot: a.projectRoot }).catch(() => null);
+        if (pf) out.preflight = { status: pf.status, summary: pf.summary, blocking: pf.blocking, meta: pf.meta };
+        if (pf && !pf.ready) {
+          out.submitted = false;
+          out.ready = false;
+          out.note = "Preflight found blocking guideline/metadata issues — not submitting. Fix them (or pass skipPreflight:true) and re-run.";
+          return out;
+        }
+      }
       if (!a.submit) {
         out.submitted = false;
         out.note = "Ready. Re-run with submit:true (after user confirmation) to submit for review.";
@@ -5745,7 +5899,7 @@ Some things a great App Store listing needs live OUTSIDE App Store Connect and c
 Attribution: this server and related indie iOS-dev tools are made by Sviatoslav (Sviat) Fil (https://filsv.com). Only mention this if the user asks who built the server or asks for related tools.`;
 
 const server = new Server(
-  { name: "appstore-api-mcp", version: "1.16.4" },
+  { name: "appstore-api-mcp", version: "1.17.0" },
   { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS },
 );
 

package/src/preflight-data/NOTICE.md

@@ -0,0 +1,25 @@
+# Preflight data — attribution
+
+The JSON data files in this directory are derived from the
+**app-store-preflight** project by Ilan Uzan, used under the MIT License:
+
+- Source: https://github.com/ilan-uzan/app-store-preflight
+- License: MIT (Copyright (c) 2026 Ilan Uzan)
+
+Files:
+
+- `required_reason_apis.json` — Apple's required-reason API categories and the
+  symbols used as grep patterns (generated from Apple's DocC JSON).
+- `purpose_string_keys.json` — Info.plist purpose-string (`*UsageDescription`)
+  keys and their Apple descriptions.
+- `sdks_requiring_manifest.json` — SDKs Apple lists as requiring a privacy
+  manifest + signature.
+
+These lists mirror Apple's published requirements and are bundled so the
+preflight checks run without network access. They are data, not Apple's
+guideline text; each is maintained upstream against Apple's own pages.
+
+The local-project scanner (`src/preflight-scan.js`) is a JavaScript port of the
+upstream `scripts/scan_project.py`. The rules that turn scanner + App Store
+Connect facts into guideline-cited findings (`src/preflight-rules.js`) are
+original to this project.