app-store-connect-mcp

두 Apple 상거래 API — App Store Connect(1,263개 작업)와 App Store Server API / StoreKit 2(30개 작업) — 를 다섯 개의 도구 뒤에 제공하는 MCP 서버입니다. 개인 키는 macOS 키체인에 보관되며, 결과를 변경하는 쓰기 작업은 명시적 확인을 거쳐야 실행됩니다.

1,293 operations · 5 tools · key never on disk · verified against the live APIs

이렇게 구축한 이유

여러 App Store Connect MCP 서버가 있습니다. 각각 문제의 일부를 해결하지만, 이 서버는 각각이 제대로 해결한 부분은 취하고 잘못된 부분은 버렸습니다.

이 서버는 세 번째 방식을 사용합니다. 커버리지는 Apple의 스펙에 달려 있으며, 누군가가 얼마나 많은 엔드포인트를 감쌌는지에 달려 있지 않습니다. 그리고 모델은 가격을 변경할 수 있는 프로세스 내에서 코드를 실행할 기회를 얻지 못합니다.

샌드박스에 관하여

코드 모드의 전제는 생성된 JavaScript가 Node의 vm 안에서 안전하게 실행된다는 것입니다. 그렇지 않습니다. Node 자체 문서에서 vm은 보안 메커니즘이 아니라고 명시하며, 전역으로 주입된 모든 호스트 객체는 자체 프로토타입 체인을 통해 호스트 영역을 다시 전달합니다:

spec.constructor.constructor('return process.env.HOME')()   // → /Users/you

해당 샌드박스의 정확한 재현을 통해 확인된 결과: 호스트 환경을 반환합니다. timeout 옵션도 도움이 되지 않습니다. 이 옵션은 동기 실행만 제한하므로, async 바쁜 루프는 영원히 실행되어 이벤트 루프를 굶깁니다.

매개변수화된 디스패치는 동일한 커버리지와 동일한 토큰 비용을 제공하며, 탈출할 수 있는 인터프리터가 없습니다.

Related MCP server: App Store Connect MCP Server

자격 증명

개인 키는 키체인에 보관해야 합니다. Apple은 .p8 파일을 정확히 한 번만 다운로드할 수 있게 하며, 디스크에 평문으로 저장된 복사본은 유출될 수 있는 복사본입니다.

ASC_KEY=keychain:my-asc-key          # recommended
ASC_KEY=/path/to/AuthKey.p8          # works, but plaintext
ASC_PRIVATE_KEY='-----BEGIN…'        # discouraged: `ps -E` exposes it

키체인 항목은 원시 PEM 또는 base64 JSON을 보유할 수 있습니다:

{ "issuerID": "…", "keyID": "…", "privateKeyPEM": "-----BEGIN PRIVATE KEY-----\n…" }

봉투 형식이 선호됩니다: 식별자가 키 자료와 함께 이동하므로 ASC_KEY_ID가 지정하는 키와 동기화되지 않을 수 없습니다. 이러한 불일치는 불투명한 401 오류로만 나타납니다.

security add-generic-password -s my-asc-key -a api -w "$(
  jq -nc --arg i "$ISSUER" --arg k "$KEYID" --arg p "$(cat AuthKey.p8)" \
    '{issuerID:$i,keyID:$k,privateKeyPEM:$p}' | base64
)"

설치

git clone https://github.com/abd3lraouf-studios/app-store-connect-mcp
cd app-store-connect-mcp
npm install && npm run build

{
  "mcpServers": {
    "app-store-connect": {
      "command": "node",
      "args": ["/path/to/app-store-connect-mcp/dist/index.js"],
      "env": {
        "ASC_KEY": "keychain:my-asc-key",
        "ASC_BUNDLE_ID": "com.example.app"
      }
    }
  }
}

ASC_BUNDLE_ID는 App Store Server API 호출에만 필요합니다. Apple은 bid 클레임 없이 Server API 토큰을 거부합니다.

도구

읽기와 쓰기는 별도의 도구입니다. Claude Code는 표준 destructiveHint 주석을 무시하지만 _meta["anthropic/requiresUserInteraction"]는 존중하기 때문입니다. 그리고 이 플래그는 도구별로 설정됩니다. 단일 디스패처는 작업별로 이 플래그를 다르게 설정할 수 없습니다. asc_write는 이 플래그를 가지고 있으므로, bypassPermissions에서도 사용자에게 쓰기 작업을 알립니다. 이는 --no-confirm으로 비활성화할 수 있는 프로세스 내 게이트보다 더 강력한 보장입니다.

리소스

모델이 @asc:를 통해 의도적으로 가져올 수 있는 참고 자료:

인라인으로 반환하기에는 너무 큰 결과는 잘리지 않습니다. 목록은 맞는 만큼만 잘리고, 잘린 사실과 요청을 좁히는 방법이 명시되며, 전체 응답은 클라이언트가 컨텍스트를 소모하지 않고 읽을 수 있는 리소스로 유지됩니다. 직렬화된 JSON을 구조 중간에서 자르면 모델이 구문 분석할 수 없는 것을 제공합니다. 조용히 자르는 것은 더 나쁩니다. 부분 목록이 완전한 목록으로 읽히기 때문입니다.

프롬프트

네 가지 워크플로우, /mcp__asc__<name>으로 사용 가능:

release-readiness · pricing-audit · review-triage · testflight-status

각각 여러 호출을 연결합니다. 하나의 요청을 감싼 슬래시 명령어는 동의어일 뿐 워크플로우가 아닙니다. 각각은 customerReviews에서 sort가 거부되는 것과 같은 함정과 리뷰 텍스트가 신뢰할 수 없는 입력이라는 것을 인코딩합니다.

쓰기 안전성

HTTP 메서드는 결과의 심각성을 반영하기에 부적절합니다: PATCH /v1/subscriptionPrices와 PATCH /v1/appInfos/{id}는 둘 다 쓰기이지만, 하나만 고객이 청구되는 금액을 변경하며, 반복한다고 해도 취소되지 않습니다. 작업에는 위험 등급이 있습니다:

기본적으로 아래 다섯 등급은 실행 대신 확인 토큰을 반환합니다. 토큰은 해시로 정확한 작업, 경로, 쿼리 및 본문에 바인딩되므로, 저렴한 호출에 대해 발급받아 비싼 호출에 사용할 수 없습니다. 일회용이며 5분 후에 만료됩니다.

--read-only    block every write        --confirm     confirm every write
--no-confirm   never confirm            (default)     confirm the five tiers above

클라이언트가 elicitation을 지원하는 경우, asc_write는 메서드, 경로, 본문 및 등급을 표시하여 사람에게 직접 질문합니다. 그렇지 않으면 해시로 정확한 작업, 경로, 쿼리 및 본문에 바인딩된 확인 토큰으로 대체되므로, 저렴한 호출에 대해 발급된 토큰을 비싼 호출에 사용할 수 없습니다. elicitation을 선언했지만 제공하지 못하는 클라이언트는 통과하는 대신 대체됩니다. dry_run은 요청을 보내지 않고 정확한 요청을 보고합니다.

전송 방식

node dist/index.js                       # stdio (default)
node dist/index.js --transport http --http-token "$(openssl rand -hex 32)"

HTTP는 127.0.0.1에 바인딩되며 베어러 토큰 없이는 시작을 거부합니다. 이 프로세스는 App Store 가격을 변경할 수 있는 키를 보유하고 있습니다. 인증되지 않은 상태로 수신 대기해서는 안 됩니다. 루프백이 아닌 주소에 바인딩하는 것은 경고를 표시하며, TLS 종료 프록시 또는 SSH 터널과 함께 사용하는 것이 가장 좋습니다.

Apple 업데이트 대응

npm run fetch:specs   # re-download both descriptions
npm run build         # recompile the operation index
npm run verify        # drift check + live calls against both APIs

두 API는 필요에 따라 다른 방식으로 소스에서 가져옵니다:

• App Store Connect — Apple은 실제 OpenAPI 3.0 문서를 게시합니다. 다운로드하여 간결한 인덱스(360KB, 3.3MB 스펙 대비)로 컴파일하여 검색이 빠르게 유지되고, 전체 문서는 하나의 작업을 설명할 때만 열립니다.

• App Store Server — Apple은 OpenAPI 문서를 게시하지 않습니다. 문서는 산문 형식입니다. 권위 있는 기계 판독 가능한 설명은 Apple 자체 클라이언트인 apple/app-store-server-library-node이며, 모든 엔드포인트는 문자 그대로의 makeRequest 호출입니다. fetch:specs는 고정된 릴리스 태그에서 해당 소스에서 엔드포인트 집합을 구문 분석하고, verify는 src/storekit.ts의 카탈로그와 비교합니다.

해당 카탈로그의 두 가지 세부 사항은 문서가 암시하는 것과 모순되며, 둘 다 중요합니다:

• 호스트는 api.storekit.apple.com / api.storekit-sandbox.apple.com입니다. 이전의 api.storekit.itunes.apple.com 이름은 더 이상 이 API를 제공하지 않습니다.

• 대량 갱신 연장 상태 경로는 세그먼트 순서가 {productId}/{requestIdentifier}입니다. 반대가 아닙니다.

검증

npm run verify는 읽기 전용이며 실제 호출을 수행합니다. 마지막 실행:

1. Catalogue drift — src/storekit.ts vs Apple’s client
  ✓ all 30 Apple endpoints present in the catalogue
  ✓ no endpoints in the catalogue that Apple does not define

2. App Store Connect API — live
  ✓ apps_getCollection → 2 apps
  ✓ apps_getInstance / builds / appStoreVersions → HTTP 200
  ✓ pagination walked 3 pages
  ✓ bogus id → structured 404

3. App Store Server API (StoreKit 2) — live
  ✓ storekit token carries bid;  connect token correctly omits it
  ✓ getTransactionInfo / getAllSubscriptionStatuses / getTransactionHistory v2
      → authenticated and routed (Apple errorCode 4000006)
  ✓ getNotificationHistory (30d window) → HTTP 200

14 passed, 0 failed

StoreKit 프로브는 의도적으로 유효하지 않은 트랜잭션 ID를 사용합니다. 신호는 응답의 형태입니다: 구조화된 Apple errorCode는 요청이 인증되고 라우팅되었음을 증명하며, 401은 그렇지 않음을 증명합니다.

견고성

• 타임아웃 및 재시도. 읽기는 408/429/5xx에서 재시도합니다. 쓰기는 429에서만 재시도합니다. Apple이 요청을 처리하기 전에 거부한 경우입니다. 모호하게 실패한 쓰기는 모호한 것으로 보고되며 절대 재전송되지 않습니다. 중복된 POST는 보고된 실패보다 더 나쁩니다.

• 속도 제한. 문서화된 시간당 제한과 문서화되지 않은 분당 제한 모두에 대해 속도가 조절되며, 키를 공유하는 다른 클라이언트를 설명하는 Apple 자체 x-rate-limit 헤더에서 수정됩니다. x-request-id는 Apple 지원을 위해 표시됩니다.

• 호스트 고정. 모든 URL( links.next 페이지네이션 커서 포함)은 Apple의 세 API 호스트 허용 목록에 대해 확인됩니다. 커서는 서버에서 제공하는 입력입니다. 맹목적으로 따라가면 베어러 토큰이 지정된 호스트로 이동합니다.

• 응답 변형. links 및 링크 전용 relationships는 제거되고, links.next는 유지됩니다. 실제 가격 포인트 목록에서 60% 이상 작아집니다.

• 수명 주기. stdio 서버는 stdin EOF 및 신호에서 종료되어 서명 키를 보유한 고아 프로세스로 남지 않습니다.

알려진 한계

• JWS 응답은 디코딩되지만 검증되지 않습니다. StoreKit 페이로드는 Apple이 서명한 상태로 도착합니다. 체인을 검증하려면 Apple의 루트 인증서가 필요합니다. 디코딩된 값은 *_decoded 필드에 나타나며 검증되지 않음으로 표시됩니다. 서명을 확인하지 않고 구매 증명으로 취급하지 마십시오.

• 위험 등급은 메서드와 경로에서 패턴 매칭됩니다. 의도적으로保守적으로 설정되었지만, 등급만 믿지 말고 쓰기 전에 asc_describe_endpoint를 읽으십시오.

• 키체인 저장소는 macOS 전용입니다. 다른 플랫폼에서는 제한적인 권한이 있는 파일 경로를 사용하십시오.

• --no-confirm은 게이트를 완전히 비활성화합니다. CI용으로 존재하며, 대화형 에이전트의 기본값으로는 적합하지 않습니다.

라이선스

MIT