Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -264,7 +264,7 @@ jobs:
contract_directory="$RUNNER_TEMP/asc_openapi_contract"
rm -rf "$contract_directory"
mkdir -p "$contract_directory"
cp Tests/ASCMCPTests/Fixtures/OpenAPI/app-store-connect-4.5.1.oas.json \
cp Tests/ASCMCPTests/Fixtures/OpenAPI/app-store-connect-4.6.oas.json \
"$contract_directory/openapi.oas.json"
shasum -a 256 "$contract_directory/openapi.oas.json" \
> "$contract_directory/specification.sha256"
Expand Down Expand Up @@ -364,7 +364,7 @@ jobs:
run: |
set -euo pipefail
python3 .github/workflows/scripts/apple_spec_drift.py \
--pinned Tests/ASCMCPTests/Fixtures/OpenAPI/app-store-connect-4.5.1.oas.json \
--pinned Tests/ASCMCPTests/Fixtures/OpenAPI/app-store-connect-4.6.oas.json \
--latest-zip "$RUNNER_TEMP/asc_latest_openapi/spec.zip" \
--output-directory "$RUNNER_TEMP/asc_latest_openapi"

Expand Down
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ Each company needs: `keyID`, `issuerID`, `privateKeyPath` (path to `.p8` file).

**WorkerManager** (`Workers/MainWorker/WorkerManager.swift`) — central registry, routes tool calls by prefix.

**Workers** (40 Swift worker classes; 36 `--workers` filter keys; 514 tools):
**Workers** (40 Swift worker classes; 36 `--workers` filter keys; 537 tools):

| Worker | Prefix | Tools | Domain |
|--------|--------|-------|--------|
Expand All @@ -76,7 +76,7 @@ Each company needs: `keyID`, `issuerID`, `privateKeyPath` (path to `.p8` file).
| UsersWorker | `users_` | 10 | Team members, roles, invitations, visible apps |
| AppEventsWorker | `app_events_` | 9 | In-app events CRUD, localizations |
| AnalyticsWorker | `analytics_` | 11 | Sales/financial reports, app summary, analytics reports/instances/segments, snapshot status |
| SubscriptionsWorker | `subscriptions_` | 99 | Subscription and group versions, pricing, plan availability, offers, assets; includes offer-code, intro, promotional, and win-back sub-worker behavior |
| SubscriptionsWorker | `subscriptions_` | 122 | Subscription and group versions, pricing, plan availability, offers, retention messaging (messages, versions, localizations, retention offers, and subscription retention relationships), assets; includes offer-code, intro, promotional, and win-back sub-worker behavior |
| SandboxTestersWorker | `sandbox_` | 3 | Sandbox testers (list, update, clear purchase history) |
| BetaAppWorker | `beta_app_` | 10 | Beta app localizations, review submissions, review details |
| PreReleaseVersionsWorker | `pre_release_` | 3 | Pre-release versions (list, get, builds) |
Expand Down
1 change: 1 addition & 0 deletions ASC-COVERAGE-MATRIX-2026-05-05.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ Update 2026-05-08: local webhook receiver helpers are available for signature ve
Update 2026-07-20: Apple 4.4.1 versioned commerce metadata, plan-type-aware subscription availability, adjusted equalizations, and generic review submissions are covered.
Update 2026-07-21: Build Upload parents, file reservations, resumable transfers, commit recovery, and processing reconciliation are covered by `build_uploads_*` tools.
Update 2026-07-21: 11 TestFlight recruitment and usage-metric tools cover 12 additional Apple operations, including app-device context in tester projections.
Update 2026-11-07: Apple 4.6 subscription retention messaging (messages, versions, localizations, retention offers, subscription retention relationships, Asset Library `retentionMessageVersion` image placements, and Review Submission `retentionMessageVersion` items) is covered.

This matrix tracks current `asc-mcp` coverage against the official App Store Connect API documentation. It is intentionally product-oriented: it names what users can do today, what is missing, and which additions should come first.

Expand Down
16 changes: 8 additions & 8 deletions ASC-OPENAPI-COVERAGE-GENERATED.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,21 @@
# App Store Connect OpenAPI Coverage

Generated: 2026-10-15
Generated: 2026-11-07

Sources:
- Apple App Store Connect API overview: https://developer.apple.com/app-store-connect/api/
- Apple App Store Connect API documentation: https://developer.apple.com/documentation/appstoreconnectapi
- Apple OpenAPI specification download: https://developer.apple.com/sample-code/app-store-connect/app-store-connect-openapi-specification.zip

Spec: App Store Connect API 4.5.1 (OpenAPI 3.0.1)
Apple paths: 1001
Apple operations: 1303
Classified paths: 1001
Spec: App Store Connect API 4.6 (OpenAPI 3.0.1)
Apple paths: 1027
Apple operations: 1337
Classified paths: 1027
Unclassified paths: 0

## Priority Gaps

- P0 App Store app metadata and release operations: Partial, 332 Apple paths, 414 operations.
- P0 App Store app metadata and release operations: Partial, 334 Apple paths, 416 operations.
- P0 TestFlight builds, testers, groups, and beta app review: Partial, 115 Apple paths, 154 operations.
- P1 Provisioning and identifiers: Partial, 32 Apple paths, 49 operations.
- P1 Reporting, analytics, metrics, and diagnostics: Partial, 47 Apple paths, 56 operations.
Expand All @@ -25,7 +25,7 @@ Unclassified paths: 0

| Domain | Status | Priority | Apple paths | Operations | Workers | Notes |
|---|---|---:|---:|---:|---|---|
| App Store app metadata and release operations | Partial | P0 | 332 | 414 | `apps`, `accessibility`, `versions`, `app_info`, `pricing`, `app_events`, `assets`, `screenshots`, `custom_pages`, `ppo`, `promoted`, `review_attachments`, `review_submissions`, `reviews`, `export_compliance` | The common release workflow includes strict version filtering and paging, safe phased-release controls, generic review submissions, App Info-owned age-rating inspection, app search keywords, expanded Custom Product Page and PPO workflows, promoted ordering, and verified screenshot and preview ordering. Remaining app-surface operations stay explicitly phased. |
| App Store app metadata and release operations | Partial | P0 | 334 | 416 | `apps`, `accessibility`, `versions`, `app_info`, `pricing`, `app_events`, `assets`, `screenshots`, `custom_pages`, `ppo`, `promoted`, `review_attachments`, `review_submissions`, `reviews`, `export_compliance` | The common release workflow includes strict version filtering and paging, safe phased-release controls, generic review submissions, App Info-owned age-rating inspection, app search keywords, expanded Custom Product Page and PPO workflows, promoted ordering, and verified screenshot and preview ordering. Remaining app-surface operations stay explicitly phased. |
| TestFlight builds, testers, groups, and beta app review | Partial | P0 | 115 | 154 | `builds`, `build_uploads`, `build_processing`, `export_compliance`, `build_beta`, `beta_groups`, `beta_feedback`, `beta_testers`, `beta_app`, `pre_release`, `beta_license`, `metrics` | Core TestFlight administration, resumable build uploads, and dedicated beta feedback retrieval are covered. Six recruitment tools and five usage-metric tools map twelve additional Apple operations; beta App Clip APIs remain the main gap. |
| Essentials: auth, errors, paging, uploads, rate limits | Partial | P1 | 0 | 0 | `auth` | Core runtime behavior is covered; OpenAPI drift is now generated from Apple's official specification. |
| Provisioning and identifiers | Partial | P1 | 32 | 49 | `provisioning` | Core signing automation exists; Wallet and Apple Pay identifiers are useful next additions. |
Expand All @@ -34,7 +34,7 @@ Unclassified paths: 0
| Xcode Cloud workflows and builds | Partial | P1 | 56 | 59 | `xcode_cloud` | Covers read-heavy CI dashboards plus start/rebuild build runs; destructive workflow/product management remains intentionally deferred. |
| Alternative distribution | Missing | P2 | 21 | 28 | none | Region- and entitlement-sensitive APIs should be opt-in and strongly documented. |
| Game Center | Missing | P2 | 244 | 343 | none | Large domain; should be added only after OpenAPI-driven scaffolding is in place. |
| In-app purchases, subscriptions, and offers | Partial | P2 | 172 | 218 | `iap`, `subscriptions` | Apple 4.4.1 versioned metadata, generic review submission handoff, plan-type-aware subscription availability, and adjusted equalizations are covered. Legacy product-scoped tools remain explicit compatibility paths; an authoritative fully paginated subscription inventory is still pending. |
| In-app purchases, subscriptions, and offers | Partial | P2 | 196 | 250 | `iap`, `subscriptions` | Apple 4.4.1 versioned metadata, Apple 4.6 subscription retention messaging, generic review submission handoff, plan-type-aware subscription availability, and adjusted equalizations are covered. Legacy product-scoped tools remain explicit compatibility paths; an authoritative fully paginated subscription inventory is still pending. |
| Users, access, and sandbox testers | Partial | P2 | 13 | 20 | `users`, `sandbox` | User management is serviceable; API key operations should remain carefully annotated as high-risk. |
| Webhook notifications | Covered | P2 | 6 | 8 | `webhooks` | Covers app webhooks, individual webhook reads, create/update/delete, delivery listing, redelivery, ping testing, and local receiver diagnostics. |

Expand Down
7 changes: 7 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

### Added

- Add 23 subscription retention messaging tools in `SubscriptionsWorker` (`subscriptions_*`) covering App Store Connect API 4.6 retention messages (`list`, `get`, `create`, `delete`), versions (`list`, `get`, `create`), localizations (`list`, `get`, `create`, `update`, `delete`) with Apple header/body/emoji/price-mention preflight validation, retention offers (`list`, `get`, `create`, `update`, `delete`, `list_retention_offer_prices`), and subscription retention relationships (`list_retention_message_subscriptions`, `get_retention_message_for_subscription`, `set_retention_message`, `add_retention_message_offers`, `remove_retention_message_offers`).
- Extend `AssetsWorker` (`assets_*`) to support `retentionMessageVersion` (`feature = "RETENTION_MESSAGING"`) image placements via Apple's to-one `/v1/retentionMessageVersions/{id}/placement` endpoint, with app-scoped ownership verification and explicit rejection of video placements and multi-placement reordering.
- Extend `ReviewSubmissionsWorker` (`review_submissions_*`) to support `retention_message_version_id` (`retentionMessageVersion` / `retentionMessageVersions`) in review submission item assembly and reads.
- Pin the official Apple 4.6 OpenAPI specification (`1,027` paths, `1,337` operations) and update the operation manifest (`537` public tools, `528` mapped operations, `440` waived, `369` scope-rule out of scope, `4,562` classified optional inputs with `0` unclassified).

## [4.2.0] - 2026-10-19

### Added
Expand Down
20 changes: 10 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@

## Overview

**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 **514 tools** across 34 App Store tool domains + 2 core domains, enabling you to automate iOS and macOS release workflows through natural language.
**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.

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.

Expand Down Expand Up @@ -482,7 +482,7 @@ You can also disable individual tools in the client. Server-side worker filterin

## Worker Filtering

The server exposes **514 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:
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:

```bash
# Only load apps, builds, and version lifecycle tools
Expand Down Expand Up @@ -533,7 +533,7 @@ swift run asc-mcp openapi-contract-check \
--strict
```

The manifest is pinned to Apple API 4.5.1 by version, SHA-256, path count, and operation count. It maps 503 Apple operations, explicitly defers 431, and scopes out 369, accounting for all 1,303 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.
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.

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`.

Expand Down Expand Up @@ -564,7 +564,7 @@ The older `openapi-coverage` command remains available for the high-level domain
| `beta_feedback` | `beta_feedback_` | 8 | TestFlight feedback screenshots, crash submissions, crash logs |
| `beta_testers` | `beta_testers_` | 12 | Tester management |
| `iap` | `iap_` | 59 | In-app purchases, versioned metadata, pricing, availability, offer codes, review assets |
| `subscriptions` | `subscriptions_` | 99 | Subscription and group versions, pricing, plan availability, offers, assets |
| `subscriptions` | `subscriptions_` | 122 | Subscription and group versions, pricing, plan availability, offers, retention messaging, assets |
| `sandbox` | `sandbox_` | 3 | Sandbox testers |
| `beta_app` | `beta_app_` | 10 | Beta app localizations and review |
| `pre_release` | `pre_release_` | 3 | Pre-release versions |
Expand All @@ -590,20 +590,20 @@ When an MCP client eagerly loads every tool definition, the approximate schema f

| Configuration | Tools | ~Tokens |
|---|---:|---:|
| All workers (default) | 514 | **~60,000** |
| All workers (default) | 537 | **~62,700** |
| Release workflow: `apps,builds,export_compliance,versions,reviews` | ~72 | ~8,900 |
| Monetization: `apps,iap,subscriptions,pricing` | 184 | ~21,100 |
| Monetization: `apps,iap,subscriptions,pricing` | 207 | ~23,800 |
| TestFlight: `apps,builds,beta_groups,beta_testers` | ~63 | ~7,100 |
| Marketing: `apps,screenshots,custom_pages,ppo,promoted` | ~78 | ~8,800 |
| `--workers apps` | 17 | ~2,100 |

**Heaviest workers:** Subscriptions (99 tools), InAppPurchases (59 tools), Xcode Cloud (42 tools), Screenshots (19 tools), Provisioning (17 tools).
**Heaviest workers:** Subscriptions (122 tools), InAppPurchases (59 tools), Xcode Cloud (42 tools), Screenshots (19 tools), Provisioning (17 tools).

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.

## Available Tools

**514 tools** organized across 34 App Store tool domains + 2 core domains (use the 36 `--workers` filter keys — see [Worker Filtering](#worker-filtering)):
**537 tools** organized across 34 App Store tool domains + 2 core domains (use the 36 `--workers` filter keys — see [Worker Filtering](#worker-filtering)):

<details>
<summary><strong>Company Management</strong> — 3 tools</summary>
Expand Down Expand Up @@ -970,9 +970,9 @@ If Apple may have accepted a version or version-localization create but the resp
</details>

<details>
<summary><strong>Subscriptions</strong> — 99 tools</summary>
<summary><strong>Subscriptions</strong> — 122 tools</summary>

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, and review screenshots. All former public `offer_codes_*`, `intro_offers_*`, `promo_offers_*`, and `winback_*` functionality is exposed through `subscriptions_*`.
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_*`.

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.

Expand Down
Loading
Loading