appstore-api-mcp 1.1.2 → 1.2.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ 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.2.0] - 2026-06-02
+
+### Added
+- **`get_screenshot`** — fetch a live screenshot as an actual **image the agent
+  can see** (not just metadata). Downloads the App Store Connect image asset,
+  downscaled by default (`maxWidth`), and returns an `image/png` content block.
+  Lets an agent review/compare what's currently on a listing.
+
+## [1.1.3] - 2026-06-02
+
+### Changed
+- Lead with analytics in the package/repo description, README one-liner, and
+  keywords — downloads, revenue, and subscriptions are now front and center.
+
 ## [1.1.2] - 2026-06-02
 
 ### Fixed

package/README.md

@@ -14,8 +14,9 @@
 **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.
+into plain-language actions — edit your listings, **track downloads, revenue &
+subscriptions**, audit your whole portfolio, and reach the entire API, from
+whatever AI agent you already use.
 
 ### ✨ What makes it stand out
 
@@ -241,6 +242,7 @@ Full parameter reference: **[docs/TOOLS.md](docs/TOOLS.md)**.
 | `create_app_store_version_localization` | Add a new locale to a version |
 | `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 currently on a listing |
 | 🚀 `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. |
 | 📊 `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. |

package/docs/TOOLS.md

@@ -117,6 +117,13 @@ Common `displayType` values: `APP_IPHONE_67`, `APP_IPHONE_65`, `APP_IPHONE_61`,
 ### `list_screenshots`
 - `screenshotSetId` **(required)**
 
+### `get_screenshot`
+Fetch the actual screenshot **image** (not just metadata) and return it as an
+image the agent can see — review/compare what's currently live.
+- `screenshotId` **(required)**
+- `maxWidth` — downscale width in px for a lighter preview (default `750`; `0` = full size)
+- **Returns:** an `image/png` content block + a caption with the file name and original dimensions.
+
 ### `upload_screenshot`
 Upload an image into a set. Handles reserve → upload bytes → commit (with checksum).
 - `screenshotSetId` **(required)**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "appstore-api-mcp",
-  "version": "1.1.2",
-  "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.",
+  "version": "1.2.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": {
     "appstore-api-mcp": "src/index.js"
@@ -33,7 +33,11 @@
     "cursor",
     "keywords",
     "screenshots",
-    "metadata"
+    "metadata",
+    "analytics",
+    "app-analytics",
+    "subscriptions",
+    "aso-tools"
   ],
   "license": "MIT",
   "author": "Sviatoslav Fil",

package/src/client.js

@@ -193,6 +193,32 @@ export class AppStoreConnectClient {
       : buf.toString("utf8");
   }
 
+  /** Fetch raw bytes from a URL (e.g. an image asset). Returns a Buffer. */
+  async fetchBinary(url) {
+    const res = await fetch(url);
+    if (!res.ok)
+      throw new Error(`Image fetch failed (${res.status}) for ${url}`);
+    return Buffer.from(await res.arrayBuffer());
+  }
+
+  /**
+   * Build a concrete image URL from an App Store Connect imageAsset
+   * (`{ templateUrl, width, height }`), optionally downscaled to maxWidth.
+   */
+  static imageUrlFromAsset(imageAsset, maxWidth, format = "png") {
+    if (!imageAsset || !imageAsset.templateUrl) return null;
+    let w = imageAsset.width || 0;
+    let h = imageAsset.height || 0;
+    if (maxWidth && w && h && w > maxWidth) {
+      h = Math.round((h * maxWidth) / w);
+      w = maxWidth;
+    }
+    return imageAsset.templateUrl
+      .replace("{w}", String(w))
+      .replace("{h}", String(h))
+      .replace("{f}", format);
+  }
+
   /** 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);

package/src/index.js

@@ -619,6 +619,49 @@ const tools = [
       return committed;
     },
   },
+  {
+    name: "get_screenshot",
+    description:
+      "Fetch the actual screenshot IMAGE by its id and return it so the agent can SEE it (not just metadata). Downloads the live image asset from App Store Connect, downscaled for a quick preview by default. Use this to review/compare what's currently live on a listing.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        screenshotId: { type: "string" },
+        maxWidth: {
+          type: "number",
+          description: "Downscale to this width in px for a lighter preview (default 750; pass 0 for full size)",
+        },
+      },
+      required: ["screenshotId"],
+    },
+    run: async (a) => {
+      const res = await client.get(`/appScreenshots/${a.screenshotId}`);
+      const attr = res.data.attributes || {};
+      const asset = attr.imageAsset;
+      if (!asset || !asset.templateUrl)
+        return {
+          note: "This screenshot has no rendered image yet (still uploading/processing). State: " +
+            (attr.assetDeliveryState && attr.assetDeliveryState.state),
+          fileName: attr.fileName,
+        };
+      const maxWidth = a.maxWidth === undefined ? 750 : a.maxWidth || 0;
+      const url = AppStoreConnectClient.imageUrlFromAsset(asset, maxWidth, "png");
+      const buf = await client.fetchBinary(url);
+      return {
+        __mcpContent: [
+          {
+            type: "image",
+            data: buf.toString("base64"),
+            mimeType: "image/png",
+          },
+          {
+            type: "text",
+            text: `Screenshot ${a.screenshotId} — ${attr.fileName || "(no name)"}, original ${asset.width}×${asset.height}.`,
+          },
+        ],
+      };
+    },
+  },
   {
     name: "delete_screenshot",
     description: "Delete a screenshot by its id.",
@@ -1091,6 +1134,8 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
   if (!tool) return fail(new Error(`Unknown tool: ${req.params.name}`));
   try {
     const result = await tool.run(req.params.arguments || {});
+    // Tools may return raw MCP content (e.g. images) via __mcpContent.
+    if (result && result.__mcpContent) return { content: result.__mcpContent };
     return ok(result);
   } catch (e) {
     if (e && e.status === 403 && REPORT_TOOLS.has(req.params.name))