appstore-api-mcp 1.7.2 → 1.8.1

package/CHANGELOG.md

@@ -4,6 +4,24 @@ 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.8.1] - 2026-06-02
+
+### Changed
+- Docs clarify that **build & ship** (`archive_app` / `upload_build` /
+  `bump_build_number`) is an optional, **Mac + Xcode** add-on — everything else
+  works from any OS. Added "build & ship" examples (archive, upload a new build)
+  to the README "What you can ask" section and refreshed the other groups.
+
+## [1.8.0] - 2026-06-02
+
+### Added
+- **Build & ship from a Mac** (local Xcode tooling):
+  - `bump_build_number` — increment/set the build number via agvtool.
+  - `archive_app` — archive + export a signed `.ipa` via xcodebuild.
+  - `upload_build` — upload to App Store Connect via `xcrun altool`, reusing the
+    same API key; auto-places the `.p8` where altool expects it.
+  - Each tool returns friendly install guidance if Xcode/CLI tools are missing.
+
 ## [1.7.2] - 2026-06-02
 
 ### Changed

package/README.md

@@ -62,7 +62,9 @@ whatever AI agent you already use.
 ## Quick start
 
 **Requirements:** Node.js ≥ 18 and an Apple Developer account with an
-[App Store Connect API key](#getting-your-api-key).
+[App Store Connect API key](#getting-your-api-key). Everything works from any
+OS — *except* the optional **build & ship** tools (`archive_app` / `upload_build`),
+which additionally need a **Mac with Xcode**.
 
 ### 🤖 Easiest: let your AI agent set it up (works with any agent)
 
@@ -253,6 +255,7 @@ Full parameter reference: **[docs/TOOLS.md](docs/TOOLS.md)**.
 | `list_game_center_leaderboards` / `list_game_center_achievements` | 🎮 Game Center leaderboards & achievements |
 | `signing_health` | 🔐 Flag **certificates & profiles expiring soon** (or invalid) across the account — catches CI breakage early |
 | `list_bundle_ids` / `register_bundle_id` / `list_devices` / `register_device` / `list_certificates` / `create_certificate` / `revoke_certificate` / `list_profiles` / `create_profile` / `download_profile` / `delete_profile` | 🔏 **Provisioning & code signing** — bundle IDs, devices, certificates, and provisioning profiles |
+| `bump_build_number` / `archive_app` / `upload_build` | 🛠️ **Build & ship from a Mac** — bump the build number (agvtool), archive + export a signed `.ipa` (xcodebuild), and upload to App Store Connect (`altool`, using your existing API key). Requires Xcode; tools explain how to install it if missing |
 | `raw_request` | 🧰 Any method/path against the API — app previews, matchmaking, Xcode Cloud, anything not above |
 
 > ⚙️ **Rate-limit aware:** the client automatically backs off and retries on
@@ -272,24 +275,41 @@ Once it's connected, just talk to your agent in plain language. A few things to
 - *"Which of my apps are missing a subtitle or screenshots?"* (fleet audit)
 - *"Tighten the keywords for <app> — dry-run it first so I can confirm."*
 - *"Show me <app>'s current screenshots and flag any that look outdated."*
-- *"Translate <app>'s description and keywords into German and French."*
+- *"Translate <app>'s description and keywords into German and French."* (bulk localization)
 
-**Performance**
+**Performance & feedback**
 - *"How many downloads did all my apps get last week?"*
 - *"Pull last month's proceeds broken down by country."*
 - *"How many active subscribers do I have, and what's the recent churn?"*
-
-**Releases & the rest of the API** (via `raw_request`)
-- *"Create a new App Store version (1.4.0) for <app>."*
 - *"Summarize this week's 1-star reviews and draft polite replies."*
+
+**Release management**
+- *"Which of my apps are waiting for review, rejected, or ready to release?"* (fleet review board)
+- *"Create a new App Store version 1.4.0 for <app>, then submit it for review."*
+- *"Release <app> — it's approved and waiting for manual release."*
 - *"List my latest TestFlight builds and which beta groups can see them."*
-- *"What's <app>'s price and which territories is it available in?"*
+
+**Pipeline & accounts**
+- *"Are any of my certificates or provisioning profiles expiring soon?"* (signing health)
+- *"What's <app>'s price, and which territories is it available in?"*
+
+**🛠️ Build & ship — *additional, Mac-only* (see note below)**
+- *"Bump SpeakerMate's build number, archive it, and upload the new build to App Store Connect."*
+- *"Create an archive of <app> and export a signed .ipa."*
+- *"Upload this .ipa to App Store Connect."*
 
 > **Dedicated tools cover it all:** app management, localization, screenshots
 > (incl. *seeing* them), sales/subscriptions/analytics, ASO audit, dry-run,
-> **customer reviews, TestFlight, in-app purchases, pricing, availability, and
-> age-rating**. Anything else in the App Store Connect API is still reachable
-> through the **`raw_request`** escape hatch — just ask.
+> customer reviews, TestFlight, in-app purchases, pricing, availability, age-rating,
+> submit/release, and signing health. Anything else in the App Store Connect API
+> is still reachable through the **`raw_request`** escape hatch — just ask.
+>
+> 🛠️ **Build & ship is different — it's an optional, local add-on.** Almost every
+> tool here talks to Apple's API and works from **any machine**. The three build
+> tools (`bump_build_number`, `archive_app`, `upload_build`) instead run **local
+> Xcode commands**, so they only work on a **Mac with Xcode installed** and an
+> Xcode project on disk. If those aren't present the tools tell you exactly what
+> to install; everything else keeps working regardless.
 
 ## Common workflows
 

package/docs/TOOLS.md

@@ -389,6 +389,30 @@ 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.
 
+## Build & ship (macOS + Xcode)
+
+These run local Xcode tooling, so they only work on a Mac with Xcode installed.
+Each returns clear install guidance if a tool is missing.
+
+### bump_build_number
+- `projectDir` **(required)** — folder containing the `.xcodeproj`
+- `setTo` — exact build number (omit to increment by 1). Uses `agvtool`.
+
+### archive_app
+Archive + export a signed `.ipa` for App Store upload (`xcodebuild`). **Can take
+several minutes** — your MCP client may need a longer tool timeout.
+- `project` **or** `workspace` **(one required)** — absolute path
+- `scheme` **(required)**, `configuration` (default Release)
+- `exportMethod` (default `app-store-connect`), `teamId`, `outputDir`
+- **Returns:** `{ ipaPath, archivePath, exportPath }`
+
+### upload_build
+Upload an `.ipa` via `xcrun altool --upload-app`, using your App Store Connect
+API key (`ASC_KEY_ID` / `ASC_ISSUER_ID`). The `.p8` is auto-placed where altool
+looks (`~/.appstoreconnect/private_keys/`). After processing, the build appears
+in `list_builds` and can be submitted with `submit_for_review`.
+- `ipaPath` **(required)**, `platform` (default `ios`), `apiKey`, `apiIssuer`
+
 ---
 
 ## Rate limits

package/package.json

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

package/src/index.js

@@ -1,6 +1,15 @@
 #!/usr/bin/env node
-import { readFileSync } from "node:fs";
-import { basename } from "node:path";
+import {
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  existsSync,
+  copyFileSync,
+  readdirSync,
+} from "node:fs";
+import { basename, join } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import { execFile } from "node:child_process";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
@@ -131,6 +140,61 @@ const EDITABLE_VERSION_STATES = new Set([
 // Optional default Vendor Number for sales/finance reports.
 const DEFAULT_VENDOR = process.env.ASC_VENDOR_NUMBER;
 
+// ---- Local build tooling (archive & upload) helpers ----
+
+/** Run a command, capturing output. timeout 0 = no timeout (for long archives). */
+function runCmd(cmd, args, opts = {}) {
+  return new Promise((resolve) => {
+    execFile(
+      cmd,
+      args,
+      {
+        cwd: opts.cwd,
+        timeout: opts.timeout || 0,
+        maxBuffer: 64 * 1024 * 1024,
+        env: process.env,
+      },
+      (err, stdout, stderr) => {
+        resolve({
+          code: err && typeof err.code === "number" ? err.code : err ? 1 : 0,
+          stdout: stdout || "",
+          stderr: stderr || "",
+          error: err ? err.message : null,
+        });
+      },
+    );
+  });
+}
+
+const tail = (s, n = 40) => (s || "").split("\n").slice(-n).join("\n");
+
+/** Throw a friendly install-guidance error if Xcode CLI tools aren't available. */
+async function ensureXcode() {
+  if (process.platform !== "darwin")
+    throw new Error(
+      "Archiving/uploading requires macOS with Xcode. These build tools only run on a Mac.",
+    );
+  const sel = await runCmd("xcode-select", ["-p"]);
+  if (sel.code !== 0)
+    throw new Error(
+      "Xcode command-line tools not found. To fix: 1) install Xcode from the Mac App Store, 2) run `xcode-select --install` (or, if Xcode is already installed, `sudo xcode-select -s /Applications/Xcode.app/Contents/Developer`), then verify with `xcodebuild -version`.",
+    );
+  return sel.stdout.trim();
+}
+
+/** Make sure altool can find the .p8: copy it to ~/.appstoreconnect/private_keys/. */
+function ensureAltoolKey(keyId) {
+  const src = process.env.ASC_PRIVATE_KEY_PATH;
+  if (!src || !existsSync(src)) return false;
+  const dir = join(homedir(), ".appstoreconnect", "private_keys");
+  const dest = join(dir, `AuthKey_${keyId}.p8`);
+  if (!existsSync(dest)) {
+    mkdirSync(dir, { recursive: true });
+    copyFileSync(src, dest);
+  }
+  return true;
+}
+
 /** Cap parsed report rows so large reports don't flood the response. */
 function reportResult(reportType, parsed, limit = 200) {
   const rows = parsed.rows;
@@ -2001,6 +2065,145 @@ const tools = [
     },
   },
 
+  // ---- Local build: archive & upload (macOS + Xcode) ----
+  {
+    name: "bump_build_number",
+    description:
+      "Increment (or set) an Xcode project's build number (CFBundleVersion / CURRENT_PROJECT_VERSION) via agvtool. macOS + Xcode required. Pass projectDir = the folder containing the .xcodeproj.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectDir: { type: "string", description: "Folder containing the .xcodeproj" },
+        setTo: { type: "string", description: "Set to this exact build number; omit to increment by 1" },
+      },
+      required: ["projectDir"],
+    },
+    run: async (a) => {
+      await ensureXcode();
+      const cur = await runCmd("xcrun", ["agvtool", "what-version", "-terse"], { cwd: a.projectDir });
+      const previous = (cur.stdout || "").trim();
+      const res = a.setTo
+        ? await runCmd("xcrun", ["agvtool", "new-version", "-all", a.setTo], { cwd: a.projectDir })
+        : await runCmd("xcrun", ["agvtool", "next-version", "-all"], { cwd: a.projectDir });
+      if (res.code !== 0)
+        return {
+          error:
+            "agvtool failed — ensure the project's Versioning System is 'Apple Generic' (target → Build Settings → Versioning), or set the build number in Xcode manually.",
+          detail: tail(res.stderr || res.stdout, 8),
+          previous,
+        };
+      const after = await runCmd("xcrun", ["agvtool", "what-version", "-terse"], { cwd: a.projectDir });
+      return { previous, current: (after.stdout || "").trim() };
+    },
+  },
+  {
+    name: "archive_app",
+    description:
+      "Archive an Xcode app and export a signed .ipa ready for App Store upload (xcodebuild archive + -exportArchive). macOS + Xcode required. Returns the .ipa path. CAN TAKE SEVERAL MINUTES — your MCP client may need a longer tool timeout; xcodebuild keeps running server-side regardless.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project: { type: "string", description: "Absolute path to the .xcodeproj" },
+        workspace: { type: "string", description: "Absolute path to the .xcworkspace (use instead of project)" },
+        scheme: { type: "string" },
+        configuration: { type: "string", description: "Release (default)" },
+        exportMethod: { type: "string", description: "app-store-connect (default), release-testing, enterprise, …" },
+        teamId: { type: "string", description: "Signing team id (optional)" },
+        outputDir: { type: "string", description: "Where to write the archive + ipa (default: a temp dir)" },
+      },
+      required: ["scheme"],
+    },
+    run: async (a) => {
+      await ensureXcode();
+      if (!a.project && !a.workspace)
+        return { error: "Provide either project (.xcodeproj) or workspace (.xcworkspace)." };
+      const safe = a.scheme.replace(/\W+/g, "_");
+      const out = a.outputDir || join(tmpdir(), `asc-archive-${safe}`);
+      mkdirSync(out, { recursive: true });
+      const archivePath = join(out, `${safe}.xcarchive`);
+      const exportPath = join(out, "export");
+      const target = a.workspace
+        ? ["-workspace", a.workspace]
+        : ["-project", a.project];
+      const archiveArgs = [
+        ...target,
+        "-scheme", a.scheme,
+        "-configuration", a.configuration || "Release",
+        "-destination", "generic/platform=iOS",
+        "-archivePath", archivePath,
+        "archive",
+        "-allowProvisioningUpdates",
+      ];
+      const arch = await runCmd("xcodebuild", archiveArgs);
+      if (arch.code !== 0)
+        return { step: "archive", error: "xcodebuild archive failed", log: tail(arch.stdout + "\n" + arch.stderr, 50) };
+      const plistPath = join(out, "ExportOptions.plist");
+      const method = a.exportMethod || "app-store-connect";
+      writeFileSync(
+        plistPath,
+        `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>method</key><string>${method}</string>
+<key>signingStyle</key><string>automatic</string>
+${a.teamId ? `<key>teamID</key><string>${a.teamId}</string>\n` : ""}<key>uploadSymbols</key><true/>
+</dict></plist>
+`,
+      );
+      const exp = await runCmd("xcodebuild", [
+        "-exportArchive",
+        "-archivePath", archivePath,
+        "-exportOptionsPlist", plistPath,
+        "-exportPath", exportPath,
+        "-allowProvisioningUpdates",
+      ]);
+      if (exp.code !== 0)
+        return { step: "export", error: "xcodebuild -exportArchive failed", log: tail(exp.stdout + "\n" + exp.stderr, 50) };
+      const ipa = existsSync(exportPath)
+        ? readdirSync(exportPath).find((f) => f.endsWith(".ipa"))
+        : null;
+      if (!ipa)
+        return { error: "No .ipa was produced.", exportPath, files: existsSync(exportPath) ? readdirSync(exportPath) : [] };
+      return { ipaPath: join(exportPath, ipa), archivePath, exportPath };
+    },
+  },
+  {
+    name: "upload_build",
+    description:
+      "Upload an .ipa to App Store Connect via `xcrun altool --upload-app`, using your App Store Connect API key (the same ASC_KEY_ID / ASC_ISSUER_ID this server already uses). macOS + Xcode required. After it finishes processing (minutes), the build appears in list_builds and can be submitted with submit_for_review.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ipaPath: { type: "string" },
+        platform: { type: "string", description: "ios (default), macos, tvos" },
+        apiKey: { type: "string", description: "Override ASC_KEY_ID" },
+        apiIssuer: { type: "string", description: "Override ASC_ISSUER_ID" },
+      },
+      required: ["ipaPath"],
+    },
+    run: async (a) => {
+      await ensureXcode();
+      if (!existsSync(a.ipaPath))
+        return { error: `File not found: ${a.ipaPath}` };
+      const keyId = a.apiKey || process.env.ASC_KEY_ID;
+      const issuer = a.apiIssuer || process.env.ASC_ISSUER_ID;
+      if (!keyId || !issuer)
+        return { error: "apiKey + apiIssuer required (or set ASC_KEY_ID / ASC_ISSUER_ID)." };
+      ensureAltoolKey(keyId);
+      const res = await runCmd("xcrun", [
+        "altool",
+        "--upload-app",
+        "-t", a.platform || "ios",
+        "-f", a.ipaPath,
+        "--apiKey", keyId,
+        "--apiIssuer", issuer,
+      ]);
+      if (res.code !== 0)
+        return { error: "Upload failed", log: tail(res.stdout + "\n" + res.stderr, 40) };
+      return { uploaded: true, output: tail(res.stdout + "\n" + res.stderr, 20) };
+    },
+  },
+
   // ---- Generic escape hatch ----
   {
     name: "raw_request",
@@ -2044,7 +2247,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.7.2" },
+  { name: "appstore-api-mcp", version: "1.8.1" },
   { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS },
 );