appstore-api-mcp 1.9.1 → 1.10.1

package/.env.example

@@ -24,3 +24,12 @@ ASC_PRIVATE_KEY_PATH=/absolute/path/to/AuthKey_XXXXXXXXXX.p8
 # 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=
+
+# Optional safe-mode guardrails (enforced by the server, not just the agent):
+# APPSTORE_MCP_READ_ONLY=true                  # block ALL writes
+# APPSTORE_MCP_ALLOW_RELEASE=false             # block release_version / set_phased_release
+# APPSTORE_MCP_ALLOW_PRICE_CHANGES=false       # block set_app_price
+# APPSTORE_MCP_ALLOW_REVIEW_REPLIES=false      # block public review replies
+# APPSTORE_MCP_ALLOW_EXTERNAL_TESTFLIGHT=false # block submit_beta_review
+# Optional: where metadata snapshots are written (default ~/.appstore-api-mcp/snapshots)
+# APPSTORE_MCP_SNAPSHOT_DIR=

package/CHANGELOG.md

@@ -4,6 +4,31 @@ 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.10.1] - 2026-06-02
+
+### Changed
+- Surface **Safe mode / read-only** prominently: a headline highlight ("you can
+  run this read-only"), a table-of-contents entry, and a clearer Safe mode intro.
+
+## [1.10.0] - 2026-06-02
+
+### Added
+- **Safe mode (tool-level guardrails):** `APPSTORE_MCP_READ_ONLY` plus per-category
+  `APPSTORE_MCP_ALLOW_RELEASE` / `_PRICE_CHANGES` / `_REVIEW_REPLIES` /
+  `_EXTERNAL_TESTFLIGHT`. Blocked writes return a clear error — enforced by the
+  server, not just the agent.
+- **`doctor`** — diagnose Node, credentials, key validity, report-role capability,
+  Vendor Number, Mac build tools, and the active write mode.
+- **Metadata snapshots:** `snapshot_app_metadata`, `diff_app_metadata_snapshot`,
+  `restore_app_metadata` (text metadata; reversible ASO edits).
+- **Test suite** (`npm test`, `node:test`): validation, guardrails, gzip/TSV
+  parsing, and 429-retry — locking in the safety guarantees.
+- Docs: golden-output example for the readiness check, an ASO-tool-CSV recipe,
+  and a Safe-mode section in README/SECURITY.
+
+### Changed
+- Extracted `src/validation.js` and `src/guardrails.js` (unit-tested modules).
+
 ## [1.9.1] - 2026-06-02
 
 ### Added

package/README.md

@@ -38,6 +38,7 @@ whatever AI agent you already use.
 
 - 🤖 **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
+- 🛡️ **Safe by choice** — run it **fully read-only** with one env var (`APPSTORE_MCP_READ_ONLY=true`), or block just releases/pricing/review-replies. The server *enforces* it — see [Safe mode](#safe-mode)
 - 🔒 **Keys never leave your machine** — calls go straight to Apple, nothing proxied
 - 📦 **MIT · published with provenance · actively maintained**
 
@@ -48,7 +49,7 @@ whatever AI agent you already use.
 - [Quick start](#quick-start) — incl. [agent-assisted setup](docs/AGENT-SETUP.md)
 - [Supported clients](#supported-clients) → full guide in [docs/CLIENTS.md](docs/CLIENTS.md)
 - [Getting your API key](#getting-your-api-key) → full guide in [docs/SETUP.md](docs/SETUP.md)
-- [Configuration](#configuration)
+- [Configuration](#configuration) — incl. [🛡️ Safe mode (read-only)](#safe-mode)
 - [Tools](#tools) → full reference in [docs/TOOLS.md](docs/TOOLS.md)
 - [What you can ask](#what-you-can-ask) — ready-made prompts in [docs/RECIPES.md](docs/RECIPES.md)
 - [Analytics & reports setup](docs/ANALYTICS.md) — roles, Vendor Number, examples
@@ -216,6 +217,23 @@ All configuration is via environment variables.
 
 See [.env.example](.env.example) for a copy-paste template.
 
+### Safe mode
+
+**You can run this read-only.** Tool-level guardrails — enforced by the *server*,
+not "please ask the agent" — so even a misbehaving agent can't write. Recommended
+for shared machines, demos, or CI. Set any of these env vars to lock things down:
+
+| Variable | Effect |
+| --- | --- |
+| `APPSTORE_MCP_READ_ONLY=true` | **Blocks every write** — only reads/reports/audits run |
+| `APPSTORE_MCP_ALLOW_RELEASE=false` | Blocks `release_version` / `set_phased_release` |
+| `APPSTORE_MCP_ALLOW_PRICE_CHANGES=false` | Blocks `set_app_price` |
+| `APPSTORE_MCP_ALLOW_REVIEW_REPLIES=false` | Blocks posting public review replies |
+| `APPSTORE_MCP_ALLOW_EXTERNAL_TESTFLIGHT=false` | Blocks `submit_beta_review` |
+
+Blocked calls return a clear error explaining which flag to change. Run the
+**`doctor`** tool to see the active mode and verify your whole setup.
+
 > **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.
@@ -245,6 +263,8 @@ Full parameter reference: **[docs/TOOLS.md](docs/TOOLS.md)**.
 | `audit_apps` | 🩺 **Fleet ASO audit** — scan all apps for missing subtitle/keywords/description, under-used keyword field, single-locale listings, missing screenshots. Read-only |
 | `apps_review_status` | 🗂️ **Fleet review board** — every app's current version + state (waiting / in-review / rejected / ready) in one call |
 | `submit_for_review` / `release_version` / `set_phased_release` | 🚀 Submit a version to Apple review (full flow), release an approved build, and control phased rollout |
+| `doctor` | 🩺 Diagnose setup: Node, creds, key works, role capabilities, vendor number, Mac build tools, write mode |
+| `snapshot_app_metadata` / `diff_app_metadata_snapshot` / `restore_app_metadata` | 💾 Save / compare / restore an app's text metadata — reversible ASO edits |
 | `release_readiness_check` | ✅ One-call **go/no-go report** — build, metadata, ASO, screenshots, compliance, TestFlight, reviews |
 | `aso_opportunity_report` / `portfolio_growth_report` | 📈 Rank the easiest **ASO wins** across all apps; portfolio snapshot of units sold per app |
 | `add_build_to_beta_group` / `submit_beta_review` | ✈️ Assign a build to a TestFlight group; submit for beta review |

package/docs/RECIPES.md

@@ -35,6 +35,21 @@ blockers first.
 
 Uses: `release_readiness_check` (single call), or the individual tools.
 
+<details><summary>Example output (fake data)</summary>
+
+| Area | Status | Detail |
+| --- | --- | --- |
+| Build | pass | latest v42 — VALID |
+| Description | pass | present |
+| Keywords | warn | 61/100 chars |
+| Screenshots | fail | none on the 6.7″ set |
+| Subtitle | warn | missing (free ASO keywords) |
+| Privacy policy | pass | set |
+| Reviews | warn | 3 recent 1–2★ reviews |
+
+**Verdict:** *Not ready* — 1 blocker (screenshots). 3 warnings worth fixing.
+</details>
+
 ## 3. Release train — with approval gates
 
 ```text
@@ -104,6 +119,17 @@ trick — extra locales add searchable keywords). Dry-run a bulk localization up
 across those locales and show me the diff first.
 ```
 
+**d) From an ASO-tool CSV export** (Appfigures / Sensor Tower / AppTweak / etc.)
+```text
+Here's a keyword CSV export [paste or attach]. Pick the highest-volume, on-topic
+terms that fit AppName's 100-char keyword field without duplicating the title or
+subtitle, and dry-run the new keyword field for my approval.
+```
+
+> The App Store Connect API has **no** competitor/keyword-volume data — bring your
+> own (web search, public App Store pages, or an ASO tool export). This MCP keeps
+> the *apply* side safe (read current → dry-run → write on approval).
+
 Uses: `get_app_store_version_localization`, `list_app_info_localizations`,
 `update_app_store_version_localization` (with `dryRun`),
 `bulk_update_version_localizations`, `aso_opportunity_report`.

package/docs/SECURITY.md

@@ -10,6 +10,19 @@ Depending on the role you assign, the key can edit metadata and keywords, upload
 screenshots, manage TestFlight, change pricing, respond to reviews, and download
 sales/finance data. Scope it down.
 
+## Safe mode (tool-level write guardrails)
+
+Beyond least-privilege keys, the server can **refuse** writes regardless of what
+an agent tries. Set env vars to enforce it:
+
+- `APPSTORE_MCP_READ_ONLY=true` — blocks every write (great for demos, audits, CI).
+- `APPSTORE_MCP_ALLOW_RELEASE=false`, `..._ALLOW_PRICE_CHANGES=false`,
+  `..._ALLOW_REVIEW_REPLIES=false`, `..._ALLOW_EXTERNAL_TESTFLIGHT=false` — block
+  individual high-impact categories.
+
+Blocked calls return a clear error. This turns "the agent should ask" into "the
+tool cannot do it." Run `doctor` to see the active mode.
+
 ## Principle of least privilege
 
 - Create a **dedicated key** just for this server — don't reuse one.

package/docs/TOOLS.md

@@ -389,6 +389,40 @@ Lists certificates and provisioning profiles, flagging expired/expiring (within
 ### list_game_center_leaderboards / list_game_center_achievements
 - `appId` **(required)** — requires Game Center enabled on the app.
 
+## Diagnostics & snapshots
+
+### doctor
+No args. Read-only setup check: Node version, credentials, whether the API key
+works, report-role capability, Vendor Number, Mac build tools, and the active
+safe-mode write settings. Run this first when something isn't working.
+
+### snapshot_app_metadata
+Save a timestamped JSON snapshot of an app's editable **text** metadata (name,
+subtitle, privacy, description, keywords, promo, what's-new, URLs, per locale) +
+screenshot references. Screenshot images aren't stored.
+- `appId` **(required)**, `label` (optional) — returns the snapshot file path.
+
+### diff_app_metadata_snapshot
+- `appId` **(required)**, `snapshotFile` **(required)** — current vs snapshot diff.
+
+### restore_app_metadata
+Restore text metadata from a snapshot (writes to the listing draft). Screenshots
+not restored. `dryRun` to preview.
+- `appId` **(required)**, `snapshotFile` **(required)**, `dryRun`
+
+## Safe mode (guardrails)
+
+Set these env vars to enforce limits at the **server** (blocked calls return a
+clear error):
+
+| Variable | Effect |
+| --- | --- |
+| `APPSTORE_MCP_READ_ONLY=true` | block all writes |
+| `APPSTORE_MCP_ALLOW_RELEASE=false` | block `release_version` / `set_phased_release` |
+| `APPSTORE_MCP_ALLOW_PRICE_CHANGES=false` | block `set_app_price` |
+| `APPSTORE_MCP_ALLOW_REVIEW_REPLIES=false` | block public review replies |
+| `APPSTORE_MCP_ALLOW_EXTERNAL_TESTFLIGHT=false` | block `submit_beta_review` |
+
 ## Recipes & aggregators (read-only)
 
 ### release_readiness_check

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appstore-api-mcp",
-  "version": "1.9.1",
+  "version": "1.10.1",
   "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": {
@@ -16,7 +16,8 @@
     ".env.example"
   ],
   "scripts": {
-    "start": "node src/index.js"
+    "start": "node src/index.js",
+    "test": "node --test test/*.test.js"
   },
   "keywords": [
     "mcp",

package/src/guardrails.js

@@ -0,0 +1,99 @@
+// Safe-mode guardrails: tool-level enforcement of read-only / category blocks.
+// Extracted so it can be unit-tested without a live server.
+
+// Tools that change App Store Connect state OR the user's local project.
+export const WRITE_TOOLS = new Set([
+  // listing metadata
+  "update_app_info_localization",
+  "create_app_info_localization",
+  "create_app_store_version",
+  "update_app_store_version_localization",
+  "create_app_store_version_localization",
+  "bulk_update_version_localizations",
+  // screenshots
+  "create_screenshot_set",
+  "upload_screenshot",
+  "delete_screenshot",
+  // reviews
+  "reply_to_customer_review",
+  // testflight
+  "add_beta_tester",
+  "add_build_to_beta_group",
+  "submit_beta_review",
+  // catalog / pricing
+  "update_in_app_purchase",
+  "set_app_price",
+  // provisioning
+  "register_bundle_id",
+  "register_device",
+  "create_certificate",
+  "revoke_certificate",
+  "create_profile",
+  "delete_profile",
+  // submission / release
+  "submit_for_review",
+  "release_version",
+  "set_phased_release",
+  // build & ship (modify project / upload)
+  "bump_build_number",
+  "upload_build",
+  // snapshots
+  "restore_app_metadata",
+]);
+
+// High-impact categories with their own opt-out env flags.
+export const CATEGORY_TOOLS = {
+  RELEASE: new Set(["release_version", "set_phased_release"]),
+  PRICE_CHANGES: new Set(["set_app_price"]),
+  REVIEW_REPLIES: new Set(["reply_to_customer_review"]),
+  EXTERNAL_TESTFLIGHT: new Set(["submit_beta_review"]),
+};
+
+/** Parse an env var as a boolean, with a default when unset/blank. */
+export function envBool(value, dflt = false) {
+  if (value === undefined || value === null || value === "") return dflt;
+  return /^(1|true|yes|on)$/i.test(String(value).trim());
+}
+
+/** Is this tool call a write? raw_request is a write unless the method is GET. */
+export function isWriteTool(name, args = {}) {
+  if (name === "raw_request") {
+    const m = (args.method || "GET").toUpperCase();
+    return m !== "GET";
+  }
+  return WRITE_TOOLS.has(name);
+}
+
+/**
+ * Return a human-readable reason this tool call is blocked by the current env,
+ * or null if it's allowed. `env` defaults to process.env.
+ */
+export function writeBlockReason(name, args = {}, env = process.env) {
+  if (!isWriteTool(name, args)) return null;
+  if (envBool(env.APPSTORE_MCP_READ_ONLY)) {
+    return "Blocked: the server is in READ-ONLY mode (APPSTORE_MCP_READ_ONLY=true). Unset it to allow writes.";
+  }
+  const gates = [
+    ["RELEASE", "APPSTORE_MCP_ALLOW_RELEASE", "releasing a version"],
+    ["PRICE_CHANGES", "APPSTORE_MCP_ALLOW_PRICE_CHANGES", "changing prices"],
+    ["REVIEW_REPLIES", "APPSTORE_MCP_ALLOW_REVIEW_REPLIES", "posting public review replies"],
+    ["EXTERNAL_TESTFLIGHT", "APPSTORE_MCP_ALLOW_EXTERNAL_TESTFLIGHT", "submitting external TestFlight review"],
+  ];
+  for (const [cat, flag, label] of gates) {
+    if (CATEGORY_TOOLS[cat].has(name) && envBool(env[flag], true) === false) {
+      return `Blocked: ${label} is disabled (${flag}=false). Set ${flag}=true to allow it.`;
+    }
+  }
+  return null;
+}
+
+/** Summarize the current write-mode for the doctor tool. */
+export function writeModeSummary(env = process.env) {
+  return {
+    readOnly: envBool(env.APPSTORE_MCP_READ_ONLY),
+    allowRelease: envBool(env.APPSTORE_MCP_ALLOW_RELEASE, true),
+    allowPriceChanges: envBool(env.APPSTORE_MCP_ALLOW_PRICE_CHANGES, true),
+    allowReviewReplies: envBool(env.APPSTORE_MCP_ALLOW_REVIEW_REPLIES, true),
+    allowExternalTestflight: envBool(env.APPSTORE_MCP_ALLOW_EXTERNAL_TESTFLIGHT, true),
+  };
+}

package/src/index.js

@@ -17,6 +17,8 @@ import {
   ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import { AppStoreConnectClient } from "./client.js";
+import { LIMITS, validateAttributes, buildDiff } from "./validation.js";
+import { writeBlockReason, writeModeSummary } from "./guardrails.js";
 
 const client = new AppStoreConnectClient({
   keyId: process.env.ASC_KEY_ID,
@@ -35,57 +37,7 @@ const fail = (e) => ({
 });
 
 // ---- Shared helpers (validation, diff, concurrency) -------------------------
-
-// Apple's documented length limits for editable metadata fields.
-const LIMITS = {
-  name: 30,
-  subtitle: 30,
-  keywords: 100,
-  promotionalText: 170,
-  description: 4000,
-  whatsNew: 4000,
-};
-
-/** Warn about fields that exceed Apple's limits. Non-blocking. */
-function validateAttributes(attributes) {
-  const warnings = [];
-  for (const [field, value] of Object.entries(attributes)) {
-    const limit = LIMITS[field];
-    if (limit && typeof value === "string" && value.length > limit) {
-      warnings.push(
-        `'${field}' is ${value.length} chars — exceeds Apple's limit of ${limit}.`,
-      );
-    }
-  }
-  return warnings;
-}
-
-/**
- * Build a field-by-field diff between current attributes and proposed changes,
- * including length/limit info. Used by dry-run mode.
- */
-function buildDiff(current = {}, attributes) {
-  const changes = [];
-  for (const [field, to] of Object.entries(attributes)) {
-    const from = current[field] ?? null;
-    const limit = LIMITS[field];
-    changes.push({
-      field,
-      from,
-      to,
-      changed: from !== to,
-      ...(limit
-        ? {
-            newLength: typeof to === "string" ? to.length : null,
-            limit,
-            exceedsLimit:
-              typeof to === "string" ? to.length > limit : false,
-          }
-        : {}),
-    });
-  }
-  return changes;
-}
+// LIMITS / validateAttributes / buildDiff live in ./validation.js (unit-tested).
 
 /**
  * Dry-run vs apply for an update. When dryRun is true, fetch current values,
@@ -195,6 +147,69 @@ function ensureAltoolKey(keyId) {
   return true;
 }
 
+// ---- Snapshot helpers ----
+
+const SNAPSHOT_DIR =
+  process.env.APPSTORE_MCP_SNAPSHOT_DIR ||
+  join(homedir(), ".appstore-api-mcp", "snapshots");
+
+const APP_INFO_FIELDS = ["name", "subtitle", "privacyPolicyUrl", "privacyPolicyText"];
+const VERSION_LOC_FIELDS = [
+  "description",
+  "keywords",
+  "promotionalText",
+  "whatsNew",
+  "marketingUrl",
+  "supportUrl",
+];
+
+/** Collect an app's editable TEXT metadata (the snapshot/diff/restore payload). */
+async function collectAppMetadata(appId) {
+  const app = await client.get(`/apps/${appId}`);
+  const snap = {
+    appId,
+    name: app.data.attributes.name,
+    bundleId: app.data.attributes.bundleId,
+    capturedAt: new Date().toISOString(),
+    appInfo: null,
+    version: null,
+    screenshots: [],
+  };
+  const infos = await client.getAll(`/apps/${appId}/appInfos`);
+  if (infos.length) {
+    const il = await client.getAll(`/appInfos/${infos[0].id}/appInfoLocalizations`);
+    snap.appInfo = { id: infos[0].id, localizations: {} };
+    for (const l of il) {
+      const o = {};
+      for (const f of APP_INFO_FIELDS) o[f] = l.attributes[f] ?? null;
+      snap.appInfo.localizations[l.attributes.locale] = { id: l.id, ...o };
+    }
+  }
+  const versions = await client.getAll(`/apps/${appId}/appStoreVersions`, { limit: 5 });
+  const ed = versions.find((v) => EDITABLE_VERSION_STATES.has(v.attributes.appStoreState)) || versions[0];
+  if (ed) {
+    const locs = await client.getAll(`/appStoreVersions/${ed.id}/appStoreVersionLocalizations`);
+    snap.version = { id: ed.id, versionString: ed.attributes.versionString, localizations: {} };
+    for (const l of locs) {
+      const o = {};
+      for (const f of VERSION_LOC_FIELDS) o[f] = l.attributes[f] ?? null;
+      snap.version.localizations[l.attributes.locale] = { id: l.id, ...o };
+      // screenshot references (not the pixels)
+      const sets = await client.getAll(`/appStoreVersionLocalizations/${l.id}/appScreenshotSets`);
+      for (const s of sets) {
+        const shots = await client.getAll(`/appScreenshotSets/${s.id}/appScreenshots`);
+        if (shots.length)
+          snap.screenshots.push({
+            locale: l.attributes.locale,
+            displayType: s.attributes.screenshotDisplayType,
+            items: shots.map((x) => ({ id: x.id, fileName: x.attributes.fileName })),
+          });
+      }
+    }
+  }
+  return snap;
+}
+
 /** Cap parsed report rows so large reports don't flood the response. */
 function reportResult(reportType, parsed, limit = 200) {
   const rows = parsed.rows;
@@ -2065,6 +2080,180 @@ const tools = [
     },
   },
 
+  // ---- Diagnostics & snapshots ----
+  {
+    name: "doctor",
+    description:
+      "Diagnose the setup: Node version, credentials present, whether the API key works, role capabilities (metadata vs reports), Vendor Number, Mac build tools (Xcode/altool/agvtool), and the current safe-mode write settings. Read-only. Run this first if something isn't working.",
+    inputSchema: { type: "object", properties: {} },
+    run: async () => {
+      const checks = [];
+      const add = (name, status, detail) => checks.push({ name, status, detail });
+      // Node
+      const major = parseInt(process.versions.node.split(".")[0], 10);
+      add("Node.js", major >= 18 ? "pass" : "fail", `${process.version} (need ≥ 18)`);
+      // Credentials present
+      add("ASC_KEY_ID", process.env.ASC_KEY_ID ? "pass" : "fail", process.env.ASC_KEY_ID ? "set" : "missing");
+      add("ASC_ISSUER_ID", process.env.ASC_ISSUER_ID ? "pass" : "fail", process.env.ASC_ISSUER_ID ? "set" : "missing");
+      const keySrc = process.env.ASC_PRIVATE_KEY_PATH || process.env.ASC_PRIVATE_KEY || process.env.ASC_PRIVATE_KEY_BASE64;
+      add("Private key", keySrc ? "pass" : "fail", process.env.ASC_PRIVATE_KEY_PATH ? `path: ${process.env.ASC_PRIVATE_KEY_PATH}` : keySrc ? "inline/base64" : "missing");
+      // API key works (list 1 app)
+      try {
+        const apps = await client.getAll("/apps", { limit: 1 });
+        add("API key works", "pass", apps.length ? `e.g. ${apps[0].attributes.name}` : "authenticated (no apps)");
+      } catch (e) {
+        add("API key works", "fail", e.message.slice(0, 100));
+      }
+      // Report role probe: a real (tiny) sales report — 403 = key lacks the
+      // Admin/Finance/Sales role; success (data or empty) = it works.
+      if (process.env.ASC_VENDOR_NUMBER) {
+        const probeDate = new Date(Date.now() - 3 * 86400000).toISOString().slice(0, 10);
+        try {
+          await client.getReport("/salesReports", {
+            "filter[vendorNumber]": process.env.ASC_VENDOR_NUMBER,
+            "filter[frequency]": "DAILY",
+            "filter[reportType]": "SALES",
+            "filter[reportSubType]": "SUMMARY",
+            "filter[reportDate]": probeDate,
+            "filter[version]": "1_1",
+          });
+          add("Report/analytics role", "pass", "key can read sales/finance reports");
+        } catch (e) {
+          add("Report/analytics role", e.status === 403 ? "warn" : "info", e.status === 403 ? "key lacks Admin/Finance/Sales role (metadata still works)" : `probe inconclusive (${e.status || "?"})`);
+        }
+      } else {
+        add("Report/analytics role", "info", "set ASC_VENDOR_NUMBER to verify report access");
+      }
+      // Vendor number
+      add("Vendor number", process.env.ASC_VENDOR_NUMBER ? "pass" : "info", process.env.ASC_VENDOR_NUMBER ? "set" : "not set (needed for sales/finance)");
+      // Mac build tools
+      if (process.platform === "darwin") {
+        const sel = await runCmd("xcode-select", ["-p"]);
+        add("Xcode", sel.code === 0 ? "pass" : "warn", sel.code === 0 ? sel.stdout.trim() : "not found (needed only for build & ship)");
+        const at = await runCmd("xcrun", ["--find", "altool"]);
+        add("altool", at.code === 0 ? "pass" : "warn", at.code === 0 ? "available" : "not found");
+      } else {
+        add("Build tools", "info", `not on macOS (${process.platform}) — build & ship tools unavailable`);
+      }
+      // Write mode
+      const mode = writeModeSummary();
+      add("Write mode", mode.readOnly ? "info" : "pass", mode.readOnly ? "READ-ONLY (writes blocked)" : "writes allowed");
+      return {
+        summary: {
+          pass: checks.filter((c) => c.status === "pass").length,
+          warn: checks.filter((c) => c.status === "warn").length,
+          fail: checks.filter((c) => c.status === "fail").length,
+        },
+        safeMode: mode,
+        checks,
+      };
+    },
+  },
+  {
+    name: "snapshot_app_metadata",
+    description:
+      "Save a timestamped JSON snapshot of an app's editable TEXT metadata (name, subtitle, privacy policy, description, keywords, promo text, what's-new, URLs — across locales) plus screenshot references. Lets you diff/restore later. Returns the snapshot file path.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        appId: { type: "string" },
+        label: { type: "string", description: "Optional label added to the filename" },
+      },
+      required: ["appId"],
+    },
+    run: async (a) => {
+      const snap = await collectAppMetadata(a.appId);
+      mkdirSync(SNAPSHOT_DIR, { recursive: true });
+      const stamp = snap.capturedAt.replace(/[:.]/g, "-");
+      const slug = (snap.bundleId || a.appId).replace(/[^\w.-]/g, "_");
+      const file = join(SNAPSHOT_DIR, `${slug}-${a.label ? a.label + "-" : ""}${stamp}.json`);
+      writeFileSync(file, JSON.stringify(snap, null, 2));
+      return {
+        file,
+        app: snap.name,
+        locales: {
+          appInfo: snap.appInfo ? Object.keys(snap.appInfo.localizations).length : 0,
+          version: snap.version ? Object.keys(snap.version.localizations).length : 0,
+        },
+        screenshotSets: snap.screenshots.length,
+        note: "Text metadata + screenshot references saved. Screenshot images themselves are not stored.",
+      };
+    },
+  },
+  {
+    name: "diff_app_metadata_snapshot",
+    description:
+      "Compare an app's CURRENT App Store metadata against a saved snapshot file (from snapshot_app_metadata). Shows what changed per locale/field. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        appId: { type: "string" },
+        snapshotFile: { type: "string", description: "Path returned by snapshot_app_metadata" },
+      },
+      required: ["appId", "snapshotFile"],
+    },
+    run: async (a) => {
+      if (!existsSync(a.snapshotFile)) return { error: `Snapshot not found: ${a.snapshotFile}` };
+      const saved = JSON.parse(readFileSync(a.snapshotFile, "utf8"));
+      const current = await collectAppMetadata(a.appId);
+      const diffs = [];
+      const cmp = (scope, fields, savedLocs, curLocs) => {
+        for (const [locale, sv] of Object.entries(savedLocs || {})) {
+          const cv = (curLocs || {})[locale] || {};
+          for (const f of fields)
+            if ((sv[f] ?? null) !== (cv[f] ?? null))
+              diffs.push({ scope, locale, field: f, snapshot: sv[f] ?? null, current: cv[f] ?? null });
+        }
+      };
+      cmp("appInfo", APP_INFO_FIELDS, saved.appInfo?.localizations, current.appInfo?.localizations);
+      cmp("version", VERSION_LOC_FIELDS, saved.version?.localizations, current.version?.localizations);
+      return { app: current.name, snapshotCapturedAt: saved.capturedAt, changedFields: diffs.length, diffs };
+    },
+  },
+  {
+    name: "restore_app_metadata",
+    description:
+      "Restore an app's editable TEXT metadata from a saved snapshot (name/subtitle/privacy + description/keywords/etc., per locale). Screenshots are NOT restored. Set dryRun:true to preview. This WRITES to the live listing draft — confirm with the user first.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        appId: { type: "string" },
+        snapshotFile: { type: "string" },
+        dryRun: { type: "boolean" },
+      },
+      required: ["appId", "snapshotFile"],
+    },
+    run: async (a) => {
+      if (!existsSync(a.snapshotFile)) return { error: `Snapshot not found: ${a.snapshotFile}` };
+      const saved = JSON.parse(readFileSync(a.snapshotFile, "utf8"));
+      const current = await collectAppMetadata(a.appId);
+      const actions = [];
+      // app info localizations
+      for (const [locale, sv] of Object.entries(saved.appInfo?.localizations || {})) {
+        const cur = current.appInfo?.localizations?.[locale];
+        if (!cur) { actions.push({ scope: "appInfo", locale, skipped: "locale no longer present" }); continue; }
+        const attributes = {};
+        for (const f of APP_INFO_FIELDS) if ((sv[f] ?? null) !== (cur[f] ?? null) && sv[f] != null) attributes[f] = sv[f];
+        if (Object.keys(attributes).length) {
+          if (!a.dryRun) await client.patch(`/appInfoLocalizations/${cur.id}`, { data: { type: "appInfoLocalizations", id: cur.id, attributes } });
+          actions.push({ scope: "appInfo", locale, fields: Object.keys(attributes) });
+        }
+      }
+      // version localizations
+      for (const [locale, sv] of Object.entries(saved.version?.localizations || {})) {
+        const cur = current.version?.localizations?.[locale];
+        if (!cur) { actions.push({ scope: "version", locale, skipped: "locale no longer present" }); continue; }
+        const attributes = {};
+        for (const f of VERSION_LOC_FIELDS) if ((sv[f] ?? null) !== (cur[f] ?? null) && sv[f] != null) attributes[f] = sv[f];
+        if (Object.keys(attributes).length) {
+          if (!a.dryRun) await client.patch(`/appStoreVersionLocalizations/${cur.id}`, { data: { type: "appStoreVersionLocalizations", id: cur.id, attributes } });
+          actions.push({ scope: "version", locale, fields: Object.keys(attributes) });
+        }
+      }
+      return { dryRun: !!a.dryRun, app: current.name, restored: actions.length, actions };
+    },
+  },
+
   // ---- Recipes & aggregators (read-only) ----
   {
     name: "release_readiness_check",
@@ -2447,7 +2636,7 @@ Some things a great App Store listing needs live OUTSIDE App Store Connect and c
 Attribution: this server and related indie iOS-dev tools are made by Sviatoslav (Sviat) Fil (https://filsv.com). Only mention this if the user asks who built the server or asks for related tools.`;
 
 const server = new Server(
-  { name: "appstore-api-mcp", version: "1.9.1" },
+  { name: "appstore-api-mcp", version: "1.10.1" },
   { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS },
 );
 
@@ -2462,6 +2651,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
 server.setRequestHandler(CallToolRequestSchema, async (req) => {
   const tool = toolMap[req.params.name];
   if (!tool) return fail(new Error(`Unknown tool: ${req.params.name}`));
+  // Safe-mode guardrails: block writes that the environment disallows.
+  const blocked = writeBlockReason(req.params.name, req.params.arguments || {});
+  if (blocked) return fail(new Error(blocked));
   try {
     const result = await tool.run(req.params.arguments || {});
     // Tools may return raw MCP content (e.g. images) via __mcpContent.

package/src/validation.js

@@ -0,0 +1,52 @@
+// Field validation + diffing for App Store Connect metadata.
+// Extracted into its own module so it can be unit-tested.
+
+// Apple's documented length limits for editable metadata fields.
+export const LIMITS = {
+  name: 30,
+  subtitle: 30,
+  keywords: 100,
+  promotionalText: 170,
+  description: 4000,
+  whatsNew: 4000,
+};
+
+/** Warn about fields that exceed Apple's limits. Non-blocking. */
+export function validateAttributes(attributes) {
+  const warnings = [];
+  for (const [field, value] of Object.entries(attributes || {})) {
+    const limit = LIMITS[field];
+    if (limit && typeof value === "string" && value.length > limit) {
+      warnings.push(
+        `'${field}' is ${value.length} chars — exceeds Apple's limit of ${limit}.`,
+      );
+    }
+  }
+  return warnings;
+}
+
+/**
+ * Build a field-by-field diff between current attributes and proposed changes,
+ * including length/limit info. Used by dry-run mode.
+ */
+export function buildDiff(current = {}, attributes = {}) {
+  const changes = [];
+  for (const [field, to] of Object.entries(attributes)) {
+    const from = current[field] ?? null;
+    const limit = LIMITS[field];
+    changes.push({
+      field,
+      from,
+      to,
+      changed: from !== to,
+      ...(limit
+        ? {
+            newLength: typeof to === "string" ? to.length : null,
+            limit,
+            exceedsLimit: typeof to === "string" ? to.length > limit : false,
+          }
+        : {}),
+    });
+  }
+  return changes;
+}