appstore-api-mcp 1.8.1 → 1.9.1

package/CHANGELOG.md

@@ -4,6 +4,25 @@ 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.9.1] - 2026-06-02
+
+### Added
+- **ASO research prompt pack** in `docs/RECIPES.md` — keyword expansion,
+  competitor positioning, and localized keyword spread, each ending in a dry-run
+  apply (the research is agent-side; App Store Connect exposes no competitor data).
+
+## [1.9.0] - 2026-06-02
+
+### Added
+- **`release_readiness_check`** — one-call go/no-go report (build, metadata, ASO,
+  screenshots, compliance, TestFlight, reviews).
+- **`aso_opportunity_report`** — ranked easiest ASO wins across apps.
+- **`portfolio_growth_report`** — units sold per app from a Sales report.
+- **TestFlight actions:** `add_build_to_beta_group`, `submit_beta_review`.
+- **`docs/RECIPES.md`** — copy-paste workflow prompts (prepare-version,
+  release-train-with-gates, readiness check, reviews→notes, portfolio operator,
+  build & ship), linked from the README.
+
 ## [1.8.1] - 2026-06-02
 
 ### Changed

package/README.md

@@ -50,7 +50,7 @@ whatever AI agent you already use.
 - [Getting your API key](#getting-your-api-key) → full guide in [docs/SETUP.md](docs/SETUP.md)
 - [Configuration](#configuration)
 - [Tools](#tools) → full reference in [docs/TOOLS.md](docs/TOOLS.md)
-- [What you can ask](#what-you-can-ask)
+- [What you can ask](#what-you-can-ask) — ready-made prompts in [docs/RECIPES.md](docs/RECIPES.md)
 - [Analytics & reports setup](docs/ANALYTICS.md) — roles, Vendor Number, examples
 - [Common workflows](#common-workflows)
 - [Security](#security) → details in [docs/SECURITY.md](docs/SECURITY.md)
@@ -245,6 +245,9 @@ Full parameter reference: **[docs/TOOLS.md](docs/TOOLS.md)**.
 | `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 |
+| `release_readiness_check` | ✅ One-call **go/no-go report** — build, metadata, ASO, screenshots, compliance, TestFlight, reviews |
+| `aso_opportunity_report` / `portfolio_growth_report` | 📈 Rank the easiest **ASO wins** across all apps; portfolio snapshot of units sold per app |
+| `add_build_to_beta_group` / `submit_beta_review` | ✈️ Assign a build to a TestFlight group; submit for beta review |
 | `get_sales_report` / `get_subscription_report` / `get_finance_report` | 📊 Units/downloads, proceeds, **subscriptions & retention**, earnings by region. Needs a Vendor Number + Admin/Finance/Sales key |
 | `request_analytics_report` → `list_analytics_reports` → `list_analytics_report_instances` → `get_analytics_report_data` | 📈 The async Analytics Reports API — downloads, sessions, active devices, App Store engagement |
 | `list_customer_reviews` / `reply_to_customer_review` | ⭐ Read reviews (filter by rating/territory, shows if you've replied) and post public replies |

package/docs/RECIPES.md

@@ -0,0 +1,126 @@
+# Recipes — copy-paste workflow prompts
+
+These are ready-made prompts you can paste into your agent. They chain the
+server's tools into real workflows. **Replace `AppName` / `1.4.0` with yours.**
+
+The agent does the reasoning (writing copy, ranking, deciding); the MCP does the
+App Store Connect work. Where a step changes live state (submit, release, post a
+review reply, invite a tester), these prompts tell the agent to **stop and ask
+first** — keep that discipline.
+
+---
+
+## 1. Prepare the next version
+
+```text
+Prepare version 1.4.0 for AppName. Use the current live listing as the baseline:
+create the new App Store version if it doesn't exist, draft "what's new" from
+these release notes/commits [paste here], audit the metadata, and propose ASO
+improvements (keywords, subtitle, promo text). Dry-run every edit and show me a
+diff table (field / current / proposed / why / limit) BEFORE writing anything.
+```
+
+Uses: `list_app_store_versions`, `create_app_store_version`,
+`update_app_store_version_localization` (with `dryRun`), `audit_apps`,
+`aso_opportunity_report`.
+
+## 2. Release readiness check
+
+```text
+Is AppName v1.4.0 ready to submit? Run a full readiness check and show a
+pass/warn/fail table covering build, metadata, ASO, screenshots, compliance
+(privacy policy, age rating), TestFlight, and recent low-star reviews. List the
+blockers first.
+```
+
+Uses: `release_readiness_check` (single call), or the individual tools.
+
+## 3. Release train — with approval gates
+
+```text
+Promote the latest processed build of AppName v1.4.0 to TestFlight internal
+testers. Do NOT submit to App Review or release to production without asking me
+first. Show me the build number, the beta groups, the tester count, and the exact
+action plan before changing anything. After I approve each gate, proceed to the
+next: (1) verify build processed → (2) add to internal beta group → (3) pause for
+my OK → (4) submit to App Review → (5) pause → (6) release or start phased rollout.
+```
+
+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.**
+
+## 4. Customer reviews → release notes loop
+
+```text
+Summarize recent 1–3 star reviews for AppName, cluster the complaints by theme,
+and suggest fixes to mention in the next release notes. Also draft polite public
+replies for reviews that mention bugs we've fixed — but do NOT post any reply
+without my approval.
+```
+
+Uses: `list_customer_reviews`, `reply_to_customer_review` (only after approval),
+`update_app_store_version_localization` (for the what's-new).
+
+## 5. Portfolio operator — weekly ASO wins
+
+```text
+Audit all my apps and rank the top 10 easiest ASO wins. For each, show app,
+issue, suggested fix, and rough effort (low/medium). Then pull last week's units
+per app so I can prioritize the wins on apps that actually get traffic.
+```
+
+Uses: `aso_opportunity_report`, `audit_apps`, `portfolio_growth_report`,
+`get_sales_report`.
+
+## 6. ASO research → dry-run apply
+
+The App Store Connect API has no competitor or keyword-volume data, so the
+**research** is the agent's job (web/app-page reading or an ASO API you have).
+This MCP handles reading your current listing and applying the result safely.
+
+**a) Keyword expansion**
+```text
+For AppName, show the current keyword field and how many of the 100 characters
+are used. Research 10–15 high-intent keywords for this app's category (use web
+search if available), pick the best set that fits 100 chars without duplicating
+words already in the title/subtitle, and dry-run the new keyword field so I can
+approve before it's written.
+```
+
+**b) Competitor positioning**
+```text
+Here are 3 competitors for AppName: [App A], [App B], [App C]. Look at their App
+Store titles, subtitles, and how they position the app. Compare to AppName's
+current title/subtitle/keywords, point out gaps, and propose an improved subtitle
+(<=30 chars) and keyword set. Dry-run the changes; don't write until I confirm.
+```
+
+**c) Localized keyword spread**
+```text
+AppName ranks only in en-US. Propose localized keyword sets for en-GB, en-CA, and
+en-AU that use each store's keyword field for *additional* terms (a known ASO
+trick — extra locales add searchable keywords). Dry-run a bulk localization update
+across those locales and show me the diff first.
+```
+
+Uses: `get_app_store_version_localization`, `list_app_info_localizations`,
+`update_app_store_version_localization` (with `dryRun`),
+`bulk_update_version_localizations`, `aso_opportunity_report`.
+
+## 7. Build & ship (Mac only)
+
+```text
+Bump AppName's build number, archive it, and upload the new build to App Store
+Connect. Tell me the new build number and confirm the upload succeeded. Don't
+submit for review yet.
+```
+
+Uses: `bump_build_number`, `archive_app`, `upload_build`, then `list_builds`.
+Requires macOS + Xcode and the project path.
+
+---
+
+> **Tip:** these are starting points — tweak the gates and outputs to taste. For a
+> first run, keep the "ask before any write" instruction so you can watch what the
+> agent proposes before it changes anything live.

package/docs/TOOLS.md

@@ -389,6 +389,28 @@ Lists certificates and provisioning profiles, flagging expired/expiring (within
 ### list_game_center_leaderboards / list_game_center_achievements
 - `appId` **(required)** — requires Game Center enabled on the app.
 
+## Recipes & aggregators (read-only)
+
+### release_readiness_check
+- `appId` **(required)** — returns `{ app, ready, verdict, summary, checks[] }` (each check has `area`, `status` pass/warn/fail/info, `detail`).
+
+### aso_opportunity_report
+- `appIds` (default all), `limit` — ranked `{ app, issue, fix, effort }` wins.
+
+### portfolio_growth_report
+- `reportDate` **(required)**, `frequency` (DAILY default) — units sold per app from a Sales report. Needs a Vendor Number + report-capable key.
+
+## TestFlight actions
+
+### add_build_to_beta_group
+- `betaGroupId` **(required)**, `buildId` **(required)** — makes the build available to that group's testers.
+
+### submit_beta_review
+- `buildId` **(required)** — submit for TestFlight external beta review.
+
+> See **[RECIPES.md](RECIPES.md)** for copy-paste prompts that chain these into
+> workflows (prepare-version, release-train-with-gates, review→notes, portfolio audit).
+
 ## 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.8.1",
+  "version": "1.9.1",
   "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

@@ -2065,6 +2065,206 @@ const tools = [
     },
   },
 
+  // ---- Recipes & aggregators (read-only) ----
+  {
+    name: "release_readiness_check",
+    description:
+      "A go/no-go readiness report for an app: latest build state, listing metadata completeness, ASO (subtitle, keyword usage), screenshots, compliance (privacy policy), TestFlight groups, and recent low-star reviews. Read-only — writes nothing. Great before submitting.",
+    inputSchema: {
+      type: "object",
+      properties: { appId: { type: "string" } },
+      required: ["appId"],
+    },
+    run: async (a) => {
+      const checks = [];
+      const add = (area, status, detail) => checks.push({ area, status, detail });
+      const app = await client.get(`/apps/${a.appId}`);
+      const primaryLocale = app.data.attributes.primaryLocale;
+      try {
+        const builds = await client.getAll(`/builds`, { "filter[app]": a.appId, sort: "-version", limit: 1 });
+        if (builds.length) {
+          const b = builds[0].attributes;
+          add("Build", b.processingState === "VALID" ? "pass" : "warn", `latest v${b.version} — ${b.processingState}`);
+        } else add("Build", "warn", "no builds uploaded");
+      } catch (e) { add("Build", "warn", e.message.slice(0, 60)); }
+
+      const versions = await client.getAll(`/apps/${a.appId}/appStoreVersions`, { limit: 5 });
+      const ed = versions.find((v) => EDITABLE_VERSION_STATES.has(v.attributes.appStoreState)) || versions[0];
+      add("Version", ed ? "info" : "warn", ed ? `v${ed.attributes.versionString} — ${ed.attributes.appStoreState}` : "no version");
+      if (ed) {
+        const locs = await client.getAll(`/appStoreVersions/${ed.id}/appStoreVersionLocalizations`);
+        const loc = locs.find((l) => l.attributes.locale === primaryLocale) || locs[0];
+        const at = (loc && loc.attributes) || {};
+        add("Description", at.description ? "pass" : "fail", at.description ? "present" : "missing");
+        const kw = (at.keywords || "").trim();
+        add("Keywords", kw ? (kw.length >= 70 ? "pass" : "warn") : "fail", kw ? `${kw.length}/100 chars` : "empty");
+        add("What's New", at.whatsNew ? "pass" : "warn", at.whatsNew ? "present" : "missing");
+        add("Support URL", at.supportUrl ? "pass" : "warn", at.supportUrl ? "set" : "missing");
+        if (loc) {
+          let shots = 0;
+          const sets = await client.getAll(`/appStoreVersionLocalizations/${loc.id}/appScreenshotSets`);
+          for (const s of sets) shots += (await client.getAll(`/appScreenshotSets/${s.id}/appScreenshots`)).length;
+          add("Screenshots", shots > 0 ? "pass" : "fail", `${shots} on ${loc.attributes.locale}`);
+        }
+      }
+      try {
+        const infos = await client.getAll(`/apps/${a.appId}/appInfos`);
+        if (infos.length) {
+          const il = await client.getAll(`/appInfos/${infos[0].id}/appInfoLocalizations`);
+          const ilc = il.find((x) => x.attributes.locale === primaryLocale) || il[0];
+          add("Subtitle", ilc?.attributes?.subtitle ? "pass" : "warn", ilc?.attributes?.subtitle ? "present" : "missing (free ASO keywords)");
+          add("Privacy policy", ilc?.attributes?.privacyPolicyUrl ? "pass" : "warn", ilc?.attributes?.privacyPolicyUrl ? "set" : "missing");
+        }
+      } catch { /* ignore */ }
+      try {
+        const groups = await client.getAll(`/apps/${a.appId}/betaGroups`);
+        add("TestFlight", groups.length ? "pass" : "info", `${groups.length} beta group(s)`);
+      } catch { /* ignore */ }
+      try {
+        const reviews = await client.getAll(`/apps/${a.appId}/customerReviews`, { sort: "-createdDate", limit: 50 });
+        const low = reviews.filter((r) => (r.attributes.rating ?? 5) <= 2).length;
+        add("Reviews", low > 0 ? "warn" : "pass", `${low} recent 1-2 star review(s)`);
+      } catch { /* may need higher role */ }
+
+      const summary = {
+        pass: checks.filter((c) => c.status === "pass").length,
+        warn: checks.filter((c) => c.status === "warn").length,
+        fail: checks.filter((c) => c.status === "fail").length,
+      };
+      const ready = summary.fail === 0;
+      return {
+        app: app.data.attributes.name,
+        ready,
+        verdict: ready ? (summary.warn ? "Ready (with warnings)" : "Ready") : "Not ready — has blocking gaps",
+        summary,
+        checks,
+      };
+    },
+  },
+  {
+    name: "aso_opportunity_report",
+    description:
+      "Rank the easiest ASO wins across your apps (or given appIds): missing subtitle, empty/under-used keyword field, single-locale listings — each with a suggested fix and rough effort. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        appIds: { type: "array", items: { type: "string" } },
+        limit: { type: "number", description: "Max apps to scan (default all)" },
+      },
+    },
+    run: async (a) => {
+      let apps = await client.getAll("/apps", { limit: 200 });
+      if (a.appIds?.length) apps = apps.filter((x) => a.appIds.includes(x.id));
+      if (a.limit) apps = apps.slice(0, a.limit);
+      const wins = [];
+      await mapLimit(apps, 6, async (app) => {
+        try {
+          const primaryLocale = app.attributes.primaryLocale;
+          const infos = await client.getAll(`/apps/${app.id}/appInfos`);
+          let subtitle = null;
+          if (infos.length) {
+            const il = await client.getAll(`/appInfos/${infos[0].id}/appInfoLocalizations`);
+            const ilc = il.find((x) => x.attributes.locale === primaryLocale) || il[0];
+            subtitle = ilc?.attributes?.subtitle;
+          }
+          const versions = await client.getAll(`/apps/${app.id}/appStoreVersions`, { limit: 5 });
+          const ed = versions.find((v) => EDITABLE_VERSION_STATES.has(v.attributes.appStoreState)) || versions[0];
+          if (!ed) return;
+          const locs = await client.getAll(`/appStoreVersions/${ed.id}/appStoreVersionLocalizations`);
+          const loc = locs.find((l) => l.attributes.locale === primaryLocale) || locs[0];
+          const kw = (loc?.attributes?.keywords || "").trim();
+          const name = app.attributes.name;
+          if (!subtitle) wins.push({ app: name, appId: app.id, issue: "no subtitle", fix: "write 3 subtitle options (<=30 chars)", effort: "low", score: 3 });
+          if (!kw) wins.push({ app: name, appId: app.id, issue: "empty keyword field", fix: "add researched keywords (up to 100 chars)", effort: "low", score: 3 });
+          else if (kw.length < 70) wins.push({ app: name, appId: app.id, issue: `keyword field ${kw.length}/100 chars`, fix: `add ~${Math.max(1, Math.round((100 - kw.length) / 12))} more terms`, effort: "low", score: 2 });
+          if (locs.length <= 1) wins.push({ app: name, appId: app.id, issue: "only one locale", fix: "add en-GB / en-CA or a major market", effort: "medium", score: 2 });
+        } catch { /* skip */ }
+      });
+      wins.sort((x, y) => y.score - x.score);
+      return { appsScanned: apps.length, opportunities: wins.length, top: wins.slice(0, a.limit || 25) };
+    },
+  },
+  {
+    name: "portfolio_growth_report",
+    description:
+      "Portfolio snapshot: recent units sold per app (aggregated from a Sales & Trends report). Needs a Vendor Number + report-capable key. Read-only. reportDate format depends on frequency (DAILY/WEEKLY = YYYY-MM-DD).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        reportDate: { type: "string", description: "DAILY=YYYY-MM-DD, MONTHLY=YYYY-MM. WEEKLY needs a week-ending Sunday." },
+        frequency: { type: "string", description: "DAILY (default), WEEKLY, MONTHLY" },
+      },
+      required: ["reportDate"],
+    },
+    run: async (a) => {
+      const vendor = requireVendor();
+      const text = await client.getReport("/salesReports", {
+        "filter[vendorNumber]": vendor,
+        "filter[frequency]": a.frequency || "DAILY",
+        "filter[reportType]": "SALES",
+        "filter[reportSubType]": "SUMMARY",
+        "filter[reportDate]": a.reportDate,
+        "filter[version]": "1_1",
+      });
+      const parsed = AppStoreConnectClient.parseDelimited(text, "\t");
+      const byApp = {};
+      for (const r of parsed.rows) {
+        const title = r["Title"] || r["SKU"];
+        if (!title) continue;
+        const units = parseInt(r["Units"] || "0", 10) || 0;
+        byApp[title] = byApp[title] || { app: title, units: 0 };
+        byApp[title].units += units;
+      }
+      const rows = Object.values(byApp).sort((x, y) => y.units - x.units);
+      return {
+        reportDate: a.reportDate,
+        frequency: a.frequency || "DAILY",
+        appsWithSales: rows.length,
+        totalUnits: rows.reduce((s, x) => s + x.units, 0),
+        topApps: rows.slice(0, 50),
+        note: "Units summed across territories. Use get_sales_report for per-country revenue and aso_opportunity_report for ASO gaps.",
+      };
+    },
+  },
+
+  // ---- TestFlight actions ----
+  {
+    name: "add_build_to_beta_group",
+    description:
+      "Add a processed build to a TestFlight beta group so its testers can install it. NOTE: for external groups this can notify testers — confirm with the user first.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        betaGroupId: { type: "string" },
+        buildId: { type: "string" },
+      },
+      required: ["betaGroupId", "buildId"],
+    },
+    run: async (a) => {
+      await client.post(`/betaGroups/${a.betaGroupId}/relationships/builds`, {
+        data: [{ type: "builds", id: a.buildId }],
+      });
+      return { added: a.buildId, toGroup: a.betaGroupId };
+    },
+  },
+  {
+    name: "submit_beta_review",
+    description:
+      "Submit a build for TestFlight (external) beta review. NOTE: sends the build to Apple's beta review — confirm with the user first.",
+    inputSchema: {
+      type: "object",
+      properties: { buildId: { type: "string" } },
+      required: ["buildId"],
+    },
+    run: async (a) =>
+      client.post(`/betaAppReviewSubmissions`, {
+        data: {
+          type: "betaAppReviewSubmissions",
+          relationships: { build: { data: { type: "builds", id: a.buildId } } },
+        },
+      }),
+  },
+
   // ---- Local build: archive & upload (macOS + Xcode) ----
   {
     name: "bump_build_number",
@@ -2247,7 +2447,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.8.1" },
+  { name: "appstore-api-mcp", version: "1.9.1" },
   { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS },
 );