appstore-api-mcp 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -4,6 +4,22 @@ 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.1.2] - 2026-06-02
+
+### Fixed
+- Report tools now treat a `404` ("no data for this report/date") as a clean
+  empty result with an explanatory `note`, instead of surfacing it as an error.
+  Validated end-to-end with an Admin key: sales, subscriptions, finance, and the
+  Analytics Reports API all return real data.
+
+## [1.1.1] - 2026-06-02
+
+### Changed
+- Documented the analytics/reporting requirements clearly: a dedicated
+  [docs/ANALYTICS.md](docs/ANALYTICS.md) (role table — App Manager returns 403,
+  Vendor Number, two-key setup, examples, troubleshooting), plus notes in the
+  README config section, SETUP, and the tools reference.
+
 ## [1.1.0] - 2026-06-02
 
 ### Added

package/README.md

@@ -49,6 +49,7 @@ and reach the entire API, from 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)
+- [Analytics & reports setup](docs/ANALYTICS.md) — roles, Vendor Number, examples
 - [Common workflows](#common-workflows)
 - [Security](#security) → details in [docs/SECURITY.md](docs/SECURITY.md)
 - [Troubleshooting](#troubleshooting)
@@ -214,7 +215,9 @@ See [.env.example](.env.example) for a copy-paste template.
 > **Reports need a higher-privilege key.** The sales/subscription/finance/analytics
 > tools require an API key with the **Admin, Finance, or Sales** role — an **App
 > Manager** key (fine for metadata/keywords/screenshots) returns `403` for reports.
-> Generate a separate report-capable key if you need analytics.
+> Sales/finance also need your **Vendor Number** (App Store Connect → Payments and
+> Financial Reports) via `ASC_VENDOR_NUMBER` or the `vendorNumber` argument.
+> Full walkthrough: **[docs/ANALYTICS.md](docs/ANALYTICS.md)**.
 
 ---
 

package/docs/ANALYTICS.md

@@ -0,0 +1,102 @@
+# Analytics, sales & finance — setup
+
+The reporting tools (`get_sales_report`, `get_subscription_report`,
+`get_finance_report`, and the `*_analytics_report*` tools) pull **downloads,
+proceeds, subscriptions, retention, and engagement** from App Store Connect.
+
+They have **two requirements** that the metadata tools don't:
+
+## 1. A key with the right role (App Manager is NOT enough)
+
+Apple gates report APIs behind specific roles. An **App Manager** key — perfect
+for keywords/descriptions/screenshots — returns **`403 FORBIDDEN`** for reports.
+The tools detect this and append a hint telling you exactly what's wrong.
+
+| Report | Role the API key needs |
+| --- | --- |
+| Sales & subscriptions (`get_sales_report`, `get_subscription_report`) | **Admin**, **Finance**, or **Sales** |
+| Finance (`get_finance_report`) | **Admin** or **Finance** |
+| Analytics Reports API (`request_analytics_report`, …) | **Admin** |
+
+**What to do:** generate a *separate* API key with the needed role in
+**App Store Connect → Users and Access → Integrations → App Store Connect API**
+(click **+**, pick e.g. **Sales** or **Admin**). You can keep your App Manager
+key for metadata and use the report key only for analytics — see
+[Using two keys](#using-two-keys) below.
+
+## 2. Your Vendor Number (for sales & finance)
+
+Sales and finance reports are scoped to a **Vendor Number** — an 8–9 digit ID,
+**not** the same as your Key ID or Issuer ID.
+
+- Find it in **App Store Connect → Payments and Financial Reports** (or **Sales
+  and Trends**) — it's the **Vendor #** shown at the top:
+
+![Where to find the Vendor Number in App Store Connect → Payments and Financial Reports](https://raw.githubusercontent.com/fil-technology/appstore-api-mcp/main/assets/where-to-find-vendor-number.png)
+
+- Provide it either way:
+  - **Per call:** pass `vendorNumber` in the tool arguments, or
+  - **Globally:** set the `ASC_VENDOR_NUMBER` environment variable in your MCP config.
+
+(The Analytics Reports API — downloads/sessions/engagement — does **not** need a
+Vendor Number, only the Admin role.)
+
+## Using two keys
+
+Keep your metadata key and add a report-capable one as a second MCP server:
+
+```bash
+# metadata (App Manager) — your existing one
+claude mcp add appstore-api --scope user \
+  --env ASC_KEY_ID=METADATA_KEY_ID \
+  --env ASC_ISSUER_ID=YOUR_ISSUER_ID \
+  --env ASC_PRIVATE_KEY_PATH=/path/to/metadata.p8 \
+  -- npx -y appstore-api-mcp
+
+# reports (Admin/Finance/Sales) + vendor number
+claude mcp add appstore-reports --scope user \
+  --env ASC_KEY_ID=REPORT_KEY_ID \
+  --env ASC_ISSUER_ID=YOUR_ISSUER_ID \
+  --env ASC_PRIVATE_KEY_PATH=/path/to/report.p8 \
+  --env ASC_VENDOR_NUMBER=12345678 \
+  -- npx -y appstore-api-mcp
+```
+
+(For other clients, add a second entry in the `mcpServers` block with its own env.)
+
+## Examples
+
+```jsonc
+// Yesterday's units & proceeds
+{ "name": "get_sales_report",
+  "arguments": { "frequency": "DAILY", "reportType": "SALES", "reportDate": "2026-06-01" } }
+
+// Active subscribers snapshot
+{ "name": "get_subscription_report",
+  "arguments": { "kind": "ACTIVE", "reportDate": "2026-06-01" } }
+
+// Subscription events (subscribe/cancel/renew) for retention analysis
+{ "name": "get_subscription_report",
+  "arguments": { "kind": "EVENTS", "reportDate": "2026-06-01" } }
+
+// Monthly proceeds, consolidated across regions
+{ "name": "get_finance_report",
+  "arguments": { "regionCode": "ZZ", "reportDate": "2026-05" } }
+```
+
+For downloads/sessions/engagement (Analytics Reports API), the flow is async:
+
+1. `request_analytics_report` with your `appId` → returns a request id
+2. wait (minutes–hours while Apple generates it)
+3. `list_analytics_reports` (filter by `category`) → pick a report id
+4. `list_analytics_report_instances` → pick an instance id
+5. `get_analytics_report_data` → parsed rows
+
+## Troubleshooting
+
+| Error | Meaning / fix |
+| --- | --- |
+| `403 ... does not allow this request` | Key role too low — use an Admin/Finance/Sales key (see table above). |
+| `vendorNumber is required` | Pass `vendorNumber` or set `ASC_VENDOR_NUMBER`. |
+| Report errors / empty | The date may have no data yet (reports lag ~1 day), or the `frequency`/`reportDate` format don't match (DAILY=`YYYY-MM-DD`, MONTHLY=`YYYY-MM`). |
+| Analytics instance has no segments | Still processing — try `get_analytics_report_data` again later. |

package/docs/SETUP.md

@@ -20,9 +20,14 @@ Step-by-step from zero to a working server.
 4. Click the **+** button to create a new key.
    - **Name:** something like `mcp-metadata`.
    - **Access (role):** choose the **least privilege** that covers your use:
-     - **App Manager** — edit metadata, keywords, screenshots, versions, TestFlight. ✅ Recommended.
+     - **App Manager** — edit metadata, keywords, screenshots, versions, TestFlight. ✅ Recommended for the listing tools.
      - **Developer** — narrower; may not allow all edits.
      - **Admin** — full control. Only if you genuinely need it.
+   - ⚠️ **Analytics/sales/finance reports need more.** An App Manager key returns
+     `403` for the report tools. To read downloads, proceeds, subscriptions, etc.,
+     use a key with the **Admin, Finance, or Sales** role (and your **Vendor
+     Number**). See [ANALYTICS.md](ANALYTICS.md). You can run two keys — one for
+     metadata, one for reports.
 5. Click **Generate**. You'll now see the key listed with a **Key ID** — that's your `ASC_KEY_ID`.
 6. Click **Download API Key** to get the `AuthKey_XXXXXXXXXX.p8` file.
    > ⚠️ You can only download this **once**. Save it somewhere safe and backed up.

package/docs/TOOLS.md

@@ -206,6 +206,7 @@ length warnings are attached to the response under `_warnings`.
 > Sales** role. An **App Manager** key returns `403`. Sales/finance also need a
 > **Vendor Number** (App Store Connect → Payments and Financial Reports; 8–9
 > digits) — pass `vendorNumber` or set the `ASC_VENDOR_NUMBER` env var.
+> Full setup walkthrough: **[ANALYTICS.md](ANALYTICS.md)**.
 
 All report tools return `{ reportType, columns, rowCount, returned, truncated, rows }`
 with `rows` capped at `limit` (default 200).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appstore-api-mcp",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "MCP server for Apple App Store Connect — manage apps, keywords, descriptions, titles, screenshots, versions and the full API from any MCP client (Claude, Codex, Cursor, Cline, Windsurf, VS Code, Zed, Continue, Gemini CLI, Google Antigravity, Amazon Q, Goose, and custom agents). Includes a fleet-wide ASO audit and dry-run previews.",
   "type": "module",
   "bin": {

package/src/client.js

@@ -157,6 +157,9 @@ export class AppStoreConnectClient {
       headers: { Authorization: `Bearer ${token}`, Accept: "application/a-gzip" },
     });
     const buf = Buffer.from(await res.arrayBuffer());
+    // 404 from a report endpoint means "no data for this report/date" — not a
+    // failure. Return empty so callers get an empty result, not an error.
+    if (res.status === 404) return "";
     if (!res.ok) {
       let detail = buf.toString("utf8");
       try {

package/src/index.js

@@ -134,7 +134,7 @@ const DEFAULT_VENDOR = process.env.ASC_VENDOR_NUMBER;
 /** Cap parsed report rows so large reports don't flood the response. */
 function reportResult(reportType, parsed, limit = 200) {
   const rows = parsed.rows;
-  return {
+  const out = {
     reportType,
     columns: parsed.columns,
     rowCount: rows.length,
@@ -142,6 +142,10 @@ function reportResult(reportType, parsed, limit = 200) {
     truncated: rows.length > limit,
     rows: rows.slice(0, limit),
   };
+  if (rows.length === 0)
+    out.note =
+      "No data found for the requested report/date. The period may have no activity, or the data isn't available yet (reports lag ~1 day). Check the date and frequency format.";
+  return out;
 }
 
 function requireVendor(v) {