# App Store Connect MCP Server

App Store Connect API 기반 MCP 서버입니다.

기능 범위:
- 앱 등록 (`register_app`)
- 앱 목록 조회 (`list_apps`)
- IPA 업로드/배포 (`deploy_app_bundle`)
- 스토어 등록정보(버전 로컬라이제이션) 업데이트 (`update_store_listing`)
- 인앱 상품 등록 (`create_in_app_purchase`)

## Requirements

- Python 3.10+
- Xcode Command Line Tools (`xcrun`) for IPA upload
- App Store Connect API Key (`.p8`, Key ID, Issuer ID)

## Install

```bash
cd app-store-mcp
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
```

## Configure

```bash
cd app-store-mcp
cp .env.example .env
```

필수 환경 변수:
- `APP_STORE_KEY_ID`
- `APP_STORE_ISSUER_ID`
- `APP_STORE_PRIVATE_KEY_PATH` 또는 `APP_STORE_PRIVATE_KEY`

선택 정책 환경 변수(권장):
- `ALLOWED_APP_SKU`
- `ALLOWED_BUNDLE_ID`

정책 변수가 설정되면:
- 쓰기 툴은 `app_id`를 반드시 요구합니다.
- 대상 `app_id`의 SKU/Bundle ID가 정책과 다르면 요청을 차단합니다.
- `list_apps`는 정책에 맞는 앱만 반환합니다.

## Run

```bash
cd app-store-mcp
. .venv/bin/activate
python server.py
```

또는

```bash
cd app-store-mcp
npm start
```

## MCP Configuration Example

```json
{
  "mcpServers": {
    "app-store": {
      "command": "python3",
      "args": ["server.py"],
      "cwd": "/Users/<you>/Foreign-Language-Battle/app-store-mcp",
      "env": {
        "APP_STORE_KEY_ID": "YOUR_KEY_ID",
        "APP_STORE_ISSUER_ID": "YOUR_ISSUER_ID",
        "APP_STORE_PRIVATE_KEY_PATH": "/absolute/path/to/AuthKey_XXXXXX.p8"
      }
    }
  }
}
```

## Tool Reference

### `register_app`
Create app record in App Store Connect.

Inputs:
- `name`
- `bundle_id`
- `sku`
- `primary_locale` (default: `en-US`)

### `list_apps`
List apps with optional bundle ID filter and sort.

Inputs:
- `limit` (default: `50`, max: `200`)
- `bundle_id` (optional, exact match)
- `sort` (default: `-createdDate`)

Notes:
- `ALLOWED_BUNDLE_ID`가 설정된 경우, 다른 `bundle_id`로 조회하면 차단됩니다.
- `ALLOWED_APP_SKU`가 설정된 경우, 결과는 해당 SKU 앱으로 제한됩니다.

### `deploy_app_bundle`
Upload IPA via `xcrun altool` and optionally link latest processed build.

Inputs:
- `ipa_path`
- `app_id` (optional)
- `version_string` (optional)
- `platform` (default: `IOS`)

Notes:
- 빌드 처리는 비동기라 업로드 직후에는 링크 대상 build가 아직 안 잡힐 수 있습니다.
- 정책 변수(`ALLOWED_APP_SKU`/`ALLOWED_BUNDLE_ID`)가 설정된 경우 `app_id`가 필수입니다.

### `update_store_listing`
Update `appStoreVersionLocalization` metadata.

Inputs:
- `app_id`
- `locale`
- `version_string` (optional; 미지정 시 편집 가능한 최신 버전 사용)
- `description`
- `keywords`
- `promotional_text`
- `support_url`
- `marketing_url`
- `whats_new`

Notes:
- 정책 변수(`ALLOWED_APP_SKU`/`ALLOWED_BUNDLE_ID`)가 설정된 경우 `app_id`가 필수입니다.

Locale 코드 가이드:
- `locale` 값은 "국가 코드 추정값"이 아니라 App Store Connect에 등록된
  정확한 localization 코드를 사용해야 합니다.
- 같은 언어라도 코드가 다를 수 있습니다.
  - English (US): `en-US`
  - English (UK): `en-GB`
  - Korean: `ko` (일부 화면에 `ko-KR`로 보이더라도 API 코드는 `ko`)
- 잘못된 코드를 넣으면 아래 오류가 발생할 수 있습니다.
  - `The language specified is not listed for localization`

실전 예시:

```json
{
  "app_id": "6759354785",
  "locale": "en-US",
  "version_string": "1.0",
  "description": "Updated description",
  "keywords": "language,learning,study",
  "promotional_text": "Build language skills daily."
}
```

```json
{
  "app_id": "6759354785",
  "locale": "ko",
  "version_string": "1.0",
  "description": "업데이트된 설명",
  "keywords": "외국어,학습,회화",
  "promotional_text": "매일 10분 학습 루틴"
}
```

문제 해결 팁:
- `locale` 관련 409 에러가 나면, 먼저 App Store Connect에서 해당 버전의
  Localizations에 실제로 어떤 코드가 생성되어 있는지 확인 후 동일 코드를
  사용하세요.

### `create_in_app_purchase`
Create IAP record and optional localization.

Inputs:
- `app_id`
- `product_id`
- `reference_name`
- `in_app_purchase_type` (default: `CONSUMABLE`)
- `locale` (default: `en-US`)
- `display_name` (optional)
- `description` (optional)
- `review_note` (optional)

Notes:
- 정책 변수(`ALLOWED_APP_SKU`/`ALLOWED_BUNDLE_ID`)가 설정된 경우 `app_id`가 필수입니다.

## Notes

- Apple API 권한/역할이 부족하면 403이 발생합니다.
- 앱/상품 생성 시 필수 필드 정책은 Apple 측 변경 가능성이 있으므로 에러 메시지의 `errors[]`를 기준으로 보완하세요.

## Official References

- App Store Connect API 시작 가이드:
  https://developer.apple.com/help/app-store-connect/get-started/app-store-connect-api/
- App Store Connect API 문서:
  https://developer.apple.com/documentation/appstoreconnectapi
- App Store Connect API 키 생성/관리:
  https://developer.apple.com/help/app-store-connect/get-started/create-api-keys-for-app-store-connect-api