appstore-api-mcp 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -4,6 +4,29 @@ 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.5.0] - 2026-06-02
+
+### Added
+- **`apps_review_status`** — fleet review-status board: every app's current
+  version + state (waiting/in-review/rejected/ready) in one call, with a summary.
+- **`submit_for_review`** — full submit flow (create submission → add version →
+  submit) and **`release_version`** for manually releasing an approved build.
+- **`signing_health`** — flags certificates & provisioning profiles that are
+  expired/expiring (within `withinDays`) or invalid, across the account.
+- **`update_in_app_purchase`** — edit an IAP's reference name / review note.
+
+## [1.4.0] - 2026-06-02
+
+### Added
+- **Provisioning & code signing:** `list_bundle_ids`, `register_bundle_id`,
+  `list_devices`, `register_device`, `list_certificates`, `create_certificate`,
+  `revoke_certificate`, `list_profiles`, `create_profile`, `download_profile`,
+  `delete_profile`.
+- **Game Center:** `list_game_center_leaderboards`, `list_game_center_achievements`.
+- **Automatic rate-limit handling** — the client backs off and retries on `429`/`503`
+  (honoring `Retry-After`, else exponential backoff), so large multi-app sweeps
+  don't fail. The latest `x-rate-limit` header is exposed on the client.
+
 ## [1.3.0] - 2026-06-02
 
 ### Added

package/README.md

@@ -250,7 +250,17 @@ Full parameter reference: **[docs/TOOLS.md](docs/TOOLS.md)**.
 | ⭐ `list_customer_reviews` / `reply_to_customer_review` | Read reviews (filter by rating/territory, shows if you've replied) and post public replies. |
 | ✈️ `list_builds` / `list_beta_groups` / `list_beta_testers` / `add_beta_tester` | TestFlight — builds, beta groups, testers, and inviting testers. |
 | 🛒 `list_in_app_purchases` / `get_app_price_schedule` / `list_available_territories` / `get_age_rating` | Catalog, pricing, territory availability, and age-rating. |
-| `raw_request` | Any method/path against the API — app previews, sales/finance edge cases, anything not above. |
+| 🔏 `list_bundle_ids` / `register_bundle_id` / `list_devices` / `register_device` / `list_certificates` / `create_certificate` / `revoke_certificate` / `list_profiles` / `create_profile` / `download_profile` / `delete_profile` | **Provisioning & code signing** — bundle IDs, devices, certificates, and provisioning profiles. |
+| 🎮 `list_game_center_leaderboards` / `list_game_center_achievements` | Game Center leaderboards & achievements. |
+| 🗂️ `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` | Submit a version to Apple review (full flow) and release an approved build. |
+| 🔐 `signing_health` | Flag **certificates & profiles expiring soon** (or invalid) across the account — catches CI breakage early. |
+| `update_in_app_purchase` | Update an IAP's reference name / review note. |
+| `raw_request` | Any method/path against the API — app previews, matchmaking, Xcode Cloud, anything not above. |
+
+> ⚙️ **Rate-limit aware:** the client automatically backs off and retries on
+> App Store Connect's `429` (hourly quota), so large sweeps (e.g. auditing 60+
+> apps) don't fall over.
 
 > 🛡️ **Dry-run:** the `update_*` tools accept `dryRun: true` — they return a field-by-field
 > diff (old → new) with length/limit checks and **write nothing**. Drop the flag to apply.

package/docs/TOOLS.md

@@ -310,6 +310,68 @@ Invites a tester by email (emails a real person — confirm first).
 ### get_age_rating
 - `appId` **(required)** — the app's age-rating declaration (content descriptors).
 
+## Submission, release & fleet status
+
+### apps_review_status
+Fleet review-status board across all (or selected) apps. Read-only.
+- `appIds` — limit to these apps; `platform`; `limit`
+- **Returns:** `{ summary: { apps, byState }, apps: [{ name, version, state, platform }] }`
+
+### submit_for_review
+Submits a version to Apple review (create submission → add version → submit).
+**Sends the app to review — confirm first.**
+- `appId` **(required)**, `versionId` **(required)**, `platform` (default IOS)
+
+### release_version
+Release an approved version waiting for manual release (PENDING_DEVELOPER_RELEASE).
+**Makes it live — confirm first.**
+- `versionId` **(required)**
+
+### update_in_app_purchase
+- `inAppPurchaseId` **(required)**, `name`, `reviewNote`
+
+## Code-signing health
+
+### signing_health
+Lists certificates and provisioning profiles, flagging expired/expiring (within
+`withinDays`, default 30) and INVALID profiles. Read-only.
+- `withinDays` — threshold in days
+- **Returns:** `{ summary, certIssues, profileIssues }` (each with `daysLeft`).
+
+## Provisioning & code signing
+
+### list_bundle_ids
+- `filterIdentifier`, `limit` (default 200)
+
+### register_bundle_id
+- `identifier` **(required)**, `name` **(required)**, `platform` (IOS/MAC_OS/UNIVERSAL)
+
+### list_devices / register_device
+- register: `name` **(required)**, `udid` **(required)**, `platform` (IOS/MAC_OS)
+
+### list_certificates / create_certificate / revoke_certificate
+- `create_certificate` needs a CSR you generate yourself (`csrContent` PEM) + `certificateType` (e.g. IOS_DISTRIBUTION).
+- `revoke_certificate` — `certificateId`.
+
+### list_profiles / create_profile / download_profile / delete_profile
+- `create_profile` — `name`, `profileType` (IOS_APP_DEVELOPMENT/IOS_APP_STORE/IOS_APP_ADHOC), `bundleId` (resource id), `certificateIds[]`, `deviceIds[]` (dev/ad-hoc).
+- `download_profile` — returns base64 `.mobileprovision` in `profileContent`.
+
+## Game Center
+
+### list_game_center_leaderboards / list_game_center_achievements
+- `appId` **(required)** — requires Game Center enabled on the app.
+
+---
+
+## Rate limits
+
+App Store Connect allows ~3,500 requests/hour and returns `429` when exceeded.
+The client handles this automatically: on `429`/`503` it waits (honoring
+`Retry-After` when present, else exponential backoff up to ~16 s) and retries up
+to 4 times. The latest `x-rate-limit` header is kept on the client for visibility.
+See <https://developer.apple.com/documentation/appstoreconnectapi/identifying-rate-limits>.
+
 ---
 
 ## Raw API access

package/package.json

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

@@ -75,7 +75,7 @@ export class AppStoreConnectClient {
     return url;
   }
 
-  async request(method, path, { query, body } = {}) {
+  async request(method, path, { query, body, _attempt = 0 } = {}) {
     const token = await this._getToken();
     const url = this._buildUrl(path, query);
     const headers = { Authorization: `Bearer ${token}` };
@@ -85,6 +85,21 @@ export class AppStoreConnectClient {
       payload = JSON.stringify(body);
     }
     const res = await fetch(url, { method, headers, body: payload });
+
+    // Rate limiting: App Store Connect returns 429 when the hourly quota is hit.
+    // Respect Retry-After if present, else exponential backoff; retry a few times.
+    if ((res.status === 429 || res.status === 503) && _attempt < 4) {
+      const retryAfter = Number(res.headers.get("retry-after"));
+      const waitMs =
+        retryAfter > 0
+          ? retryAfter * 1000
+          : Math.min(1000 * 2 ** _attempt, 16000);
+      await new Promise((r) => setTimeout(r, waitMs));
+      return this.request(method, path, { query, body, _attempt: _attempt + 1 });
+    }
+    // Expose remaining quota for visibility (parsed from x-rate-limit header).
+    this.rateLimit = res.headers.get("x-rate-limit") || this.rateLimit;
+
     const text = await res.text();
     let data = null;
     if (text) {

package/src/index.js

@@ -1337,6 +1337,467 @@ const tools = [
       }),
   },
 
+  // ---- Provisioning & code signing ----
+  {
+    name: "list_bundle_ids",
+    description:
+      "List registered Bundle IDs (app identifiers). Optionally filter by identifier.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        filterIdentifier: { type: "string" },
+        limit: { type: "number", description: "Max (default 200)" },
+      },
+    },
+    run: async (a) => {
+      const q = { limit: a.limit ?? 200 };
+      if (a.filterIdentifier) q["filter[identifier]"] = a.filterIdentifier;
+      const data = await client.getAll("/bundleIds", q);
+      return data.map((x) => ({ id: x.id, ...x.attributes }));
+    },
+  },
+  {
+    name: "register_bundle_id",
+    description:
+      "Register a new Bundle ID. platform: IOS, MAC_OS, or UNIVERSAL.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        identifier: { type: "string", description: "e.g. com.example.app" },
+        name: { type: "string" },
+        platform: { type: "string", description: "IOS (default), MAC_OS, UNIVERSAL" },
+      },
+      required: ["identifier", "name"],
+    },
+    run: async (a) =>
+      client.post("/bundleIds", {
+        data: {
+          type: "bundleIds",
+          attributes: {
+            identifier: a.identifier,
+            name: a.name,
+            platform: a.platform || "IOS",
+          },
+        },
+      }),
+  },
+  {
+    name: "list_devices",
+    description: "List registered devices (UDIDs) for ad-hoc/development distribution.",
+    inputSchema: {
+      type: "object",
+      properties: { limit: { type: "number", description: "Max (default 200)" } },
+    },
+    run: async (a) => {
+      const data = await client.getAll("/devices", { limit: a.limit ?? 200 });
+      return data.map((x) => ({ id: x.id, ...x.attributes }));
+    },
+  },
+  {
+    name: "register_device",
+    description: "Register a device by UDID. platform: IOS (default) or MAC_OS.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        udid: { type: "string" },
+        platform: { type: "string", description: "IOS (default), MAC_OS" },
+      },
+      required: ["name", "udid"],
+    },
+    run: async (a) =>
+      client.post("/devices", {
+        data: {
+          type: "devices",
+          attributes: {
+            name: a.name,
+            udid: a.udid,
+            platform: a.platform || "IOS",
+          },
+        },
+      }),
+  },
+  {
+    name: "list_certificates",
+    description: "List code-signing certificates (development & distribution).",
+    inputSchema: {
+      type: "object",
+      properties: { limit: { type: "number", description: "Max (default 200)" } },
+    },
+    run: async (a) => {
+      const data = await client.getAll("/certificates", { limit: a.limit ?? 200 });
+      return data.map((x) => ({ id: x.id, ...x.attributes }));
+    },
+  },
+  {
+    name: "create_certificate",
+    description:
+      "Create a code-signing certificate from a CSR. You must generate the Certificate Signing Request yourself (openssl) and pass its PEM as csrContent. certificateType e.g. IOS_DEVELOPMENT, IOS_DISTRIBUTION, DEVELOPMENT, DISTRIBUTION.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        csrContent: { type: "string", description: "PEM contents of the CSR" },
+        certificateType: { type: "string" },
+      },
+      required: ["csrContent", "certificateType"],
+    },
+    run: async (a) =>
+      client.post("/certificates", {
+        data: {
+          type: "certificates",
+          attributes: {
+            csrContent: a.csrContent,
+            certificateType: a.certificateType,
+          },
+        },
+      }),
+  },
+  {
+    name: "revoke_certificate",
+    description: "Revoke (delete) a code-signing certificate by id.",
+    inputSchema: {
+      type: "object",
+      properties: { certificateId: { type: "string" } },
+      required: ["certificateId"],
+    },
+    run: async (a) => {
+      await client.delete(`/certificates/${a.certificateId}`);
+      return { revoked: a.certificateId };
+    },
+  },
+  {
+    name: "list_profiles",
+    description: "List provisioning profiles (includes the bundle id they target).",
+    inputSchema: {
+      type: "object",
+      properties: { limit: { type: "number", description: "Max (default 200)" } },
+    },
+    run: async (a) => {
+      const data = await client.getAll("/profiles", {
+        limit: a.limit ?? 200,
+        include: "bundleId",
+      });
+      return data.map((x) => ({ id: x.id, ...x.attributes }));
+    },
+  },
+  {
+    name: "create_profile",
+    description:
+      "Create a provisioning profile. profileType e.g. IOS_APP_DEVELOPMENT, IOS_APP_STORE, IOS_APP_ADHOC. Pass the bundleId resource id, plus certificate ids (and device ids for development/ad-hoc).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        profileType: { type: "string" },
+        bundleId: { type: "string", description: "bundleId resource id" },
+        certificateIds: { type: "array", items: { type: "string" } },
+        deviceIds: { type: "array", items: { type: "string" } },
+      },
+      required: ["name", "profileType", "bundleId", "certificateIds"],
+    },
+    run: async (a) => {
+      const relationships = {
+        bundleId: { data: { type: "bundleIds", id: a.bundleId } },
+        certificates: {
+          data: (a.certificateIds || []).map((id) => ({
+            type: "certificates",
+            id,
+          })),
+        },
+      };
+      if (a.deviceIds && a.deviceIds.length)
+        relationships.devices = {
+          data: a.deviceIds.map((id) => ({ type: "devices", id })),
+        };
+      return client.post("/profiles", {
+        data: {
+          type: "profiles",
+          attributes: { name: a.name, profileType: a.profileType },
+          relationships,
+        },
+      });
+    },
+  },
+  {
+    name: "download_profile",
+    description:
+      "Get a provisioning profile's contents (base64 .mobileprovision in profileContent) by id.",
+    inputSchema: {
+      type: "object",
+      properties: { profileId: { type: "string" } },
+      required: ["profileId"],
+    },
+    run: async (a) => {
+      const res = await client.get(`/profiles/${a.profileId}`);
+      return { id: res.data.id, ...res.data.attributes };
+    },
+  },
+  {
+    name: "delete_profile",
+    description: "Delete a provisioning profile by id.",
+    inputSchema: {
+      type: "object",
+      properties: { profileId: { type: "string" } },
+      required: ["profileId"],
+    },
+    run: async (a) => {
+      await client.delete(`/profiles/${a.profileId}`);
+      return { deleted: a.profileId };
+    },
+  },
+
+  // ---- Game Center ----
+  {
+    name: "list_game_center_leaderboards",
+    description:
+      "List Game Center leaderboards for an app (requires Game Center enabled on the app).",
+    inputSchema: {
+      type: "object",
+      properties: { appId: { type: "string" } },
+      required: ["appId"],
+    },
+    run: async (a) => {
+      const detail = await client.get(`/apps/${a.appId}/gameCenterDetail`);
+      const detailId = detail.data && detail.data.id;
+      if (!detailId)
+        return { note: "Game Center is not enabled for this app." };
+      const data = await client.getAll(
+        `/gameCenterDetails/${detailId}/gameCenterLeaderboards`,
+      );
+      return data.map((x) => ({ id: x.id, ...x.attributes }));
+    },
+  },
+  {
+    name: "list_game_center_achievements",
+    description:
+      "List Game Center achievements for an app (requires Game Center enabled on the app).",
+    inputSchema: {
+      type: "object",
+      properties: { appId: { type: "string" } },
+      required: ["appId"],
+    },
+    run: async (a) => {
+      const detail = await client.get(`/apps/${a.appId}/gameCenterDetail`);
+      const detailId = detail.data && detail.data.id;
+      if (!detailId)
+        return { note: "Game Center is not enabled for this app." };
+      const data = await client.getAll(
+        `/gameCenterDetails/${detailId}/gameCenterAchievements`,
+      );
+      return data.map((x) => ({ id: x.id, ...x.attributes }));
+    },
+  },
+
+  // ---- Submission, release & fleet status ----
+  {
+    name: "apps_review_status",
+    description:
+      "Fleet review-status board: for all (or selected) apps, returns the most relevant App Store version and its state (WAITING_FOR_REVIEW, IN_REVIEW, PENDING_DEVELOPER_RELEASE, REJECTED, PROCESSING_FOR_APP_STORE, READY_FOR_SALE, …) plus an account summary. One call instead of opening every app. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        appIds: { type: "array", items: { type: "string" } },
+        platform: { type: "string", description: "IOS, MAC_OS, TV_OS, VISION_OS" },
+        limit: { type: "number", description: "Audit at most this many apps" },
+      },
+    },
+    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 IN_FLIGHT = new Set([
+        "PREPARE_FOR_SUBMISSION",
+        "WAITING_FOR_REVIEW",
+        "IN_REVIEW",
+        "PENDING_DEVELOPER_RELEASE",
+        "PENDING_APPLE_RELEASE",
+        "PROCESSING_FOR_APP_STORE",
+        "METADATA_REJECTED",
+        "REJECTED",
+        "DEVELOPER_REJECTED",
+        "INVALID_BINARY",
+        "WAITING_FOR_EXPORT_COMPLIANCE",
+      ]);
+      const rows = await mapLimit(apps, 6, async (app) => {
+        try {
+          const q = { limit: 10 };
+          if (a.platform) q["filter[platform]"] = a.platform;
+          const vers = await client.getAll(
+            `/apps/${app.id}/appStoreVersions`,
+            q,
+          );
+          const chosen =
+            vers.find((v) => IN_FLIGHT.has(v.attributes.appStoreState)) ||
+            vers.find((v) => v.attributes.appStoreState === "READY_FOR_SALE") ||
+            vers[0];
+          return {
+            appId: app.id,
+            name: app.attributes.name,
+            version: chosen?.attributes?.versionString,
+            state: chosen?.attributes?.appStoreState || "NO_VERSION",
+            platform: chosen?.attributes?.platform,
+          };
+        } catch (e) {
+          return { appId: app.id, name: app.attributes.name, error: e.message.slice(0, 80) };
+        }
+      });
+      const byState = {};
+      for (const r of rows) {
+        const s = r.state || (r.error ? "ERROR" : "unknown");
+        byState[s] = (byState[s] || 0) + 1;
+      }
+      return {
+        summary: { apps: rows.length, byState },
+        apps: rows.sort((x, y) =>
+          String(x.state).localeCompare(String(y.state)),
+        ),
+      };
+    },
+  },
+  {
+    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.",
+    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" },
+      },
+      required: ["appId", "versionId"],
+    },
+    run: async (a) => {
+      const sub = await client.post("/reviewSubmissions", {
+        data: {
+          type: "reviewSubmissions",
+          attributes: { platform: a.platform || "IOS" },
+          relationships: { app: { data: { type: "apps", id: a.appId } } },
+        },
+      });
+      const subId = sub.data.id;
+      await client.post("/reviewSubmissionItems", {
+        data: {
+          type: "reviewSubmissionItems",
+          relationships: {
+            reviewSubmission: {
+              data: { type: "reviewSubmissions", id: subId },
+            },
+            appStoreVersion: {
+              data: { type: "appStoreVersions", id: a.versionId },
+            },
+          },
+        },
+      });
+      const submitted = await client.patch(`/reviewSubmissions/${subId}`, {
+        data: {
+          type: "reviewSubmissions",
+          id: subId,
+          attributes: { submitted: true },
+        },
+      });
+      return { reviewSubmissionId: subId, result: submitted };
+    },
+  },
+  {
+    name: "release_version",
+    description:
+      "Release an approved version that's waiting for manual release (state PENDING_DEVELOPER_RELEASE). NOTE: this makes the version live on the App Store — confirm with the user first.",
+    inputSchema: {
+      type: "object",
+      properties: { versionId: { type: "string" } },
+      required: ["versionId"],
+    },
+    run: async (a) =>
+      client.post("/appStoreVersionReleaseRequests", {
+        data: {
+          type: "appStoreVersionReleaseRequests",
+          relationships: {
+            appStoreVersion: {
+              data: { type: "appStoreVersions", id: a.versionId },
+            },
+          },
+        },
+      }),
+  },
+
+  // ---- Code-signing health ----
+  {
+    name: "signing_health",
+    description:
+      "Code-signing health check: lists certificates and provisioning profiles, flagging any expired or expiring within `withinDays` (default 30) and any INVALID profiles. Catches silent CI breakage before it happens. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        withinDays: { type: "number", description: "Flag items expiring within N days (default 30)" },
+      },
+    },
+    run: async (a) => {
+      const within = a.withinDays ?? 30;
+      const now = Date.now();
+      const daysLeft = (d) =>
+        d ? Math.round((new Date(d).getTime() - now) / 86400000) : null;
+      const certs = await client.getAll("/certificates", { limit: 200 });
+      const profs = await client.getAll("/profiles", { limit: 200 });
+      const certRows = certs.map((c) => ({
+        id: c.id,
+        name: c.attributes.name,
+        type: c.attributes.certificateType,
+        expirationDate: c.attributes.expirationDate,
+        daysLeft: daysLeft(c.attributes.expirationDate),
+      }));
+      const profRows = profs.map((p) => ({
+        id: p.id,
+        name: p.attributes.name,
+        type: p.attributes.profileType,
+        state: p.attributes.profileState,
+        expirationDate: p.attributes.expirationDate,
+        daysLeft: daysLeft(p.attributes.expirationDate),
+      }));
+      const certIssues = certRows.filter(
+        (c) => c.daysLeft !== null && c.daysLeft <= within,
+      );
+      const profileIssues = profRows.filter(
+        (p) =>
+          p.state === "INVALID" ||
+          (p.daysLeft !== null && p.daysLeft <= within),
+      );
+      return {
+        summary: {
+          certificates: certRows.length,
+          profiles: profRows.length,
+          certsExpiringOrExpired: certIssues.length,
+          profilesInvalidOrExpiring: profileIssues.length,
+          withinDays: within,
+        },
+        certIssues: certIssues.sort((x, y) => (x.daysLeft ?? 0) - (y.daysLeft ?? 0)),
+        profileIssues: profileIssues.sort((x, y) => (x.daysLeft ?? 0) - (y.daysLeft ?? 0)),
+      };
+    },
+  },
+  {
+    name: "update_in_app_purchase",
+    description:
+      "Update an in-app purchase product's editable fields (reference name and/or review note). Pass the inAppPurchasesV2 id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        inAppPurchaseId: { type: "string" },
+        name: { type: "string", description: "Reference name" },
+        reviewNote: { type: "string" },
+      },
+      required: ["inAppPurchaseId"],
+    },
+    run: async (a) => {
+      const attributes = {};
+      if (a.name !== undefined) attributes.name = a.name;
+      if (a.reviewNote !== undefined) attributes.reviewNote = a.reviewNote;
+      return client.patch(`/inAppPurchasesV2/${a.inAppPurchaseId}`, {
+        data: { type: "inAppPurchasesV2", id: a.inAppPurchaseId, attributes },
+      });
+    },
+  },
+
   // ---- Generic escape hatch ----
   {
     name: "raw_request",