asc-mcp-pro 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rsalim0
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,241 @@
+# asc-mcp
+
+An MCP server that exposes **191 tools** spanning the entire App Store Connect API: apps, versions, builds, TestFlight, IAP & subscriptions, pricing, screenshots, certificates, reports — plus high-level **workflow macros** (`release_next_version`, `submission_health`, `aso_audit`, `crash_triage`, etc.) and a **declarative workflow runner** that executes JSON manifests.
+
+Built so you can do *"translate my what's-new to all locales and push"* or *"submit the latest build to External Testers"* from a Claude conversation instead of clicking through ASC for 40 minutes.
+
+[![Add asc-mcp-pro to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=asc-mcp-pro&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImFzYy1tY3AtcHJvIl0sImVudiI6eyJBUFBfU1RPUkVfQ09OTkVDVF9LRVlfSUQiOiJZT1VSX0tFWV9JRCIsIkFQUF9TVE9SRV9DT05ORUNUX0lTU1VFUl9JRCI6IllPVVJfSVNTVUVSX0lEIiwiQVBQX1NUT1JFX0NPTk5FQ1RfUDhfUEFUSCI6Ii9hYnNvbHV0ZS9wYXRoL3RvL0F1dGhLZXkucDgifX0%3D)
+
+> The button opens Cursor with a pre-filled install dialog. After install, edit `~/.cursor/mcp.json` and replace `YOUR_KEY_ID`, `YOUR_ISSUER_ID`, and the `.p8` path with your real values — see [Getting an App Store Connect API key](#getting-an-app-store-connect-api-key) below.
+
+---
+
+## Install
+
+### Option A — npm (recommended for end users)
+
+```bash
+claude mcp add appstore-connect \
+  -e APP_STORE_CONNECT_KEY_ID=YOUR_KEY_ID \
+  -e APP_STORE_CONNECT_ISSUER_ID=YOUR_ISSUER_ID \
+  -e APP_STORE_CONNECT_P8_PATH=/absolute/path/to/AuthKey_XXXXXX.p8 \
+  -- npx -y asc-mcp-pro
+```
+
+### Option B — install directly from GitHub
+
+```bash
+claude mcp add appstore-connect \
+  -e APP_STORE_CONNECT_KEY_ID=YOUR_KEY_ID \
+  -e APP_STORE_CONNECT_ISSUER_ID=YOUR_ISSUER_ID \
+  -e APP_STORE_CONNECT_P8_PATH=/absolute/path/to/AuthKey_XXXXXX.p8 \
+  -- npx -y github:rsalim0/asc-mcp
+```
+
+### Option C — local clone (for hacking on the code)
+
+```bash
+git clone https://github.com/rsalim0/asc-mcp.git
+cd asc-mcp
+npm install
+npm run build
+
+claude mcp add appstore-connect \
+  -e APP_STORE_CONNECT_KEY_ID=YOUR_KEY_ID \
+  -e APP_STORE_CONNECT_ISSUER_ID=YOUR_ISSUER_ID \
+  -e APP_STORE_CONNECT_P8_PATH=/absolute/path/to/AuthKey_XXXXXX.p8 \
+  -- node $(pwd)/build/index.js
+```
+
+Add `APP_STORE_CONNECT_VENDOR_NUMBER=XXXXXXXXXX` to enable sales / finance report tools (find your vendor number under *Payments and Financial Reports* in App Store Connect).
+
+---
+
+## Other MCP clients
+
+MCP is a standard protocol — this server works with **any** MCP client, not just Claude Code. The config snippet is the same shape everywhere:
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "asc-mcp-pro"],
+  "env": {
+    "APP_STORE_CONNECT_KEY_ID": "YOUR_KEY_ID",
+    "APP_STORE_CONNECT_ISSUER_ID": "YOUR_ISSUER_ID",
+    "APP_STORE_CONNECT_P8_PATH": "/absolute/path/to/AuthKey.p8"
+  }
+}
+```
+
+Drop it into your client's MCP config file:
+
+| Client | Config file | How to slot it in |
+|---|---|---|
+| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)<br>`%APPDATA%\Claude\claude_desktop_config.json` (Windows) | Under `"mcpServers": { "asc-mcp-pro": { …snippet… } }` |
+| **Cursor** | `~/.cursor/mcp.json` | Under `"mcpServers": { "asc-mcp-pro": { …snippet… } }` (or use the button above) |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | Under `"mcpServers": { "asc-mcp-pro": { …snippet… } }` |
+| **Zed** | Zed settings (`~/.config/zed/settings.json`) | Under `"context_servers": { "asc-mcp-pro": { …snippet… } }` |
+| **Continue** (VS Code / JetBrains) | `.continue/config.json` | See [Continue MCP docs](https://docs.continue.dev/customization/mcp-tools) — same `command/args/env` shape |
+| **OpenAI Codex CLI** | `~/.codex/config.toml` | TOML form (see below) |
+
+### Codex CLI (TOML form)
+
+Codex uses TOML, not JSON. Add this to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.asc_mcp_pro]
+command = "npx"
+args = ["-y", "asc-mcp-pro"]
+env = { APP_STORE_CONNECT_KEY_ID = "YOUR_KEY_ID", APP_STORE_CONNECT_ISSUER_ID = "YOUR_ISSUER_ID", APP_STORE_CONNECT_P8_PATH = "/absolute/path/to/AuthKey.p8" }
+```
+
+(Note: Codex config keys must be valid TOML identifiers, so the table name uses `asc_mcp_pro` with underscores rather than hyphens.)
+
+After editing the config file, restart your client.
+
+---
+
+## Getting an App Store Connect API key
+
+1. Go to https://appstoreconnect.apple.com/access/integrations/api
+2. Click **+** to generate a new key. Role: **App Manager** (or **Admin** if you need full provisioning access).
+3. Note the **Key ID** (10 chars, e.g. `7Y3QAAD5HX`) and **Issuer ID** (UUID).
+4. **Download API Key** — saves `AuthKey_<KEYID>.p8`. ⚠️ One-time download — keep it safe.
+5. Pass all three to the `claude mcp add` command above.
+
+---
+
+## Quick wins
+
+Once installed, try in Claude Code:
+
+```
+list my apps
+audit the latest version of <app name> for submission readiness
+draft what's new from git log v1.2.0..HEAD in ~/code/myapp
+find the newest valid build for <app name> and add it to my "Beta" group
+list reviews I haven't responded to yet for <app name>
+show me the keyword overlap and gaps for <app name>'s latest version
+```
+
+---
+
+## Tool catalog (191 tools)
+
+| Group | Tools | Notable |
+|---|---:|---|
+| `asc_ping` | 1 | Smoke test |
+| `asc_apps_*` | 11 | List/get/update apps + app info localizations |
+| `asc_versions_*` | 28 | Version CRUD, localizations, submission, phased release, review details, age rating |
+| `asc_review_submissions_*` | 4 | v2 review submission API (bundles version + IAPs) |
+| `asc_builds_*` | 12 | Builds + beta build localizations + export compliance |
+| `asc_testflight_*` | 25 | Groups, testers (single + bulk), public links, beta review, feedback |
+| `asc_reviews_*` | 3 | Customer reviews + developer responses |
+| `asc_iap_*` | 8 | IAP CRUD + localizations + review submission |
+| `asc_subscription*` / `asc_subscriptions_*` | 17 | Groups, subscriptions, prices, intro + promotional offers, localizations |
+| `asc_pricing_*` | 6 | Price schedules, territories, availability, pre-orders |
+| `asc_reports_*` / `asc_analytics_*` | 6 | Sales/finance (gzip TSV parsed), async analytics flow |
+| `asc_users_*` / `asc_user_invitations_*` | 4 | Team management |
+| `asc_bundle_*` / `asc_certificates_*` / `asc_profiles_*` / `asc_devices_*` | 14 | Signing assets |
+| `asc_screenshots_*` / `asc_previews_*` | 17 | Sets, single upload, **folder matrix upload**, reorder, delete |
+| `asc_workflow_*` | 14 | Macros (see below) + declarative runner |
+
+### Workflow macros (the payoff)
+
+- **`asc_workflow_release_next_version`** — copy metadata from prior version, attach latest build, set release type. Caller pushes "what's new" separately.
+- **`asc_workflow_whats_new_from_git`** — `git log <since>..HEAD` → clean release-note bullets.
+- **`asc_workflow_localize_metadata`** — push a translations map across locales (calling model does the translation inline).
+- **`asc_workflow_testflight_quick_ship`** — newest valid build → groups → "what to test" → optional beta submit.
+- **`asc_workflow_submission_health`** — pre-submit audit: locales complete, screenshots present, export compliance, review details, build attached, age rating.
+- **`asc_workflow_aso_audit`** — keyword duplicates, unused chars, words wasted in description, optional competitor diff.
+- **`asc_workflow_build_lifecycle`** — all builds w/ days-to-expiry, flag <7 days.
+- **`asc_workflow_crash_triage`** — top diagnostic signatures grouped across recent builds.
+- **`asc_workflow_id_resolver`** — bundle id / name / sku → canonical appId + latest version/build.
+- **`asc_workflow_review_responses`** — list unanswered reviews.
+- **`asc_workflow_metadata_sync`** — pull metadata to a JSON object or push from one.
+- **`asc_workflow_analytics_oneshot`** — create analytics request + poll until ready.
+
+### Declarative workflow runner
+
+`asc_workflow_run` executes JSON manifests with templated values:
+
+```json
+{
+  "name": "Cut next App Store version",
+  "vars": { "appId": "1234", "newVersion": "1.2.3" },
+  "steps": [
+    {
+      "name": "create",
+      "tool": "asc_workflow_release_next_version",
+      "input": { "appId": "${vars.appId}", "platform": "IOS", "newVersionString": "${vars.newVersion}" }
+    },
+    {
+      "name": "audit",
+      "tool": "asc_workflow_submission_health",
+      "input": { "versionId": "${steps.create.newVersionId}" }
+    }
+  ]
+}
+```
+
+Run it via `asc_workflow_run({ workflowPath: "/abs/path/to/release.workflow.json" })`. Use `dryRun: true` to validate + propagate dry-run to every step. Examples in `examples/`.
+
+---
+
+## Safety
+
+- Every write tool supports `dryRun: true` → returns `{ method, path, body }` without sending.
+- App Store char limits enforced before request (name 30, subtitle 30, keywords 100, promo 170, description 4000, what's-new 4000).
+- The runner propagates `dryRun` to every step automatically when set.
+- Stdio server logs only to stderr — never stdout (preserves JSON-RPC framing).
+
+---
+
+## Development
+
+```bash
+npm install
+npm run typecheck       # tsc --noEmit
+npm run build           # compiles to ./build/
+npm run dev             # tsx src/index.ts (for iterating)
+npm test                # runs scripts/test-all.ts against real ASC — requires .env
+```
+
+The test runner exercises every registered tool (reads as-is, writes with `dryRun: true`) and reports a pass/fail/skip matrix.
+
+### Project layout
+
+```
+src/
+├── index.ts          # stdio bootstrap
+├── auth.ts           # ES256 JWT generation + caching
+├── client.ts         # HTTP client, JSON:API error normalization
+├── lib/
+│   ├── jsonapi.ts    # JSON:API flatten helpers
+│   ├── jsonapi-write.ts  # PATCH/POST body builders + dryRun gate
+│   ├── pagination.ts # cursor walker
+│   ├── projections.ts # default sparse fields per resource
+│   ├── locales.ts    # locale codes + char limits
+│   └── upload.ts     # 3-step asset reservation flow
+└── tools/
+    ├── registry.ts   # aggregates all tools
+    ├── ping.ts apps.ts versions.ts builds.ts testflight.ts reviews.ts
+    ├── iap.ts pricing.ts reports.ts users.ts provisioning.ts privacy.ts
+    ├── screenshots.ts workflows.ts runner.ts
+    └── types.ts
+```
+
+---
+
+## Known limitations
+
+- **App Privacy nutrition labels** are not exposed by Apple's public API. Edit them in the ASC web UI.
+- **Power & Performance metrics** endpoint was removed from the public API.
+- **Feedback submissions** (screenshots/crashes) can only be accessed by id (no listing endpoint).
+- **Analytics reports** are async — `analytics_create_request` returns immediately; the reports are generated over the following minutes/hours. Use `asc_workflow_analytics_oneshot` to poll.
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/build/auth.d.ts

@@ -0,0 +1,8 @@
+export interface AscCredentials {
+    keyId: string;
+    issuerId: string;
+    privateKey: string;
+    vendorNumber?: string;
+}
+export declare function loadCredentialsFromEnv(): AscCredentials;
+export declare function generateToken(creds: AscCredentials): string;

package/build/auth.js

@@ -0,0 +1,44 @@
+import jwt from "jsonwebtoken";
+import { readFileSync } from "node:fs";
+export function loadCredentialsFromEnv() {
+    const keyId = process.env.APP_STORE_CONNECT_KEY_ID;
+    const issuerId = process.env.APP_STORE_CONNECT_ISSUER_ID;
+    const keyPath = process.env.APP_STORE_CONNECT_P8_PATH;
+    const inlineKey = process.env.APP_STORE_CONNECT_P8;
+    const vendorNumber = process.env.APP_STORE_CONNECT_VENDOR_NUMBER;
+    if (!keyId)
+        throw new Error("APP_STORE_CONNECT_KEY_ID is required");
+    if (!issuerId)
+        throw new Error("APP_STORE_CONNECT_ISSUER_ID is required");
+    let privateKey;
+    if (inlineKey) {
+        privateKey = inlineKey.replace(/\\n/g, "\n");
+    }
+    else if (keyPath) {
+        privateKey = readFileSync(keyPath, "utf8");
+    }
+    else {
+        throw new Error("APP_STORE_CONNECT_P8_PATH or APP_STORE_CONNECT_P8 is required");
+    }
+    return { keyId, issuerId, privateKey, vendorNumber };
+}
+let cachedToken = null;
+export function generateToken(creds) {
+    const now = Math.floor(Date.now() / 1000);
+    if (cachedToken && cachedToken.expiresAt > now + 60) {
+        return cachedToken.token;
+    }
+    const expiresIn = 20 * 60;
+    const token = jwt.sign({
+        iss: creds.issuerId,
+        iat: now,
+        exp: now + expiresIn,
+        aud: "appstoreconnect-v1",
+    }, creds.privateKey, {
+        algorithm: "ES256",
+        header: { alg: "ES256", kid: creds.keyId, typ: "JWT" },
+    });
+    cachedToken = { token, expiresAt: now + expiresIn };
+    return token;
+}
+//# sourceMappingURL=auth.js.map

package/build/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,cAAc,CAAC;AAC/B,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AASvC,MAAM,UAAU,sBAAsB;IACpC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC;IACnD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC;IACzD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC;IACtD,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;IACnD,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,+BAA+B,CAAC;IAEjE,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IACpE,IAAI,CAAC,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IAE1E,IAAI,UAAkB,CAAC;IACvB,IAAI,SAAS,EAAE,CAAC;QACd,UAAU,GAAG,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC/C,CAAC;SAAM,IAAI,OAAO,EAAE,CAAC;QACnB,UAAU,GAAG,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC7C,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,KAAK,CACb,+DAA+D,CAChE,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;AACvD,CAAC;AAED,IAAI,WAAW,GAAgD,IAAI,CAAC;AAEpE,MAAM,UAAU,aAAa,CAAC,KAAqB;IACjD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IAC1C,IAAI,WAAW,IAAI,WAAW,CAAC,SAAS,GAAG,GAAG,GAAG,EAAE,EAAE,CAAC;QACpD,OAAO,WAAW,CAAC,KAAK,CAAC;IAC3B,CAAC;IAED,MAAM,SAAS,GAAG,EAAE,GAAG,EAAE,CAAC;IAC1B,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CACpB;QACE,GAAG,EAAE,KAAK,CAAC,QAAQ;QACnB,GAAG,EAAE,GAAG;QACR,GAAG,EAAE,GAAG,GAAG,SAAS;QACpB,GAAG,EAAE,oBAAoB;KAC1B,EACD,KAAK,CAAC,UAAU,EAChB;QACE,SAAS,EAAE,OAAO;QAClB,MAAM,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE;KACvD,CACF,CAAC;IAEF,WAAW,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,GAAG,SAAS,EAAE,CAAC;IACpD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/build/client.d.ts

@@ -0,0 +1,21 @@
+import { type AscCredentials } from "./auth.js";
+export type QueryValue = string | number | boolean | string[] | undefined;
+export interface RequestOptions {
+    method?: string;
+    query?: Record<string, QueryValue>;
+    body?: unknown;
+    rawBody?: BodyInit;
+    headers?: Record<string, string>;
+    expectBinary?: boolean;
+}
+export interface AscError extends Error {
+    status?: number;
+    details?: unknown;
+}
+export declare class AscClient {
+    private creds;
+    constructor(creds: AscCredentials);
+    get vendorNumber(): string | undefined;
+    buildUrl(path: string, query?: Record<string, QueryValue>): URL;
+    request<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+}

package/build/client.js

@@ -0,0 +1,91 @@
+import { generateToken } from "./auth.js";
+const BASE_URL = "https://api.appstoreconnect.apple.com/v1";
+export class AscClient {
+    creds;
+    constructor(creds) {
+        this.creds = creds;
+    }
+    get vendorNumber() {
+        return this.creds.vendorNumber;
+    }
+    buildUrl(path, query) {
+        const url = new URL(path.startsWith("http") ? path : `${BASE_URL}${path}`);
+        if (!query)
+            return url;
+        for (const [k, v] of Object.entries(query)) {
+            if (v === undefined || v === null)
+                continue;
+            if (Array.isArray(v)) {
+                if (v.length === 0)
+                    continue;
+                url.searchParams.set(k, v.join(","));
+            }
+            else {
+                url.searchParams.set(k, String(v));
+            }
+        }
+        return url;
+    }
+    async request(path, options = {}) {
+        const url = this.buildUrl(path, options.query);
+        const token = generateToken(this.creds);
+        const headers = {
+            Authorization: `Bearer ${token}`,
+            ...(options.headers ?? {}),
+        };
+        if (options.body !== undefined && !options.rawBody) {
+            headers["Content-Type"] = headers["Content-Type"] ?? "application/json";
+        }
+        const res = await fetch(url, {
+            method: options.method ?? "GET",
+            headers,
+            body: options.rawBody ?? (options.body ? JSON.stringify(options.body) : undefined),
+        });
+        if (options.expectBinary) {
+            if (!res.ok) {
+                const text = await res.text().catch(() => "");
+                throw makeError(res.status, res.statusText, text);
+            }
+            return (await res.arrayBuffer());
+        }
+        const text = await res.text();
+        if (!res.ok) {
+            throw makeError(res.status, res.statusText, text);
+        }
+        if (!text)
+            return undefined;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+}
+function makeError(status, statusText, body) {
+    let detail = body;
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+        if (typeof parsed === "object" &&
+            parsed !== null &&
+            "errors" in parsed &&
+            Array.isArray(parsed.errors)) {
+            const errs = parsed.errors;
+            detail = errs
+                .map((e) => {
+                const where = e.source?.pointer ?? e.source?.parameter ?? "";
+                return [e.code, e.title, e.detail, where].filter(Boolean).join(" — ");
+            })
+                .join("; ");
+        }
+    }
+    catch {
+        // not JSON, keep raw
+    }
+    const err = new Error(`App Store Connect API ${status} ${statusText}: ${detail}`);
+    err.status = status;
+    err.details = parsed ?? body;
+    return err;
+}
+//# sourceMappingURL=client.js.map

package/build/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAuB,MAAM,WAAW,CAAC;AAE/D,MAAM,QAAQ,GAAG,0CAA0C,CAAC;AAkB5D,MAAM,OAAO,SAAS;IACA;IAApB,YAAoB,KAAqB;QAArB,UAAK,GAAL,KAAK,CAAgB;IAAG,CAAC;IAE7C,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC;IACjC,CAAC;IAED,QAAQ,CAAC,IAAY,EAAE,KAAkC;QACvD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,QAAQ,GAAG,IAAI,EAAE,CAAC,CAAC;QAC3E,IAAI,CAAC,KAAK;YAAE,OAAO,GAAG,CAAC;QACvB,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3C,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI;gBAAE,SAAS;YAC5C,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;gBACrB,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;oBAAE,SAAS;gBAC7B,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YACvC,CAAC;iBAAM,CAAC;gBACN,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;YACrC,CAAC;QACH,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,KAAK,CAAC,OAAO,CACX,IAAY,EACZ,UAA0B,EAAE;QAE5B,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QAC/C,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAExC,MAAM,OAAO,GAA2B;YACtC,aAAa,EAAE,UAAU,KAAK,EAAE;YAChC,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;SAC3B,CAAC;QACF,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YACnD,OAAO,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,IAAI,kBAAkB,CAAC;QAC1E,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAC3B,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,KAAK;YAC/B,OAAO;YACP,IAAI,EAAE,OAAO,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;SACnF,CAAC,CAAC;QAEH,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;YACzB,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;gBAC9C,MAAM,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;YACpD,CAAC;YACD,OAAO,CAAC,MAAM,GAAG,CAAC,WAAW,EAAE,CAAM,CAAC;QACxC,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9B,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QACpD,CAAC;QACD,IAAI,CAAC,IAAI;YAAE,OAAO,SAAc,CAAC;QACjC,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAS,CAAC;QACnB,CAAC;IACH,CAAC;CACF;AAED,SAAS,SAAS,CAAC,MAAc,EAAE,UAAkB,EAAE,IAAY;IACjE,IAAI,MAAM,GAAG,IAAI,CAAC;IAClB,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1B,IACE,OAAO,MAAM,KAAK,QAAQ;YAC1B,MAAM,KAAK,IAAI;YACf,QAAQ,IAAI,MAAM;YAClB,KAAK,CAAC,OAAO,CAAE,MAAgC,CAAC,MAAM,CAAC,EACvD,CAAC;YACD,MAAM,IAAI,GAAI,MAAmI,CAAC,MAAM,CAAC;YACzJ,MAAM,GAAG,IAAI;iBACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;gBACT,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,EAAE,OAAO,IAAI,CAAC,CAAC,MAAM,EAAE,SAAS,IAAI,EAAE,CAAC;gBAC7D,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACxE,CAAC,CAAC;iBACD,IAAI,CAAC,IAAI,CAAC,CAAC;QAChB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,qBAAqB;IACvB,CAAC;IACD,MAAM,GAAG,GAAa,IAAI,KAAK,CAC7B,yBAAyB,MAAM,IAAI,UAAU,KAAK,MAAM,EAAE,CAC3D,CAAC;IACF,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC;IACpB,GAAG,CAAC,OAAO,GAAG,MAAM,IAAI,IAAI,CAAC;IAC7B,OAAO,GAAG,CAAC;AACb,CAAC"}

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/index.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// IMPORTANT: stdio MCP servers must never write to stdout. console.log corrupts
+// the JSON-RPC frame. Always use console.error (which writes to stderr).
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { AscClient } from "./client.js";
+import { loadCredentialsFromEnv } from "./auth.js";
+import { allTools } from "./tools/registry.js";
+async function main() {
+    const creds = loadCredentialsFromEnv();
+    const client = new AscClient(creds);
+    const tools = allTools(client);
+    const toolMap = new Map(tools.map((t) => [t.name, t]));
+    const server = new Server({ name: "appstore-connect-mcp", version: "0.1.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: zodToJsonSchema(t.inputSchema, { target: "openApi3" }),
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const tool = toolMap.get(req.params.name);
+        if (!tool)
+            throw new Error(`Unknown tool: ${req.params.name}`);
+        const parsed = tool.inputSchema.parse(req.params.arguments ?? {});
+        const result = await tool.handler(parsed);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: typeof result === "string" ? result : JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`appstore-connect-mcp ready (${tools.length} tools)`);
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/build/lib/jsonapi-write.d.ts

@@ -0,0 +1,32 @@
+import type { AscClient } from "../client.js";
+export interface JsonApiBody {
+    data: {
+        type: string;
+        id?: string;
+        attributes?: Record<string, unknown>;
+        relationships?: Record<string, {
+            data: {
+                type: string;
+                id: string;
+            } | Array<{
+                type: string;
+                id: string;
+            }> | null;
+        }>;
+    };
+}
+export declare function patchBody(type: string, id: string, attributes?: Record<string, unknown>, relationships?: JsonApiBody["data"]["relationships"]): JsonApiBody;
+export declare function postBody(type: string, attributes?: Record<string, unknown>, relationships?: JsonApiBody["data"]["relationships"]): JsonApiBody;
+export declare function singleRel(type: string, id: string): {
+    readonly data: {
+        readonly type: string;
+        readonly id: string;
+    };
+};
+export interface DryRunResult {
+    dryRun: true;
+    method: string;
+    path: string;
+    body?: unknown;
+}
+export declare function maybeSend<T>(client: AscClient, dryRun: boolean | undefined, method: "POST" | "PATCH" | "DELETE", path: string, body?: unknown): Promise<T | DryRunResult>;

package/build/lib/jsonapi-write.js

@@ -0,0 +1,18 @@
+export function patchBody(type, id, attributes, relationships) {
+    return { data: { type, id, attributes, relationships } };
+}
+export function postBody(type, attributes, relationships) {
+    return { data: { type, attributes, relationships } };
+}
+export function singleRel(type, id) {
+    return { data: { type, id } };
+}
+export async function maybeSend(client, dryRun, method, path, body) {
+    if (dryRun)
+        return { dryRun: true, method, path, body };
+    return client.request(path, {
+        method,
+        body,
+    });
+}
+//# sourceMappingURL=jsonapi-write.js.map

package/build/lib/jsonapi-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonapi-write.js","sourceRoot":"","sources":["../../src/lib/jsonapi-write.ts"],"names":[],"mappings":"AAcA,MAAM,UAAU,SAAS,CACvB,IAAY,EACZ,EAAU,EACV,UAAoC,EACpC,aAAoD;IAEpD,OAAO,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,UAAU,EAAE,aAAa,EAAE,EAAE,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,QAAQ,CACtB,IAAY,EACZ,UAAoC,EACpC,aAAoD;IAEpD,OAAO,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,aAAa,EAAE,EAAE,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,EAAU;IAChD,OAAO,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,EAAW,CAAC;AACzC,CAAC;AASD,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,MAAiB,EACjB,MAA2B,EAC3B,MAAmC,EACnC,IAAY,EACZ,IAAc;IAEd,IAAI,MAAM;QAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACxD,OAAO,MAAM,CAAC,OAAO,CAAI,IAAI,EAAE;QAC7B,MAAM;QACN,IAAI;KACL,CAAC,CAAC;AACL,CAAC"}

package/build/lib/jsonapi.d.ts

@@ -0,0 +1,27 @@
+export interface JsonApiResource {
+    type: string;
+    id: string;
+    attributes?: Record<string, unknown>;
+    relationships?: Record<string, {
+        data?: {
+            type: string;
+            id: string;
+        } | Array<{
+            type: string;
+            id: string;
+        }>;
+    }>;
+}
+export interface JsonApiResponse<T = JsonApiResource> {
+    data: T | T[];
+    included?: JsonApiResource[];
+    links?: {
+        next?: string;
+        self?: string;
+    };
+    meta?: Record<string, unknown>;
+}
+/** Flatten a single JSON:API resource into `{ id, type, ...attributes, _rel: {...} }`. */
+export declare function flatten(resource: JsonApiResource): Record<string, unknown>;
+/** Flatten a list response. */
+export declare function flattenList(resp: JsonApiResponse<JsonApiResource>): Record<string, unknown>[];

package/build/lib/jsonapi.js

@@ -0,0 +1,27 @@
+/** Flatten a single JSON:API resource into `{ id, type, ...attributes, _rel: {...} }`. */
+export function flatten(resource) {
+    const out = {
+        id: resource.id,
+        type: resource.type,
+        ...(resource.attributes ?? {}),
+    };
+    if (resource.relationships) {
+        const rels = {};
+        for (const [name, rel] of Object.entries(resource.relationships)) {
+            if (!rel.data)
+                continue;
+            rels[name] = Array.isArray(rel.data)
+                ? rel.data.map((d) => d.id)
+                : rel.data.id;
+        }
+        if (Object.keys(rels).length > 0)
+            out._rel = rels;
+    }
+    return out;
+}
+/** Flatten a list response. */
+export function flattenList(resp) {
+    const data = Array.isArray(resp.data) ? resp.data : [resp.data];
+    return data.map(flatten);
+}
+//# sourceMappingURL=jsonapi.js.map

package/build/lib/jsonapi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonapi.js","sourceRoot":"","sources":["../../src/lib/jsonapi.ts"],"names":[],"mappings":"AAiBA,0FAA0F;AAC1F,MAAM,UAAU,OAAO,CAAC,QAAyB;IAC/C,MAAM,GAAG,GAA4B;QACnC,EAAE,EAAE,QAAQ,CAAC,EAAE;QACf,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,GAAG,CAAC,QAAQ,CAAC,UAAU,IAAI,EAAE,CAAC;KAC/B,CAAC;IACF,IAAI,QAAQ,CAAC,aAAa,EAAE,CAAC;QAC3B,MAAM,IAAI,GAA4B,EAAE,CAAC;QACzC,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;YACjE,IAAI,CAAC,GAAG,CAAC,IAAI;gBAAE,SAAS;YACxB,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;gBAClC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC3B,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QAClB,CAAC;QACD,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC;YAAE,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;IACpD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,+BAA+B;AAC/B,MAAM,UAAU,WAAW,CACzB,IAAsC;IAEtC,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChE,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AAC3B,CAAC"}

package/build/lib/locales.d.ts

@@ -0,0 +1,24 @@
+/**
+ * App Store locale codes. Apple uses a fixed list — this is the canonical set
+ * the API accepts for App Store Version Localizations as of 2026.
+ * Source: https://developer.apple.com/documentation/appstoreconnectapi/applocalecodes
+ */
+export declare const APP_STORE_LOCALES: readonly ["ar-SA", "ca", "cs", "da", "de-DE", "el", "en-AU", "en-CA", "en-GB", "en-US", "es-ES", "es-MX", "fi", "fr-CA", "fr-FR", "he", "hi", "hr", "hu", "id", "it", "ja", "ko", "ms", "nl-NL", "no", "pl", "pt-BR", "pt-PT", "ro", "ru", "sk", "sv", "th", "tr", "uk", "vi", "zh-Hans", "zh-Hant"];
+export type AppStoreLocale = (typeof APP_STORE_LOCALES)[number];
+/**
+ * Character limits enforced by App Store Connect on metadata fields,
+ * keyed by the JSON:API attribute name.
+ */
+export declare const METADATA_CHAR_LIMITS: {
+    readonly name: 30;
+    readonly subtitle: 30;
+    readonly keywords: 100;
+    readonly promotionalText: 170;
+    readonly description: 4000;
+    readonly whatsNew: 4000;
+    readonly privacyPolicyText: 4000;
+    readonly marketingUrl: 255;
+    readonly supportUrl: 255;
+    readonly privacyPolicyUrl: 255;
+};
+export declare function isValidLocale(code: string): code is AppStoreLocale;