appstore-api-mcp 1.1.3 → 1.3.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ 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.3.0] - 2026-06-02
+
+### Added
+- Promoted popular App Store Connect capabilities from `raw_request` to dedicated tools:
+  - **Customer reviews:** `list_customer_reviews` (filter by rating/territory, shows reply status) + `reply_to_customer_review`.
+  - **TestFlight:** `list_builds`, `list_beta_groups`, `list_beta_testers`, `add_beta_tester`.
+  - **Catalog/pricing/availability:** `list_in_app_purchases`, `get_app_price_schedule`, `list_available_territories`, `get_age_rating`.
+- All read tools validated end-to-end against a live account (reviews, builds, groups, testers, IAPs, 175 territories, age rating).
+
+## [1.2.0] - 2026-06-02
+
+### Added
+- **`get_screenshot`** — fetch a live screenshot as an actual **image the agent
+  can see** (not just metadata). Downloads the App Store Connect image asset,
+  downscaled by default (`maxWidth`), and returns an `image/png` content block.
+  Lets an agent review/compare what's currently on a listing.
+
 ## [1.1.3] - 2026-06-02
 
 ### Changed

package/README.md

@@ -50,6 +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)
 - [Analytics & reports setup](docs/ANALYTICS.md) — roles, Vendor Number, examples
 - [Common workflows](#common-workflows)
 - [Security](#security) → details in [docs/SECURITY.md](docs/SECURITY.md)
@@ -242,16 +243,47 @@ Full parameter reference: **[docs/TOOLS.md](docs/TOOLS.md)**.
 | `create_app_store_version_localization` | Add a new locale to a version |
 | `list_screenshot_sets` / `create_screenshot_set` | Manage per-device screenshot sets |
 | `list_screenshots` / `upload_screenshot` / `delete_screenshot` | Manage screenshots (upload handles the full reserve→upload→commit flow) |
+| 👁️ `get_screenshot` | Fetch a live screenshot **as an image the agent can see** — review/compare what's currently on a listing |
 | 🚀 `audit_apps` | **Fleet health check** — scan all (or selected) apps for missing subtitle/keywords/description, under-used keyword field, single-locale listings, missing screenshots, and more. Read-only. |
 | 📊 `get_sales_report` / `get_subscription_report` / `get_finance_report` | Units/downloads, proceeds, **subscriptions & retention**, earnings by region (parsed rows). Needs a Vendor Number + a key with Admin/Finance/Sales role. |
 | 📈 `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. |
-| `raw_request` | Any method/path against the API — previews, pricing, TestFlight, IAP, reviews, … |
+| ⭐ `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. |
 
 > 🛡️ **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.
 
 ---
 
+## What you can ask
+
+Once it's connected, just talk to your agent in plain language. A few things to try:
+
+**Listings & ASO**
+- *"Which of my apps are missing a subtitle or screenshots?"* (fleet audit)
+- *"Tighten the keywords for <app> — dry-run it first so I can confirm."*
+- *"Show me <app>'s current screenshots and flag any that look outdated."*
+- *"Translate <app>'s description and keywords into German and French."*
+
+**Performance**
+- *"How many downloads did all my apps get last week?"*
+- *"Pull last month's proceeds broken down by country."*
+- *"How many active subscribers do I have, and what's the recent churn?"*
+
+**Releases & the rest of the API** (via `raw_request`)
+- *"Create a new App Store version (1.4.0) for <app>."*
+- *"Summarize this week's 1-star reviews and draft polite replies."*
+- *"List my latest TestFlight builds and which beta groups can see them."*
+- *"What's <app>'s price and which territories is it available in?"*
+
+> **Dedicated tools cover it all:** app management, localization, screenshots
+> (incl. *seeing* them), sales/subscriptions/analytics, ASO audit, dry-run,
+> **customer reviews, TestFlight, in-app purchases, pricing, availability, and
+> age-rating**. Anything else in the App Store Connect API is still reachable
+> through the **`raw_request`** escape hatch — just ask.
+
 ## Common workflows
 
 ### Update keywords or description

package/docs/TOOLS.md

@@ -117,6 +117,13 @@ Common `displayType` values: `APP_IPHONE_67`, `APP_IPHONE_65`, `APP_IPHONE_61`,
 ### `list_screenshots`
 - `screenshotSetId` **(required)**
 
+### `get_screenshot`
+Fetch the actual screenshot **image** (not just metadata) and return it as an
+image the agent can see — review/compare what's currently live.
+- `screenshotId` **(required)**
+- `maxWidth` — downscale width in px for a lighter preview (default `750`; `0` = full size)
+- **Returns:** an `image/png` content block + a caption with the file name and original dimensions.
+
 ### `upload_screenshot`
 Upload an image into a set. Handles reserve → upload bytes → commit (with checksum).
 - `screenshotSetId` **(required)**
@@ -259,6 +266,52 @@ Download + decompress + parse an instance's segments into rows.
 
 ---
 
+## Customer reviews
+
+### list_customer_reviews
+- `appId` **(required)**
+- `rating` — filter to a star rating 1–5
+- `territory` — 3-letter code, e.g. `USA`, `GBR`
+- `sort` — `-createdDate` (default), `createdDate`, `rating`, `-rating`
+- `limit` — max reviews (default 50)
+- **Returns:** reviews with `rating`, `title`, `body`, `reviewerNickname`, `createdDate`, `territory`, and `hasResponse`.
+
+### reply_to_customer_review
+Posts a **public** reply (confirm the text with the user first).
+- `reviewId` **(required)**
+- `responseBody` **(required)** — max ~5970 chars
+
+## TestFlight
+
+### list_builds
+- `appId` **(required)**, `limit` (default 25) — newest first: `version`, `processingState`, upload/expiration dates, min OS.
+
+### list_beta_groups
+- `appId` **(required)** — group `name`, internal/external, public-link status.
+
+### list_beta_testers
+- `appId` **or** `betaGroupId` **(one required)**, `limit` (default 100).
+
+### add_beta_tester
+Invites a tester by email (emails a real person — confirm first).
+- `betaGroupId` **(required)**, `email` **(required)**, `firstName`, `lastName`
+
+## Catalog, pricing & availability
+
+### list_in_app_purchases
+- `appId` **(required)** — `name`, `productId`, type, `state`.
+
+### get_app_price_schedule
+- `appId` **(required)** — base territory + manual price points (raw schedule for inspection).
+
+### list_available_territories
+- `appId` **(required)**, `limit` (default 200) — `{ count, territories: [{ territory, available, releaseDate }] }`.
+
+### get_age_rating
+- `appId` **(required)** — the app's age-rating declaration (content descriptors).
+
+---
+
 ## Raw API access
 
 ### `raw_request`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appstore-api-mcp",
-  "version": "1.1.3",
+  "version": "1.3.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

@@ -193,6 +193,32 @@ export class AppStoreConnectClient {
       : buf.toString("utf8");
   }
 
+  /** Fetch raw bytes from a URL (e.g. an image asset). Returns a Buffer. */
+  async fetchBinary(url) {
+    const res = await fetch(url);
+    if (!res.ok)
+      throw new Error(`Image fetch failed (${res.status}) for ${url}`);
+    return Buffer.from(await res.arrayBuffer());
+  }
+
+  /**
+   * Build a concrete image URL from an App Store Connect imageAsset
+   * (`{ templateUrl, width, height }`), optionally downscaled to maxWidth.
+   */
+  static imageUrlFromAsset(imageAsset, maxWidth, format = "png") {
+    if (!imageAsset || !imageAsset.templateUrl) return null;
+    let w = imageAsset.width || 0;
+    let h = imageAsset.height || 0;
+    if (maxWidth && w && h && w > maxWidth) {
+      h = Math.round((h * maxWidth) / w);
+      w = maxWidth;
+    }
+    return imageAsset.templateUrl
+      .replace("{w}", String(w))
+      .replace("{h}", String(h))
+      .replace("{f}", format);
+  }
+
   /** Parse TSV/CSV text into an array of row objects. Auto-detects delimiter. */
   static parseDelimited(text, delimiter) {
     const lines = text.split(/\r?\n/).filter((l) => l.length > 0);

package/src/index.js

@@ -619,6 +619,49 @@ const tools = [
       return committed;
     },
   },
+  {
+    name: "get_screenshot",
+    description:
+      "Fetch the actual screenshot IMAGE by its id and return it so the agent can SEE it (not just metadata). Downloads the live image asset from App Store Connect, downscaled for a quick preview by default. Use this to review/compare what's currently live on a listing.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        screenshotId: { type: "string" },
+        maxWidth: {
+          type: "number",
+          description: "Downscale to this width in px for a lighter preview (default 750; pass 0 for full size)",
+        },
+      },
+      required: ["screenshotId"],
+    },
+    run: async (a) => {
+      const res = await client.get(`/appScreenshots/${a.screenshotId}`);
+      const attr = res.data.attributes || {};
+      const asset = attr.imageAsset;
+      if (!asset || !asset.templateUrl)
+        return {
+          note: "This screenshot has no rendered image yet (still uploading/processing). State: " +
+            (attr.assetDeliveryState && attr.assetDeliveryState.state),
+          fileName: attr.fileName,
+        };
+      const maxWidth = a.maxWidth === undefined ? 750 : a.maxWidth || 0;
+      const url = AppStoreConnectClient.imageUrlFromAsset(asset, maxWidth, "png");
+      const buf = await client.fetchBinary(url);
+      return {
+        __mcpContent: [
+          {
+            type: "image",
+            data: buf.toString("base64"),
+            mimeType: "image/png",
+          },
+          {
+            type: "text",
+            text: `Screenshot ${a.screenshotId} — ${attr.fileName || "(no name)"}, original ${asset.width}×${asset.height}.`,
+          },
+        ],
+      };
+    },
+  },
   {
     name: "delete_screenshot",
     description: "Delete a screenshot by its id.",
@@ -1038,6 +1081,262 @@ const tools = [
     },
   },
 
+  // ---- Customer reviews ----
+  {
+    name: "list_customer_reviews",
+    description:
+      "List customer reviews for an app. Filter by rating (1–5) and/or territory (3-letter code, e.g. USA, GBR). Sorted newest-first by default. Each review includes whether you've already responded.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        appId: { type: "string" },
+        rating: { type: "number", description: "Filter to a star rating 1–5" },
+        territory: { type: "string", description: "3-letter territory code, e.g. USA" },
+        sort: {
+          type: "string",
+          description: "'-createdDate' (default, newest first), 'createdDate', 'rating', '-rating'",
+        },
+        limit: { type: "number", description: "Max reviews (default 50)" },
+      },
+      required: ["appId"],
+    },
+    run: async (a) => {
+      const query = {
+        sort: a.sort || "-createdDate",
+        limit: a.limit ?? 50,
+        include: "response",
+      };
+      if (a.rating !== undefined) query["filter[rating]"] = a.rating;
+      if (a.territory) query["filter[territory]"] = a.territory;
+      const data = await client.getAll(
+        `/apps/${a.appId}/customerReviews`,
+        query,
+      );
+      return data.map((x) => ({
+        id: x.id,
+        ...x.attributes,
+        hasResponse: !!(x.relationships?.response?.data),
+      }));
+    },
+  },
+  {
+    name: "reply_to_customer_review",
+    description:
+      "Publicly reply to a customer review. NOTE: this publishes a response visible on the App Store — confirm the text with the user first. responseBody max ~5970 chars.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        reviewId: { type: "string" },
+        responseBody: { type: "string" },
+      },
+      required: ["reviewId", "responseBody"],
+    },
+    run: async (a) =>
+      client.post("/customerReviewResponses", {
+        data: {
+          type: "customerReviewResponses",
+          attributes: { responseBody: a.responseBody },
+          relationships: {
+            review: { data: { type: "customerReviews", id: a.reviewId } },
+          },
+        },
+      }),
+  },
+
+  // ---- TestFlight ----
+  {
+    name: "list_builds",
+    description:
+      "List TestFlight builds for an app (newest first): version, upload/expiration dates, processing state, min OS.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        appId: { type: "string" },
+        limit: { type: "number", description: "Max builds (default 25)" },
+      },
+      required: ["appId"],
+    },
+    run: async (a) => {
+      // The /builds collection supports sort; the app relationship does not.
+      const data = await client.getAll(`/builds`, {
+        "filter[app]": a.appId,
+        sort: "-version",
+        limit: a.limit ?? 25,
+      });
+      return data.map((x) => ({ id: x.id, ...x.attributes }));
+    },
+  },
+  {
+    name: "list_beta_groups",
+    description:
+      "List TestFlight beta groups for an app (internal/external, public-link status).",
+    inputSchema: {
+      type: "object",
+      properties: { appId: { type: "string" } },
+      required: ["appId"],
+    },
+    run: async (a) => {
+      const data = await client.getAll(`/apps/${a.appId}/betaGroups`);
+      return data.map((x) => ({ id: x.id, ...x.attributes }));
+    },
+  },
+  {
+    name: "list_beta_testers",
+    description:
+      "List TestFlight beta testers — either for a whole app (pass appId) or a specific group (pass betaGroupId).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        appId: { type: "string" },
+        betaGroupId: { type: "string" },
+        limit: { type: "number", description: "Max testers (default 100)" },
+      },
+    },
+    run: async (a) => {
+      let data;
+      if (a.betaGroupId)
+        data = await client.getAll(
+          `/betaGroups/${a.betaGroupId}/betaTesters`,
+          { limit: a.limit ?? 100 },
+        );
+      else if (a.appId)
+        data = await client.getAll(`/betaTesters`, {
+          "filter[apps]": a.appId,
+          limit: a.limit ?? 100,
+        });
+      else throw new Error("Provide appId or betaGroupId.");
+      return data.map((x) => ({ id: x.id, ...x.attributes }));
+    },
+  },
+  {
+    name: "add_beta_tester",
+    description:
+      "Add a beta tester to a TestFlight group by email (sends them an invite). NOTE: this emails a real person — confirm with the user first.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        betaGroupId: { type: "string" },
+        email: { type: "string" },
+        firstName: { type: "string" },
+        lastName: { type: "string" },
+      },
+      required: ["betaGroupId", "email"],
+    },
+    run: async (a) => {
+      const attributes = { email: a.email };
+      if (a.firstName) attributes.firstName = a.firstName;
+      if (a.lastName) attributes.lastName = a.lastName;
+      return client.post("/betaTesters", {
+        data: {
+          type: "betaTesters",
+          attributes,
+          relationships: {
+            betaGroups: { data: [{ type: "betaGroups", id: a.betaGroupId }] },
+          },
+        },
+      });
+    },
+  },
+
+  // ---- Catalog, pricing & availability ----
+  {
+    name: "list_in_app_purchases",
+    description:
+      "List the in-app purchase products for an app (name, product id, type, state).",
+    inputSchema: {
+      type: "object",
+      properties: { appId: { type: "string" } },
+      required: ["appId"],
+    },
+    run: async (a) => {
+      const data = await client.getAll(`/apps/${a.appId}/inAppPurchasesV2`);
+      return data.map((x) => ({ id: x.id, ...x.attributes }));
+    },
+  },
+  {
+    name: "list_available_territories",
+    description:
+      "List the territories (countries/regions) where an app is available. Returns territory codes and currencies.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        appId: { type: "string" },
+        limit: { type: "number", description: "Max territories (default 200)" },
+      },
+      required: ["appId"],
+    },
+    run: async (a) => {
+      // v2 availability model: app → appAvailabilityV2 → territoryAvailabilities.
+      // Follow the relationship's own related link (it points at the /v2 API).
+      const av = await client.get(`/apps/${a.appId}/appAvailabilityV2`);
+      const related =
+        av.data?.relationships?.territoryAvailabilities?.links?.related;
+      if (!related) return { note: "No availability record for this app." };
+      // Apple caps page size at 200; getAll paginates to cover the rest.
+      const data = await client.getAll(related, {
+        limit: Math.min(a.limit ?? 200, 200),
+      });
+      const territories = data
+        .map((x) => {
+          // The territory code is base64-encoded JSON in the item id: {"s":appId,"t":"USA"}.
+          let territory = null;
+          try {
+            territory = JSON.parse(
+              Buffer.from(x.id, "base64").toString("utf8"),
+            ).t;
+          } catch {
+            /* ignore */
+          }
+          return {
+            territory,
+            available: x.attributes?.available,
+            releaseDate: x.attributes?.releaseDate,
+          };
+        })
+        .filter((x) => x.territory);
+      return {
+        availableInNewTerritories: av.data?.attributes?.availableInNewTerritories,
+        count: territories.length,
+        territories,
+      };
+    },
+  },
+  {
+    name: "get_age_rating",
+    description:
+      "Get an app's age-rating declaration (the content descriptors that determine its age rating).",
+    inputSchema: {
+      type: "object",
+      properties: { appId: { type: "string" } },
+      required: ["appId"],
+    },
+    run: async (a) => {
+      const res = await client.get(`/apps/${a.appId}/appInfos`, {
+        include: "ageRatingDeclaration",
+        limit: 1,
+      });
+      const decl = (res.included || []).find(
+        (x) => x.type === "ageRatingDeclarations",
+      );
+      return decl ? { id: decl.id, ...decl.attributes } : { note: "No age-rating declaration found." };
+    },
+  },
+  {
+    name: "get_app_price_schedule",
+    description:
+      "Get an app's price schedule (base territory + manual price points). Pricing in the App Store Connect API is multi-step; this returns the schedule with its included prices for inspection.",
+    inputSchema: {
+      type: "object",
+      properties: { appId: { type: "string" } },
+      required: ["appId"],
+    },
+    run: async (a) =>
+      client.get(`/apps/${a.appId}/appPriceSchedule`, {
+        include: "baseTerritory,manualPrices",
+        "limit[manualPrices]": 50,
+      }),
+  },
+
   // ---- Generic escape hatch ----
   {
     name: "raw_request",
@@ -1091,6 +1390,8 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
   if (!tool) return fail(new Error(`Unknown tool: ${req.params.name}`));
   try {
     const result = await tool.run(req.params.arguments || {});
+    // Tools may return raw MCP content (e.g. images) via __mcpContent.
+    if (result && result.__mcpContent) return { content: result.__mcpContent };
     return ok(result);
   } catch (e) {
     if (e && e.status === 403 && REPORT_TOOLS.has(req.params.name))