Skip to content

Commit 72eed62

Browse files
zelentsov-devzelentsov-dev
committed
feat: App Store Connect MCP Server v1.0.0
109 tools across 17 workers for App Store Connect API. Multi-account support, JWT auth, pagination, worker filtering. Swift 6.1, macOS 14+, 296 unit tests.
0 parents  commit 72eed62

149 files changed

Lines changed: 23957 additions & 0 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: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main, develop]
6+
tags: ['*']
7+
pull_request:
8+
branches: [main, develop]
9+
10+
concurrency:
11+
group: ${{ github.workflow }}-${{ github.ref }}
12+
cancel-in-progress: true
13+
14+
jobs:
15+
build-and-test:
16+
name: Build & Test
17+
runs-on: macos-15
18+
steps:
19+
- uses: actions/checkout@v4
20+
21+
- name: Select Xcode
22+
run: sudo xcode-select -s /Applications/Xcode_26.2.app
23+
24+
- name: Build
25+
run: swift build
26+
27+
- name: Test
28+
run: swift test

‎.gitignore‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Xcode
2+
#
3+
# gitignore contributors: remember to update Global/Xcode.gitignore, Objective-C.gitignore & Swift.gitignore
4+
5+
## User settings
6+
xcuserdata/
7+
8+
## compatibility with Xcode 8 and earlier (ignoring not required starting Xcode 9)
9+
*.xcscmblueprint
10+
*.xccheckout
11+
12+
## compatibility with Xcode 3 and earlier (ignoring not required starting Xcode 4)
13+
build/
14+
DerivedData/
15+
*.moved-aside
16+
*.pbxuser
17+
!default.pbxuser
18+
*.mode1v3
19+
!default.mode1v3
20+
*.mode2v3
21+
!default.mode2v3
22+
*.perspectivev3
23+
!default.perspectivev3
24+
25+
## Obj-C/Swift specific
26+
*.hmap
27+
28+
## App packaging
29+
*.ipa
30+
*.dSYM.zip
31+
*.dSYM
32+
33+
## Playgrounds
34+
timeline.xctimeline
35+
playground.xcworkspace
36+
37+
# Swift Package Manager
38+
.swiftpm
39+
.build/
40+
Package.resolved
41+
42+
# CocoaPods
43+
Pods/
44+
45+
# Carthage
46+
Carthage/Build/
47+
48+
# Accio dependency management
49+
Dependencies/
50+
.accio/
51+
52+
# fastlane
53+
fastlane/report.xml
54+
fastlane/Preview.html
55+
fastlane/screenshots/**/*.png
56+
fastlane/test_output
57+
58+
# Code Injection
59+
iOSInjectionProject/
60+
61+
# Configuration files with sensitive data
62+
companies.json
63+
.env
64+
.env.local
65+
.env.*.local
66+
67+
# App Store Connect Keys
68+
*.p8
69+
*.pem
70+
*.key
71+
AuthKey_*.p8
72+
companies.*.json
73+
74+
# XcodeBuildMCP
75+
.xcodebuildmcp/
76+
77+
# macOS
78+
.DS_Store
79+
.AppleDouble
80+
.LSOverride
81+
82+
# Thumbnails
83+
._*
84+
85+
# Files that might appear in the root of a volume
86+
.DocumentRevisions-V100
87+
.fseventsd
88+
.Spotlight-V100
89+
.TemporaryItems
90+
.Trashes
91+
.VolumeIcon.icns
92+
.com.apple.timemachine.donotpresent
93+
94+
# Directories potentially created on remote AFP share
95+
.AppleDB
96+
.AppleDesktop
97+
Network Trash Folder
98+
Temporary Items
99+
.apdisk
100+
101+
# Test files
102+
test_input.json
103+
test_output.json
104+
*.test.json
105+
test_main.swift
106+
107+
# IDE
108+
.vscode/
109+
.idea/
110+
*.swp
111+
*.swo
112+
*~
113+
114+
# Claude settings
115+
.claude/
116+
117+
# Debug
118+
*.log
119+
debug/
120+
logs/
121+
122+
# Other
123+
.netrc
124+
Packages/

‎CHANGELOG.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [1.0.0] - 2025-02-17
9+
10+
### Added
11+
12+
- **17 workers** with ~109 tools covering the full App Store Connect API
13+
- **Multi-account support** via `companies.json` configuration
14+
- **Worker filtering** with `--workers` flag for tool-limited MCP clients
15+
- **JWT authentication** with ES256 signing and automatic 20-minute refresh
16+
- **HTTP client** as actor with retry logic, 429 rate-limit handling, and idempotent request support
17+
- **Pagination** helper for traversing large API result sets
18+
19+
#### Workers
20+
21+
- **CompaniesWorker** (3 tools) — multi-account management, switching, listing
22+
- **AuthWorker** (4 tools) — JWT token generation, validation, refresh
23+
- **AppsWorker** (9 tools) — app listing, metadata, localized descriptions, keywords
24+
- **BuildsWorker** (4 tools) — build listing, details, individual build info
25+
- **BuildBetaDetailsWorker** (9 tools) — TestFlight localizations, beta groups, notifications
26+
- **BuildProcessingWorker** (5 tools) — build states, encryption declarations
27+
- **AppLifecycleWorker** (12 tools) — version create/submit/release, phased rollout
28+
- **ReviewsWorker** (8 tools) — customer reviews, responses, statistics
29+
- **BetaGroupsWorker** (9 tools) — TestFlight groups CRUD, testers, builds
30+
- **BetaTestersWorker** (6 tools) — tester management, search, invite
31+
- **InAppPurchasesWorker** (12 tools) — IAP and subscriptions CRUD, localizations, submit
32+
- **ProvisioningWorker** (17 tools) — bundle IDs, devices, certificates, profiles, capabilities
33+
- **AppInfoWorker** (6 tools) — app info, categories, age rating, localizations
34+
- **PricingWorker** (6 tools) — territories, availability, price points and schedules
35+
- **UsersWorker** (6 tools) — team members, roles, invitations
36+
- **AppEventsWorker** (6 tools) — in-app events CRUD, localizations
37+
- **AnalyticsWorker** (4 tools) — sales reports, financial reports, analytics
38+
39+
### Security
40+
41+
- SSRF protection for pagination URL validation
42+
- Sensitive credential masking in MCP responses
43+
- HTTPS-only communication with App Store Connect API
44+
- JWT tokens held in memory only, never persisted
45+
46+
### Testing
47+
48+
- 295+ unit tests using Swift Testing framework
49+
- Test fixtures with placeholder credentials (no real keys)

‎CLAUDE.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.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 Claude Code 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 the MCP server (requires environment variables)
20+
./.build/debug/asc-mcp
21+
22+
# Run tests/debug mode
23+
./.build/debug/asc-mcp --test
24+
25+
# Clean build
26+
swift package clean
27+
```
28+
29+
## Environment Configuration
30+
31+
Uses `companies.json` for multi-account configuration. Each company entry contains `keyID`, `issuerID`, and `privateKeyPath`.
32+
33+
## Architecture
34+
35+
### Core Components
36+
37+
**WorkerManager** (`Workers/MainWorker/WorkerManager.swift`) — central registry, routes tool calls by prefix.
38+
39+
**Workers** (17 workers, ~109 tools):
40+
41+
| Worker | Prefix | Tools | Domain |
42+
|--------|--------|-------|--------|
43+
| CompaniesWorker | `company_` | 3 | Multi-account management |
44+
| AuthWorker | `auth_` | 4 | JWT tokens |
45+
| AppsWorker | `apps_` | 9 | App listing, metadata, localizations, create/delete localization |
46+
| BuildsWorker | `builds_` | 4 | Build management |
47+
| BuildBetaDetailsWorker | `builds_*_beta_` | 9 | TestFlight localizations, notifications, beta groups |
48+
| BuildProcessingWorker | `builds_*_processing_` | 5 | Build states, encryption |
49+
| AppLifecycleWorker | `app_versions_` | 12 | Versions, submit, release, phased rollout |
50+
| ReviewsWorker | `reviews_` | 8 | Customer reviews and responses |
51+
| BetaGroupsWorker | `beta_groups_` | 9 | TestFlight groups CRUD, testers, builds |
52+
| InAppPurchasesWorker | `iap_` | 12 | IAP, subscriptions, localizations CRUD, submit |
53+
| ProvisioningWorker | `provisioning_` | 17 | Bundle IDs, devices, certificates, profiles, capabilities |
54+
| BetaTestersWorker | `beta_testers_` | 6 | Tester management, search, invite |
55+
| AppInfoWorker | `app_info_` | 6 | App info, categories, localizations |
56+
| PricingWorker | `pricing_` | 6 | Territories, availability, price points/schedule |
57+
| UsersWorker | `users_` | 6 | Team members, roles, invitations |
58+
| AppEventsWorker | `app_events_` | 6 | In-app events CRUD, localizations |
59+
| AnalyticsWorker | `analytics_` | 4 | Sales/financial reports, analytics requests |
60+
61+
**Services**: HTTPClient (actor, GET/POST/PATCH/PUT/DELETE + retry with 429), JWTService (ES256)
62+
63+
### Key Implementation Details
64+
65+
1. **Swift 6 Compliance**: All types `Sendable`, proper actor isolation
66+
2. **JWT Auth**: CryptoKit ES256, tokens expire after 20 min
67+
3. **Worker Pattern**: 3 files per worker (Main + ToolDefinitions + Handlers)
68+
4. **Routing**: WorkerManager routes by tool name prefix
69+
5. **Error Handling**: Custom `ASCError` type
70+
71+
## API Constraints
72+
73+
- **No emojis** in metadata fields (What's New, Description, etc.)
74+
- **Version states**:
75+
- `READY_FOR_SALE`: Published, read-only
76+
- `PREPARE_FOR_SUBMISSION`: Editable
77+
- `WAITING_FOR_REVIEW`, `IN_REVIEW`: Read-only
78+
- **Locale codes**: Use standard format (en-US, ru-RU, de-DE, etc.)
79+
80+
## Testing
81+
82+
Test mode (`--test` flag) performs:
83+
1. Lists app versions to find editable one
84+
2. If found, updates What's New field
85+
3. Verifies the update succeeded
86+
87+
## Common Tasks
88+
89+
### Adding New Tool
90+
91+
1. Implement method in appropriate Worker (e.g., `AppsWorker+Handlers.swift`)
92+
2. Add tool definition method in Worker's tool definitions file (e.g., `AppsWorker+ToolDefinitions.swift`)
93+
3. Register the tool in Worker's `getTools()` method
94+
4. Add case to Worker's `handleTool()` switch
95+
5. No changes needed in WorkerManager - it automatically routes by prefix
96+
97+
### Debugging API Issues
98+
99+
- Check version state (must be PREPARE_FOR_SUBMISSION for edits)
100+
- Verify locale exists for the version
101+
- Remove any emojis from text fields
102+
- Check JWT token expiration (20 minutes)
103+
104+
## Important Files
105+
106+
- `main.swift`: Entry point with test mode
107+
- `Workers/MainWorker/WorkerManager.swift`: Tool registry and routing
108+
- `Models/`: API response/request models (AppStoreConnect, Builds, InAppPurchases, Provisioning)
109+
- `Services/HTTPClient.swift`: HTTP actor with JWT auth and retry logic
110+
111+
## Development Workflow Rules
112+
113+
### Testing Approach
114+
- **ALWAYS test as real MCP**: When testing functionality, use actual MCP commands as if you're a real user working with the server
115+
- Test edge cases and error scenarios
116+
- Verify responses contain all necessary data for practical use
117+
118+
### Development Process
119+
1. **After making changes and building the project:**
120+
- Always respond: "✅ Готово к перезагрузке MCP"
121+
- Wait for user confirmation: "я перезагрузил" or similar
122+
- Then proceed with testing via MCP commands
123+
- Fix any issues found during testing
124+
125+
2. **After implementing features:**
126+
- Explain what each method returns
127+
- Describe practical use cases for the returned data
128+
- Example: "Метод `builds_list` возвращает список билдов с их статусами и датами. Это нужно для выбора билда для TestFlight или отправки в App Store"
129+
130+
### Code Documentation Requirements
131+
- **MANDATORY**: Comment all public methods with:
132+
```swift
133+
/// Brief description of what the method does
134+
/// - Returns: Description of return value and its structure
135+
/// - Throws: What errors can be thrown
136+
```
137+
- Document complex logic inline
138+
- Add usage examples for non-obvious methods

0 commit comments

Comments
 (0)