v1.12.0: app preview videos + auto-snapshot safety net

Add app preview (video) tools (list/get/create-set/upload/delete) and
preview backup/restore (includePreviews + restore_app_previews). Add
APPSTORE_MCP_AUTO_SNAPSHOT so the server snapshots text metadata before the first
listing edit — making 'revert' reliable even without a manual snapshot. 80 tools.

Author: fil-technology

.env.example

@@ -33,3 +33,5 @@ ASC_PRIVATE_KEY_PATH=/absolute/path/to/AuthKey_XXXXXXXXXX.p8
 # 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=
+# Optional: auto-snapshot an app's text metadata before the first listing edit (a safety net for "revert")
+# APPSTORE_MCP_AUTO_SNAPSHOT=true

CHANGELOG.md

@@ -4,6 +4,18 @@ 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.12.0] - 2026-06-03
+
+### Added
+- **App preview videos:** `list_app_preview_sets`, `list_app_previews`,
+  `get_app_preview` (incl. `videoUrl`), `create_app_preview_set`,
+  `upload_app_preview`, `delete_app_preview`. Snapshots can back up previews
+  (`includePreviews:true`) and **`restore_app_previews`** re-uploads them.
+- **Auto-snapshot safety net:** `APPSTORE_MCP_AUTO_SNAPSHOT=true` makes the server
+  save a text-metadata snapshot of an app before the **first** listing edit of the
+  session — so "revert" works even if you forgot to snapshot. Plus a server-side
+  habit nudge to snapshot before bulk/risky edits, and a revert recipe.
+
 ## [1.11.0] - 2026-06-03
 
 ### Added

README.md

@@ -261,11 +261,12 @@ 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) |
 | `get_screenshot` | 👁️ Fetch a live screenshot **as an image the agent can see** — review/compare what's on a listing |
+| `list_app_preview_sets` / `list_app_previews` / `get_app_preview` / `create_app_preview_set` / `upload_app_preview` / `delete_app_preview` | 🎬 **App preview videos** — list, inspect (incl. `videoUrl`), upload, delete |
 | `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` / `restore_screenshots` | 💾 Back up / compare / restore an app's metadata. Text is always saved; pass `includeScreenshots:true` to also download the images so **deleted screenshots can be re-uploaded** |
+| `snapshot_app_metadata` / `diff_app_metadata_snapshot` / `restore_app_metadata` / `restore_screenshots` / `restore_app_previews` | 💾 Back up / compare / restore an app's metadata. Text always saved; `includeScreenshots:true` and `includePreviews:true` also download the images/videos so **deleted screenshots and previews can be re-uploaded**. Set `APPSTORE_MCP_AUTO_SNAPSHOT=true` to auto-snapshot text before the first edit |
 | `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 |

docs/RECIPES.md

@@ -134,7 +134,22 @@ Uses: `get_app_store_version_localization`, `list_app_info_localizations`,
 `update_app_store_version_localization` (with `dryRun`),
 `bulk_update_version_localizations`, `aso_opportunity_report`.
 
-## 7. Build & ship (Mac only)
+## 7. Safety net — snapshot before risky edits, then revert if needed
+
+```text
+Before we change anything on AppName, take a full snapshot (include screenshots
+and previews). Then make the edits I describe. If I say "revert", restore the
+metadata, screenshots, and previews from that snapshot.
+```
+
+Uses: `snapshot_app_metadata` (with `includeScreenshots:true` / `includePreviews:true`),
+then `restore_app_metadata` + `restore_screenshots` + `restore_app_previews`.
+
+> Or set `APPSTORE_MCP_AUTO_SNAPSHOT=true` so the server auto-snapshots text
+> metadata before the first edit — then "revert" works even if you forgot to
+> snapshot. (Screenshots/previews still need the explicit include flags.)
+
+## 8. Build & ship (Mac only)
 
 ```text
 Bump AppName's build number, archive it, and upload the new build to App Store

docs/TOOLS.md

@@ -419,6 +419,29 @@ Re-upload screenshots from a snapshot that was taken with `includeScreenshots:tr
 - `replace` — delete the set's current screenshots first (true restore)
 - `dryRun` — preview what would be uploaded
 
+### restore_app_previews
+Re-upload app preview **videos** from a snapshot taken with `includePreviews:true`.
+- `appId` **(required)**, `snapshotFile` **(required)**, `replace`, `dryRun`
+
+> **Auto-snapshot:** set `APPSTORE_MCP_AUTO_SNAPSHOT=true` and the server saves a
+> text-metadata snapshot of an app before the **first** listing edit of the session
+> — a built-in safety net so you can always revert. (Screenshots/previews still
+> need `includeScreenshots` / `includePreviews` to be restorable.)
+
+## App previews (video)
+
+### list_app_preview_sets / list_app_previews / get_app_preview
+- sets: `localizationId`; previews: `previewSetId`; one preview: `previewId` (includes `videoUrl` when available).
+
+### create_app_preview_set
+- `localizationId` **(required)**, `previewType` **(required)** (e.g. IPHONE_67).
+
+### upload_app_preview
+- `previewSetId` **(required)**, `filePath` **(required)** (.mp4/.mov), `fileName`, `previewFrameTimeCode` (e.g. `00:00:05:00`).
+
+### delete_app_preview
+- `previewId` **(required)**.
+
 ## Safe mode (guardrails)
 
 Set these env vars to enforce limits at the **server** (blocked calls return a

package.json

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

src/guardrails.js

@@ -14,6 +14,11 @@ export const WRITE_TOOLS = new Set([
   "create_screenshot_set",
   "upload_screenshot",
   "delete_screenshot",
+  // app previews (video)
+  "create_app_preview_set",
+  "upload_app_preview",
+  "delete_app_preview",
+  "restore_app_previews",
   // reviews
   "reply_to_customer_review",
   // testflight