appstore-api-mcp 1.0.3 → 1.1.0

package/.env.example

@@ -18,3 +18,9 @@ ASC_PRIVATE_KEY_PATH=/absolute/path/to/AuthKey_XXXXXXXXXX.p8
 
 # 3) ...or base64 of the .p8 file (no newline headaches):  base64 -i AuthKey_XXXX.p8
 # ASC_PRIVATE_KEY_BASE64=
+
+# Optional: default Vendor Number for sales/finance reports (8–9 digits).
+# Found in App Store Connect → Payments and Financial Reports (or Sales and Trends).
+# Sales/finance/analytics reports also require a key with the Admin, Finance, or
+# Sales role — an App Manager key cannot read them.
+# ASC_VENDOR_NUMBER=

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.1.0] - 2026-06-02
+
+### Added
+- **Analytics, sales, subscriptions & finance reporting:**
+  - `get_sales_report` — units/downloads, proceeds, and subscription data (Sales & Trends).
+  - `get_subscription_report` — active subscribers, events, and per-subscriber detail.
+  - `get_finance_report` — proceeds/earnings by region.
+  - `request_analytics_report` + `list_analytics_reports` +
+    `list_analytics_report_instances` + `get_analytics_report_data` — the async
+    Analytics Reports API (downloads, sessions, active devices, engagement).
+  - Gzip/TSV/CSV handling in the client so report files are decompressed and
+    returned as parsed rows.
+  - Optional `ASC_VENDOR_NUMBER` env var as a default for sales/finance reports.
+  - Friendly 403 hint: report APIs need a key with the Admin, Finance, or Sales
+    role (App Manager is not sufficient).
+
+## [1.0.4] - 2026-06-02
+
+### Changed
+- Agent-setup prompt now **guides the user to obtain missing credentials**
+  (where to find the Key ID / Issuer ID, how to generate and download the .p8)
+  instead of stopping with an error when values are still placeholders.
+
 ## [1.0.3] - 2026-06-02
 
 ### Changed

package/README.md

@@ -1,22 +1,44 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/fil-technology/appstore-api-mcp/main/assets/banner.png" alt="appstore-api-mcp — manage App Store Connect from any AI agent" width="100%">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/appstore-api-mcp"><img src="https://img.shields.io/npm/v/appstore-api-mcp?color=0a84ff&label=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/appstore-api-mcp"><img src="https://img.shields.io/npm/dm/appstore-api-mcp?color=22d3ee" alt="npm downloads"></a>
+  <img src="https://img.shields.io/npm/l/appstore-api-mcp?color=blue" alt="license">
+  <img src="https://img.shields.io/node/v/appstore-api-mcp" alt="node version">
+</p>
+
 # App Store Connect MCP
 
-An [MCP](https://modelcontextprotocol.io) server that lets **any AI agent** read
-and edit your **App Store Connect** apps in plain language — keywords,
-descriptions, titles, subtitles, promotional text, what's-new, screenshots,
-versions — plus a raw-request tool that reaches the **entire**
-[App Store Connect API](https://developer.apple.com/documentation/appstoreconnectapi).
+**Run App Store Connect by talking to your AI.** An
+[MCP](https://modelcontextprotocol.io) server that turns Apple's
+[App Store Connect API](https://developer.apple.com/documentation/appstoreconnectapi)
+into plain-language actions — edit your listings, audit your whole portfolio,
+and reach the entire API, from whatever AI agent you already use.
+
+### ✨ What makes it stand out
+
+> **🚀 Audit your whole portfolio in one shot.** *"Audit all my apps for ASO gaps"* → a ranked report across **every** app: empty keyword fields, missing subtitles, under-used 100‑char keyword space, single‑locale listings, missing screenshots. Built for indies shipping dozens of apps — not one at a time.
+
+> **🛡️ See every change before it ships.** Dry-run mode returns the exact diff (old → new) with Apple's character limits pre-checked, so nothing hits your **live** listing by surprise.
+
+> **📊 Track performance, not just listings.** Pull downloads, proceeds, **subscriptions & retention**, and engagement straight from the Sales, Finance, and Analytics report APIs — parsed into rows, gzip handled for you.
 
-> Ask things like *"update the keywords for my app to X, Y, Z"*,
-> *"show the English description for MyApp"*, or
-> *"upload these screenshots to the 6.7-inch set"* — the agent calls the right tools.
+> **🌐 The whole API, not a curated slice.** First-class tools for the daily work (keywords, descriptions, titles, subtitles, screenshots, versions) **plus** a `raw_request` escape hatch for everything else — TestFlight, pricing, in-app purchases, customer reviews (read & reply), and more.
 
-- 🤖 **Works with any MCP client** — Claude Code/Desktop, OpenAI Codex CLI, Cursor, Cline, Windsurf, VS Code (agent mode), Zed, Continue, Gemini CLI, Google Antigravity, Amazon Q, Goose, JetBrains AI, Warp, and custom agents on the MCP SDKs. Standard stdio server, no client-specific code. → [docs/CLIENTS.md](docs/CLIENTS.md)
-- ✅ **One-line install** via `npx` — no clone, no build
-- ✅ **Credentials stay on your machine** — calls go straight to Apple, nothing is proxied
-- ✅ **Slim, well-described tool set** + a `raw_request` escape hatch for the whole API
-- 🛡️ **Dry-run mode** — preview any metadata change (old→new + length checks) before writing
-- 🚀 **Fleet audit** — one call health-checks **all** your apps for ASO gaps (built for indies with many apps)
-- ✅ MIT licensed, actively maintained
+### 💬 Just ask
+
+> *“Set the keywords for my budgeting app to budget, expenses, money tracker.”*
+> *“Which of my apps are missing a subtitle or screenshots?”*
+> *“Dry-run a shorter description for MyApp, then upload these 6.7″ screenshots.”*
+
+### ⚙️ Built right
+
+- 🤖 **Any MCP client** — Claude, Codex, Cursor, Windsurf, Antigravity, Gemini CLI, Amazon Q, Goose, Zed, VS Code… → [docs/CLIENTS.md](docs/CLIENTS.md)
+- ⚡ **One-line install** (`npx`, no build) — or paste a prompt and let your agent set it up for you
+- 🔒 **Keys never leave your machine** — calls go straight to Apple, nothing proxied
+- 📦 **MIT · published with provenance · actively maintained**
 
 ---
 
@@ -54,14 +76,23 @@ My App Store Connect API credentials:
 - Path to my .p8 private key file: <ABSOLUTE_PATH_TO_AuthKey_XXXX.p8>
 
 Please:
-1. Detect which MCP client I'm using and add the server to its config. Run it
-   with: npx -y appstore-api-mcp
-2. Pass these env vars: ASC_KEY_ID, ASC_ISSUER_ID, and ASC_PRIVATE_KEY_PATH
+1. If any of the three values above are still placeholders or I didn't provide
+   them, do NOT stop with an error — guide me to get them, then wait for me:
+     - Key ID & Issuer ID: go to App Store Connect → Users and Access →
+       Integrations tab → "App Store Connect API". The Issuer ID is shown at the
+       top of that page; the Key ID is listed next to each key.
+     - No key yet? Click the + to generate one, give it the "App Manager" role
+       (enough to edit metadata/keywords/screenshots), then Download the .p8
+       file — you can only download it once, so save it somewhere safe.
+     - The .p8 path is the absolute path to wherever you saved that file.
+2. Detect which MCP client I'm using and add the server to its config (run it
+   with: npx -y appstore-api-mcp).
+3. Pass these env vars: ASC_KEY_ID, ASC_ISSUER_ID, and ASC_PRIVATE_KEY_PATH
    (point ASC_PRIVATE_KEY_PATH at my .p8 path — reference the PATH, do not
    inline the key contents).
-3. Install it at user/global scope (for Claude Code use `--scope user`).
-4. Do NOT print, echo, log, or commit the key. Keep the .p8 outside any git repo.
-5. When done, verify by listing my App Store apps and report the result.
+4. Install it at user/global scope (for Claude Code use `--scope user`).
+5. Do NOT print, echo, log, or commit the key. Keep the .p8 outside any git repo.
+6. When done, verify by listing my App Store apps and report the result.
 
 Config formats per client: https://github.com/fil-technology/appstore-api-mcp/blob/main/docs/CLIENTS.md
 ```
@@ -153,6 +184,14 @@ Copy-paste config snippets for each are in **[docs/CLIENTS.md](docs/CLIENTS.md)*
 3. Note the **Issuer ID** (top of the page) and the **Key ID** (next to the key).
 4. **Download the `.p8` file** — you can only download it once. Store it somewhere safe.
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/fil-technology/appstore-api-mcp/main/assets/where-to-find-credentials.png" alt="Where to find the Issuer ID and Key ID in App Store Connect → Users and Access → Integrations → App Store Connect API" width="100%">
+</p>
+
+> The **Issuer ID** is at the top of the page; each key's **Key ID** is in its
+> row. The `.p8` is downloaded from the **+** / key actions. These map to
+> `ASC_ISSUER_ID`, `ASC_KEY_ID`, and `ASC_PRIVATE_KEY_PATH`.
+
 Full walkthrough with screenshots-worth of detail: **[docs/SETUP.md](docs/SETUP.md)**.
 
 ---
@@ -168,9 +207,15 @@ All configuration is via environment variables.
 | `ASC_PRIVATE_KEY_PATH` | one of these three | Absolute path to the `.p8` file |
 | `ASC_PRIVATE_KEY` | one of these three | The raw PEM contents of the key |
 | `ASC_PRIVATE_KEY_BASE64` | one of these three | Base64 of the `.p8` (`base64 -i AuthKey.p8`) — easiest for env vars |
+| `ASC_VENDOR_NUMBER` | optional | Default Vendor Number for sales/finance reports (8–9 digits; App Store Connect → Payments and Financial Reports) |
 
 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.
+
 ---
 
 ## Tools
@@ -194,7 +239,9 @@ Full parameter reference: **[docs/TOOLS.md](docs/TOOLS.md)**.
 | `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) |
 | 🚀 `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. |
-| `raw_request` | Any method/path against the API — previews, pricing, TestFlight, IAP, reviews, analytics, sales reports, … |
+| 📊 `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, … |
 
 > 🛡️ **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/AGENT-SETUP.md

@@ -15,17 +15,26 @@ My App Store Connect API credentials:
 - Path to my .p8 private key file: <ABSOLUTE_PATH_TO_AuthKey_XXXX.p8>
 
 Please:
-1. Detect which MCP client I'm using and add the server to that client's
+1. If any of the three values above are still placeholders or I didn't provide
+   them, do NOT stop with an error — guide me to get them, then wait for me:
+     - Key ID & Issuer ID: go to App Store Connect → Users and Access →
+       Integrations tab → "App Store Connect API". The Issuer ID is shown at the
+       top of that page; the Key ID is listed next to each key.
+     - No key yet? Click the + to generate one, give it the "App Manager" role
+       (enough to edit metadata/keywords/screenshots), then Download the .p8
+       file — you can only download it once, so save it somewhere safe.
+     - The .p8 path is the absolute path to wherever you saved that file.
+2. Detect which MCP client I'm using and add the server to that client's
    correct config file/command. Run it with: npx -y appstore-api-mcp
-2. Pass these env vars to the server:
+3. Pass these env vars to the server:
      ASC_KEY_ID         = my Key ID
      ASC_ISSUER_ID      = my Issuer ID
      ASC_PRIVATE_KEY_PATH = the path to my .p8 file (reference the PATH; do not
                             inline the key contents)
-3. Install it at user/global scope so it's available in all my projects
+4. Install it at user/global scope so it's available in all my projects
    (for Claude Code, use `claude mcp add ... --scope user`).
-4. Do NOT print, echo, log, or commit the key. Keep the .p8 outside any git repo.
-5. When done, verify it works by listing my App Store apps, then tell me the
+5. Do NOT print, echo, log, or commit the key. Keep the .p8 outside any git repo.
+6. When done, verify it works by listing my App Store apps, then tell me the
    result (or any error and how to fix it).
 
 Config formats per client are documented here:

package/docs/SETUP.md

@@ -11,6 +11,8 @@ Step-by-step from zero to a working server.
 
 ## 2. Create an App Store Connect API key
 
+![Where to find the Issuer ID and Key ID in App Store Connect](https://raw.githubusercontent.com/fil-technology/appstore-api-mcp/main/assets/where-to-find-credentials.png)
+
 1. Sign in to [App Store Connect](https://appstoreconnect.apple.com).
 2. Go to **Users and Access** → **Integrations** tab → **App Store Connect API**.
 3. Copy the **Issuer ID** shown near the top — this is your `ASC_ISSUER_ID`

package/docs/TOOLS.md

@@ -200,6 +200,64 @@ length warnings are attached to the response under `_warnings`.
 
 ---
 
+## Analytics, sales, subscriptions & finance
+
+> **Permissions:** these tools require an API key with the **Admin, Finance, or
+> 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.
+
+All report tools return `{ reportType, columns, rowCount, returned, truncated, rows }`
+with `rows` capped at `limit` (default 200).
+
+### get_sales_report
+Units/downloads, proceeds, and subscription data from Sales & Trends.
+- `reportDate` **(required)** — `YYYY-MM-DD` (daily/weekly), `YYYY-MM` (monthly), `YYYY` (yearly)
+- `vendorNumber` — or `ASC_VENDOR_NUMBER`
+- `frequency` — `DAILY` (default), `WEEKLY`, `MONTHLY`, `YEARLY`
+- `reportType` — `SALES` (default), `SUBSCRIPTION`, `SUBSCRIBER`, `SUBSCRIPTION_EVENT`, `INSTALLS`, …
+- `reportSubType` — `SUMMARY` (default) or `DETAILED`
+- `version` — report-version override (e.g. `1_1` for SALES, `1_4` for subscriptions)
+- `limit` — max rows (default 200)
+
+### get_subscription_report
+Convenience wrapper for subscription analytics (DAILY only).
+- `reportDate` **(required)** — `YYYY-MM-DD`
+- `kind` — `ACTIVE` (default, active-subscriber snapshot), `EVENTS` (subscribe/cancel/renew/retention), `SUBSCRIBERS` (per-subscriber detail)
+- `vendorNumber`, `limit`
+
+### get_finance_report
+Proceeds/earnings by region.
+- `reportDate` **(required)** — fiscal month `YYYY-MM`
+- `regionCode` — `ZZ` (default, consolidated), `US`, `EU`, `JP`, …
+- `vendorNumber`, `limit`
+
+### request_analytics_report
+Start an Analytics report request for an app (downloads, sessions, active
+devices, App Store engagement). **Async** — generation can take minutes to hours.
+- `appId` **(required)**
+- `accessType` — `ONE_TIME_SNAPSHOT` (default) or `ONGOING`
+
+### list_analytics_reports
+- `requestId` **(required)** — from `request_analytics_report`
+- `category` — `APP_USAGE`, `APP_STORE_ENGAGEMENT`, `COMMERCE`, `FRAMEWORK_USAGE`, `PERFORMANCE`
+
+### list_analytics_report_instances
+- `reportId` **(required)**
+- `granularity` — `DAILY`, `WEEKLY`, `MONTHLY`
+- `processingDate` — `YYYY-MM-DD`
+
+### get_analytics_report_data
+Download + decompress + parse an instance's segments into rows.
+- `instanceId` **(required)**
+- `limit` — max rows (default 200)
+
+**Typical analytics flow:** `request_analytics_report` → (wait) →
+`list_analytics_reports` → `list_analytics_report_instances` →
+`get_analytics_report_data`.
+
+---
+
 ## Raw API access
 
 ### `raw_request`

package/package.json

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

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { createHash } from "node:crypto";
+import { gunzipSync } from "node:zlib";
 import { importPKCS8, SignJWT } from "jose";
 
 const BASE_URL = "https://api.appstoreconnect.apple.com";
@@ -54,8 +55,7 @@ export class AppStoreConnectClient {
    * Core request. `path` may be a full URL (e.g. a paging `next` link) or a
    * path relative to the API root, with or without the leading /v1.
    */
-  async request(method, path, { query, body } = {}) {
-    const token = await this._getToken();
+  _buildUrl(path, query) {
     let url;
     if (/^https?:\/\//.test(path)) {
       url = new URL(path);
@@ -72,6 +72,12 @@ export class AppStoreConnectClient {
         url.searchParams.set(k, Array.isArray(v) ? v.join(",") : String(v));
       }
     }
+    return url;
+  }
+
+  async request(method, path, { query, body } = {}) {
+    const token = await this._getToken();
+    const url = this._buildUrl(path, query);
     const headers = { Authorization: `Bearer ${token}` };
     let payload;
     if (body !== undefined) {
@@ -133,6 +139,72 @@ export class AppStoreConnectClient {
     return all;
   }
 
+  /** True if the buffer starts with the gzip magic bytes. */
+  static _isGzip(buf) {
+    return buf.length > 2 && buf[0] === 0x1f && buf[1] === 0x8b;
+  }
+
+  /**
+   * GET a report endpoint (salesReports / financeReports) that returns a
+   * gzip-compressed TSV. Returns the decompressed text. On error, the API
+   * sends JSON instead of gzip — surfaced as a readable Error.
+   */
+  async getReport(path, query) {
+    const token = await this._getToken();
+    const url = this._buildUrl(path, query);
+    const res = await fetch(url, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${token}`, Accept: "application/a-gzip" },
+    });
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (!res.ok) {
+      let detail = buf.toString("utf8");
+      try {
+        const j = JSON.parse(detail);
+        if (j.errors)
+          detail = j.errors
+            .map((e) => `${e.status} ${e.code}: ${e.title} — ${e.detail}`)
+            .join("; ");
+      } catch {
+        /* leave detail as text */
+      }
+      const err = new Error(
+        `App Store Connect report ${url.pathname} failed: ${res.status} ${res.statusText} — ${detail}`,
+      );
+      err.status = res.status;
+      throw err;
+    }
+    return AppStoreConnectClient._isGzip(buf)
+      ? gunzipSync(buf).toString("utf8")
+      : buf.toString("utf8");
+  }
+
+  /** Download a (possibly gzipped) report/segment file from a pre-signed URL. */
+  async downloadUrl(url) {
+    const res = await fetch(url);
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (!res.ok)
+      throw new Error(`Download failed (${res.status}) for ${url}`);
+    return AppStoreConnectClient._isGzip(buf)
+      ? gunzipSync(buf).toString("utf8")
+      : buf.toString("utf8");
+  }
+
+  /** 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);
+    if (lines.length === 0) return { columns: [], rows: [] };
+    const d = delimiter || (lines[0].includes("\t") ? "\t" : ",");
+    const columns = lines[0].split(d);
+    const rows = lines.slice(1).map((line) => {
+      const cells = line.split(d);
+      const row = {};
+      columns.forEach((c, i) => (row[c] = cells[i]));
+      return row;
+    });
+    return { columns, rows };
+  }
+
   /**
    * Upload an image to a freshly-reserved upload-asset (screenshot or preview).
    * `uploadOperations` come from the reservation's attributes.

package/src/index.js

@@ -128,6 +128,45 @@ const EDITABLE_VERSION_STATES = new Set([
   "INVALID_BINARY",
 ]);
 
+// Optional default Vendor Number for sales/finance reports.
+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 {
+    reportType,
+    columns: parsed.columns,
+    rowCount: rows.length,
+    returned: Math.min(rows.length, limit),
+    truncated: rows.length > limit,
+    rows: rows.slice(0, limit),
+  };
+}
+
+function requireVendor(v) {
+  const vendor = v || DEFAULT_VENDOR;
+  if (!vendor)
+    throw new Error(
+      "vendorNumber is required (or set the ASC_VENDOR_NUMBER env var). Find it in App Store Connect → Payments and Financial Reports (or Sales and Trends) — an 8–9 digit number.",
+    );
+  return vendor;
+}
+
+// Tools that hit role-gated report/analytics endpoints. On a 403 the dispatcher
+// appends a hint that these need a higher-privilege key than App Manager.
+const REPORT_TOOLS = new Set([
+  "get_sales_report",
+  "get_subscription_report",
+  "get_finance_report",
+  "request_analytics_report",
+  "list_analytics_reports",
+  "list_analytics_report_instances",
+  "get_analytics_report_data",
+]);
+const ROLE_HINT =
+  " — NOTE: report/analytics APIs require an API key with the Admin, Finance, or Sales role. An App Manager key is not sufficient; generate a key with the needed role in App Store Connect → Users and Access → Integrations.";
+
 // ---- Tool definitions -------------------------------------------------------
 
 const tools = [
@@ -751,6 +790,250 @@ const tools = [
     },
   },
 
+  // ---- Analytics, sales, subscriptions & finance ----
+  {
+    name: "get_sales_report",
+    description:
+      "Download a Sales & Trends report (units/downloads, proceeds, and subscription data) and return parsed rows. Requires your Vendor Number (App Store Connect → Payments and Financial Reports / Sales and Trends; 8–9 digits) via vendorNumber or the ASC_VENDOR_NUMBER env var. reportType: SALES (units & proceeds, default), SUBSCRIPTION (active subs snapshot), SUBSCRIBER (per-subscriber detail), SUBSCRIPTION_EVENT (subscribe/cancel/renew), INSTALLS, FIRST_ANNUAL. reportDate format by frequency: DAILY/WEEKLY = YYYY-MM-DD, MONTHLY = YYYY-MM, YEARLY = YYYY.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        vendorNumber: { type: "string" },
+        reportDate: {
+          type: "string",
+          description: "e.g. 2024-01-15 (daily) or 2024-01 (monthly)",
+        },
+        frequency: {
+          type: "string",
+          description: "DAILY (default), WEEKLY, MONTHLY, YEARLY",
+        },
+        reportType: {
+          type: "string",
+          description: "SALES (default), SUBSCRIPTION, SUBSCRIBER, SUBSCRIPTION_EVENT, INSTALLS, …",
+        },
+        reportSubType: {
+          type: "string",
+          description: "SUMMARY (default) or DETAILED",
+        },
+        version: {
+          type: "string",
+          description: "Report version override (e.g. 1_1 for SALES, 1_4 for subscriptions)",
+        },
+        limit: { type: "number", description: "Max rows to return (default 200)" },
+      },
+      required: ["reportDate"],
+    },
+    run: async (a) => {
+      const vendor = requireVendor(a.vendorNumber);
+      const reportType = a.reportType || "SALES";
+      const subType =
+        a.reportSubType || (reportType === "SUBSCRIBER" ? "DETAILED" : "SUMMARY");
+      const version =
+        a.version ||
+        (reportType === "SALES"
+          ? "1_1"
+          : reportType.startsWith("SUBSC")
+            ? "1_4"
+            : "1_0");
+      const text = await client.getReport("/salesReports", {
+        "filter[vendorNumber]": vendor,
+        "filter[frequency]": a.frequency || "DAILY",
+        "filter[reportType]": reportType,
+        "filter[reportSubType]": subType,
+        "filter[reportDate]": a.reportDate,
+        "filter[version]": version,
+      });
+      return reportResult(
+        reportType,
+        AppStoreConnectClient.parseDelimited(text, "\t"),
+        a.limit ?? 200,
+      );
+    },
+  },
+  {
+    name: "get_subscription_report",
+    description:
+      "Subscription analytics via Sales & Trends (convenience wrapper). kind: ACTIVE = current active-subscriber snapshot, EVENTS = subscribe/cancel/renew/retention events, SUBSCRIBERS = per-subscriber detail. Requires the Vendor Number. These reports are DAILY only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        vendorNumber: { type: "string" },
+        kind: {
+          type: "string",
+          description: "ACTIVE (default), EVENTS, SUBSCRIBERS",
+        },
+        reportDate: { type: "string", description: "YYYY-MM-DD" },
+        limit: { type: "number", description: "Max rows (default 200)" },
+      },
+      required: ["reportDate"],
+    },
+    run: async (a) => {
+      const vendor = requireVendor(a.vendorNumber);
+      const map = {
+        ACTIVE: ["SUBSCRIPTION", "SUMMARY"],
+        EVENTS: ["SUBSCRIPTION_EVENT", "SUMMARY"],
+        SUBSCRIBERS: ["SUBSCRIBER", "DETAILED"],
+      };
+      const [reportType, subType] = map[a.kind || "ACTIVE"] || map.ACTIVE;
+      const text = await client.getReport("/salesReports", {
+        "filter[vendorNumber]": vendor,
+        "filter[frequency]": "DAILY",
+        "filter[reportType]": reportType,
+        "filter[reportSubType]": subType,
+        "filter[reportDate]": a.reportDate,
+        "filter[version]": "1_4",
+      });
+      return reportResult(
+        reportType,
+        AppStoreConnectClient.parseDelimited(text, "\t"),
+        a.limit ?? 200,
+      );
+    },
+  },
+  {
+    name: "get_finance_report",
+    description:
+      "Download a Finance report (proceeds/earnings by region) and return parsed rows. Requires the Vendor Number, a regionCode (e.g. 'ZZ' for the consolidated/all-regions report, or 'US', 'EU', 'JP', …) and reportDate as YYYY-MM (a fiscal month).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        vendorNumber: { type: "string" },
+        regionCode: { type: "string", description: "e.g. ZZ (default), US, EU, JP" },
+        reportDate: { type: "string", description: "Fiscal month, YYYY-MM" },
+        limit: { type: "number", description: "Max rows (default 200)" },
+      },
+      required: ["reportDate"],
+    },
+    run: async (a) => {
+      const vendor = requireVendor(a.vendorNumber);
+      const text = await client.getReport("/financeReports", {
+        "filter[vendorNumber]": vendor,
+        "filter[regionCode]": a.regionCode || "ZZ",
+        "filter[reportDate]": a.reportDate,
+        "filter[reportType]": "FINANCIAL",
+      });
+      return reportResult(
+        "FINANCIAL",
+        AppStoreConnectClient.parseDelimited(text, "\t"),
+        a.limit ?? 200,
+      );
+    },
+  },
+  {
+    name: "request_analytics_report",
+    description:
+      "Start an Analytics report request for an app — covers downloads, installs, sessions, active devices, App Store engagement (impressions, product page views, conversion), and more. accessType: ONE_TIME_SNAPSHOT (historical, default) or ONGOING (kept up to date daily). Generation is ASYNC and can take minutes to hours. Afterwards: list_analytics_reports → list_analytics_report_instances → get_analytics_report_data.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        appId: { type: "string" },
+        accessType: {
+          type: "string",
+          description: "ONE_TIME_SNAPSHOT (default) or ONGOING",
+        },
+      },
+      required: ["appId"],
+    },
+    run: async (a) =>
+      client.post("/analyticsReportRequests", {
+        data: {
+          type: "analyticsReportRequests",
+          attributes: { accessType: a.accessType || "ONE_TIME_SNAPSHOT" },
+          relationships: { app: { data: { type: "apps", id: a.appId } } },
+        },
+      }),
+  },
+  {
+    name: "list_analytics_reports",
+    description:
+      "List the reports available under an analytics report request (from request_analytics_report). category filter: APP_USAGE, APP_STORE_ENGAGEMENT, COMMERCE, FRAMEWORK_USAGE, PERFORMANCE.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        requestId: { type: "string" },
+        category: { type: "string" },
+      },
+      required: ["requestId"],
+    },
+    run: async (a) => {
+      const q = {};
+      if (a.category) q["filter[category]"] = a.category;
+      const data = await client.getAll(
+        `/analyticsReportRequests/${a.requestId}/reports`,
+        q,
+      );
+      return data.map((x) => ({ id: x.id, ...x.attributes }));
+    },
+  },
+  {
+    name: "list_analytics_report_instances",
+    description:
+      "List instances of an analytics report (one per processing date). granularity: DAILY, WEEKLY, MONTHLY. Use the instance id with get_analytics_report_data.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        reportId: { type: "string" },
+        granularity: { type: "string", description: "DAILY, WEEKLY, MONTHLY" },
+        processingDate: { type: "string", description: "YYYY-MM-DD" },
+      },
+      required: ["reportId"],
+    },
+    run: async (a) => {
+      const q = {};
+      if (a.granularity) q["filter[granularity]"] = a.granularity;
+      if (a.processingDate) q["filter[processingDate]"] = a.processingDate;
+      const data = await client.getAll(
+        `/analyticsReports/${a.reportId}/instances`,
+        q,
+      );
+      return data.map((x) => ({ id: x.id, ...x.attributes }));
+    },
+  },
+  {
+    name: "get_analytics_report_data",
+    description:
+      "Download and parse the data for an analytics report instance. Fetches its segments (gzipped CSV), decompresses, and returns parsed rows.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        instanceId: { type: "string" },
+        limit: { type: "number", description: "Max rows (default 200)" },
+      },
+      required: ["instanceId"],
+    },
+    run: async (a) => {
+      const segs = await client.getAll(
+        `/analyticsReportInstances/${a.instanceId}/segments`,
+      );
+      if (!segs.length)
+        return {
+          rowCount: 0,
+          rows: [],
+          note: "No segments yet — the instance may still be processing. Try again later.",
+        };
+      let columns = [];
+      const allRows = [];
+      for (const s of segs) {
+        const url = s.attributes && s.attributes.url;
+        if (!url) continue;
+        const parsed = AppStoreConnectClient.parseDelimited(
+          await client.downloadUrl(url),
+        );
+        if (!columns.length) columns = parsed.columns;
+        allRows.push(...parsed.rows);
+      }
+      const limit = a.limit ?? 200;
+      return {
+        columns,
+        segments: segs.length,
+        rowCount: allRows.length,
+        returned: Math.min(allRows.length, limit),
+        truncated: allRows.length > limit,
+        rows: allRows.slice(0, limit),
+      };
+    },
+  },
+
   // ---- Generic escape hatch ----
   {
     name: "raw_request",
@@ -806,6 +1089,8 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
     const result = await tool.run(req.params.arguments || {});
     return ok(result);
   } catch (e) {
+    if (e && e.status === 403 && REPORT_TOOLS.has(req.params.name))
+      e.message += ROLE_HINT;
     return fail(e);
   }
 });