@yoonion/mimi-seed-mcp 0.17.0 → 0.18.0

package/dist/appstore/auth.d.ts

@@ -9,8 +9,39 @@ export interface AppStoreCredentials {
      * 여기 적어두는 수밖에 없다. 리포트 도구에만 쓰이므로 없어도 나머지는 다 동작한다.
      */
     vendorNumber?: string;
+    /**
+     * 매출 리포트 전용 별도 키 (선택).
+     *
+     * 리포트 엔드포인트는 다른 ASC API 와 요구 롤이 다르다 —
+     * **Admin / Finance / Sales and Reports** 중 하나여야 한다. 배포에 쓰는 키는 보통
+     * App Manager 라 여기서만 403 이 나는데, **Apple 은 발급된 키의 롤을 수정할 수 없게**
+     * 해놨다(폐기 후 재발급만 가능).
+     *
+     * 그렇다고 배포 키를 Admin 으로 갈아끼우면 잘 돌던 릴리스 파이프라인의 자격증명을
+     * 전부 교체해야 하고, 권한도 사용자·재무까지 넓어진다. 그래서 **읽기 전용 Finance 키를
+     * 따로 두고 리포트 도구만 이걸 쓰게** 한다. 배포 키는 손대지 않는다.
+     *
+     * 없으면 최상위 키로 폴백하므로, 배포 키가 이미 Admin 이면 설정할 필요가 없다.
+     */
+    reportsKey?: AppStoreKey;
+}
+/** ASC API 키 한 벌. 최상위 자격증명과 reportsKey 가 같은 모양을 공유한다. */
+export interface AppStoreKey {
+    issuerId: string;
+    keyId: string;
+    privateKey: string;
 }
 export declare function getAppStoreCredentials(): AppStoreCredentials | null;
 export declare function saveAppStoreCredentials(creds: AppStoreCredentials): void;
 export declare function generateToken(creds: AppStoreCredentials): Promise<string>;
 export declare function getAuthHeaders(): Promise<Record<string, string> | null>;
+/**
+ * 매출 리포트용 헤더 — reportsKey 가 있으면 그걸로, 없으면 최상위 키로 폴백.
+ *
+ * 폴백이 조용하면 안 된다: 403 이 났을 때 "어느 키가 거부당했는지" 를 모르면 사용자가
+ * 엉뚱한 키의 롤을 들여다보게 된다. 그래서 어느 키를 썼는지 함께 돌려준다.
+ */
+export declare function getReportsAuthHeaders(): Promise<{
+    headers: Record<string, string>;
+    source: 'reportsKey' | 'default';
+} | null>;

package/dist/appstore/auth.js

@@ -66,3 +66,24 @@ export async function getAuthHeaders() {
     const token = await generateToken(creds);
     return { Authorization: `Bearer ${token}` };
 }
+/**
+ * 매출 리포트용 헤더 — reportsKey 가 있으면 그걸로, 없으면 최상위 키로 폴백.
+ *
+ * 폴백이 조용하면 안 된다: 403 이 났을 때 "어느 키가 거부당했는지" 를 모르면 사용자가
+ * 엉뚱한 키의 롤을 들여다보게 된다. 그래서 어느 키를 썼는지 함께 돌려준다.
+ */
+export async function getReportsAuthHeaders() {
+    const creds = getAppStoreCredentials();
+    if (!creds)
+        return null;
+    if (creds.reportsKey) {
+        return {
+            headers: { Authorization: `Bearer ${await generateToken(creds.reportsKey)}` },
+            source: 'reportsKey',
+        };
+    }
+    return {
+        headers: { Authorization: `Bearer ${await generateToken(creds)}` },
+        source: 'default',
+    };
+}

package/dist/appstore/sales.d.ts

@@ -40,6 +40,19 @@ export declare function getSalesReport(options: {
     reportSubType?: string;
     version?: string;
 }): Promise<SalesSummary>;
+/**
+ * 리포트 접근 가능 여부만 싸게 확인한다 (appstore_verify_credentials 용).
+ *
+ * 왜 별도 프로브가 필요한가: 리포트 엔드포인트는 **다른 ASC API 와 요구 롤이 다르다.**
+ * App Manager 키는 GET /apps 가 멀쩡히 되므로 기존 검증은 전부 통과하는데, 매출 도구만
+ * 403 으로 죽는다. 그 사실이 첫 매출 조회 때까지 드러나지 않으면 "도구가 고장났다" 로
+ * 오진하게 된다 — Play 쪽 playstore_verify_service_account 가 'View financial data' 를
+ * 함께 확인하는 것과 같은 이유다.
+ */
+export declare function probeReportsAccess(): Promise<{
+    status: 'ok' | 'no_vendor_number' | 'forbidden' | 'error';
+    detail: string;
+}>;
 export declare function getFinanceReport(options: {
     vendorNumber?: string;
     /** YYYY-MM. **Apple 회계월**이라 달력월과 어긋날 수 있다 — 도구 설명 참고. */

package/dist/appstore/sales.js

@@ -9,9 +9,9 @@
 // sandbox 가 들어오지 않는 창구를 봐야 하고, 그게 이 리포트다.
 import zlib from 'node:zlib';
 import { fetchWithTimeout } from '../lib/http.js';
-import { getAppStoreCredentials } from './auth.js';
+import { getAppStoreCredentials, getReportsAuthHeaders } from './auth.js';
 import { friendlyAppStoreError } from './errors.js';
-import { authHeadersOrThrow, V1_BASE } from './http.js';
+import { V1_BASE } from './http.js';
 /**
  * vendorNumber 해석: 명시 인자 > ~/.mimi-seed/appstore.json 의 vendorNumber.
  *
@@ -41,13 +41,44 @@ function resolveVendorNumber(explicit) {
  * 여기서는 빈 배열로 뭉개지 않고 notFound 플래그를 그대로 올려보낸다.
  */
 async function fetchReport(resourcePath, params) {
-    const authHeaders = await authHeadersOrThrow();
+    const auth = await getReportsAuthHeaders();
+    if (!auth) {
+        throw new Error([
+            '❌ App Store Connect 인증이 필요해.',
+            '',
+            '터미널에서 실행:',
+            '  npx -p @yoonion/mimi-seed-mcp mimi-seed-appstore-auth',
+        ].join('\n'));
+    }
     const query = new URLSearchParams(params).toString();
     const response = await fetchWithTimeout(`${V1_BASE}${resourcePath}?${query}`, {
-        headers: { ...authHeaders, Accept: 'application/a-gzip' },
+        headers: { ...auth.headers, Accept: 'application/a-gzip' },
     });
     if (response.status === 404)
         return { notFound: true, rows: [], raw: '' };
+    if (response.status === 403) {
+        // 일반 403 안내("키 role 확인")로는 못 고친다 — 리포트 엔드포인트만 요구 롤이 다르다.
+        // 앱 메타데이터가 멀쩡히 조회되는 키에서도 여기서만 막히는 게 정상 동작이라,
+        // "키가 깨졌나" 로 헤매기 쉽다.
+        throw new Error([
+            '❌ 매출 리포트 접근 거부 (403) — 키는 정상인데 **롤이 부족**하다.',
+            `   거부당한 키: ${auth.source === 'reportsKey' ? 'reportsKey (리포트 전용)' : '최상위 키 (배포용과 동일)'}`,
+            '',
+            '리포트 엔드포인트는 다른 App Store Connect API 와 요구 롤이 다르다:',
+            '  필요: **Admin / Finance / Sales and Reports(ACCESS_TO_REPORTS)** 중 하나',
+            'App Manager·Developer 키는 앱 메타데이터는 다 되는데 여기서만 막힌다 —',
+            '다른 도구가 잘 도는 것은 이 403 과 아무 관계가 없다.',
+            '',
+            '⚠️ **발급된 키의 롤은 수정할 수 없다** (Apple 정책 — 폐기 후 재발급만 가능).',
+            '그렇다고 배포 키를 갈아끼우면 릴리스 파이프라인 자격증명을 전부 교체해야 한다.',
+            '',
+            '권장: **읽기 전용 Finance 키를 따로 발급**해 리포트 도구만 쓰게 한다.',
+            '  1) ASC > 사용자 및 액세스 > 통합 > 팀 키 > 키 생성, 액세스 = Finance',
+            '  2) 받은 .p8 내용을 ~/.mimi-seed/appstore.json 의 reportsKey 에 넣는다:',
+            '     "reportsKey": { "issuerId": "...", "keyId": "...", "privateKey": "-----BEGIN..." }',
+            '배포 키는 그대로 두면 된다 — 리포트 도구만 reportsKey 를 쓴다.',
+        ].join('\n'));
+    }
     if (!response.ok) {
         throw friendlyAppStoreError(response.status, await response.text());
     }
@@ -165,6 +196,60 @@ export async function getSalesReport(options) {
     }
     return { datesWithData, datesWithoutData, lines, proceedsByCurrency, paidUnits, freeUnits };
 }
+/**
+ * 리포트 접근 가능 여부만 싸게 확인한다 (appstore_verify_credentials 용).
+ *
+ * 왜 별도 프로브가 필요한가: 리포트 엔드포인트는 **다른 ASC API 와 요구 롤이 다르다.**
+ * App Manager 키는 GET /apps 가 멀쩡히 되므로 기존 검증은 전부 통과하는데, 매출 도구만
+ * 403 으로 죽는다. 그 사실이 첫 매출 조회 때까지 드러나지 않으면 "도구가 고장났다" 로
+ * 오진하게 된다 — Play 쪽 playstore_verify_service_account 가 'View financial data' 를
+ * 함께 확인하는 것과 같은 이유다.
+ */
+export async function probeReportsAccess() {
+    let vendorNumber;
+    try {
+        vendorNumber = resolveVendorNumber();
+    }
+    catch {
+        return {
+            status: 'no_vendor_number',
+            detail: 'vendorNumber 미설정 — ~/.mimi-seed/appstore.json 에 추가하면 매출 리포트를 쓸 수 있다.',
+        };
+    }
+    // 어제 날짜 하루치. 데이터가 없어 404 여도 **권한 확인 목적은 달성**된다 —
+    // 403 이 아니라는 것 자체가 롤이 충분하다는 뜻이다.
+    const probeDate = new Date(Date.now() - 86_400_000).toISOString().slice(0, 10);
+    try {
+        await fetchReport('/salesReports', {
+            'filter[frequency]': 'DAILY',
+            'filter[reportType]': 'SALES',
+            'filter[reportSubType]': 'SUMMARY',
+            'filter[vendorNumber]': vendorNumber,
+            'filter[reportDate]': probeDate,
+            'filter[version]': '1_0',
+        });
+        const usingSeparateKey = getAppStoreCredentials()?.reportsKey != null;
+        return {
+            status: 'ok',
+            detail: `매출 리포트 접근 가능 (vendorNumber ${vendorNumber}, ` +
+                `${usingSeparateKey ? 'reportsKey 사용' : '최상위 키 사용'})`,
+        };
+    }
+    catch (err) {
+        const message = err?.message ?? '';
+        if (message.includes('403')) {
+            const usingSeparateKey = getAppStoreCredentials()?.reportsKey != null;
+            return {
+                status: 'forbidden',
+                detail: '매출 리포트 403 — 키 롤 부족 (Admin / Finance / Sales and Reports 필요). ' +
+                    (usingSeparateKey
+                        ? 'reportsKey 가 거부당했다.'
+                        : 'reportsKey 를 따로 두면 배포 키를 건드리지 않아도 된다.'),
+            };
+        }
+        return { status: 'error', detail: message.split('\n')[0] };
+    }
+}
 export async function getFinanceReport(options) {
     return fetchReport('/financeReports', {
         'filter[vendorNumber]': resolveVendorNumber(options.vendorNumber),

package/dist/registers/appstore.js

@@ -24,9 +24,18 @@ export function registerAppstoreTools(server) {
         const apps = await appstore.listApps();
         return jsonResult(apps);
     });
-    server.tool('appstore_verify_credentials', 'App Store Connect API 키(appstore.json) 유효성 검증 — JWT 서명 + GET /apps 호출로 creds/sign/auth/api 단계별 진단. 첫 도구 호출에서 401로 늦게 터지기 전에 setup 직후 확인용. 인자 없음.', {}, async () => {
+    server.tool('appstore_verify_credentials', [
+        'App Store Connect API 키(appstore.json) 유효성 검증 — JWT 서명 + GET /apps 호출로',
+        'creds/sign/auth/api 단계별 진단. 첫 도구 호출에서 401로 늦게 터지기 전에 setup 직후 확인용.',
+        '매출 리포트 접근 가능 여부도 함께 확인한다 — 그쪽만 요구 롤이 달라서',
+        '(Admin/Finance/Sales and Reports) 앱 메타데이터는 다 되는데 매출만 403 인 키가 흔하다.',
+        '인자 없음.',
+    ].join(' '), {}, async () => {
         const r = await appstore.verifyAppStoreCredentials();
         if (r.ok) {
+            // 키가 유효할 때만 물어본다 — 인증 자체가 깨졌으면 403/401 구분이 무의미하다.
+            const reports = await appstoreSales.probeReportsAccess();
+            const reportsIcon = reports.status === 'ok' ? '✓' : reports.status === 'forbidden' ? '✗' : '·';
             return {
                 content: [{
                         type: 'text',
@@ -34,6 +43,10 @@ export function registerAppstoreTools(server) {
                             '✓ App Store Connect 인증 유효',
                             r.appCount != null ? `   접근 가능 앱: ${r.appCount}개` : '',
                             r.firstApp ? `   예: ${r.firstApp.name ?? r.firstApp.id}` : '',
+                            `${reportsIcon} 매출 리포트: ${reports.detail}`,
+                            reports.status === 'forbidden'
+                                ? '   → 키 롤은 나중에 못 바꾸는 경우가 있다. 그때는 위 롤로 새 키를 발급해 다시 등록할 것.'
+                                : '',
                         ].filter(Boolean).join('\n'),
                     }],
             };
@@ -1504,6 +1517,9 @@ export function registerAppstoreTools(server) {
         '⚠️ 데이터가 없는 날짜는 Apple 이 404 를 주므로 datesWithoutData 로 따로 돌려준다 —',
         '"매출 0" 과 "리포트 미생성/설정 오류"를 섞지 말 것. 당일치는 보통 아직 없다.',
         'vendorNumber 는 ~/.mimi-seed/appstore.json 에 저장해두면 생략 가능.',
+        '⚠️ **리포트는 요구 롤이 다르다** — Admin/Finance/Sales and Reports 중 하나여야 하고,',
+        '배포에 흔히 쓰는 App Manager 키는 여기서만 403 이 난다. 발급된 키의 롤은 수정할 수 없으므로,',
+        '읽기 전용 Finance 키를 발급해 appstore.json 의 **reportsKey** 에 넣으면 배포 키를 건드리지 않아도 된다.',
     ].join(' '), {
         startDate: z.string().describe('시작일 YYYY-MM-DD (DAILY 가 아니면 이 값이 곧 reportDate)'),
         endDate: z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yoonion/mimi-seed-mcp",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Mimi Seed MCP server \u2014 Firebase + AdMob + Google Play + App Store management for Claude Code / Codex / Cursor / any MCP client.",
   "type": "module",
   "bin": {