Skip to content

Commit 322295c

Browse files
zelentsov-devzelentsov-dev
committed
merge: develop into main — v2.5.0
2 parents a19b7ed + 3297116 commit 322295c

137 files changed

Lines changed: 13403 additions & 1863 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,5 +24,19 @@ jobs:
2424
- name: Build
2525
run: swift build
2626

27+
- name: Release build
28+
run: swift build -c release 2>&1 | tee /tmp/asc_mcp_release.log
29+
30+
- name: Fail on release warnings
31+
run: '! grep -q "warning:" /tmp/asc_mcp_release.log'
32+
33+
- name: OpenAPI coverage tooling smoke
34+
run: |
35+
swift run asc-mcp openapi-coverage \
36+
--spec Tests/ASCMCPTests/Fixtures/openapi_minimal.oas.json \
37+
--output /tmp/asc_openapi_coverage.md \
38+
--generated-at 2026-05-07
39+
test -s /tmp/asc_openapi_coverage.md
40+
2741
- name: Test
2842
run: swift test

‎.gitignore‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,6 @@ playground.xcworkspace
3737
# Swift Package Manager
3838
.swiftpm
3939
.build/
40-
Package.resolved
4140

4241
# CocoaPods
4342
Pods/

‎AGENTS.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
# AGENTS.md
2+
3+
This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
4+
5+
## Language
6+
Response language: Russian
7+
Comment language: English
8+
9+
## Project Overview
10+
11+
MCP (Model Context Protocol) server for App Store Connect API integration, designed for Codex CLI. This server provides tools to manage iOS/macOS apps through App Store Connect.
12+
13+
## Build and Run Commands
14+
15+
```bash
16+
# Build the project
17+
swift build
18+
19+
# Run all unit tests (436 tests)
20+
swift test
21+
22+
# Run the MCP server (requires environment variables or companies.json)
23+
./.build/debug/asc-mcp
24+
25+
# Run with worker filtering (for clients with tool limits)
26+
./.build/debug/asc-mcp --workers apps,builds,versions,reviews
27+
28+
# Run integration tests
29+
./.build/debug/asc-mcp --test
30+
31+
# Clean build
32+
swift package clean
33+
```
34+
35+
## Environment Configuration
36+
37+
Three config methods (checked in priority order):
38+
1. `--companies /path/to/companies.json` (CLI argument)
39+
2. `ASC_MCP_COMPANIES` env var → path to JSON file
40+
3. Default JSON: `~/.config/asc-mcp/companies.json`
41+
4. `ASC_COMPANY_1_KEY_ID`, `ASC_COMPANY_2_KEY_ID`... (multi-company env vars)
42+
5. `ASC_KEY_ID` + `ASC_ISSUER_ID` + `ASC_PRIVATE_KEY_PATH` (single company env vars)
43+
44+
Each company needs: `keyID`, `issuerID`, `privateKeyPath` (path to `.p8` file).
45+
46+
## Architecture
47+
48+
### Core Components
49+
50+
**WorkerManager** (`Workers/MainWorker/WorkerManager.swift`) — central registry, routes tool calls by prefix.
51+
52+
**Workers** (33 workers, 293 tools):
53+
54+
| Worker | Prefix | Tools | Domain |
55+
|--------|--------|-------|--------|
56+
| CompaniesWorker | `company_` | 3 | Multi-account management |
57+
| AuthWorker | `auth_` | 4 | JWT tokens |
58+
| AppsWorker | `apps_` | 9 | App listing, metadata, localizations |
59+
| BuildsWorker | `builds_` | 4 | Build management |
60+
| BuildBetaDetailsWorker | `builds_*_beta_` | 11 | TestFlight localizations, notifications, beta groups, individual testers |
61+
| BuildProcessingWorker | `builds_*_processing_` | 4 | Build states, encryption |
62+
| AppLifecycleWorker | `app_versions_` | 14 | Versions, submit, release, phased rollout, delete |
63+
| ReviewsWorker | `reviews_` | 8 | Customer reviews, responses, AI summarizations |
64+
| BetaGroupsWorker | `beta_groups_` | 9 | TestFlight groups CRUD, testers, builds |
65+
| InAppPurchasesWorker | `iap_` | 24 | IAP, subscriptions, localizations, prices, screenshots, availability, images |
66+
| ProvisioningWorker | `provisioning_` | 17 | Bundle IDs, devices, certificates, profiles, capabilities |
67+
| BetaTestersWorker | `beta_testers_` | 12 | Tester management, search, invite, relationships, invitations |
68+
| AppInfoWorker | `app_info_` | 10 | App info, categories, localizations, EULA |
69+
| PricingWorker | `pricing_` | 9 | Territories, availability, price points/schedule, app availabilities v2 |
70+
| UsersWorker | `users_` | 10 | Team members, roles, invitations, visible apps |
71+
| AppEventsWorker | `app_events_` | 9 | In-app events CRUD, localizations |
72+
| AnalyticsWorker | `analytics_` | 11 | Sales/financial reports, app summary, analytics reports/instances/segments, snapshot status |
73+
| SubscriptionsWorker | `subscriptions_` | 29 | Subscription CRUD, groups, localizations, prices, submit, group localizations, images, review screenshots |
74+
| OfferCodesWorker | `offer_codes_` | 10 | Subscription offer codes, one-time codes, custom codes |
75+
| WinBackOffersWorker | `winback_` | 5 | Win-back offers for subscriptions |
76+
| IntroductoryOffersWorker | `intro_offers_` | 4 | Introductory offers (free trial, pay-as-you-go, pay-up-front) |
77+
| PromotionalOffersWorker | `promo_offers_` | 6 | Promotional offers for subscriptions |
78+
| SandboxTestersWorker | `sandbox_` | 3 | Sandbox testers (list, update, clear purchase history) |
79+
| BetaAppWorker | `beta_app_` | 10 | Beta app localizations, review submissions, review details |
80+
| PreReleaseVersionsWorker | `pre_release_` | 3 | Pre-release versions (list, get, builds) |
81+
| BetaLicenseAgreementsWorker | `beta_license_` | 3 | Beta license agreements (list, get, update) |
82+
| ScreenshotsWorker | `screenshots_` | 16 | Screenshots, previews, sets, reorder, full upload, batch upload |
83+
| CustomProductPagesWorker | `custom_pages_` | 10 | Custom product pages, versions, localizations |
84+
| ProductPageOptimizationWorker | `ppo_` | 9 | A/B test experiments, treatments |
85+
| PromotedPurchasesWorker | `promoted_` | 9 | Promoted in-app purchases, images upload |
86+
| ReviewAttachmentsWorker | `review_attachments_` | 4 | App Store review attachments (upload, get, delete, list) |
87+
| MetricsWorker | `metrics_` | 4 | Performance/power metrics, diagnostics |
88+
89+
**Services**: HTTPClient (actor, GET/POST/PATCH/PUT/DELETE + retry with 429), JWTService (ES256), CompaniesManager
90+
91+
### Key Implementation Details
92+
93+
1. **Swift 6 Compliance**: All types `Sendable`, proper actor isolation
94+
2. **JWT Auth**: CryptoKit ES256, tokens expire after 20 min
95+
3. **Worker Pattern**: 3 files per worker (Main + ToolDefinitions + Handlers)
96+
4. **Routing**: WorkerManager routes by tool name prefix
97+
5. **Error Handling**: Custom `ASCError` type
98+
99+
## API Constraints
100+
101+
- **No emojis** in metadata fields (What's New, Description, etc.)
102+
- **Version states**:
103+
- `READY_FOR_SALE`: Published, read-only
104+
- `PREPARE_FOR_SUBMISSION`: Editable
105+
- `WAITING_FOR_REVIEW`, `IN_REVIEW`: Read-only
106+
- **Locale codes**: Use standard format (en-US, ru-RU, de-DE, etc.)
107+
108+
## Testing
109+
110+
### Unit Tests (Swift Testing)
111+
112+
```bash
113+
swift test # Run all 436 tests across 31 suites
114+
```
115+
116+
Test categories:
117+
- **Worker tests** (`Tests/ASCMCPTests/Workers/`):
118+
- `WorkerToolDefinitionsTests` — tool count and name correctness per worker
119+
- `WorkerRoutingTests` — unknown tool throws `MCPError.methodNotFound`
120+
- `ParameterValidationTests` — missing required params returns `isError`
121+
- **Model tests** (`Tests/ASCMCPTests/Models/`) — decode, roundtrip, edge cases
122+
- **Service tests** (`Tests/ASCMCPTests/Services/`) — JWT generation
123+
- **Helper tests** (`Tests/ASCMCPTests/HelperTests/`) — JSON formatting, pagination
124+
- **Core tests** (`Tests/ASCMCPTests/Core/`) — ASCError, config models
125+
126+
Test infrastructure: `TestFactory` (`Tests/ASCMCPTests/Helpers/TestHelpers.swift`) — creates mock HTTPClient, JWTService, loads fixtures.
127+
128+
### Integration Test Mode
129+
130+
```bash
131+
./.build/debug/asc-mcp --test # Test company switching
132+
./.build/debug/asc-mcp --test-metadata # Test metadata update
133+
```
134+
135+
## Common Tasks
136+
137+
### Adding New Tool to Existing Worker
138+
139+
1. Implement handler in `Worker+Handlers.swift`
140+
2. Add tool definition in `Worker+ToolDefinitions.swift`
141+
3. Register in worker's `getTools()` array
142+
4. Add case to worker's `handleTool()` switch
143+
5. No changes needed in WorkerManager — it automatically routes by prefix
144+
145+
### Adding New Worker
146+
147+
1. Create directory `Workers/MyWorker/` with 3 files:
148+
- `MyWorker.swift` — class, `getTools()`, `handleTool()` switch
149+
- `MyWorker+ToolDefinitions.swift` — tool schemas
150+
- `MyWorker+Handlers.swift` — handler implementations
151+
2. Create models in `Models/MyDomain/MyModels.swift`
152+
3. Register in `WorkerManager.swift`: property, init, `registerWorkers()` (ListTools + CallTool), `reinitializeWorkers()`, getter method
153+
4. Add worker name to `EntryPoint.swift` → `validWorkers` set
154+
5. Add prefix description to `Application.swift` → server instructions
155+
6. Update tests: `WorkerToolDefinitionsTests`, `WorkerRoutingTests`, `ParameterValidationTests`
156+
157+
### Debugging API Issues
158+
159+
- Check version state (must be PREPARE_FOR_SUBMISSION for edits)
160+
- Verify locale exists for the version
161+
- Remove any emojis from text fields
162+
- Check JWT token expiration (20 minutes)
163+
164+
## Important Files
165+
166+
- `EntryPoint.swift`: Entry point with `--workers` filtering and test modes
167+
- `Core/Application.swift`: MCP server setup and initialization
168+
- `Workers/MainWorker/WorkerManager.swift`: Tool registry and routing
169+
- `Models/`: API response/request models organized by domain:
170+
- `AppStoreConnect/`, `Builds/`, `AppLifecycle/` — apps, versions, builds
171+
- `InAppPurchases/`, `Subscriptions/` — IAP, subscriptions, offer codes, win-back
172+
- `Marketing/` — screenshots, custom pages, PPO experiments, promoted purchases
173+
- `Metrics/`, `Analytics/`, `AppEvents/` — performance, reports, events
174+
- `Provisioning/`, `Pricing/`, `Users/`, `AppInfo/` — provisioning, pricing, users
175+
- `Shared/` — shared types (upload operations, image assets)
176+
- `Services/HTTPClient.swift`: HTTP actor with JWT auth and retry logic
177+
- `Services/CompaniesManager.swift`: Multi-account management
178+
- `Services/JWTService.swift`: ES256 JWT token generation
179+
- `Helpers/`: JSONFormatter, SafeJSONHelpers, PaginationHelper, StderrWriter
180+
181+
## Development Workflow Rules
182+
183+
### Testing Approach
184+
- **ALWAYS test as real MCP**: When testing functionality, use actual MCP commands as if you're a real user working with the server
185+
- Test edge cases and error scenarios
186+
- Verify responses contain all necessary data for practical use
187+
188+
### Development Process
189+
1. **After making changes and building the project:**
190+
- Always respond: "Ready to reload MCP"
191+
- Wait for user confirmation: "reloaded" or similar
192+
- Then proceed with testing via MCP commands
193+
- Fix any issues found during testing
194+
195+
2. **After implementing features:**
196+
- Explain what each method returns
197+
- Describe practical use cases for the returned data
198+
- Example: "The `builds_list` method returns a list of builds with their statuses and dates. This is useful for selecting a build for TestFlight or submitting to the App Store"
199+
200+
### Code Documentation Requirements
201+
- **MANDATORY**: Comment all public methods with:
202+
```swift
203+
/// Brief description of what the method does
204+
/// - Returns: Description of return value and its structure
205+
/// - Throws: What errors can be thrown
206+
```
207+
- Document complex logic inline
208+
- Add usage examples for non-obvious methods

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

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# App Store Connect API Coverage Matrix
2+
3+
Date: 2026-05-05
4+
5+
Source baseline:
6+
- Apple App Store Connect API overview: https://developer.apple.com/documentation/appstoreconnectapi
7+
- Apple API 4.0 release notes: https://developer.apple.com/documentation/appstoreconnectapi/app-store-connect-api-4-0-release-notes
8+
- Apple Webhook notifications: https://developer.apple.com/documentation/appstoreconnectapi/webhook-notifications
9+
10+
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.
11+
Update 2026-05-08: accessibility declaration management is covered by `accessibility_*` tools.
12+
Update 2026-05-08: local webhook receiver helpers are available for signature verification, payload parsing, and event/delivery triage.
13+
14+
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.
15+
16+
## Executive Priority
17+
18+
P0 additions:
19+
- App Clips, background assets, app tags, routing app coverages, and customer review summaries.
20+
21+
P1 additions:
22+
- Hosted webhook receiver templates and reusable triage resources/prompts.
23+
- Merchant IDs and Pass Type IDs under provisioning.
24+
- Analytics/customer-review summarization and metric recommendation ergonomics.
25+
26+
## Area Matrix
27+
28+
| Area | Status | Priority | Current worker keys | Missing / next |
29+
|---|---|---:|---|---|
30+
| Essentials: auth, errors, paging, uploads, rate limits | Partial | P1 | `auth` | API key inventory/revocation helpers |
31+
| App Store app metadata and release operations | Partial | P0 | `apps`, `accessibility`, `versions`, `app_info`, `pricing`, `app_events`, `screenshots`, `custom_pages`, `ppo`, `promoted`, `review_attachments`, `reviews` | App Clips; background assets; app tags; routing app coverages; customer review summary endpoint |
32+
| 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 |
33+
| Webhook notifications | Covered | P2 | `webhooks` | OpenAPI drift checks and hosted receiver examples |
34+
| Webhook notification receiver resources | Partial | P1 | `webhooks` | hosted receiver server templates; prompt/resource templates for event triage |
35+
| In-app purchases, subscriptions, and offers | Covered | P2 | `iap`, `subscriptions`, `offer_codes`, `winback`, `intro_offers`, `promo_offers` | OpenAPI drift checks and schema tightening |
36+
| Provisioning and identifiers | Partial | P1 | `provisioning` | merchant IDs; pass type IDs |
37+
| Users, access, and sandbox testers | Partial | P2 | `users`, `sandbox` | API key inventory helpers; API key revocation workflow |
38+
| Reporting, analytics, metrics, and diagnostics | Partial | P1 | `analytics`, `metrics` | analytics segment discovery ergonomics; customer review summarization; perf power metric recommendations |
39+
| Xcode Cloud workflows and builds | Partial | P1 | `xcode_cloud` | workflow create/update/delete; product delete; relationship-only linkage endpoints |
40+
| Game Center | Missing | P2 | none | Game Center details; leaderboards; achievements; activities; challenges |
41+
| Alternative distribution | Missing | P2 | none | alternative marketplace and web distribution workflows |
42+
43+
## Implementation Order
44+
45+
1. Add `--read-only` runtime guard so static and live validation can run safely in production-like MCP hosts.
46+
2. Update `AppsWorker` for app-level `accessibilityUrl` if Apple keeps it as a separate app metadata field outside declaration resources.
47+
3. Add reusable webhook receiver playbooks and optional hosted receiver templates around the new local helper tools.
48+
4. Add merchant/pass identifiers, App Clips, background assets, Game Center, and alternative distribution as larger domain workers.
49+
50+
## Safety Notes
51+
52+
- Mutation tools must remain statically reviewable without live App Store Connect calls.
53+
- All new write tools should carry MCP annotations with `readOnlyHint = false`; destructive operations should carry `destructiveHint = true`.
54+
- Live validation should stay read-only unless a user explicitly provides a sandbox-like target and confirms the exact mutation.
55+
- Region- or entitlement-sensitive domains, especially alternative distribution, should be opt-in and clearly documented.

‎ASC-OPENAPI-COVERAGE-GENERATED.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# App Store Connect OpenAPI Coverage
2+
3+
Generated: 2026-05-08
4+
5+
Sources:
6+
- Apple App Store Connect API overview: https://developer.apple.com/app-store-connect/api/
7+
- Apple App Store Connect API documentation: https://developer.apple.com/documentation/appstoreconnectapi
8+
- Apple OpenAPI specification download: https://developer.apple.com/sample-code/app-store-connect/app-store-connect-openapi-specification.zip
9+
- Apple App Store Connect API 4.3 release: https://developer.apple.com/news/releases/?id=03102026b
10+
11+
Spec: App Store Connect API 4.3 (OpenAPI 3.0.1)
12+
Apple paths: 923
13+
Apple operations: 1208
14+
Classified paths: 923
15+
Unclassified paths: 0
16+
17+
## Priority Gaps
18+
19+
- P0 App Store app metadata and release operations: Partial, 303 Apple paths, 380 operations.
20+
- P0 TestFlight builds, testers, groups, and beta app review: Partial, 115 Apple paths, 154 operations.
21+
- P1 Provisioning and identifiers: Partial, 32 Apple paths, 49 operations.
22+
- P1 Reporting, analytics, metrics, and diagnostics: Partial, 47 Apple paths, 56 operations.
23+
- P1 Xcode Cloud workflows and builds: Partial, 56 Apple paths, 59 operations.
24+
25+
## Domain Matrix
26+
27+
| Domain | Status | Priority | Apple paths | Operations | Workers | Notes |
28+
|---|---|---:|---:|---:|---|---|
29+
| App Store app metadata and release operations | Partial | P0 | 303 | 380 | `apps`, `accessibility`, `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. |
30+
| 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. |
31+
| 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. |
32+
| Provisioning and identifiers | Partial | P1 | 32 | 49 | `provisioning` | Core signing automation exists; Wallet and Apple Pay identifiers are useful next additions. |
33+
| 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. |
34+
| Webhook notification receiver resources | Partial | P1 | 0 | 0 | `webhooks` | Local receiver helpers are now available and remain read-only; future work can add deployable receiver templates and reusable playbooks. |
35+
| 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. |
36+
| Alternative distribution | Missing | P2 | 21 | 28 | none | Region- and entitlement-sensitive APIs should be opt-in and strongly documented. |
37+
| Game Center | Missing | P2 | 238 | 337 | none | Large domain; should be added only after OpenAPI-driven scaffolding is in place. |
38+
| 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. |
39+
| 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. |
40+
| 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. |
41+
42+
## Missing Apple Domains
43+
44+
- Alternative distribution: 21 paths, 28 operations.
45+
- Game Center: 238 paths, 337 operations.
46+
47+
## Unclassified Apple Paths
48+
49+
All Apple paths matched at least one maintained coverage rule.
50+
51+
## How To Regenerate
52+
53+
```bash
54+
rm -rf /tmp/asc-openapi
55+
mkdir -p /tmp/asc-openapi
56+
curl -L --fail -o /tmp/asc-openapi/spec.zip https://developer.apple.com/sample-code/app-store-connect/app-store-connect-openapi-specification.zip
57+
unzip -q /tmp/asc-openapi/spec.zip -d /tmp/asc-openapi
58+
swift run asc-mcp openapi-coverage --spec /tmp/asc-openapi/openapi.oas.json --output ASC-OPENAPI-COVERAGE-GENERATED.md
59+
```

0 commit comments

Comments
 (0)