appstore-api-mcp 1.0.0

package/docs/TOOLS.md

@@ -0,0 +1,239 @@
+# Tool reference
+
+Every tool the server exposes, with parameters and return shape. You normally
+don't call these by hand — you ask the model in plain language and it picks the
+right ones. This is for when you want the exact contract.
+
+All tools return JSON (pretty-printed text). IDs are App Store Connect resource
+ids (strings). Required params are marked **(required)**.
+
+---
+
+## Apps
+
+### `list_apps`
+List all apps in the account.
+- `limit` — max apps (default 100)
+- `filterBundleId` — exact bundle id filter
+- **Returns:** array of `{ id, name, bundleId, sku, primaryLocale, ... }`
+
+### `get_app`
+Get one app's details.
+- `appId` **(required)**
+
+---
+
+## App info — name, subtitle, privacy policy
+
+These live on `appInfo` records, separate from version-specific copy.
+
+### `list_app_infos`
+List the appInfo records for an app. Usually one is editable.
+- `appId` **(required)**
+
+### `list_app_info_localizations`
+List per-locale name/subtitle/privacy for an appInfo.
+- `appInfoId` **(required)**
+- **Returns:** array of `{ id, locale, name, subtitle, privacyPolicyUrl, privacyPolicyText }`
+
+### `update_app_info_localization`
+Update name/subtitle/privacy for one locale. Only pass fields you want to change.
+- `localizationId` **(required)** — an appInfoLocalization id
+- `name` — app name (max 30 chars)
+- `subtitle` — subtitle (max 30 chars)
+- `privacyPolicyUrl`
+- `privacyPolicyText`
+- `dryRun` — if true, **write nothing**; return a diff + length/limit checks (see [Dry-run mode](#dry-run-mode))
+
+### `create_app_info_localization`
+Add a brand-new locale's name/subtitle/privacy.
+- `appInfoId` **(required)**
+- `locale` **(required)** — e.g. `fr-FR`, `de-DE`
+- `name`, `subtitle`, `privacyPolicyUrl`, `privacyPolicyText`
+
+---
+
+## Versions
+
+### `list_app_store_versions`
+List versions and states for an app.
+- `appId` **(required)**
+- `filterState` — e.g. `PREPARE_FOR_SUBMISSION`, `READY_FOR_SALE`
+- `filterPlatform` — `IOS`, `MAC_OS`, `TV_OS`, `VISION_OS`
+
+### `create_app_store_version`
+Create a new version to prepare for submission.
+- `appId` **(required)**
+- `versionString` **(required)** — e.g. `1.3.0`
+- `platform` — default `IOS`
+
+---
+
+## Version localizations — description, keywords, what's-new
+
+### `list_app_store_version_localizations`
+List per-locale listing copy for a version.
+- `versionId` **(required)**
+- **Returns:** array of `{ id, locale, description, keywords, promotionalText, whatsNew, marketingUrl, supportUrl }`
+
+### `get_app_store_version_localization`
+Read one locale's listing copy.
+- `localizationId` **(required)**
+
+### `update_app_store_version_localization`
+Update keywords/description/etc. for one locale. Only pass fields to change.
+- `localizationId` **(required)**
+- `keywords` — comma-separated, **max 100 chars total** (e.g. `todo,tasks,planner`)
+- `description` — max 4000 chars
+- `promotionalText` — max 170 chars (editable without a new version)
+- `whatsNew` — release notes, max 4000 chars
+- `marketingUrl`
+- `supportUrl`
+- `dryRun` — if true, **write nothing**; return a diff + length/limit checks (see [Dry-run mode](#dry-run-mode))
+
+### `create_app_store_version_localization`
+Add a new locale to a version.
+- `versionId` **(required)**
+- `locale` **(required)**
+- `description`, `keywords`, `promotionalText`, `whatsNew`, `marketingUrl`, `supportUrl`
+
+---
+
+## Screenshots
+
+Screenshots are organized into **sets**, one per device display type, attached to
+a version localization.
+
+Common `displayType` values: `APP_IPHONE_67`, `APP_IPHONE_65`, `APP_IPHONE_61`,
+`APP_IPHONE_55`, `APP_IPAD_PRO_129`, `APP_IPAD_PRO_3GEN_11`.
+
+### `list_screenshot_sets`
+- `localizationId` **(required)** — an appStoreVersionLocalization id
+
+### `create_screenshot_set`
+- `localizationId` **(required)**
+- `displayType` **(required)**
+
+### `list_screenshots`
+- `screenshotSetId` **(required)**
+
+### `upload_screenshot`
+Upload an image into a set. Handles reserve → upload bytes → commit (with checksum).
+- `screenshotSetId` **(required)**
+- `filePath` **(required)** — absolute path to a PNG/JPEG matching the device's exact dimensions
+- `fileName` — optional override for the stored name
+
+### `delete_screenshot`
+- `screenshotId` **(required)**
+
+---
+
+## Fleet audit
+
+### audit_apps
+Read-only health check across **all** your apps (or a subset). For each app it
+inspects the editable App Store version and app info, then flags listing/ASO
+issues. Writes nothing.
+
+- `appIds` — array of app ids to limit the audit to (default: all apps)
+- `limit` — audit at most this many apps (default: all)
+- `checkScreenshots` — also flag the primary locale when it has no screenshots
+  (slower; extra API calls). Default `false`.
+- `keywordUseThreshold` — flag the keyword field as under-used below this many
+  chars (default `70` of 100).
+
+**Issue codes** (each finding has `severity` of `error` / `warning` / `info` / `opportunity`):
+
+| code | meaning |
+| --- | --- |
+| `missing_subtitle` | No subtitle (wasted free ASO keywords) |
+| `missing_keywords` | Keyword field empty |
+| `keywords_underused` | Keyword field uses < threshold of 100 chars |
+| `missing_description` | No description |
+| `missing_promotional_text` | No promotional text |
+| `missing_whats_new` | No release notes |
+| `single_locale` | Listing in only one locale |
+| `missing_screenshots` | No screenshots (only when `checkScreenshots: true`) |
+| `no_editable_version` | No version in an editable state right now |
+| `audit_failed` | The app could not be fully read (details in the message) |
+
+**Returns**
+```jsonc
+{
+  "summary": {
+    "appsAudited": 62,
+    "appsWithNoIssues": 11,
+    "appsWithIssues": 51,
+    "issuesByType": { "missing_subtitle": 8, "keywords_underused": 14, ... },
+    "screenshotsChecked": false
+  },
+  "findings": [
+    { "appId": "…", "name": "…", "bundleId": "…", "primaryLocale": "en-US",
+      "issueCount": 6, "issues": [ { "severity": "warning", "code": "missing_keywords", "message": "…" } ] }
+  ]  // sorted by issueCount, worst first
+}
+```
+
+---
+
+## Dry-run mode
+
+The `update_app_store_version_localization` and `update_app_info_localization`
+tools accept `dryRun: true`. Instead of writing, the tool reads the current
+values, computes a diff, validates lengths against Apple's limits, and returns:
+
+```jsonc
+{
+  "dryRun": true,
+  "id": "…",
+  "changes": [
+    { "field": "keywords", "from": "old,kw", "to": "new,kw",
+      "changed": true, "newLength": 6, "limit": 100, "exceedsLimit": false }
+  ],
+  "warnings": [ "'keywords' is 111 chars — exceeds Apple's limit of 100." ],
+  "note": "No changes were written. Re-run without dryRun to apply."
+}
+```
+
+Re-run the same call **without** `dryRun` to apply. On a real write, any
+length warnings are attached to the response under `_warnings`.
+
+---
+
+## Raw API access
+
+### `raw_request`
+Call any App Store Connect endpoint not covered above — previews, pricing,
+availability, TestFlight, in-app purchases, subscriptions, customer reviews,
+analytics, sales & finance reports, etc.
+
+- `method` **(required)** — `GET` | `POST` | `PATCH` | `DELETE`
+- `path` **(required)** — relative (e.g. `/apps` or `/appStoreVersions/{id}`; `/v1`
+  is prepended automatically) or a full `https://…` URL (e.g. a paging `next` link)
+- `query` — flat object of query params
+- `body` — JSON request body for POST/PATCH
+
+**Examples**
+```jsonc
+// Read customer reviews
+{ "method": "GET", "path": "/apps/123456/customerReviews", "query": { "limit": 50 } }
+
+// Reply to a review
+{ "method": "POST", "path": "/customerReviewResponses",
+  "body": { "data": { "type": "customerReviewResponses",
+    "attributes": { "responseBody": "Thanks for the feedback!" },
+    "relationships": { "review": { "data": { "type": "customerReviews", "id": "REVIEW_ID" } } } } } }
+```
+
+Reference: <https://developer.apple.com/documentation/appstoreconnectapi>
+
+---
+
+## Notes on editability
+
+- Listing copy (description, keywords, name, subtitle, what's-new) only **saves on a
+  version in an editable state** such as `PREPARE_FOR_SUBMISSION`. Promotional text
+  is the exception — it can be updated on a live version.
+- Edits change the **draft**. Changes go public only after you submit and Apple approves.
+- The API paginates; list tools auto-follow pages (up to a safety cap). For very
+  large accounts use `raw_request` with explicit `limit`/cursor if needed.

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "appstore-api-mcp",
+  "version": "1.0.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, Cursor, Cline, Windsurf, VS Code, Zed, Continue, and custom agents). Includes a fleet-wide ASO audit and dry-run previews.",
+  "type": "module",
+  "bin": {
+    "appstore-api-mcp": "src/index.js"
+  },
+  "main": "src/index.js",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "docs",
+    ".env.example"
+  ],
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "app-store-connect",
+    "appstore",
+    "app-store",
+    "itunes-connect",
+    "aso",
+    "ios",
+    "apple",
+    "claude",
+    "keywords",
+    "screenshots",
+    "metadata"
+  ],
+  "license": "MIT",
+  "author": "Sviatoslav Fil",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fil-technology/appstore-api-mcp.git"
+  },
+  "homepage": "https://github.com/fil-technology/appstore-api-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/fil-technology/appstore-api-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "jose": "^5.9.6"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/client.js

@@ -0,0 +1,162 @@
+import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { importPKCS8, SignJWT } from "jose";
+
+const BASE_URL = "https://api.appstoreconnect.apple.com";
+
+/**
+ * Thin client for the App Store Connect API.
+ * Handles ES256 JWT minting (cached until shortly before expiry) and
+ * exposes request helpers plus a multi-step screenshot uploader.
+ */
+export class AppStoreConnectClient {
+  constructor({ keyId, issuerId, privateKeyPath, privateKey, privateKeyBase64 }) {
+    if (!keyId) throw new Error("ASC_KEY_ID is required");
+    if (!issuerId) throw new Error("ASC_ISSUER_ID is required");
+    this.keyId = keyId;
+    this.issuerId = issuerId;
+    // Accept the .p8 key three ways, in priority order:
+    //   1. inline PEM text          (ASC_PRIVATE_KEY)
+    //   2. base64-encoded PEM       (ASC_PRIVATE_KEY_BASE64) — easiest for env vars
+    //   3. path to the .p8 file     (ASC_PRIVATE_KEY_PATH)
+    this._pem =
+      privateKey ||
+      (privateKeyBase64
+        ? Buffer.from(privateKeyBase64, "base64").toString("utf8")
+        : null) ||
+      (privateKeyPath ? readFileSync(privateKeyPath, "utf8") : null);
+    if (!this._pem)
+      throw new Error(
+        "Provide the API key via ASC_PRIVATE_KEY_PATH, ASC_PRIVATE_KEY, or ASC_PRIVATE_KEY_BASE64",
+      );
+    this._token = null;
+    this._tokenExp = 0;
+  }
+
+  async _getToken() {
+    const now = Math.floor(Date.now() / 1000);
+    // Reuse token while it still has >60s of life.
+    if (this._token && now < this._tokenExp - 60) return this._token;
+    const key = await importPKCS8(this._pem, "ES256");
+    const exp = now + 19 * 60; // App Store Connect caps token life at 20 min.
+    this._token = await new SignJWT({})
+      .setProtectedHeader({ alg: "ES256", kid: this.keyId, typ: "JWT" })
+      .setIssuedAt(now)
+      .setIssuer(this.issuerId)
+      .setExpirationTime(exp)
+      .setAudience("appstoreconnect-v1")
+      .sign(key);
+    this._tokenExp = exp;
+    return this._token;
+  }
+
+  /**
+   * 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();
+    let url;
+    if (/^https?:\/\//.test(path)) {
+      url = new URL(path);
+    } else {
+      const clean = path.startsWith("/") ? path : `/${path}`;
+      const withVersion = clean.startsWith("/v1") || clean.startsWith("/v2")
+        ? clean
+        : `/v1${clean}`;
+      url = new URL(BASE_URL + withVersion);
+    }
+    if (query) {
+      for (const [k, v] of Object.entries(query)) {
+        if (v === undefined || v === null) continue;
+        url.searchParams.set(k, Array.isArray(v) ? v.join(",") : String(v));
+      }
+    }
+    const headers = { Authorization: `Bearer ${token}` };
+    let payload;
+    if (body !== undefined) {
+      headers["Content-Type"] = "application/json";
+      payload = JSON.stringify(body);
+    }
+    const res = await fetch(url, { method, headers, body: payload });
+    const text = await res.text();
+    let data = null;
+    if (text) {
+      try {
+        data = JSON.parse(text);
+      } catch {
+        data = text;
+      }
+    }
+    if (!res.ok) {
+      const detail =
+        data && data.errors
+          ? data.errors
+              .map((e) => `${e.status} ${e.code}: ${e.title} — ${e.detail}`)
+              .join("; ")
+          : typeof data === "string"
+            ? data
+            : JSON.stringify(data);
+      const err = new Error(
+        `App Store Connect ${method} ${url.pathname} failed: ${res.status} ${res.statusText} — ${detail}`,
+      );
+      err.status = res.status;
+      err.body = data;
+      throw err;
+    }
+    return data;
+  }
+
+  get(path, query) {
+    return this.request("GET", path, { query });
+  }
+  post(path, body) {
+    return this.request("POST", path, { body });
+  }
+  patch(path, body) {
+    return this.request("PATCH", path, { body });
+  }
+  delete(path) {
+    return this.request("DELETE", path);
+  }
+
+  /** Follow `links.next` and concatenate `data` arrays up to `maxPages`. */
+  async getAll(path, query, maxPages = 20) {
+    let page = await this.get(path, query);
+    const all = Array.isArray(page.data) ? [...page.data] : [];
+    let pages = 1;
+    while (page.links && page.links.next && pages < maxPages) {
+      page = await this.request("GET", page.links.next);
+      if (Array.isArray(page.data)) all.push(...page.data);
+      pages++;
+    }
+    return all;
+  }
+
+  /**
+   * Upload an image to a freshly-reserved upload-asset (screenshot or preview).
+   * `uploadOperations` come from the reservation's attributes.
+   */
+  async uploadAsset(uploadOperations, fileBuffer) {
+    for (const op of uploadOperations) {
+      const chunk = fileBuffer.subarray(op.offset, op.offset + op.length);
+      const headers = {};
+      for (const h of op.requestHeaders || []) headers[h.name] = h.value;
+      const res = await fetch(op.url, {
+        method: op.method,
+        headers,
+        body: chunk,
+      });
+      if (!res.ok) {
+        const t = await res.text();
+        throw new Error(
+          `Asset chunk upload failed (${op.method} ${op.url}): ${res.status} ${t}`,
+        );
+      }
+    }
+  }
+
+  static md5(buffer) {
+    return createHash("md5").update(buffer).digest("hex");
+  }
+}