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
45 changes: 40 additions & 5 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,8 @@ permissions:
contents: read

concurrency:
group: ${{ github.workflow }}-${{ (github.event_name == 'pull_request' || github.ref == 'refs/heads/develop') && github.ref || github.run_id }}
cancel-in-progress: ${{ github.event_name == 'pull_request' || github.ref == 'refs/heads/develop' }}
group: ${{ github.workflow }}-${{ (github.event_name == 'pull_request' || (github.event_name == 'push' && (github.ref == 'refs/heads/develop' || github.ref == 'refs/heads/main'))) && (github.event.pull_request.number || github.ref) || github.run_id }}
cancel-in-progress: ${{ github.event_name == 'pull_request' || (github.event_name == 'push' && (github.ref == 'refs/heads/develop' || github.ref == 'refs/heads/main')) }}

jobs:
promotion-lineage:
Expand Down Expand Up @@ -132,6 +132,7 @@ jobs:

tests:
name: Tests
if: github.event_name != 'schedule'
needs: promotion-lineage
runs-on: macos-15
timeout-minutes: 20
Expand All @@ -145,6 +146,17 @@ jobs:
- name: Select Xcode
run: sudo xcode-select -s /Applications/Xcode_26.2.app

- name: Cache SwiftPM test build
uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.2.3
with:
path: |
~/Library/Caches/org.swift.swiftpm
~/.swiftpm
.build
key: swiftpm-tests-${{ runner.os }}-xcode26.2-${{ hashFiles('Package.swift', 'Package.resolved') }}-${{ hashFiles('Sources/**', 'Tests/**') }}
restore-keys: |
swiftpm-tests-${{ runner.os }}-xcode26.2-${{ hashFiles('Package.swift', 'Package.resolved') }}-

- name: Run tests
shell: bash
run: |
Expand Down Expand Up @@ -189,6 +201,7 @@ jobs:

release-contract:
name: Release & Apple Contract
if: github.event_name != 'schedule'
needs: promotion-lineage
runs-on: macos-15
timeout-minutes: 20
Expand All @@ -202,6 +215,17 @@ jobs:
- name: Select Xcode
run: sudo xcode-select -s /Applications/Xcode_26.2.app

- name: Cache SwiftPM release build
uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.2.3
with:
path: |
~/Library/Caches/org.swift.swiftpm
~/.swiftpm
.build
key: swiftpm-release-${{ runner.os }}-xcode26.2-${{ hashFiles('Package.swift', 'Package.resolved') }}-${{ hashFiles('Sources/**') }}
restore-keys: |
swiftpm-release-${{ runner.os }}-xcode26.2-${{ hashFiles('Package.swift', 'Package.resolved') }}-

- name: Build release binary
shell: bash
run: |
Expand Down Expand Up @@ -240,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 @@ -340,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 Expand Up @@ -389,11 +413,22 @@ jobs:
- name: Select Xcode
run: sudo xcode-select -s /Applications/Xcode_26.2.app

- name: Cache Mint and SwiftPM packages
uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.2.3
with:
path: |
~/Library/Caches/org.swift.swiftpm
~/.swiftpm
~/.mint
key: mint-swiftpm-${{ runner.os }}-xcode26.2-${{ hashFiles('Package.swift', 'Package.resolved') }}-${{ hashFiles('Sources/**') }}
restore-keys: |
mint-swiftpm-${{ runner.os }}-xcode26.2-${{ hashFiles('Package.swift', 'Package.resolved') }}-

- name: Install tagged release through Mint
shell: bash
run: |
set -euo pipefail
brew install mint
command -v mint >/dev/null 2>&1 || brew install mint
mint install "zelentsov-dev/asc-mcp@$GITHUB_REF_NAME" --force

- name: Run installed MCP smoke
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/scripts/assets_mcp_smoke.py
Original file line number Diff line number Diff line change
Expand Up @@ -642,7 +642,7 @@ def start(workers: str = "assets,review_submissions", read_only: bool = False) -
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--binary", required=True, help="Previously built candidate asc-mcp executable")
parser.add_argument("--expected-version", default="4.2.0")
parser.add_argument("--expected-version", default="4.3.0")
arguments = parser.parse_args()
try:
report = run(arguments)
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
19 changes: 19 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

## [4.3.0] - 2026-11-07

### 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 multi-page 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).

### Fixed

- Preserve `include=territory,subscriptionPricePoint` and related `fields[...]` projections across initial and continuation requests in `subscriptions_list_retention_offer_prices`, and bind all 6 retention list handlers to `HTTPClient.getPage` with `PaginationScope` validation.
- Allow Plane 2 CJK Unified Ideographs Extension B+ characters (such as `𠮷` `U+20BB7`) in metadata and retention copy validation while rejecting single and compound emoji sequences (`U+FE0F`, `U+20E3`).
- Route `JWTService` debug token diagnostics to `stderr` so debug builds preserve a clean JSON-RPC `stdout` stream.

### Compatibility

- Preserve all 514 existing tool names and 36 `--workers` filter keys; the complete catalog now has 537 tools.

## [4.2.0] - 2026-10-19

### Added
Expand Down
Loading
Loading