Skip to content
Back to search

asc-mcp

MCP server for App Store Connect API - 502 tools for apps, builds, TestFlight, subscriptions, Xcode Cloud, and more from Claude, Cursor, VS Code, or any MCP client

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zelentsov-dev--asc-mcp/badge.svg)](/listings/zelentsov-dev--asc-mcp)

HTML

<a href="/listings/zelentsov-dev--asc-mcp"><img src="/api/listings/zelentsov-dev--asc-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The recommended setup stores App Store Connect credentials once in a private local file. MCP clients then need only the path to the `asc-mcp` executable.

1. Install asc-mcp

brew install mint
mint install zelentsov-dev/asc-mcp@v4.1.6
~/.mint/bin/asc-mcp --version

2. Create an App Store Connect API key

1. Open [App Store Connect → Users and Access → Integrations → Team Keys](https://appstoreconnect.apple.com/access/integrations/api). 2. Generate a key with the least-privileged role that covers your workflow. App Manager or Admin is needed only when the corresponding operations require it. 3. Download the `.p8` file. Apple allows it to be downloaded only once. 4. Copy the Key ID and Issuer ID.

3. Save the credentials locally

Create private configuration directories, then move the downloaded `.p8` file into `~/.keys/`. Replace the source path and filename in the second command:

mkdir -p ~/.config/asc-mcp ~/.keys
chmod 700 ~/.config/asc-mcp ~/.keys
mv /path/to/downloaded/AuthKey_XXXXXXXXXX.p8 ~/.keys/

Create `~/.config/asc-mcp/companies.json`:

{
  "companies": [
    {
      "id": "my-company",
      "name": "My Company",
      "key_id": "XXXXXXXXXX",
      "issuer_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "key_path": "/Users/you/.keys/AuthKey_XXXXXXXXXX.p8"
    }
  ]
}

Replace `/Users/you` with your actual home-directory path. Keep both files outside the repository and restrict access:

chmod 600 ~/.config/asc-mcp/companies.json
chmod 600 /Users/you/.keys/AuthKey_XXXXXXXXXX.p8

> [!CAUTION] > Never commit `companies.json`, a `.p8` key, or raw credentials to Git. Revoke the App Store Connect key immediately if it is exposed.

4. Connect your MCP client

Choose one client. You do not need to configure every client.

**Codex**

codex mcp add asc-mcp -- ~/.mint/bin/asc-mcp
codex mcp list

**Claude Code**

claude mcp add \
  --transport stdio \
  --scope user \
  asc-mcp \
  -- ~/.mint/bin/asc-mcp

claude mcp get asc-mcp
claude mcp list

For Claude Desktop, Gemini CLI, VS Code, Continue, Cursor, and Devin Desktop, use the ready-to-copy examples in [MCP Client Setup](#mcp-client-setup).

5. Try it

Restart a GUI client after changing its configuration, open its MCP tool list, and ask:

List my App Store Connect apps.

If the connection or request fails, see [Troubleshooting](#troubleshooting).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,491 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <h1 align="center">App Store Connect MCP Server</h1>
  3. <p align="center">
  4. A local Model Context Protocol server for the App Store Connect API.<br/>
  5. Manage apps, builds, TestFlight, reviews, and more from Codex, Claude, and other MCP clients on macOS.
  6. </p>
  7. </p>
  8. <p align="center">
  9. <a href="https://swift.org"><img src="https://img.shields.io/badge/Swift-6.2+-F05138.svg?style=flat&logo=swift&logoColor=white" alt="Swift 6.2+"></a>
  10. <a href="https://developer.apple.com/macos/"><img src="https://img.shields.io/badge/macOS_15-CI_tested-000000.svg?style=flat&logo=apple&logoColor=white" alt="macOS 15 CI tested"></a>
  11. <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-4A90D9.svg?style=flat" alt="MCP Compatible"></a>
  12. <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat" alt="MIT License"></a>
  13. <a href="https://github.com/zelentsov-dev/asc-mcp/actions"><img src="https://github.com/zelentsov-dev/asc-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  14. </p>
  15. ---
  16. ## Overview
  17. **asc-mcp** is a Swift-based MCP server that connects a local macOS MCP client to the [App Store Connect API](https://developer.apple.com/documentation/appstoreconnectapi). It exposes **537 tools** across 34 App Store tool domains + 2 core domains, enabling you to automate iOS and macOS release workflows through natural language.
  18. Configuration examples are included for Codex, Claude Code, Claude Desktop, Gemini CLI, VS Code with GitHub Copilot, Continue, Cursor, and Devin Desktop (formerly Windsurf). Client configuration is documented; release CI verifies installation, MCP initialization, and tool discovery on macOS rather than launching every third-party client.
  19. New here? Follow the [Quick Start](#quick-start). The remaining sections are reference material for advanced configuration, tool selection, and contributors.
  20. ### Key capabilities
  21. - **Release and metadata** — versions, localizations, builds, review submissions, phased rollout, and Xcode Cloud
  22. - **TestFlight and uploads** — beta groups, testers, feedback, recruitment, build delivery, processing, and export compliance
  23. - **Monetization** — in-app purchases, subscriptions, pricing, availability, offer codes, and promotional offers
  24. - **Marketing** — screenshots, previews, custom product pages, product page optimization, and promoted purchases
  25. - **Accounts and provisioning** — multiple App Store Connect teams, users, bundle IDs, devices, certificates, profiles, and capabilities
  26. - **Feedback and operations** — customer reviews, webhooks, accessibility declarations, analytics, metrics, and diagnostics
  27. - **Safer automation** — read-only mode, confirmation safeguards, strict pagination, and mutation recovery guidance
  28. - **Auditable API coverage** — a versioned Apple OpenAPI contract and release-time drift checks
  29. The source tree prepares **4.3.0**; the installation examples below remain pinned to the last stable release until candidate acceptance and owner publication. See the [migration guide](docs/migrations/4.2.0-asset-library.md) for the separate Asset Library workflow.
  30. ## Platform Support
  31. `asc-mcp` is a local `stdio` server: the MCP client starts it on the same computer. A client being available on Linux or Windows does not make this Swift server cross-platform.
  32. | Environment | Status | Notes |
  33. |---|---|---|
  34. | macOS 15.6+ with Xcode 26.x | **Recommended** | Release CI specifically uses GitHub's macOS 15 runner with Xcode 26.2 |
  35. | macOS 14.0-15.5 | Declared deployment target only | Build and runtime are unverified; a separately installed Swift 6.2+ toolchain may be needed |
  36. | Linux | Not supported yet | Porting work and Linux CI are not complete |
  37. | Windows | Not supported | Current source dependencies and Swift MCP `stdio` transport are not Windows-compatible |
  38. See [Apple's Xcode system requirements](https://developer.apple.com/support/xcode/) for the macOS versions supported by each Xcode release.
  39. Web and cloud sessions do not automatically inherit a local MCP configuration. Run the MCP client locally on a compatible Mac, or use a client feature that explicitly keeps execution on that Mac.
  40. ## Quick Start
  41. The recommended setup stores App Store Connect credentials once in a private local file. MCP clients then need only the path to the `asc-mcp` executable.
  42. ### 1. Install asc-mcp
  43. ```bash
  44. brew install mint
  45. mint install zelentsov-dev/asc-mcp@v4.3.0
  46. ~/.mint/bin/asc-mcp --version
  47. ```
  48. ### 2. Create an App Store Connect API key
  49. 1. Open [App Store Connect → Users and Access → Integrations → Team Keys](https://appstoreconnect.apple.com/access/integrations/api).
  50. 2. Generate a key with the least-privileged role that covers your workflow. App Manager or Admin is needed only when the corresponding operations require it.
  51. 3. Download the `.p8` file. Apple allows it to be downloaded only once.
  52. 4. Copy the Key ID and Issuer ID.
  53. ### 3. Save the credentials locally
  54. Create private configuration directories, then move the downloaded `.p8` file into `~/.keys/`. Replace the source path and filename in the second command:
  55. ```bash
  56. mkdir -p ~/.config/asc-mcp ~/.keys
  57. chmod 700 ~/.config/asc-mcp ~/.keys
  58. mv /path/to/downloaded/AuthKey_XXXXXXXXXX.p8 ~/.keys/
  59. ```
  60. Create `~/.config/asc-mcp/companies.json`:
  61. ```json
  62. {
  63. "companies": [
  64. {
  65. "id": "my-company",
  66. "name": "My Company",
  67. "key_id": "XXXXXXXXXX",
  68. "issuer_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  69. "key_path": "/Users/you/.keys/AuthKey_XXXXXXXXXX.p8"
  70. }
  71. ]
  72. }
  73. ```
  74. Replace `/Users/you` with your actual home-directory path. Keep both files outside the repository and restrict access:
  75. ```bash
  76. chmod 600 ~/.config/asc-mcp/companies.json
  77. chmod 600 /Users/you/.keys/AuthKey_XXXXXXXXXX.p8
  78. ```
  79. > [!CAUTION]
  80. > Never commit `companies.json`, a `.p8` key, or raw credentials to Git. Revoke the App Store Connect key immediately if it is exposed.
  81. ### 4. Connect your MCP client
  82. Choose one client. You do not need to configure every client.
  83. **Codex**
  84. ```bash
  85. codex mcp add asc-mcp -- ~/.mint/bin/asc-mcp
  86. codex mcp list
  87. ```
  88. **Claude Code**
  89. ```bash
  90. claude mcp add \
  91. --transport stdio \
  92. --scope user \
  93. asc-mcp \
  94. -- ~/.mint/bin/asc-mcp
  95. claude mcp get asc-mcp
  96. claude mcp list
  97. ```
  98. For Claude Desktop, Gemini CLI, VS Code, Continue, Cursor, and Devin Desktop, use the ready-to-copy examples in [MCP Client Setup](#mcp-client-setup).
  99. ### 5. Try it
  100. Restart a GUI client after changing its configuration, open its MCP tool list, and ask:
  101. ```text
  102. List my App Store Connect apps.
  103. ```
  104. If the connection or request fails, see [Troubleshooting](#troubleshooting).
  105. ## Installation
  106. ### Mint on macOS (recommended)
  107. [Mint](https://github.com/yonaskolb/Mint) installs the pinned release from source and keeps the executable at `~/.mint/bin/asc-mcp`.
  108. ```bash
  109. brew install mint
  110. mint install zelentsov-dev/asc-mcp@v4.3.0
  111. ```
  112. Update or reinstall the pinned release:
  113. ```bash
  114. mint install zelentsov-dev/asc-mcp@v4.3.0 --force
  115. ```
  116. Stable users should install a version tag. Installing `main` or `develop` is intended only for maintainers and pre-release testing.
  117. ### Build from source
  118. Use Xcode 26.x on a compatible macOS version, or install a standalone Swift 6.2+ toolchain.
  119. ```bash
  120. git clone https://github.com/zelentsov-dev/asc-mcp.git
  121. cd asc-mcp
  122. swift build -c release
  123. ```
  124. The executable is `.build/release/asc-mcp`. If you copy it elsewhere, also copy the adjacent resource bundle:
  125. ```bash
  126. cp .build/release/asc-mcp /usr/local/bin/asc-mcp
  127. cp -R .build/release/asc-mcp_asc-mcp.bundle /usr/local/bin/
  128. ```
  129. The bundle contains the versioned OpenAPI operation contract used by release checks.
  130. ### Upgrading from an older release
  131. <details>
  132. <summary><strong>From v4.0.x</strong></summary>
  133. Version 4.1 keeps every existing tool name, required input, projection key, and array shape. Xcode Cloud read tools now reject undocumented arguments and validate returned links, paging, relationship lineage, and included resources more strictly. New `*Present` projection fields distinguish Apple-omitted arrays from present empty arrays while legacy array fields remain arrays. Newly exposed nested `*_limit` inputs must be paired with their matching `include` value, and continuation calls must repeat the original request scope unchanged. The new product and workflow delete tools default to a safe preview and require the latest preview receipt plus exact inventory confirmation before permanent deletion.
  134. </details>
  135. <details>
  136. <summary><strong>From v3.18.x</strong></summary>
  137. Version 4 keeps every existing tool name and worker filter, but destructive Marketing and review-attachment calls now require an exact confirmation ID before any Apple request:
  138. | Existing tool | New required confirmation |
  139. |---|---|
  140. | `custom_pages_delete` | `confirm_page_id` |
  141. | `ppo_delete_experiment` | `confirm_experiment_id` |
  142. | `promoted_delete` | `confirm_promoted_purchase_id` |
  143. | `review_attachments_delete` | `confirm_attachment_id` |
  144. | `screenshots_delete_set`, `screenshots_delete_preview_set` | `confirm_set_id` |
  145. | `screenshots_delete` | `confirm_screenshot_id` |
  146. | `screenshots_delete_preview` | `confirm_preview_id` |
  147. `ppo_update_experiment` also requires `confirm_experiment_id` when `state` is supplied. Calls that update only name or traffic proportion remain unchanged. After an `unknown` or `committed_unverified` mutation result, use the returned inspection action before retrying.
  148. Remove undocumented top-level arguments from existing Marketing and review-attachment calls. Version 4 rejects unknown keys before any network request instead of silently ignoring them.
  149. </details>
  150. ## Configuration
  151. ### Credentials
  152. The default `~/.config/asc-mcp/companies.json` file shown in the Quick Start is recommended because it works consistently for terminal and GUI clients without duplicating secrets in every client configuration.
  153. For multiple companies, add more entries:
  154. ```json
  155. {
  156. "companies": [
  157. {
  158. "id": "my-company",
  159. "name": "My Company",
  160. "key_id": "XXXXXXXXXX",
  161. "issuer_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  162. "key_path": "/Users/you/.keys/AuthKey_XXXXXXXXXX.p8",
  163. "vendor_number": "YOUR_VENDOR_NUMBER"
  164. },
  165. {
  166. "id": "client-company",
  167. "name": "Client Company",
  168. "key_id": "YYYYYYYYYY",
  169. "issuer_id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
  170. "key_path": "/Users/you/.keys/AuthKey_YYYYYYYYYY.p8"
  171. }
  172. ]
  173. }
  174. ```
  175. `vendor_number` is required only for `analytics_sales_report`, `analytics_financial_report`, and `analytics_app_summary`. Find it in [App Store Connect → Sales and Trends → Reports](https://appstoreconnect.apple.com/trends/reports).
  176. <details>
  177. <summary><strong>Environment-variable alternative</strong></summary>
  178. Environment variables are useful for automation, but GUI apps launched from Finder may not inherit your shell environment. The file-based setup above is simpler for most users.
  179. Single company:
  180. ```bash
  181. export ASC_KEY_ID=XXXXXXXXXX
  182. export ASC_ISSUER_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  183. export ASC_PRIVATE_KEY_PATH=/Users/you/.keys/AuthKey_XXXXXXXXXX.p8
  184. export ASC_COMPANY_NAME="My Company" # optional
  185. export ASC_VENDOR_NUMBER=YOUR_VENDOR_NUMBER # optional, analytics only
  186. ```
  187. Multiple companies:
  188. ```bash
  189. export ASC_COMPANY_1_NAME="My Company"
  190. export ASC_COMPANY_1_KEY_ID=XXXXXXXXXX
  191. export ASC_COMPANY_1_ISSUER_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  192. export ASC_COMPANY_1_KEY_PATH=/Users/you/.keys/AuthKey_XXXXXXXXXX.p8
  193. export ASC_COMPANY_2_NAME="Client Company"
  194. export ASC_COMPANY_2_KEY_ID=YYYYYYYYYY
  195. export ASC_COMPANY_2_ISSUER_ID=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy
  196. export ASC_COMPANY_2_KEY_PATH=/Users/you/.keys/AuthKey_YYYYYYYYYY.p8
  197. ```
  198. Numbering starts at 1. Each consecutive entry must provide both `ASC_COMPANY_{N}_KEY_ID` and `ASC_COMPANY_{N}_ISSUER_ID`; scanning stops at the first missing pair.
  199. </details>
  200. <details>
  201. <summary><strong>Configuration resolution order</strong></summary>
  202. The server resolves credentials in this order:
  203. 1. `--companies /absolute/path/to/companies.json`
  204. 2. Constructor parameter for programmatic embedding
  205. 3. `ASC_MCP_COMPANIES=/absolute/path/to/companies.json`
  206. 4. Default configuration file locations, including `~/.config/asc-mcp/companies.json`
  207. 5. `ASC_COMPANY_1_KEY_ID` and the other numbered multi-company variables
  208. 6. `ASC_KEY_ID`, `ASC_ISSUER_ID`, and a private-key variable for one company
  209. </details>
  210. ## MCP Client Setup
  211. All examples below assume a Mint installation and the recommended `companies.json` credential file. Replace `/Users/you` with your actual home-directory path. GUI clients generally require an absolute executable path.
  212. | Client | Configuration scope | Notes |
  213. |---|---|---|
  214. | Codex | User config by CLI; optional trusted-project config | Shared by local Codex clients on the same Mac |
  215. | Claude Code | `user`, `local`, or `project` scope | `user` is simplest for a personal App Store utility |
  216. | Claude Desktop | User-level desktop config | Restart after editing |
  217. | Gemini CLI | User settings | Local `stdio` server |
  218. | VS Code with GitHub Copilot | User profile or `.vscode/mcp.json` | Confirm server trust on first start |
  219. | Continue | Workspace `.continue/mcpServers/` | Separate from native VS Code MCP configuration |
  220. | Cursor | User or project `mcp.json` | Use an absolute command path |
  221. | Devin Desktop (formerly Windsurf) | User MCP config | Keep no more than 100 active tools |
  222. <details>
  223. <summary><strong>Codex CLI, IDE extension, and desktop client</strong></summary>
  224. Recommended CLI registration:
  225. ```bash
  226. codex mcp add asc-mcp -- ~/.mint/bin/asc-mcp
  227. codex mcp list
  228. codex mcp get asc-mcp --json
  229. ```
  230. The same local MCP configuration is shared by Codex clients on that Mac. The user configuration is `$CODEX_HOME/config.toml`, which defaults to `~/.codex/config.toml`:
  231. ```toml
  232. [mcp_servers.asc-mcp]
  233. command = "/Users/you/.mint/bin/asc-mcp"
  234. startup_timeout_sec = 20
  235. tool_timeout_sec = 60
  236. enabled = true
  237. ```
  238. For a project-specific setup, place the same table in `.codex/config.toml`; Codex loads project configuration only after the project is trusted. If you use shell credentials instead of `companies.json`, explicitly forward them:
  239. ```toml
  240. env_vars = ["ASC_KEY_ID", "ASC_ISSUER_ID", "ASC_PRIVATE_KEY_PATH"]
  241. ```
  242. Restart a GUI client after changing the configuration, then use its MCP view or `/mcp` to confirm that `asc-mcp` is active. See the [official Codex MCP documentation](https://developers.openai.com/codex/mcp/).
  243. </details>
  244. <details>
  245. <summary><strong>Claude Code</strong></summary>
  246. Register once for all local projects:
  247. ```bash
  248. claude mcp add \
  249. --transport stdio \
  250. --scope user \
  251. asc-mcp \
  252. -- ~/.mint/bin/asc-mcp
  253. claude mcp get asc-mcp
  254. claude mcp list
  255. ```
  256. Use `--scope local` for only the current project or `--scope project` to create a shared `.mcp.json`. Project servers require trust approval. Never place raw App Store Connect credentials in a committed `.mcp.json`.
  257. Claude stores `user` and `local` MCP entries in `~/.claude.json`; `.claude/settings.json` is not the global MCP registry. Use `/mcp` inside Claude Code to inspect or reconnect the server. See the [official Claude Code MCP documentation](https://code.claude.com/docs/en/mcp).
  258. </details>
  259. <details>
  260. <summary><strong>Claude Desktop</strong></summary>
  261. Add the server to `~/Library/Application Support/Claude/claude_desktop_config.json`:
  262. ```json
  263. {
  264. "mcpServers": {
  265. "asc-mcp": {
  266. "command": "/Users/you/.mint/bin/asc-mcp"
  267. }
  268. }
  269. }
  270. ```
  271. Quit and reopen Claude Desktop after saving the file.
  272. </details>
  273. <details>
  274. <summary><strong>Gemini CLI</strong></summary>
  275. Add the server to `~/.gemini/settings.json`:
  276. ```json
  277. {
  278. "mcpServers": {
  279. "asc-mcp": {
  280. "command": "/Users/you/.mint/bin/asc-mcp"
  281. }
  282. }
  283. }
  284. ```
  285. The default Gemini MCP timeout is intentionally retained. See the [official Gemini CLI MCP documentation](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html).
  286. </details>
  287. <details>
  288. <summary><strong>VS Code with GitHub Copilot</strong></summary>
  289. Run **MCP: Add Server** from the Command Palette and choose the user profile for a personal setup. For a workspace setup, create `.vscode/mcp.json`:
  290. ```json
  291. {
  292. "servers": {
  293. "asc-mcp": {
  294. "type": "stdio",
  295. "command": "/Users/you/.mint/bin/asc-mcp"
  296. }
  297. }
  298. }
  299. ```
  300. Confirm that you trust the local server when VS Code first starts it. Do not commit user-specific paths or secrets in a shared workspace file. See the [official VS Code MCP documentation](https://code.visualstudio.com/docs/agent-customization/mcp-servers).
  301. </details>
  302. <details>
  303. <summary><strong>Continue</strong></summary>
  304. Continue does not use `.vscode/mcp.json`. Create `.continue/mcpServers/asc-mcp.json` in the workspace:
  305. ```json
  306. {
  307. "mcpServers": {
  308. "asc-mcp": {
  309. "command": "/Users/you/.mint/bin/asc-mcp"
  310. }
  311. }
  312. }
  313. ```
  314. MCP tools are available in Continue agent mode. See the [official Continue MCP documentation](https://docs.continue.dev/customize/deep-dives/mcp).
  315. </details>
  316. <details>
  317. <summary><strong>Cursor</strong></summary>
  318. Use `~/.cursor/mcp.json` for all projects or `.cursor/mcp.json` for one project:
  319. ```json
  320. {
  321. "mcpServers": {
  322. "asc-mcp": {
  323. "command": "/Users/you/.mint/bin/asc-mcp"
  324. }
  325. }
  326. }
  327. ```
  328. Restart or refresh the MCP server from Cursor settings after editing the file. See the [official Cursor MCP documentation](https://cursor.com/docs/mcp).
  329. </details>
  330. <details>
  331. <summary><strong>Devin Desktop (formerly Windsurf)</strong></summary>
  332. Add the server to `~/.codeium/windsurf/mcp_config.json`. This example enables a 72-tool release subset, below Cascade's 100-tool limit:
  333. ```json
  334. {
  335. "mcpServers": {
  336. "asc-mcp": {
  337. "command": "/Users/you/.mint/bin/asc-mcp",
  338. "args": [
  339. "--workers",
  340. "apps,builds,export_compliance,versions,reviews"
  341. ]
  342. }
  343. }
  344. }
  345. ```
  346. You can also disable individual tools in the client. Server-side worker filtering is recommended because it keeps the active catalog predictable. See the [official Devin Desktop MCP documentation](https://docs.devin.ai/desktop/cascade/mcp).
  347. </details>
  348. > [!IMPORTANT]
  349. > `command` must point to the real executable. GUI clients often do not inherit shell aliases, PATH changes, or environment variables. Use an absolute path and prefer the default `companies.json` credential file.
  350. ## Worker Filtering
  351. The server exposes **537 tools** across 34 App Store tool domains + 2 core domains. Some MCP clients impose a tool limit; Cascade in Devin Desktop currently allows 100 active tools. Use the 36 `--workers` filter keys to enable only the workers you need:
  352. ```bash
  353. # Only load apps, builds, and version lifecycle tools
  354. asc-mcp --workers apps,builds,versions
  355. # App Store release preparation subset (99 tools, including always-on and build sub-workers)
  356. asc-mcp --workers apps,accessibility,builds,export_compliance,versions,app_info,screenshots
  357. # TestFlight review helpers can be loaded separately (49 tools)
  358. asc-mcp --workers apps,builds,beta_app,pre_release
  359. # Monetization focus
  360. asc-mcp --workers apps,iap,subscriptions,pricing,promoted,review_submissions
  361. ```
  362. `company` and `auth` workers are **always enabled** regardless of the filter (they provide core multi-account and authentication functionality).
  363. When `builds` is enabled, it automatically includes `build_processing` and `build_beta` sub-workers.
  364. ## Read-Only Mode
  365. Use `--read-only` when you want safe inspection without App Store Connect mutations:
  366. ```bash
  367. asc-mcp --read-only
  368. asc-mcp --read-only --workers apps,builds,reviews,analytics
  369. ```
  370. In this mode, read tools such as `*_list`, `*_get`, `*_search`, `*_status`, `*_verify`, `*_parse`, `*_triage`, `auth_*`, analytics, and metrics remain available. Tools that can create, update, upload, submit, release, delete, revoke, clear, cancel, or otherwise mutate App Store Connect are blocked before their worker handler runs. `company_switch` remains available because it changes only the local active company context.
  371. ## OpenAPI Contract and Drift Tooling
  372. Use the operation-contract command to compare the actual credential-free `WorkerManager` catalog with the semantic manifest and the pinned Apple App Store Connect OpenAPI specification. The production manifest records exact Apple `operationId`, HTTP method, path, invocation-scoped input bindings, typed fixed values, response lineage, local workflows, implementation state, deprecated aliases, and deliberately deferred operations. The command does **not** load App Store Connect credentials or start the MCP server.
  373. ```bash
  374. rm -rf /tmp/asc-openapi
  375. mkdir -p /tmp/asc-openapi
  376. curl -L --fail -o /tmp/asc-openapi/spec.zip \
  377. https://developer.apple.com/sample-code/app-store-connect/app-store-connect-openapi-specification.zip
  378. spec_entry="$(unzip -Z1 /tmp/asc-openapi/spec.zip | grep -E '(^|/)openapi\.oas[^/]*\.json$')"
  379. test "$(echo "$spec_entry" | grep -c .)" -eq 1
  380. unzip -p /tmp/asc-openapi/spec.zip "$spec_entry" > /tmp/asc-openapi/openapi.oas.json
  381. swift run asc-mcp openapi-contract-check \
  382. --spec /tmp/asc-openapi/openapi.oas.json \
  383. --json-output /tmp/asc-openapi/operation-contract.json \
  384. --markdown-output /tmp/asc-openapi/operation-contract.md \
  385. --strict
  386. ```
  387. The manifest is pinned to Apple API 4.6 by version, SHA-256, path count, and operation count. It maps 528 Apple operations, explicitly defers 440, and scopes out 369, accounting for all 1,337 operations. Required CI checks the committed snapshot reproducibly. A separate latest-Apple comparison produces a semantic drift report and blocks publication until changes are reviewed. Contract CI fails when a mapped operation moves or disappears, a public tool or worker drifts from the manifest, an input field loses its binding, response lineage becomes invalid, or a deferred decision expires. Unexposed optional Apple parameters are warnings so they remain visible in the generated backlog.
  388. Manifest schema v2 also accounts for every optional Apple query and request-body input as publicly bound, internally controlled, intentionally omitted with a reviewed reason, or still unclassified. The checked-in `optionalInputCoveragePin` records the exact current totals and a SHA-256 digest of the sorted input identities and dispositions; `--strict` rejects a missing pin or any count- or identity-level drift. The pin makes phased remediation auditable and regression-safe, but it is not a claim that every optional Apple input is already public. The v4.1.3 pin is 2,905 total: 1,122 bound, 40 internally controlled, 1,743 intentionally omitted, and 0 unclassified. Its identity SHA-256 is `c975f4e4eebb62ec87864a73fbf72bb8841f644108e54e6ffb25168bcf2a2766`.
  389. `--strict` is the merge- and tag-time release gate. Every declared `target` or `broken` tool remains an error in reports, and a regression test pins their exact state. The current baseline has no `target` or `broken` implementations and no implementation drift, so any implementation that leaves `asBuilt`, any structural contract error, or any optional-input coverage drift blocks both merges and releases. `--structural-strict` remains available only for local phased remediation work.
  390. This gate proves operation identity, top-level MCP field ownership, required Apple inputs, typed internal values, and response source/pointer lineage. Full MCP type/enum/range parity and complete typed response schemas remain separate optimization phases; mapping status does not certify Apple account permissions or successful real-world acceptance.
  391. The older `openapi-coverage` command remains available for the high-level domain report in [`ASC-OPENAPI-COVERAGE-GENERATED.md`](ASC-OPENAPI-COVERAGE-GENERATED.md). The operation contract is the authoritative release gate.
  392. **Available worker names:**
  393. | Worker | Prefix | Tools | Description |
  394. |--------|--------|-------|-------------|
  395. | `company` | `company_` | 3 | Multi-account management |
  396. | `auth` | `auth_` | 4 | JWT token tools |
  397. | `apps` | `apps_` | 10 | App listing, metadata, localizations, search keyword IDs |
  398. | `accessibility` | `accessibility_` | 6 | App Store accessibility declarations |
  399. | `webhooks` | `webhooks_` | 11 | Webhook notifications, delivery diagnostics, and receiver helpers |
  400. | `xcode_cloud` | `xcode_cloud_` | 42 | Xcode Cloud products, workflow management, build runs, artifacts, issues, test results, and SCM |
  401. | `builds` | `builds_` | 4 | Build management |
  402. | `build_uploads` | `build_uploads_` | 10 | Build upload parents, files, safe transfers, and recovery |
  403. | `build_processing` | `builds_get_processing_*`, `builds_update_encryption`, `builds_check_readiness` | 4 | Build states, encryption |
  404. | `export_compliance` | `export_compliance_` | 11 | Encryption declarations, document uploads, build linkage, readiness |
  405. | `build_beta` | `builds_*_beta_*`, individual tester build tools | 11 | TestFlight localizations, notifications |
  406. | `versions` | `app_versions_` | 17 | Version lifecycle, age ratings, submit, release |
  407. | `reviews` | `reviews_` | 8 | Customer reviews and responses |
  408. | `beta_groups` | `beta_groups_` | 15 | TestFlight groups and public-link recruitment criteria |
  409. | `beta_feedback` | `beta_feedback_` | 8 | TestFlight feedback screenshots, crash submissions, crash logs |
  410. | `beta_testers` | `beta_testers_` | 12 | Tester management |
  411. | `iap` | `iap_` | 59 | In-app purchases, versioned metadata, pricing, availability, offer codes, review assets |
  412. | `subscriptions` | `subscriptions_` | 122 | Subscription and group versions, pricing, plan availability, offers, retention messaging, assets |
  413. | `sandbox` | `sandbox_` | 3 | Sandbox testers |
  414. | `beta_app` | `beta_app_` | 10 | Beta app localizations and review |
  415. | `pre_release` | `pre_release_` | 3 | Pre-release versions |
  416. | `beta_license` | `beta_license_` | 3 | Beta license agreements |
  417. | `provisioning` | `provisioning_` | 17 | Bundle IDs, devices, certificates |
  418. | `app_info` | `app_info_` | 10 | App info, categories, EULA |
  419. | `pricing` | `pricing_` | 9 | Territories, pricing |
  420. | `users` | `users_` | 10 | Team members, roles |
  421. | `app_events` | `app_events_` | 9 | In-app events, localizations |
  422. | `analytics` | `analytics_` | 11 | Sales/financial reports, analytics |
  423. | `assets` | `assets_` | 11 | Reusable images/videos, placement, preview, one-use execution, and recovery |
  424. | `screenshots` | `screenshots_` | 19 | Screenshots, previews, sets, and verified ordering |
  425. | `custom_pages` | `custom_pages_` | 17 | Custom product pages, versions, localizations, and search keywords |
  426. | `ppo` | `ppo_` | 15 | Product page optimization experiments, treatments, and localizations |
  427. | `promoted` | `promoted_` | 10 | Promoted in-app purchases and verified ordering |
  428. | `review_attachments` | `review_attachments_` | 4 | App Store review attachments |
  429. | `review_submissions` | `review_submissions_` | 9 | Generic App Store review submissions and submission items |
  430. | `metrics` | `metrics_` | 10 | Performance metrics, diagnostics, and TestFlight usage metrics |
  431. ### Tool Catalog Size
  432. When an MCP client eagerly loads every tool definition, the approximate schema footprint is:
  433. | Configuration | Tools | ~Tokens |
  434. |---|---:|---:|
  435. | All workers (default) | 537 | **~62,700** |
  436. | Release workflow: `apps,builds,export_compliance,versions,reviews` | ~72 | ~8,900 |
  437. | Monetization: `apps,iap,subscriptions,pricing` | 207 | ~23,800 |
  438. | TestFlight: `apps,builds,beta_groups,beta_testers` | ~63 | ~7,100 |
  439. | Marketing: `apps,screenshots,custom_pages,ppo,promoted` | ~78 | ~8,800 |
  440. | `--workers apps` | 17 | ~2,100 |
  441. **Heaviest workers:** Subscriptions (122 tools), InAppPurchases (59 tools), Xcode Cloud (42 tools), Screenshots (19 tools), Provisioning (17 tools).
  442. Exact cost depends on the MCP host's serialization, tokenizer, and tool-discovery strategy. Modern clients may defer schemas until they are needed. Use `--workers` when the client enforces a tool limit or when you want a smaller, more focused catalog.
  443. ## Available Tools
  444. **537 tools** organized across 34 App Store tool domains + 2 core domains (use the 36 `--workers` filter keys — see [Worker Filtering](#worker-filtering)):
  445. <details>
  446. <summary><strong>Company Management</strong> — 3 tools</summary>
  447. | Tool | Description |
  448. |------|-------------|
  449. | `company_list` | List all configured companies |
  450. | `company_switch` | Switch active company for API operations |
  451. | `company_current` | Get current active company info |
  452. </details>
  453. <details>
  454. <summary><strong>Authentication</strong> — 4 tools</summary>
  455. | Tool | Description |
  456. |------|-------------|
  457. | `auth_generate_token` | Generate JWT token for API access |
  458. | `auth_validate_token` | Locally validate a standard team-key JWT: ES256 signature, configured `kid`/`iss`, App Store Connect audience, issued-at and expiration claims, and the 20-minute maximum lifetime. This makes no Apple API call and does not prove server acceptance. |
  459. | `auth_refresh_token` | Force refresh JWT token |
  460. | `auth_token_status` | Get JWT token cache status |
  461. </details>
  462. <details>
  463. <summary><strong>Apps Management</strong> — 10 tools</summary>
  464. | Tool | Description |
  465. |------|-------------|
  466. | `apps_list` | List all applications with filtering |
  467. | `apps_get_details` | Get detailed app information |
  468. | `apps_search` | Search apps by name or Bundle ID |
  469. | `apps_list_versions` | List all versions with states |
  470. | `apps_get_metadata` | Get localized metadata for a version |
  471. | `apps_list_search_keywords` | List canonical App Store search keyword IDs for custom-page targeting |
  472. | `apps_update_metadata` | Update metadata (What's New, description, etc.) |
  473. | `apps_list_localizations` | List localizations with content status |
  474. | `apps_create_localization` | Create a new localization for a version |
  475. | `apps_delete_localization` | Delete a localization from a version |
  476. </details>
  477. <details>
  478. <summary><strong>Accessibility Declarations</strong> — 6 tools</summary>
  479. | Tool | Description |
  480. |------|-------------|
  481. | `accessibility_list` | List accessibility declarations for an app |
  482. | `accessibility_get` | Get one accessibility declaration |
  483. | `accessibility_create` | Create a declaration for a device family |
  484. | `accessibility_update` | Update support flags or publish a declaration |
  485. | `accessibility_delete` | Delete a declaration |
  486. | `accessibility_list_relationships` | List declaration relationship IDs for an app |
  487. </details>
  488. <details>
  489. <summary><strong>Webhook Notifications</strong> — 11 tools</summary>
  490. | Tool | Description |
  491. |------|-------------|
  492. | `webhooks_list` | List webhooks for an app |
  493. | `webhooks_get` | Get a webhook by ID |
  494. | `webhooks_create` | Create a webhook configuration |
  495. | `webhooks_update` | Update webhook fields |
  496. | `webhooks_delete` | Delete a webhook |
  497. | `webhooks_list_deliveries` | List delivery attempts |
  498. | `webhooks_redeliver` | Redeliver an existing delivery |
  499. | `webhooks_ping` | Send a test ping |
  500. | `webhooks_verify_signature` | Verify `x-apple-signature` against the exact raw payload body |
  501. | `webhooks_parse_payload` | Parse and normalize a raw webhook notification payload |
  502. | `webhooks_triage_event` | Produce an actionable triage plan for webhook events or delivery failures |
  503. </details>
  504. <details>
  505. <summary><strong>Xcode Cloud</strong> — 42 tools</summary>
  506. | Tool | Description |
  507. |------|-------------|
  508. | `xcode_cloud_products_list` | List Xcode Cloud products |
  509. | `xcode_cloud_products_get` | Get an Xcode Cloud product |
  510. | `xcode_cloud_products_delete` | Preview or permanently delete an Xcode Cloud product with confirmation safeguards |
  511. | `xcode_cloud_app_product_get` | Get the Xcode Cloud product associated with an app |
  512. | `xcode_cloud_product_app_get` | Get the app associated with an Xcode Cloud product |
  513. | `xcode_cloud_product_primary_repositories_list` | List primary repositories attached to a product |
  514. | `xcode_cloud_product_additional_repositories_list` | List additional repositories attached to a product |
  515. | `xcode_cloud_product_workflows_list` | List workflows for a product |
  516. | `xcode_cloud_product_build_runs_list` | List build runs for a product |
  517. | `xcode_cloud_workflows_get` | Get a workflow |
  518. | `xcode_cloud_workflows_create` | Create an Xcode Cloud workflow |
  519. | `xcode_cloud_workflows_update` | Update an Xcode Cloud workflow |
  520. | `xcode_cloud_workflows_delete` | Preview or permanently delete a workflow with confirmation safeguards |
  521. | `xcode_cloud_workflow_repository_get` | Get the repository used by a workflow |
  522. | `xcode_cloud_workflow_build_runs_list` | List build runs for a workflow |
  523. | `xcode_cloud_build_runs_get` | Get a build run |
  524. | `xcode_cloud_build_runs_start` | Start or rebuild an Xcode Cloud build |
  525. | `xcode_cloud_build_run_actions_list` | List build actions for a run |
  526. | `xcode_cloud_build_run_builds_list` | List App Store Connect builds created by a run |
  527. | `xcode_cloud_actions_get` | Get a build action |
  528. | `xcode_cloud_action_build_run_get` | Get the build run that owns a build action |
  529. | `xcode_cloud_action_artifacts_list` | List artifacts for an action |
  530. | `xcode_cloud_action_issues_list` | List issues for an action |
  531. | `xcode_cloud_action_test_results_list` | List test results for an action |
  532. | `xcode_cloud_artifacts_get` | Get an artifact |
  533. | `xcode_cloud_issues_get` | Get an issue |
  534. | `xcode_cloud_test_results_get` | Get a test result |
  535. | `xcode_cloud_xcode_versions_list` | List available Xcode versions |
  536. | `xcode_cloud_xcode_versions_get` | Get an Xcode version |
  537. | `xcode_cloud_xcode_version_macos_versions_list` | List macOS versions compatible with an Xcode version |
  538. | `xcode_cloud_macos_versions_list` | List available macOS versions |
  539. | `xcode_cloud_macos_versions_get` | Get a macOS version |
  540. | `xcode_cloud_macos_version_xcode_versions_list` | List Xcode versions compatible with a macOS version |
  541. | `xcode_cloud_scm_providers_list` | List SCM providers |
  542. | `xcode_cloud_scm_providers_get` | Get an SCM provider |
  543. | `xcode_cloud_scm_provider_repositories_list` | List repositories for an SCM provider |
  544. | `xcode_cloud_scm_repositories_list` | List SCM repositories |
  545. | `xcode_cloud_scm_repositories_get` | Get an SCM repository |
  546. | `xcode_cloud_scm_repository_git_references_list` | List repository git references |
  547. | `xcode_cloud_scm_repository_pull_requests_list` | List repository pull requests |
  548. | `xcode_cloud_scm_git_references_get` | Get a git reference |
  549. | `xcode_cloud_scm_pull_requests_get` | Get a pull request |
  550. </details>
  551. <details>
  552. <summary><strong>TestFlight Beta Feedback</strong> — 8 tools</summary>
  553. | Tool | Description |
  554. |------|-------------|
  555. | `beta_feedback_list_crashes` | List beta crash feedback submissions |
  556. | `beta_feedback_get_crash` | Get one beta crash feedback submission |
  557. | `beta_feedback_get_crash_log` | Read crash log for a submission |
  558. | `beta_feedback_get_crash_log_by_id` | Read crash log by crash log ID |
  559. | `beta_feedback_delete_crash` | Delete a beta crash feedback submission |
  560. | `beta_feedback_list_screenshots` | List beta screenshot feedback submissions |
  561. | `beta_feedback_get_screenshot` | Get one beta screenshot feedback submission |
  562. | `beta_feedback_delete_screenshot` | Delete a beta screenshot feedback submission |
  563. </details>
  564. <details>
  565. <summary><strong>Builds</strong> — 4 tools</summary>
  566. | Tool | Description |
  567. |------|-------------|
  568. | `builds_list` | List builds with processing states |
  569. | `builds_get` | Get detailed build information |
  570. | `builds_find_by_number` | Find build by version number |
  571. | `builds_list_for_version` | Get builds for specific app version |
  572. </details>
  573. <details>
  574. <summary><strong>Build Uploads</strong> — 10 tools</summary>
  575. | Tool | Description |
  576. |------|-------------|
  577. | `build_uploads_list` | List an app's Build Upload parents with filters, sparse fields, includes, and strict pagination |
  578. | `build_uploads_get` | Get one Build Upload with processing diagnostics and optional included resources |
  579. | `build_uploads_create` | Create a Build Upload parent without replaying an ambiguous POST |
  580. | `build_uploads_delete` | Delete a Build Upload parent after exact ID confirmation |
  581. | `build_uploads_list_files` | List file reservations under one Build Upload with strict pagination |
  582. | `build_uploads_get_file` | Get one Build Upload File and its delivery state |
  583. | `build_uploads_reserve_file` | Reserve one exact file without replaying an ambiguous POST |
  584. | `build_uploads_commit_file` | Commit checksum or uploaded-state changes with omission and null preserved separately |
  585. | `build_uploads_upload_file` | Transfer a new or existing reservation from an immutable local snapshot |
  586. | `build_uploads_upload` | Run parent creation, reservation, transfer, commit, and processing reconciliation |
  587. Compound uploads retain the same lowercase MD5 fingerprint from reservation through recovery. Explicit resume and recovered-continuation instructions carry `expected_md5`; the next invocation verifies a fresh immutable snapshot against it before any Apple request or transfer. An existing reservation already marked `UPLOAD_COMPLETE` or `COMPLETE` is accepted only when Apple's `sourceFileChecksums.file` MD5 matches that snapshot; missing, unsupported, or mismatched evidence is retained for inspection without another transfer, commit, or delete. Presigned operations retry only when their method is `PUT`; redirects, `POST`, and unknown methods are not replayed. If an ambiguous create is uniquely recovered, the workflow stops and returns its resource ID for explicit continuation. Transfer credentials stay redacted unless `include_sensitive_details` is explicitly enabled on a direct read.
  588. </details>
  589. <details>
  590. <summary><strong>Build Processing</strong> — 4 tools</summary>
  591. | Tool | Description |
  592. |------|-------------|
  593. | `builds_get_processing_state` | Get current processing state |
  594. | `builds_update_encryption` | Set encryption compliance |
  595. | `builds_get_processing_status` | Get detailed processing status |
  596. | `builds_check_readiness` | Check if build is ready for submission |
  597. </details>
  598. <details>
  599. <summary><strong>Export Compliance</strong> — 11 tools</summary>
  600. | Tool | Description |
  601. |------|-------------|
  602. | `export_compliance_list_declarations` | List an app's encryption declarations with strict pagination |
  603. | `export_compliance_get_declaration` | Get one declaration without deprecated document URL fields |
  604. | `export_compliance_create_declaration` | Create an encryption declaration questionnaire for an app |
  605. | `export_compliance_create_document` | Reserve, transfer, commit, and poll a document from one immutable local snapshot |
  606. | `export_compliance_get_document` | Get safe delivery metadata without signed URLs, tokens, or upload headers |
  607. | `export_compliance_update_document` | Apply a low-level nullable checksum or uploaded-state patch |
  608. | `export_compliance_upload_document` | Resume an AWAITING_UPLOAD reservation with exact bytes and its lowercase MD5 receipt |
  609. | `export_compliance_inspect_document` | Inspect document presence and classify its delivery state |
  610. | `export_compliance_get_build_declaration` | Get the declaration currently attached to a build |
  611. | `export_compliance_attach_build_declaration` | Attach an approved declaration and verify the relationship |
  612. | `export_compliance_check_release_readiness` | Evaluate only the build's export-compliance release gate |
  613. </details>
  614. <details>
  615. <summary><strong>TestFlight Beta Details</strong> — 11 tools</summary>
  616. | Tool | Description |
  617. |------|-------------|
  618. | `builds_get_beta_detail` | Get TestFlight configuration for build |
  619. | `builds_update_beta_detail` | Update TestFlight settings |
  620. | `builds_set_beta_localization` | Set What's New for TestFlight |
  621. | `builds_list_beta_localizations` | List all TestFlight localizations |
  622. | `builds_get_beta_groups` | Get beta groups for a build |
  623. | `builds_get_beta_testers` | Get individual testers for a build |
  624. | `builds_send_beta_notification` | Send notification to beta testers |
  625. | `builds_add_to_beta_groups` | Add build to beta groups |
  626. | `builds_add_individual_testers` | Add individual testers to a build |
  627. | `builds_remove_individual_testers` | Remove individual testers from a build |
  628. | `builds_list_individual_testers` | List individual testers assigned to a build |
  629. </details>
  630. <details>
  631. <summary><strong>TestFlight Beta Groups</strong> — 15 tools</summary>
  632. | Tool | Description |
  633. |------|-------------|
  634. | `beta_groups_list` | List TestFlight beta groups for an app |
  635. | `beta_groups_create` | Create a new beta group |
  636. | `beta_groups_update` | Update beta group settings |
  637. | `beta_groups_delete` | Delete a beta group |
  638. | `beta_groups_add_testers` | Add testers to a beta group |
  639. | `beta_groups_remove_testers` | Remove testers from a beta group |
  640. | `beta_groups_list_testers` | List testers in a beta group |
  641. | `beta_groups_add_builds` | Add builds to a beta group |
  642. | `beta_groups_remove_builds` | Remove builds from a beta group |
  643. | `beta_groups_get_recruitment_criteria` | Get the public-link recruitment criteria attached to a beta group |
  644. | `beta_groups_create_recruitment_criteria` | Create device-family and OS-version recruitment criteria |
  645. | `beta_groups_update_recruitment_criteria` | Replace or explicitly clear recruitment filters |
  646. | `beta_groups_delete_recruitment_criteria` | Delete recruitment criteria after exact criterion-ID confirmation |
  647. | `beta_groups_list_recruitment_options` | List device families and OS versions Apple currently permits |
  648. | `beta_groups_check_recruitment_compatibility` | Check whether a group has a build compatible with its criteria |
  649. </details>
  650. <details>
  651. <summary><strong>TestFlight Beta Testers</strong> — 12 tools</summary>
  652. Includes tester list/search/get/create/delete, app relationships, invitations, beta group assignment, build assignment, and app removal tools.
  653. </details>
  654. <details>
  655. <summary><strong>App Version Lifecycle</strong> — 17 tools</summary>
  656. | Tool | Description |
  657. |------|-------------|
  658. | `app_versions_create` | Create a new app version |
  659. | `app_versions_list` | List versions with state filtering |
  660. | `app_versions_get` | Get detailed version information |
  661. | `app_versions_get_age_rating_declaration` | Read the App Info age rating questionnaire |
  662. | `app_versions_list_territory_age_ratings` | List calculated age ratings by territory |
  663. | `app_versions_update` | Update version attributes |
  664. | `app_versions_attach_build` | Attach build to version |
  665. | `app_versions_submit_for_review` | Submit for App Store review |
  666. | `app_versions_cancel_review` | Cancel ongoing review |
  667. | `app_versions_release` | Release approved version |
  668. | `app_versions_create_phased_release` | Create gradual rollout |
  669. | `app_versions_get_phased_release` | Get phased release info and ID |
  670. | `app_versions_update_phased_release` | Pause/resume/complete rollout |
  671. | `app_versions_delete_phased_release` | Delete an eligible planned phased release with exact-ID confirmation and unknown-outcome safety |
  672. | `app_versions_set_review_details` | Set reviewer contact info |
  673. | `app_versions_update_age_rating` | Configure age rating declaration |
  674. | `app_versions_delete` | Delete an editable app version with exact-ID confirmation and unknown-outcome safety |
  675. </details>
  676. <details>
  677. <summary><strong>Customer Reviews</strong> — 8 tools</summary>
  678. | Tool | Description |
  679. |------|-------------|
  680. | `reviews_list` | Get reviews with filtering and pagination |
  681. | `reviews_get` | Get specific review details |
  682. | `reviews_list_for_version` | Get reviews for a specific version |
  683. | `reviews_stats` | Aggregated review statistics |
  684. | `reviews_create_response` | Respond to a customer review |
  685. | `reviews_delete_response` | Delete a response |
  686. | `reviews_get_response` | Get response for a review |
  687. | `reviews_summarizations` | Summarize review themes and ratings |
  688. </details>
  689. <details>
  690. <summary><strong>In-App Purchases</strong> — 59 tools</summary>
  691. | Tool | Description |
  692. |------|-------------|
  693. | `iap_list` | List in-app purchases for an app |
  694. | `iap_get` | Get IAP details |
  695. | `iap_create` | Create a new IAP |
  696. | `iap_update` | Update IAP attributes |
  697. | `iap_delete` | Delete an IAP |
  698. | `iap_list_localizations` | List IAP localizations |
  699. | `iap_create_localization` | Create IAP localization |
  700. | `iap_update_localization` | Update IAP localization |
  701. | `iap_delete_localization` | Delete IAP localization |
  702. | `iap_submit_for_review` | Submit IAP for review |
  703. | `iap_list_subscriptions` | List subscription groups |
  704. | `iap_get_subscription_group` | Get subscription group details |
  705. | `iap_inventory` | AI-friendly IAP inventory for an app |
  706. | `iap_list_price_points` | List territory-aware price points |
  707. | `iap_list_price_point_equalizations` | List price point equalizations |
  708. | `iap_get_price_schedule` | Get price schedule |
  709. | `iap_set_price_schedule` | Set price schedule |
  710. | `iap_pricing_summary` | Summarize current and scheduled prices |
  711. | `iap_prepare_offer_prices` | Find price point candidates for offers |
  712. | `iap_set_availability` | Set territory availability |
  713. | `iap_get_availability` | Get availability by IAP or availability ID |
  714. | `iap_list_available_territories` | List available territories |
  715. | `iap_get_promoted_purchase` | Get promoted purchase state |
  716. | `iap_list_offer_codes` | List IAP offer codes |
  717. | `iap_get_offer_code` | Get an IAP offer code |
  718. | `iap_create_offer_code` | Create an IAP offer code |
  719. | `iap_update_offer_code` | Update an IAP offer code |
  720. | `iap_deactivate_offer_code` | Deactivate an IAP offer code |
  721. | `iap_list_offer_code_prices` | List territory-aware offer prices |
  722. | `iap_generate_one_time_codes` | Generate one-time offer codes |
  723. | `iap_list_one_time_codes` | List one-time code batches |
  724. | `iap_get_one_time_code` | Get a one-time code batch |
  725. | `iap_update_one_time_code` | Update a one-time code batch |
  726. | `iap_deactivate_one_time_code` | Deactivate a one-time code batch |
  727. | `iap_get_one_time_code_values` | Get generated one-time code values |
  728. | `iap_create_custom_code` | Create a custom offer code |
  729. | `iap_get_custom_code` | Get custom code details |
  730. | `iap_update_custom_code` | Update a custom code |
  731. | `iap_deactivate_custom_code` | Deactivate a custom code |
  732. | `iap_get_review_screenshot` | Get review screenshot |
  733. | `iap_upload_review_screenshot` | Upload review screenshot |
  734. | `iap_delete_review_screenshot` | Delete review screenshot |
  735. | `iap_upload_image` | Upload promotional image |
  736. | `iap_get_image` | Get promotional image |
  737. | `iap_delete_image` | Delete promotional image |
  738. | `iap_list_images` | List promotional images |
  739. | `iap_create_version` | Create a reviewable IAP metadata version |
  740. | `iap_get_version` | Get an IAP version and its review state |
  741. | `iap_list_versions` | List reviewable versions for an IAP |
  742. | `iap_list_version_localizations` | List localizations owned by an IAP version |
  743. | `iap_create_version_localization` | Create a localization for an IAP version |
  744. | `iap_get_version_localization` | Get an IAP version localization |
  745. | `iap_update_version_localization` | Update nullable text on an IAP version localization |
  746. | `iap_delete_version_localization` | Delete an IAP version localization |
  747. | `iap_get_version_image` | Get the singular image related to an IAP version |
  748. | `iap_list_version_images` | List every image resource owned by an IAP version with strict continuation support |
  749. | `iap_upload_version_image` | Upload, commit, and reconcile an immutable IAP version image |
  750. | `iap_get_version_image_resource` | Get a version-scoped IAP image resource |
  751. | `iap_delete_version_image` | Delete a version-scoped IAP image |
  752. The legacy product-scoped localization, submission, and image tools remain callable for compatibility. Apple 4.4.1 deprecates `iap_list_localizations`, `iap_create_localization`, `iap_update_localization`, `iap_delete_localization`, `iap_submit_for_review`, `iap_upload_image`, `iap_get_image`, `iap_delete_image`, and `iap_list_images`; successful responses identify the versioned replacement tools. For localization creation, promotional image upload, and review submission, first use `iap_list_versions`, call `iap_create_version` only when a new metadata version is needed, and pass that version ID to the downstream versioned tool. These compatibility calls never create or select a version automatically.
  753. If Apple may have accepted a version or version-localization create but the response is lost or cannot be decoded, the tool returns `write_outcome: not_confirmed` and `retrySafe: false` with the requested identity plus list/get inspection steps. Inspect before retrying to avoid duplicate metadata resources.
  754. </details>
  755. <details>
  756. <summary><strong>Subscriptions</strong> — 122 tools</summary>
  757. Includes subscription and group metadata versions, version-owned localizations and images, plan-type-aware availability, territory-aware prices, price points and adjusted equalizations, promoted purchase reads, inventory/pricing helpers, intro offers, promotional offers, offer codes, one-time/custom codes, win-back offers, subscription retention messaging (retention messages, versions, localizations, retention offers, and subscription retention relationships), and review screenshots. All former public `offer_codes_*`, `intro_offers_*`, `promo_offers_*`, and `winback_*` functionality is exposed through `subscriptions_*`.
  758. Apple 4.4.1 also deprecates the legacy product- or group-scoped localization, image, and submission tools. They remain callable for compatibility, return explicit replacement guidance on success, and never create or select a metadata version automatically. New integrations should use `subscriptions_create_version` or `subscriptions_create_group_version`, the corresponding version-localization/image tools, and the generic `review_submissions_*` workflow.
  759. Subscription version, group-version, localization, and plan-availability creates use the same non-idempotent recovery contract: an ambiguous Apple write returns `write_outcome: not_confirmed`, `retrySafe: false`, the requested fingerprint, and deterministic collection/get inspection guidance.
  760. The following names remain available for compatibility, but Apple 4.4.1 deprecates their legacy `subscriptionAvailability` resource in favor of plan-type-aware `subscriptionPlanAvailabilities`:
  761. | Tool | Compatibility status |
  762. |------|----------------------|
  763. | `subscriptions_get_availability` | Deprecated legacy availability read |
  764. | `subscriptions_set_availability` | Deprecated legacy availability write |
  765. | `subscriptions_list_available_territories` | Deprecated legacy territory listing |
  766. | `subscriptions_inventory` | Deprecated helper; can omit subscriptions beyond the first included relationship page and is not an authoritative complete inventory |
  767. </details>
  768. <details>
  769. <summary><strong>Sandbox Testers</strong> — 3 tools</summary>
  770. | Tool | Description |
  771. |------|-------------|
  772. | `sandbox_list` | List sandbox testers |
  773. | `sandbox_update` | Update sandbox tester settings |
  774. | `sandbox_clear_purchase_history` | Clear purchase history for sandbox testers |
  775. </details>
  776. <details>
  777. <summary><strong>Beta App</strong> — 10 tools</summary>
  778. | Tool | Description |
  779. |------|-------------|
  780. | `beta_app_list_localizations` | List beta app localizations |
  781. | `beta_app_create_localization` | Create beta app localization |
  782. | `beta_app_get_localization` | Get beta app localization |
  783. | `beta_app_update_localization` | Update beta app localization |
  784. | `beta_app_delete_localization` | Delete beta app localization |
  785. | `beta_app_submit_for_review` | Submit build for beta review |
  786. | `beta_app_list_submissions` | List beta review submissions |
  787. | `beta_app_get_submission` | Get beta review submission |
  788. | `beta_app_get_review_details` | Get beta app review details |
  789. | `beta_app_update_review_details` | Update beta app review details |
  790. </details>
  791. <details>
  792. <summary><strong>Pre-Release Versions</strong> — 3 tools</summary>
  793. Includes pre-release version listing, details, and associated builds.
  794. </details>
  795. <details>
  796. <summary><strong>Beta License Agreements</strong> — 3 tools</summary>
  797. Includes beta license agreement list, get, and update.
  798. </details>
  799. <details>
  800. <summary><strong>Provisioning</strong> — 17 tools</summary>
  801. | Tool | Description |
  802. |------|-------------|
  803. | `provisioning_list_bundle_ids` | List registered bundle identifiers |
  804. | `provisioning_get_bundle_id` | Get bundle ID details |
  805. | `provisioning_create_bundle_id` | Register a new bundle identifier |
  806. | `provisioning_delete_bundle_id` | Delete a bundle identifier |
  807. | `provisioning_list_devices` | List registered devices |
  808. | `provisioning_register_device` | Register a new device (UDID) |
  809. | `provisioning_update_device` | Update device name or status |
  810. | `provisioning_list_certificates` | List signing certificates |
  811. | `provisioning_get_certificate` | Get certificate details |
  812. | `provisioning_revoke_certificate` | Revoke a certificate |
  813. | `provisioning_list_profiles` | List provisioning profiles |
  814. | `provisioning_get_profile` | Get profile details |
  815. | `provisioning_delete_profile` | Delete a profile |
  816. | `provisioning_create_profile` | Create a provisioning profile |
  817. | `provisioning_list_capabilities` | List bundle ID capabilities |
  818. | `provisioning_enable_capability` | Enable a capability |
  819. | `provisioning_disable_capability` | Disable a capability |
  820. </details>
  821. <details>
  822. <summary><strong>App Info</strong> — 10 tools</summary>
  823. Includes app info list/get/update, app info localizations, and EULA get/create/update tools.
  824. </details>
  825. <details>
  826. <summary><strong>Pricing</strong> — 9 tools</summary>
  827. Includes territories, availability, price points, price schedules, and App Store availability v2 tools.
  828. </details>
  829. <details>
  830. <summary><strong>Users</strong> — 10 tools</summary>
  831. Includes team member list/get/update/remove, invitations, visible apps, and visible app relationship updates.
  832. </details>
  833. <details>
  834. <summary><strong>App Events</strong> — 9 tools</summary>
  835. Includes in-app event CRUD plus event localization list/create/update/delete.
  836. </details>
  837. <details>
  838. <summary><strong>Analytics</strong> — 11 tools</summary>
  839. Includes sales, financial, app summary, analytics report request, report, instance, snapshot, and segment tools.
  840. </details>
  841. <details>
  842. <summary><strong>Screenshots & Previews</strong> — 19 tools</summary>
  843. | Tool | Description |
  844. |------|-------------|
  845. | `screenshots_list_sets` | List screenshot sets |
  846. | `screenshots_get_set` | Get a screenshot set by ID |
  847. | `screenshots_create_set` | Create a screenshot set |
  848. | `screenshots_delete_set` | Delete a screenshot set |
  849. | `screenshots_list` | List screenshots in a set |
  850. | `screenshots_upload` | Upload a screenshot |
  851. | `screenshots_get` | Get screenshot details |
  852. | `screenshots_delete` | Delete a screenshot |
  853. | `screenshots_reorder` | Reorder screenshots in a set |
  854. | `screenshots_list_preview_sets` | List app preview sets |
  855. | `screenshots_get_preview_set` | Get an app preview set by ID |
  856. | `screenshots_create_preview_set` | Create a preview set |
  857. | `screenshots_delete_preview_set` | Delete a preview set |
  858. | `screenshots_upload_preview` | Upload an app preview |
  859. | `screenshots_get_preview` | Get preview details |
  860. | `screenshots_list_previews` | List previews in a preview set |
  861. | `screenshots_reorder_previews` | Reorder every preview in a set with membership and postflight verification |
  862. | `screenshots_upload_batch` | Upload screenshots in a batch |
  863. | `screenshots_delete_preview` | Delete a preview |
  864. </details>
  865. <details>
  866. <summary><strong>Custom Product Pages</strong> — 17 tools</summary>
  867. | Tool | Description |
  868. |------|-------------|
  869. | `custom_pages_list` | List custom product pages |
  870. | `custom_pages_get` | Get page details |
  871. | `custom_pages_create` | Create a custom page |
  872. | `custom_pages_update` | Update a custom page |
  873. | `custom_pages_delete` | Delete a custom page |
  874. | `custom_pages_list_versions` | List page versions |
  875. | `custom_pages_get_version` | Get a page version by ID |
  876. | `custom_pages_create_version` | Create a page version |
  877. | `custom_pages_update_version` | Update a page version |
  878. | `custom_pages_list_localizations` | List version localizations |
  879. | `custom_pages_get_localization` | Get a localization by ID |
  880. | `custom_pages_create_localization` | Create a localization |
  881. | `custom_pages_update_localization` | Update a localization |
  882. | `custom_pages_delete_localization` | Delete a localization after exact confirmation |
  883. | `custom_pages_list_search_keywords` | List search keyword IDs assigned to a localization |
  884. | `custom_pages_add_search_keywords` | Add search keyword relationships |
  885. | `custom_pages_remove_search_keywords` | Remove search keyword relationships after exact confirmation |
  886. </details>
  887. <details>
  888. <summary><strong>Product Page Optimization (A/B Tests)</strong> — 15 tools</summary>
  889. | Tool | Description |
  890. |------|-------------|
  891. | `ppo_list_experiments` | List A/B test experiments |
  892. | `ppo_list_version_experiments` | List V2 experiments for an App Store version |
  893. | `ppo_get_experiment` | Get experiment details |
  894. | `ppo_create_experiment` | Create an experiment |
  895. | `ppo_update_experiment` | Update/start/stop experiment |
  896. | `ppo_delete_experiment` | Delete an experiment |
  897. | `ppo_list_treatments` | List experiment treatments |
  898. | `ppo_get_treatment` | Get a treatment by ID |
  899. | `ppo_create_treatment` | Create a treatment variant |
  900. | `ppo_update_treatment` | Update a treatment variant |
  901. | `ppo_delete_treatment` | Delete a treatment after exact confirmation |
  902. | `ppo_list_treatment_localizations` | List treatment localizations |
  903. | `ppo_get_treatment_localization` | Get a treatment localization by ID |
  904. | `ppo_create_treatment_localization` | Create treatment localization |
  905. | `ppo_delete_treatment_localization` | Delete a treatment localization after exact confirmation |
  906. </details>
  907. <details>
  908. <summary><strong>Promoted Purchases</strong> — 10 tools</summary>
  909. | Tool | Description |
  910. |------|-------------|
  911. | `promoted_list` | List promoted purchases for an app |
  912. | `promoted_get` | Get promotion details |
  913. | `promoted_create` | Create a promotion |
  914. | `promoted_update` | Update promotion visibility or enabled state |
  915. | `promoted_delete` | Delete a promotion |
  916. | `promoted_reorder` | Replace and verify the complete promoted-purchase order for an app |
  917. | `promoted_upload_image` | Deprecated: returns migration guidance; the endpoint is absent from pinned Apple OpenAPI 4.5.1 |
  918. | `promoted_get_image` | Deprecated: returns migration guidance; the endpoint is absent from pinned Apple OpenAPI 4.5.1 |
  919. | `promoted_delete_image` | Deprecated: returns migration guidance; the endpoint is absent from pinned Apple OpenAPI 4.5.1 |
  920. | `promoted_get_image_for_purchase` | Deprecated: returns migration guidance; the relationship is absent from pinned Apple OpenAPI 4.5.1 |
  921. </details>
  922. <details>
  923. <summary><strong>Review Attachments</strong> — 4 tools</summary>
  924. Includes App Store review attachment upload, get, delete, and list tools.
  925. </details>
  926. <details>
  927. <summary><strong>Review Submissions</strong> — 9 tools</summary>
  928. | Tool | Description |
  929. |------|-------------|
  930. | `review_submissions_list` | List generic review submissions for an app |
  931. | `review_submissions_get` | Get one generic review submission |
  932. | `review_submissions_create` | Create a generic review submission for an app and platform |
  933. | `review_submissions_list_items` | List items attached to a review submission |
  934. | `review_submissions_add_item` | Attach a reviewable resource version to a submission |
  935. | `review_submissions_update_item` | Update nullable `resolved` or `removed` state on a submitted item |
  936. | `review_submissions_remove_item` | Remove an item from a submission |
  937. | `review_submissions_submit` | Submit all attached items for review |
  938. | `review_submissions_cancel` | Cancel a submitted generic review submission |
  939. `review_submissions_add_item` reports success only when Apple's response confirms a valid item ID and exactly the requested relationship name, JSON:API type, and resource ID. Any mismatch is returned as an unconfirmed write with submission and item-list recovery steps.
  940. </details>
  941. <details>
  942. <summary><strong>App Asset Library</strong> — 11 tools</summary>
  943. | Tool | Description |
  944. |------|-------------|
  945. | `assets_get_library` | Read the app-owned reusable asset library |
  946. | `assets_get_reference_data` | Read dynamic media and placement requirements, optionally by ID |
  947. | `assets_list_images` | Browse the app's images with scoped pagination |
  948. | `assets_list_videos` | Browse the app's videos with scoped pagination |
  949. | `assets_get_image` | Read image processing/review state and safe properties |
  950. | `assets_get_video` | Read video and independent poster-frame processing state |
  951. | `assets_list_placements` | Browse uses of one asset or contents of one localization |
  952. | `assets_get_placement` | Read a placement and verify its parent app |
  953. | `assets_prepare_change` | Prepare a typed change without writing to Apple; return a ten-minute preview |
  954. | `assets_apply_change` | Consume a preview once, revalidate, execute and read back |
  955. | `assets_get_operation` | Inspect the private journal and reconcile through reads only |
  956. Read the [migration and recovery guide](docs/migrations/4.2.0-asset-library.md) before applying changes. Upload, placement and review are separate operations; published-placement changes are outside this candidate's acceptance scope.
  957. </details>
  958. <details>
  959. <summary><strong>Performance Metrics</strong> — 10 tools</summary>
  960. | Tool | Description |
  961. |------|-------------|
  962. | `metrics_performance_overview` | Read app performance overview with device filtering |
  963. | `metrics_app_perf` | Get app performance/power metrics |
  964. | `metrics_build_perf` | Get build performance metrics |
  965. | `metrics_build_diagnostics` | List diagnostics for a build |
  966. | `metrics_get_diagnostic_logs` | Get diagnostic logs |
  967. | `metrics_app_beta_tester_usage` | Get app TestFlight crash, session, and feedback metrics by beta tester |
  968. | `metrics_group_beta_tester_usage` | Get beta-group TestFlight crash, session, and feedback metrics by beta tester |
  969. | `metrics_group_public_link_usage` | Get public-link views, acceptance outcomes, criteria failures, and survey ratios |
  970. | `metrics_tester_usage` | Get one tester's TestFlight usage metrics within an app |
  971. | `metrics_build_beta_usage` | Get build TestFlight crash, install, session, feedback, and invitation metrics |
  972. </details>
  973. ## Usage Examples
  974. ### Complete Release Workflow
  975. ```
  976. You: "Release version 2.2.0 of my app with build 456"
  977. Claude will:
  978. 1. app_versions_create(app_id, platform: "IOS", version_string: "2.2.0")
  979. 2. app_versions_attach_build(version_id, build_id)
  980. 3. app_versions_set_review_details(version_id, contact_email: "...")
  981. 4. app_versions_submit_for_review(version_id)
  982. 5. app_versions_create_phased_release(version_id) # after approval
  983. ```
  984. ### TestFlight Distribution
  985. ```
  986. You: "Create a beta group 'External Testers' and distribute the latest build"
  987. Claude will:
  988. 1. beta_groups_create(app_id, name: "External Testers")
  989. 2. builds_list(app_id, limit: 1) # find latest
  990. 3. builds_set_beta_localization(build_id, locale: "en-US", whats_new: "...")
  991. 4. beta_groups_add_testers(group_id, tester_ids: [...])
  992. ```
  993. ### Review Management
  994. ```
  995. You: "Show me all 1-star reviews from the last week and draft responses"
  996. Claude will:
  997. 1. reviews_list(app_id, rating: 1, sort: "-createdDate", limit: 50)
  998. 2. reviews_create_response(review_id, response_body: "...") # for each
  999. ```
  1000. ### Multi-Company Workflow
  1001. ```
  1002. You: "Switch to ClientCorp and check their latest build status"
  1003. Claude will:
  1004. 1. company_switch(company: "ClientCorp")
  1005. 2. apps_list(limit: 5)
  1006. 3. builds_list(app_id, limit: 1)
  1007. 4. builds_get_processing_state(build_id)
  1008. ```
  1009. ## API Constraints
  1010. | Constraint | Details |
  1011. |------------|---------|
  1012. | **No emojis** | Metadata fields (What's New, Description, Keywords) must not contain emoji characters |
  1013. | **Version state** | App Store Connect validates editable states for metadata updates. Rejected and metadata-rejected versions can be edited for resubmission; published or in-review versions may be rejected by Apple. |
  1014. | **JWT expiry** | Tokens expire after 20 minutes — the server auto-refreshes them |
  1015. | **Rate limits** | Apple enforces per-account rate limits ([documentation](https://developer.apple.com/documentation/appstoreconnectapi/identifying-rate-limits)) |
  1016. | **Locale format** | Use standard codes: `en-US`, `ru`, `de-DE`, `ja`, `zh-Hans` |
  1017. ## Architecture
  1018. ```
  1019. Sources/asc-mcp/
  1020. ├── EntryPoint.swift # Entry point, --workers filtering
  1021. ├── Core/
  1022. │ ├── Application.swift # MCP server setup & initialization
  1023. │ └── ASCError.swift # Custom error types
  1024. ├── Helpers/ # JSON formatting, pagination, safe helpers
  1025. ├── Models/ # API request/response models
  1026. │ ├── AppStoreConnect/ # Apps, versions, localizations
  1027. │ ├── Builds/ # Builds, beta details, beta groups
  1028. │ ├── AppLifecycle/ # Version lifecycle models
  1029. │ ├── InAppPurchases/ # IAP models
  1030. │ ├── Subscriptions/ # Subscriptions, offer codes, win-back
  1031. │ ├── Marketing/ # Screenshots, custom pages, PPO, promoted
  1032. │ ├── Metrics/ # Performance metrics, diagnostics
  1033. │ ├── Analytics/ # Sales/financial reports
  1034. │ ├── Provisioning/ # Bundle IDs, devices, certificates
  1035. │ ├── Shared/ # Shared upload/image types
  1036. │ └── ... # AppEvents, AppInfo, Pricing, Users
  1037. ├── Services/
  1038. │ ├── HTTPClient.swift # Actor-based HTTP with retry logic
  1039. │ ├── JWTService.swift # ES256 JWT token generation
  1040. │ └── CompaniesManager.swift # Multi-account management
  1041. └── Workers/ # MCP tool implementations (40 Swift worker classes + MainWorker router)
  1042. ├── MainWorker/WorkerManager # Central tool registry & routing
  1043. ├── CompaniesWorker/ # company_* tools
  1044. ├── AuthWorker/ # auth_* tools
  1045. ├── AppsWorker/ # apps_* tools
  1046. ├── AccessibilityWorker/ # accessibility_* tools
  1047. ├── WebhooksWorker/ # webhooks_* tools
  1048. ├── XcodeCloudWorker/ # xcode_cloud_* tools
  1049. ├── BuildsWorker/ # builds_* tools
  1050. ├── BuildUploadsWorker/ # build_uploads_* tools
  1051. ├── BuildProcessingWorker/ # builds_*_processing tools
  1052. ├── ExportComplianceWorker/ # export_compliance_* tools
  1053. ├── BuildBetaDetailsWorker/ # builds_*_beta_* tools
  1054. ├── AppLifecycleWorker/ # app_versions_* tools
  1055. ├── ReviewsWorker/ # reviews_* tools
  1056. ├── BetaGroupsWorker/ # beta_groups_* tools
  1057. ├── BetaFeedbackWorker/ # beta_feedback_* tools
  1058. ├── BetaTestersWorker/ # beta_testers_* tools
  1059. ├── InAppPurchasesWorker/ # iap_* tools
  1060. ├── SubscriptionsWorker/ # subscriptions_* tools
  1061. ├── OfferCodesWorker/ # subscriptions offer-code tools
  1062. ├── IntroductoryOffersWorker/ # subscriptions intro-offer tools
  1063. ├── PromotionalOffersWorker/ # subscriptions promotional-offer tools
  1064. ├── WinBackOffersWorker/ # subscriptions win-back tools
  1065. ├── SandboxTestersWorker/ # sandbox_* tools
  1066. ├── BetaAppWorker/ # beta_app_* tools
  1067. ├── PreReleaseVersionsWorker/ # pre_release_* tools
  1068. ├── BetaLicenseAgreementsWorker/ # beta_license_* tools
  1069. ├── ProvisioningWorker/ # provisioning_* tools
  1070. ├── AppInfoWorker/ # app_info_* tools
  1071. ├── PricingWorker/ # pricing_* tools
  1072. ├── UsersWorker/ # users_* tools
  1073. ├── AppEventsWorker/ # app_events_* tools
  1074. ├── AnalyticsWorker/ # analytics_* tools
  1075. ├── ScreenshotsWorker/ # screenshots_* tools
  1076. ├── CustomProductPagesWorker/ # custom_pages_* tools
  1077. ├── ProductPageOptimizationWorker/ # ppo_* tools
  1078. ├── PromotedPurchasesWorker/ # promoted_* tools
  1079. ├── ReviewAttachmentsWorker/ # review_attachments_* tools
  1080. ├── ReviewSubmissionsWorker/ # review_submissions_* tools
  1081. └── MetricsWorker/ # metrics_* tools
  1082. ```
  1083. ### Design Principles
  1084. - **Swift 6 strict concurrency** — all workers and services are `Sendable`, proper actor isolation
  1085. - **Actor-based HTTP client** — thread-safe with exponential backoff and retry logic
  1086. - **Prefix-based routing** — `WorkerManager` routes tool calls by name prefix (zero config)
  1087. - **Minimal dependencies** — only the [MCP Swift SDK](https://github.com/modelcontextprotocol/swift-sdk)
  1088. ## Troubleshooting
  1089. <details>
  1090. <summary><strong>Server not responding / MCP disconnection</strong></summary>
  1091. 1. Run `~/.mint/bin/asc-mcp --version` to verify the installation independently of the MCP client.
  1092. 2. Verify that the MCP client uses the absolute path to the installed executable.
  1093. 3. For Codex, run `codex mcp list` and `codex mcp get asc-mcp --json`.
  1094. 4. For Claude Code, run `claude mcp get asc-mcp` and `claude mcp list`.
  1095. 5. Check either the configured `companies.json` file or the environment variables used by your chosen setup.
  1096. 6. Ensure every `.p8` key path is absolute and the file exists.
  1097. 7. Restart GUI clients after changing their MCP configuration, then inspect the client's MCP output log.
  1098. </details>
  1099. <details>
  1100. <summary><strong>Authentication errors (401)</strong></summary>
  1101. 1. Verify your Key ID and Issuer ID match what's shown in App Store Connect
  1102. 2. Ensure the `.p8` file is the original download (not modified)
  1103. 3. Check that the API key hasn't been revoked
  1104. 4. JWT tokens auto-refresh, but if the key is invalid, all requests will fail
  1105. </details>
  1106. <details>
  1107. <summary><strong>Metadata update rejected by App Store Connect state rules</strong></summary>
  1108. `apps_update_metadata` sends the metadata PATCH to App Store Connect after local text, locale, and URL validation. Apple decides whether the current version state is editable. Rejected and metadata-rejected versions can be edited and resubmitted; published, in-review, or otherwise locked versions may return an Apple API error.
  1109. </details>
  1110. <details>
  1111. <summary><strong>Build processing takes too long</strong></summary>
  1112. Use `builds_get_processing_status` to inspect the current processing state and `builds_check_readiness` to verify App Store/TestFlight readiness. Apple's build processing typically takes 5-30 minutes but can be longer during peak times.
  1113. </details>
  1114. <details>
  1115. <summary><strong>Rate limiting (429 errors)</strong></summary>
  1116. The HTTP client automatically retries with exponential backoff on 429 responses. If you consistently hit limits, reduce the frequency of API calls or use pagination with smaller page sizes.
  1117. </details>
  1118. ## Getting Help
  1119. Before opening a report, search the [existing issues](https://github.com/zelentsov-dev/asc-mcp/issues). If the problem is new, [open an issue](https://github.com/zelentsov-dev/asc-mcp/issues/new/choose) and include:
  1120. - macOS version and installation method;
  1121. - MCP client name and version;
  1122. - the selected `--workers` value, if any;
  1123. - the exact error message and the smallest reproducible request.
  1124. Remove Key IDs, Issuer IDs, private keys, signed URLs, tokens, and account data from logs before posting them. Report security vulnerabilities privately by following [SECURITY.md](SECURITY.md). For code contributions, see [CONTRIBUTING.md](CONTRIBUTING.md).
  1125. ## Development
  1126. ### Building
  1127. ```bash
  1128. swift build # Debug build
  1129. swift build -c release # Release build (optimized)
  1130. swift package clean # Clean build artifacts
  1131. ```
  1132. ### Test Mode
  1133. ```bash
  1134. .build/debug/asc-mcp --test # Runs built-in integration tests
  1135. ```
  1136. ### Adding a New Tool
  1137. 1. Create handler method in the appropriate `Worker+Handlers.swift`
  1138. 2. Add tool definition in `Worker+ToolDefinitions.swift`
  1139. 3. Register in worker's `getTools()` method
  1140. 4. Add routing case in worker's `handleTool()` switch
  1141. 5. The `WorkerManager` auto-routes by prefix — no changes needed there
  1142. ### Adding a New Worker
  1143. 1. Create directory: `Workers/MyWorker/`
  1144. 2. Create 3 files: `MyWorker.swift`, `MyWorker+ToolDefinitions.swift`, `MyWorker+Handlers.swift`
  1145. 3. Add worker property and initialization in `WorkerManager.swift`
  1146. 4. Add routing rule in `WorkerManager.registerWorkers()`
  1147. 5. Add `getMyTools()` helper method
  1148. ## Contributing
  1149. We welcome contributions! See [Contributing Guide](CONTRIBUTING.md) for details.
  1150. ## License
  1151. This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
  1152. ## Acknowledgments
  1153. - [Model Context Protocol](https://modelcontextprotocol.io) — the protocol specification and [Swift SDK](https://github.com/modelcontextprotocol/swift-sdk)
  1154. - [App Store Connect API](https://developer.apple.com/documentation/appstoreconnectapi) — Apple's official REST API
  1155. ---
  1156. <sub>This is an unofficial, community-maintained tool and is not affiliated with or endorsed by Apple Inc.</sub>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.