feat: add ASC OpenAPI coverage tooling

Author: zelentsov-dev

.github/workflows/ci.yml

@@ -30,5 +30,13 @@ jobs:
       - name: Fail on release warnings
         run: '! grep -q "warning:" /tmp/asc_mcp_release.log'
 
+      - name: OpenAPI coverage tooling smoke
+        run: |
+          swift run asc-mcp openapi-coverage \
+            --spec Tests/ASCMCPTests/Fixtures/openapi_minimal.oas.json \
+            --output /tmp/asc_openapi_coverage.md \
+            --generated-at 2026-05-07
+          test -s /tmp/asc_openapi_coverage.md
+
       - name: Test
         run: swift test

ASC-COVERAGE-MATRIX-2026-05-05.md

@@ -7,6 +7,8 @@ Source baseline:
 - Apple API 4.0 release notes: https://developer.apple.com/documentation/appstoreconnectapi/app-store-connect-api-4-0-release-notes
 - Apple Webhook notifications: https://developer.apple.com/documentation/appstoreconnectapi/webhook-notifications
 
+Update 2026-05-07: automated OpenAPI coverage tooling is now available. See `ASC-OPENAPI-COVERAGE-GENERATED.md` for the generated Apple 4.3 path/operation matrix.
+
 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.
 
 ## Executive Priority
@@ -15,7 +17,6 @@ P0 additions:
 - Accessibility declarations, App Clips, background assets, app tags, routing app coverages, and customer review summaries.
 
 P1 additions:
-- Automated OpenAPI spec diff against `app-store-connect-openapi-specification.zip`.
 - Webhook receiver-side signature verification, event payload decoder, and triage resources/prompts.
 - Merchant IDs and Pass Type IDs under provisioning.
 - Analytics/customer-review summarization and metric recommendation ergonomics.
@@ -24,7 +25,7 @@ P1 additions:
 
 | Area | Status | Priority | Current worker keys | Missing / next |
 |---|---|---:|---|---|
-| Essentials: auth, errors, paging, uploads, rate limits | Partial | P1 | `auth` | OpenAPI spec diff; API key inventory/revocation helpers |
+| Essentials: auth, errors, paging, uploads, rate limits | Partial | P1 | `auth` | API key inventory/revocation helpers |
 | App Store app metadata and release operations | Partial | P0 | `apps`, `versions`, `app_info`, `pricing`, `app_events`, `screenshots`, `custom_pages`, `ppo`, `promoted`, `review_attachments`, `reviews` | accessibility declarations; App Clips; background assets; app tags; routing app coverages; customer review summary endpoint |
 | TestFlight builds, testers, groups, and beta app review | Partial | P0 | `builds`, `build_processing`, `build_beta`, `beta_groups`, `beta_feedback`, `beta_testers`, `beta_app`, `pre_release`, `beta_license` | beta recruitment criteria; beta app clip invocation/localization APIs |
 | Webhook notifications | Covered | P2 | `webhooks` | OpenAPI drift checks and receiver-side helper ergonomics |
@@ -41,9 +42,8 @@ P1 additions:
 
 1. Add `--read-only` runtime guard so static and live validation can run safely in production-like MCP hosts.
 2. Add `AccessibilityWorker` and update `AppsWorker` for `accessibilityUrl`: this closes a new compliance-oriented App Store gap.
-3. Add OpenAPI drift tooling so future Apple release-note changes become visible before users report missing methods.
-4. Add webhook receiver helpers: signature verification, event payload decoder, and triage prompts/resources.
-5. Add merchant/pass identifiers, App Clips, background assets, Game Center, and alternative distribution as larger domain workers.
+3. Add webhook receiver helpers: signature verification, event payload decoder, and triage prompts/resources.
+4. Add merchant/pass identifiers, App Clips, background assets, Game Center, and alternative distribution as larger domain workers.
 
 ## Safety Notes
 

ASC-OPENAPI-COVERAGE-GENERATED.md

@@ -0,0 +1,59 @@
+# App Store Connect OpenAPI Coverage
+
+Generated: 2026-05-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
+- Apple App Store Connect API 4.3 release: https://developer.apple.com/news/releases/?id=03102026b
+
+Spec: App Store Connect API 4.3 (OpenAPI 3.0.1)
+Apple paths: 923
+Apple operations: 1208
+Classified paths: 923
+Unclassified paths: 0
+
+## Priority Gaps
+
+- P0 App Store app metadata and release operations: Partial, 303 Apple paths, 380 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.
+- P1 Xcode Cloud workflows and builds: Partial, 56 Apple paths, 59 operations.
+
+## Domain Matrix
+
+| Domain | Status | Priority | Apple paths | Operations | Workers | Notes |
+|---|---|---:|---:|---:|---|---|
+| App Store app metadata and release operations | Partial | P0 | 303 | 380 | `apps`, `versions`, `app_info`, `pricing`, `app_events`, `screenshots`, `custom_pages`, `ppo`, `promoted`, `review_attachments`, `reviews` | The common release workflow is strong; API 4.0 app-surface additions are the highest App Store coverage gap. |
+| TestFlight builds, testers, groups, and beta app review | Partial | P0 | 115 | 154 | `builds`, `build_processing`, `build_beta`, `beta_groups`, `beta_feedback`, `beta_testers`, `beta_app`, `pre_release`, `beta_license` | Current TestFlight management is useful, but feedback retrieval is now core user value and should become a dedicated worker. |
+| 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. |
+| Reporting, analytics, metrics, and diagnostics | Partial | P1 | 47 | 56 | `analytics`, `metrics` | Read-heavy workflows are safe and valuable; summaries and recommendations are high UX leverage. |
+| Webhook notification receiver resources | Missing | P1 | 0 | 0 | none | The App Store Connect management API is covered; receiver-side helpers are local MCP value-add and should not call Apple. |
+| 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 | 238 | 337 | none | Large domain; should be added only after OpenAPI-driven scaffolding is in place. |
+| In-app purchases, subscriptions, and offers | Covered | P2 | 129 | 163 | `iap`, `subscriptions`, `offer_codes`, `winback`, `intro_offers`, `promo_offers` | Coverage is broad enough for production workflows; future work is mostly schema tightening and OpenAPI drift checks. |
+| 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, and ping testing. |
+
+## Missing Apple Domains
+
+- Alternative distribution: 21 paths, 28 operations.
+- Game Center: 238 paths, 337 operations.
+
+## Unclassified Apple Paths
+
+All Apple paths matched at least one maintained coverage rule.
+
+## How To Regenerate
+
+```bash
+rm -rf /tmp/asc-openapi
+mkdir -p /tmp/asc-openapi
+curl -L --fail -o /tmp/asc-openapi/spec.zip https://developer.apple.com/sample-code/app-store-connect/app-store-connect-openapi-specification.zip
+unzip -q /tmp/asc-openapi/spec.zip -d /tmp/asc-openapi
+swift run asc-mcp openapi-coverage --spec /tmp/asc-openapi/openapi.oas.json --output ASC-OPENAPI-COVERAGE-GENERATED.md
+```

CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- OpenAPI coverage tooling via `asc-mcp openapi-coverage`, using Apple's official App Store Connect OpenAPI JSON without loading ASC credentials or starting the MCP server.
+- Generated `ASC-OPENAPI-COVERAGE-GENERATED.md` report for Apple App Store Connect API 4.3 with domain-level path/operation counts and drift triage.
+
+### Changed
+
+- CI now smoke-tests the OpenAPI coverage command against a local fixture.
+- Coverage inventory now marks automated OpenAPI drift reporting as implemented.
+
 ## [2.1.0] - 2026-05-05
 
 ### Added

README.md

@@ -45,6 +45,7 @@
 - **Analytics & Metrics** — sales/financial reports, analytics reports, performance metrics, diagnostics
 - **Metadata management** — localized descriptions, keywords, What's New across all locales
 - **MCP 2025-11-25 surface** — tool annotations, output schemas for stable tools, structured JSON results, and safe result-size metadata
+- **OpenAPI drift tooling** — generate coverage reports from Apple's official App Store Connect OpenAPI specification
 
 ## Quick Start
 
@@ -397,6 +398,24 @@ asc-mcp --read-only --workers apps,builds,reviews,analytics
 
 In this mode, read tools such as `*_list`, `*_get`, `*_search`, `*_status`, `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.
 
+### OpenAPI Drift Tooling
+
+Use the built-in OpenAPI coverage command to compare the maintained `asc-mcp` coverage map with Apple's latest App Store Connect OpenAPI specification. This command does **not** load App Store Connect credentials, does **not** start the MCP server, and does **not** call Apple APIs beyond your explicit spec download.
+
+```bash
+rm -rf /tmp/asc-openapi
+mkdir -p /tmp/asc-openapi
+curl -L --fail -o /tmp/asc-openapi/spec.zip \
+  https://developer.apple.com/sample-code/app-store-connect/app-store-connect-openapi-specification.zip
+unzip -q /tmp/asc-openapi/spec.zip -d /tmp/asc-openapi
+
+swift run asc-mcp openapi-coverage \
+  --spec /tmp/asc-openapi/openapi.oas.json \
+  --output ASC-OPENAPI-COVERAGE-GENERATED.md
+```
+
+The generated report records Apple spec metadata, path and operation counts, domain status, P0/P1 gaps, missing domains, and unclassified paths. The current checked-in report is [`ASC-OPENAPI-COVERAGE-GENERATED.md`](ASC-OPENAPI-COVERAGE-GENERATED.md), generated from App Store Connect API 4.3.
+
 **Available worker names:**
 
 | Worker | Prefix | Tools | Description |

Sources/asc-mcp/Core/ASCCoverageInventory.swift

@@ -53,13 +53,13 @@ enum ASCCoverageInventory {
                 "Apple API error decoding",
                 "pagination helpers",
                 "bounded upload flow",
-                "rate-limit metadata capture"
+                "rate-limit metadata capture",
+                "automated OpenAPI spec coverage report generation"
             ],
             missingCapabilities: [
-                "automated OpenAPI spec diff against app-store-connect-openapi-specification.zip",
                 "first-class API key revocation/read inventory helpers"
             ],
-            notes: "Core runtime behavior is covered, but release-time API drift detection still needs an automated spec diff."
+            notes: "Core runtime behavior is covered; OpenAPI drift is now generated from Apple's official specification."
         ),
         ASCCoverageArea(
             name: "App Store app metadata and release operations",

Sources/asc-mcp/EntryPoint.swift

@@ -4,6 +4,15 @@ import MCP
 @main
 struct ASCMCPApp {
     static func main() async throws {
+        do {
+            if try ASCOpenAPICoverageCommand.runIfRequested(arguments: CommandLine.arguments) {
+                return
+            }
+        } catch {
+            print("OpenAPI coverage error: \(error.localizedDescription)", to: &standardError)
+            exit(1)
+        }
+
         #if DEBUG
         if CommandLine.arguments.contains("--test") {
             print("Test mode activated", to: &standardError)