@yoonion/mimi-seed-mcp 0.15.6 → 0.17.0

package/README.md

@@ -75,12 +75,12 @@ export ANTHROPIC_API_KEY=sk-ant-...
 
 ---
 
-## 제공 도구 (150+ 개 · 20개 영역)
+## 제공 도구 (150+ 개 · 21개 영역)
 
 | 영역 | 도구 수 | 주요 도구 |
 |------|---------|-----------|
-| App Store Connect | 61 | `appstore_submit_for_review` / `appstore_upload_screenshot` / `appstore_update_product_review_note` / `appstore_upload_product_review_screenshot` |
-| Google Play | 37 | `playstore_submit_release` / `playstore_promote_release` / `playstore_replace_images` / `playstore_reply_review` / `playstore_verify_service_account` |
+| App Store Connect | 63 | `appstore_submit_for_review` / `appstore_upload_screenshot` / `appstore_update_product_review_note` / `appstore_upload_product_review_screenshot` |
+| Google Play | 39 | `playstore_submit_release` / `playstore_promote_release` / `playstore_replace_images` / `playstore_reply_review` / `playstore_verify_service_account` |
 | Firebase | 20 | `firebase_create_project` / `firebase_create_android_app` / `firebase_get_android_config` / `firebase_create_ios_app` |
 | AdMob | 7 | `admob_list_apps` / `admob_create_ad_unit` / `admob_get_today_earnings` / `admob_get_report` |
 | CI/CD (GitHub Actions · GitLab) | 6 | `ci_trigger_build` / `ci_get_build_status` / `ci_list_workflows` / `ci_cancel_build` |
@@ -90,6 +90,7 @@ export ANTHROPIC_API_KEY=sk-ant-...
 | Google Ads | 6 | `googleads_list_campaigns` / `googleads_get_uac_report` / `googleads_get_campaign_report` |
 | Facebook | 6 | `facebook_post_photo` / `facebook_post_multi_photo` / `facebook_list_pages` |
 | Google Cloud IAM | 5 | `iam_create_service_account` / `iam_create_key` / `iam_add_iam_policy_binding` |
+| GCP Billing | 4 | `gcp_get_billing_info` / `gcp_list_billing_projects` / `gcp_list_budgets` / `gcp_create_budget` |
 | BigQuery | 5 | `bigquery_run_query` / `bigquery_list_datasets` / `bigquery_get_table_schema` |
 | Threads | 7 | `threads_post` / `threads_post_video` / `threads_post_carousel` / `threads_refresh_token` |
 | TikTok Business | 7 | `tiktok_business_plan_video_post` / `tiktok_business_publish_video` / `tiktok_business_get_publish_status` |

package/assets/agent-guide.md

@@ -69,6 +69,8 @@ you can paste. Pick the row for the job; batching two rows in one `select:` call
 | Firebase apps + services (incl. web) | `select:firebase_list_android_apps,firebase_list_ios_apps,firebase_list_web_apps,firebase_create_web_app,firebase_get_web_config,firebase_enable_service,firebase_list_enabled_services,firebase_delete_android_app,firebase_delete_ios_app,firebase_delete_web_app` |
 | Analytics wiring (Firebase ↔ GA4 ↔ BigQuery) | `select:firebase_link_analytics,firebase_get_analytics_details,ga4_list_account_summaries,ga4_list_properties,ga4_create_property,ga4_list_data_streams,ga4_create_data_stream,ga4_plan_bigquery_link,ga4_create_bigquery_link,ga4_run_report` |
 | BigQuery | `select:bigquery_auth_status,bigquery_list_datasets,bigquery_list_tables,bigquery_get_table_schema,bigquery_run_query` |
+| GCP billing (Blaze 여부 · 비용 범위 · 예산) | `select:gcp_get_billing_info,gcp_list_billing_projects,gcp_list_budgets,gcp_create_budget` |
+| Real revenue (스토어 정산 원장 — sandbox·테스터가 섞이지 않는 유일한 창구) | `select:appstore_get_sales_report,appstore_get_finance_report,playstore_list_financial_reports,playstore_get_financial_report` |
 | AdMob | `select:admob_list_accounts,admob_list_apps,admob_create_app,admob_create_ad_unit,admob_list_ad_units,admob_get_today_earnings,admob_get_report` |
 | Google Ads (UAC) | `select:googleads_config_status,googleads_save_config,googleads_list_accessible_customers,googleads_list_campaigns,googleads_get_campaign_report,googleads_get_uac_report` |
 | Search Console | `select:gsc_list_sites,gsc_list_sitemaps,gsc_get_sitemap,gsc_submit_sitemap,gsc_inspect_url,gsc_search_analytics` |

package/dist/appstore/auth.d.ts

@@ -2,6 +2,13 @@ export interface AppStoreCredentials {
     issuerId: string;
     keyId: string;
     privateKey: string;
+    /**
+     * Sales and Trends / Finance 리포트 전용 판매자 번호.
+     *
+     * **API 로는 조회할 수 없다** — ASC > 지급 및 재무 보고서 화면에서 눈으로 읽어
+     * 여기 적어두는 수밖에 없다. 리포트 도구에만 쓰이므로 없어도 나머지는 다 동작한다.
+     */
+    vendorNumber?: string;
 }
 export declare function getAppStoreCredentials(): AppStoreCredentials | null;
 export declare function saveAppStoreCredentials(creds: AppStoreCredentials): void;

package/dist/appstore/sales.d.ts

@@ -0,0 +1,53 @@
+export type SalesFrequency = 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'YEARLY';
+/** 리포트 한 줄 = TSV 헤더명 → 값. 컬럼 구성은 reportType 마다 다르다. */
+export type ReportRow = Record<string, string>;
+export declare function parseTsv(text: string): ReportRow[];
+export interface SalesLine {
+    sku: string;
+    title: string;
+    /** Apple 의 Product Type Identifier. IA* / IAY 계열이 인앱결제·구독이다. */
+    productType: string;
+    country: string;
+    /** 환불은 **음수 units** 로 들어온다 — 합계에서 자연히 상쇄된다. */
+    units: number;
+    customerPrice: number;
+    customerCurrency: string;
+    /** 개발자 수취액 **1개당** 금액. 총액은 units 를 곱해야 한다. */
+    proceedsPerUnit: number;
+    proceedsCurrency: string;
+    proceedsTotal: number;
+}
+export interface SalesSummary {
+    /** 데이터가 존재한 날짜들. 요청 범위 중 리포트가 없던 날은 빠진다. */
+    datesWithData: string[];
+    datesWithoutData: string[];
+    lines: SalesLine[];
+    /** 통화별 개발자 수취액 합계. 통화가 섞이므로 절대 하나로 더하지 않는다. */
+    proceedsByCurrency: Record<string, number>;
+    /** 유료 결제 건수 합계 (customerPrice > 0 인 줄의 units). */
+    paidUnits: number;
+    /** 무료 다운로드/설치 units — 매출과 무관하지만 같은 리포트에 섞여 온다. */
+    freeUnits: number;
+}
+/** 날짜 문자열(YYYY-MM-DD)을 하루씩 증가시키며 나열. endDate 포함. */
+export declare function eachDate(startDate: string, endDate: string, maxDays: number): string[];
+export declare function getSalesReport(options: {
+    vendorNumber?: string;
+    startDate: string;
+    endDate?: string;
+    frequency?: SalesFrequency;
+    reportType?: string;
+    reportSubType?: string;
+    version?: string;
+}): Promise<SalesSummary>;
+export declare function getFinanceReport(options: {
+    vendorNumber?: string;
+    /** YYYY-MM. **Apple 회계월**이라 달력월과 어긋날 수 있다 — 도구 설명 참고. */
+    reportDate: string;
+    regionCode?: string;
+    reportType?: 'FINANCIAL' | 'FINANCE_DETAIL';
+}): Promise<{
+    notFound: boolean;
+    rows: ReportRow[];
+    raw: string;
+}>;

package/dist/appstore/sales.js

@@ -0,0 +1,175 @@
+// App Store Connect Sales and Trends / Finance 리포트.
+//
+// 왜 별도 모듈인가: 이 두 엔드포인트만 **JSON 이 아니다.** gzip 으로 압축된 TSV 를
+// 돌려주므로 appstore/http.ts 의 apiRequest(JSON.parse 전제)를 그대로 쓸 수 없다.
+//
+// 왜 이 도구가 필요한가: GA4 의 in_app_purchase / 자체 결제 이벤트는 **sandbox 를
+// 구분하지 못한다.** TestFlight·Xcode 설치에서 일어난 결제는 실제 청구가 0원인데도
+// 클라이언트 입장에선 성공한 결제라 그대로 이벤트가 나간다. 실매출을 세려면 애초에
+// sandbox 가 들어오지 않는 창구를 봐야 하고, 그게 이 리포트다.
+import zlib from 'node:zlib';
+import { fetchWithTimeout } from '../lib/http.js';
+import { getAppStoreCredentials } from './auth.js';
+import { friendlyAppStoreError } from './errors.js';
+import { authHeadersOrThrow, V1_BASE } from './http.js';
+/**
+ * vendorNumber 해석: 명시 인자 > ~/.mimi-seed/appstore.json 의 vendorNumber.
+ *
+ * API 로 조회할 방법이 없어서 둘 다 없으면 여기서 끊는다. 빈 문자열로 요청을 보내면
+ * Apple 은 404 를 주는데, 그건 "그 날 매출 0" 과 **구분되지 않는다** — 설정 누락이
+ * 매출 0 으로 둔갑하는 게 이 도구에서 제일 위험한 오답이라 사전에 막는다.
+ */
+function resolveVendorNumber(explicit) {
+    const vendorNumber = explicit?.trim() || getAppStoreCredentials()?.vendorNumber?.trim();
+    if (!vendorNumber) {
+        throw new Error([
+            '❌ vendorNumber 가 없어 — 매출 리포트는 판매자 번호가 반드시 필요해.',
+            '',
+            'App Store Connect > 비즈니스(지급 및 재무 보고서) 상단에 있는 8~9자리 숫자야.',
+            'API 로는 조회할 수 없으니 한 번만 저장해 두면 이후 생략할 수 있어:',
+            '  ~/.mimi-seed/appstore.json 에 "vendorNumber": "<번호>" 추가',
+            '또는 이 도구의 vendorNumber 인자로 직접 넘겨.',
+        ].join('\n'));
+    }
+    return vendorNumber;
+}
+/**
+ * gzip TSV 를 받아 헤더 기준 객체 배열로 만든다.
+ *
+ * Apple 은 **데이터가 없는 날짜에 404** 를 준다 — 인증 실패나 잘못된 vendorNumber 도
+ * 같은 404 로 올 수 있어서, 호출부가 "매출 0" 과 "설정 틀림" 을 구분할 수 있도록
+ * 여기서는 빈 배열로 뭉개지 않고 notFound 플래그를 그대로 올려보낸다.
+ */
+async function fetchReport(resourcePath, params) {
+    const authHeaders = await authHeadersOrThrow();
+    const query = new URLSearchParams(params).toString();
+    const response = await fetchWithTimeout(`${V1_BASE}${resourcePath}?${query}`, {
+        headers: { ...authHeaders, Accept: 'application/a-gzip' },
+    });
+    if (response.status === 404)
+        return { notFound: true, rows: [], raw: '' };
+    if (!response.ok) {
+        throw friendlyAppStoreError(response.status, await response.text());
+    }
+    const buffer = Buffer.from(await response.arrayBuffer());
+    // 빈 리포트는 gzip 헤더조차 없이 0바이트로 오는 경우가 있다.
+    if (buffer.length === 0)
+        return { notFound: false, rows: [], raw: '' };
+    let text;
+    try {
+        text = zlib.gunzipSync(buffer).toString('utf-8');
+    }
+    catch {
+        // Accept 헤더가 무시되고 평문이 온 경우(에러 본문 포함) — 그대로 파싱을 시도한다.
+        text = buffer.toString('utf-8');
+    }
+    return { notFound: false, rows: parseTsv(text), raw: text };
+}
+export function parseTsv(text) {
+    const lines = text.split(/\r?\n/).filter((line) => line.trim().length > 0);
+    if (lines.length < 2)
+        return [];
+    const headers = lines[0].split('\t').map((h) => h.trim());
+    return lines.slice(1).map((line) => {
+        const cells = line.split('\t');
+        const row = {};
+        headers.forEach((header, i) => {
+            row[header] = (cells[i] ?? '').trim();
+        });
+        return row;
+    });
+}
+function toNumber(value) {
+    const n = Number.parseFloat((value ?? '').replace(/,/g, ''));
+    return Number.isFinite(n) ? n : 0;
+}
+/** SALES/SUMMARY 리포트 행을 매출 판독에 필요한 형태로만 좁힌다. */
+function toSalesLine(row) {
+    const units = toNumber(row['Units']);
+    const proceedsPerUnit = toNumber(row['Developer Proceeds']);
+    return {
+        sku: row['SKU'] ?? '',
+        title: row['Title'] ?? '',
+        productType: row['Product Type Identifier'] ?? '',
+        country: row['Country Code'] ?? '',
+        units,
+        customerPrice: toNumber(row['Customer Price']),
+        customerCurrency: row['Customer Currency'] ?? '',
+        proceedsPerUnit,
+        proceedsCurrency: row['Currency of Proceeds'] ?? '',
+        proceedsTotal: units * proceedsPerUnit,
+    };
+}
+/** 날짜 문자열(YYYY-MM-DD)을 하루씩 증가시키며 나열. endDate 포함. */
+export function eachDate(startDate, endDate, maxDays) {
+    const start = Date.parse(`${startDate}T00:00:00Z`);
+    const end = Date.parse(`${endDate}T00:00:00Z`);
+    if (!Number.isFinite(start) || !Number.isFinite(end)) {
+        throw new Error('날짜는 YYYY-MM-DD 형식이어야 해.');
+    }
+    if (end < start)
+        throw new Error('endDate 가 startDate 보다 앞설 수 없어.');
+    const dates = [];
+    for (let t = start; t <= end; t += 86_400_000) {
+        if (dates.length >= maxDays) {
+            throw new Error(`한 번에 조회할 수 있는 일수는 ${maxDays}일까지야. 범위를 나눠서 호출해.`);
+        }
+        dates.push(new Date(t).toISOString().slice(0, 10));
+    }
+    return dates;
+}
+/** DAILY 는 하루에 리포트 하나라, 범위 조회는 날짜별 호출을 합치는 수밖에 없다. */
+const MAX_DAILY_RANGE = 62;
+export async function getSalesReport(options) {
+    const vendorNumber = resolveVendorNumber(options.vendorNumber);
+    const frequency = options.frequency ?? 'DAILY';
+    const endDate = options.endDate ?? options.startDate;
+    // DAILY 만 날짜를 펼친다. WEEKLY/MONTHLY/YEARLY 는 reportDate 자체가 기간을 뜻해서
+    // 하루씩 도는 게 의미가 없고, 오히려 같은 기간을 며칠치 중복 합산하게 된다.
+    const reportDates = frequency === 'DAILY' ? eachDate(options.startDate, endDate, MAX_DAILY_RANGE) : [options.startDate];
+    const datesWithData = [];
+    const datesWithoutData = [];
+    const rows = [];
+    for (const reportDate of reportDates) {
+        const result = await fetchReport('/salesReports', {
+            'filter[frequency]': frequency,
+            'filter[reportType]': options.reportType ?? 'SALES',
+            'filter[reportSubType]': options.reportSubType ?? 'SUMMARY',
+            'filter[vendorNumber]': vendorNumber,
+            'filter[reportDate]': reportDate,
+            'filter[version]': options.version ?? '1_0',
+        });
+        if (result.notFound || result.rows.length === 0)
+            datesWithoutData.push(reportDate);
+        else {
+            datesWithData.push(reportDate);
+            rows.push(...result.rows);
+        }
+    }
+    const lines = rows.map(toSalesLine);
+    const proceedsByCurrency = {};
+    let paidUnits = 0;
+    let freeUnits = 0;
+    for (const line of lines) {
+        if (line.proceedsTotal !== 0) {
+            const currency = line.proceedsCurrency || 'UNKNOWN';
+            proceedsByCurrency[currency] = (proceedsByCurrency[currency] ?? 0) + line.proceedsTotal;
+        }
+        if (line.customerPrice > 0)
+            paidUnits += line.units;
+        else
+            freeUnits += line.units;
+    }
+    for (const currency of Object.keys(proceedsByCurrency)) {
+        proceedsByCurrency[currency] = Math.round(proceedsByCurrency[currency] * 100) / 100;
+    }
+    return { datesWithData, datesWithoutData, lines, proceedsByCurrency, paidUnits, freeUnits };
+}
+export async function getFinanceReport(options) {
+    return fetchReport('/financeReports', {
+        'filter[vendorNumber]': resolveVendorNumber(options.vendorNumber),
+        'filter[reportDate]': options.reportDate,
+        'filter[regionCode]': options.regionCode ?? 'ZZ',
+        'filter[reportType]': options.reportType ?? 'FINANCIAL',
+    });
+}

package/dist/billing/tools.d.ts

@@ -0,0 +1,50 @@
+import type { OAuth2Client } from 'google-auth-library';
+/** `01F1F4-FD007B-2973A7` / `billingAccounts/01F1F4-...` 어느 형태로 줘도 정규화. */
+export declare function normalizeBillingAccount(input: string): string;
+export type BillingInfo = {
+    projectId: string;
+    billingEnabled: boolean;
+    billingAccountName: string | null;
+    /** 사람이 읽을 판정 — Blaze/Spark 오판을 막기 위해 문장으로 준다. */
+    verdict: string;
+};
+export declare function getBillingInfo(auth: OAuth2Client, projectId: string): Promise<BillingInfo>;
+/**
+ * 결제 계정에 붙은 프로젝트 목록 = **비용 범위 확인**.
+ * 여기서 프로젝트가 여러 개면 계정 전체 예산은 의미가 없고 프로젝트 필터를 써야 한다.
+ */
+export declare function listBillingProjects(auth: OAuth2Client, billingAccount: string, quotaProjectId?: string): Promise<{
+    billingAccount: string;
+    count: number;
+    shared: boolean;
+    projects: {
+        projectId: string | null | undefined;
+        billingEnabled: boolean;
+    }[];
+}>;
+export declare function listBudgets(auth: OAuth2Client, billingAccount: string, quotaProjectId?: string): Promise<{
+    name: string | null | undefined;
+    displayName: string | null | undefined;
+    amount: string;
+    projects: string[];
+    thresholds: (number | null | undefined)[];
+}[]>;
+export type CreateBudgetInput = {
+    billingAccount: string;
+    displayName: string;
+    /** 통화 단위 정수 금액 (KRW 는 소수 없음 — 10000 = ₩10,000). */
+    amountUnits: number;
+    currencyCode?: string;
+    /** 감시할 프로젝트 ID 목록. **비우면 결제 계정 전체** — 공용 계정이면 소음이 된다. */
+    projectIds?: string[];
+    /** 알림 임계 비율 (0~1). 기본 0.5 / 0.9 / 1.0. */
+    thresholds?: number[];
+    /** quota 주체 프로젝트 — Billing Budget API 를 켜 둔 프로젝트. quotaHeaders 주석 참고. */
+    quotaProjectId?: string;
+};
+export declare function createBudget(auth: OAuth2Client, input: CreateBudgetInput): Promise<{
+    name: string | null | undefined;
+    displayName: string | null | undefined;
+    projects: string[];
+    thresholds: number[];
+}>;

package/dist/billing/tools.js

@@ -0,0 +1,138 @@
+import { google } from '../lib/googleapis-lite.js';
+/**
+ * Cloud Billing + Billing Budgets 래퍼.
+ *
+ * 앱마다 전용 Firebase/GCP 프로젝트를 만드는 컨벤션이라, 새 프로젝트가 생길 때마다
+ * "이 프로젝트가 Blaze 인가 → 결제 계정이 공용인가 → 예산 알림을 걸었나"가 반복 작업이 된다.
+ *
+ * 실제로 겪은 함정 2개가 이 모듈의 존재 이유다:
+ *
+ * 1. **Billing API 가 꺼져 있으면 조회 자체가 403** 이고, 그 403 을 "Spark 이라서"로
+ *    오해하기 쉽다. 실제로는 이미 Blaze 였다. `getBillingInfo` 는 이 구분을 명확히 한다
+ *    (API 미활성 → firebase_enable_service 안내 / 활성인데 billingEnabled=false → 진짜 Spark).
+ *
+ * 2. **결제 계정이 회사 공용이면 계정 전체 예산은 쓸 수 없다.** 기존 지출(BigQuery export 등)만으로
+ *    즉시 임계를 넘겨 알림이 소음이 된다. 그래서 `createBudget` 은 `projects` 필터를 1급으로 받는다 —
+ *    프로젝트 범위 예산이 신규 앱 감시의 기본형이다.
+ *
+ * ⚠️ 예산은 **알림만 한다. 지출을 막지 않는다.** 하드 차단은 Pub/Sub → 결제 해제 함수뿐이고
+ *    그건 앱을 죽이는 조치다. 실질 방어는 각 서비스의 상한(예: functions maxInstances)이다.
+ *
+ * ⚠️ 권한은 **결제 계정 레벨 IAM** 이다(프로젝트 IAM 과 별개). 서비스 계정 키로는 대개 403 이고
+ *    사용자 OAuth(cloud-platform)로 호출해야 한다.
+ */
+const billing = () => google.cloudbilling('v1');
+const budgets = () => google.billingbudgets('v1');
+/**
+ * 🔴 quota 프로젝트 지정이 **필수**다.
+ *
+ * 사용자 OAuth 로 호출하면 GCP 는 quota/billing 을 **OAuth 클라이언트의 프로젝트**에 청구한다.
+ * mimi-seed 의 OAuth 클라이언트 프로젝트에는 Cloud Billing API 가 없으므로, 지정하지 않으면
+ * 대상 프로젝트가 아무리 정상이어도 항상 이렇게 실패한다 (2026-08-04 실측):
+ *
+ *   "Cloud Billing API has not been used in project <OAuth 클라이언트 프로젝트 번호> before or it is disabled"
+ *
+ * 이 메시지의 프로젝트 번호는 **우리가 조회하려는 프로젝트가 아니라 OAuth 클라이언트 쪽**이다 —
+ * 그래서 "대상 프로젝트에서 API 를 켰는데도 왜 403 이냐"로 헤매게 된다.
+ * `x-goog-user-project` 로 우리가 통제하는(그리고 API 를 켜 둔) 프로젝트를 quota 주체로 넘긴다.
+ */
+function quotaHeaders(quotaProjectId) {
+    return quotaProjectId ? { headers: { 'x-goog-user-project': quotaProjectId } } : {};
+}
+/** `01F1F4-FD007B-2973A7` / `billingAccounts/01F1F4-...` 어느 형태로 줘도 정규화. */
+export function normalizeBillingAccount(input) {
+    const trimmed = input.trim();
+    return trimmed.startsWith('billingAccounts/') ? trimmed : `billingAccounts/${trimmed}`;
+}
+export async function getBillingInfo(auth, projectId) {
+    // 조회 대상 프로젝트 자신을 quota 주체로 쓴다 — 거기 Billing API 가 켜져 있어야 한다.
+    const res = await billing().projects.getBillingInfo({
+        auth,
+        name: `projects/${projectId}`,
+        ...quotaHeaders(projectId),
+    });
+    const enabled = res.data.billingEnabled ?? false;
+    const account = res.data.billingAccountName ?? null;
+    return {
+        projectId,
+        billingEnabled: enabled,
+        billingAccountName: account,
+        verdict: enabled
+            ? `Blaze — 결제 계정 ${account} 연결됨. Cloud Functions/Run 배포 가능.`
+            : 'Spark — 결제 계정 미연결. Cloud Functions 등 유료 서비스 배포 불가.',
+    };
+}
+/**
+ * 결제 계정에 붙은 프로젝트 목록 = **비용 범위 확인**.
+ * 여기서 프로젝트가 여러 개면 계정 전체 예산은 의미가 없고 프로젝트 필터를 써야 한다.
+ */
+export async function listBillingProjects(auth, billingAccount, quotaProjectId) {
+    const name = normalizeBillingAccount(billingAccount);
+    const res = await billing().billingAccounts.projects.list({
+        auth,
+        name,
+        pageSize: 200,
+        ...quotaHeaders(quotaProjectId),
+    });
+    const projects = (res.data.projectBillingInfo ?? []).map((p) => ({
+        projectId: p.projectId,
+        billingEnabled: p.billingEnabled ?? false,
+    }));
+    return {
+        billingAccount: name,
+        count: projects.length,
+        shared: projects.length > 1,
+        projects,
+    };
+}
+export async function listBudgets(auth, billingAccount, quotaProjectId) {
+    const parent = normalizeBillingAccount(billingAccount);
+    const res = await budgets().billingAccounts.budgets.list({
+        auth,
+        parent,
+        pageSize: 200,
+        ...quotaHeaders(quotaProjectId),
+    });
+    return (res.data.budgets ?? []).map((b) => ({
+        name: b.name,
+        displayName: b.displayName,
+        amount: b.amount?.specifiedAmount
+            ? `${b.amount.specifiedAmount.units ?? '0'} ${b.amount.specifiedAmount.currencyCode ?? ''}`.trim()
+            : b.amount?.lastPeriodAmount
+                ? '(직전 기간 금액)'
+                : '(미지정)',
+        projects: b.budgetFilter?.projects ?? [],
+        thresholds: (b.thresholdRules ?? []).map((t) => t.thresholdPercent),
+    }));
+}
+export async function createBudget(auth, input) {
+    const parent = normalizeBillingAccount(input.billingAccount);
+    const thresholds = input.thresholds?.length ? input.thresholds : [0.5, 0.9, 1.0];
+    const res = await budgets().billingAccounts.budgets.create({
+        auth,
+        parent,
+        requestBody: {
+            displayName: input.displayName,
+            budgetFilter: {
+                // projects 는 `projects/<번호 또는 ID>` 형태를 받는다.
+                ...(input.projectIds?.length
+                    ? { projects: input.projectIds.map((p) => (p.startsWith('projects/') ? p : `projects/${p}`)) }
+                    : {}),
+            },
+            amount: {
+                specifiedAmount: {
+                    currencyCode: input.currencyCode ?? 'KRW',
+                    units: String(input.amountUnits),
+                },
+            },
+            thresholdRules: thresholds.map((t) => ({ thresholdPercent: t })),
+        },
+        ...quotaHeaders(input.quotaProjectId),
+    });
+    return {
+        name: res.data.name,
+        displayName: res.data.displayName,
+        projects: res.data.budgetFilter?.projects ?? [],
+        thresholds,
+    };
+}

package/dist/lib/googleapis-lite.d.ts

@@ -16,6 +16,8 @@ import { analyticsadmin } from 'googleapis/build/src/apis/analyticsadmin/index.j
 import { analyticsdata } from 'googleapis/build/src/apis/analyticsdata/index.js';
 import { androidpublisher } from 'googleapis/build/src/apis/androidpublisher/index.js';
 import { bigquery } from 'googleapis/build/src/apis/bigquery/index.js';
+import { billingbudgets } from 'googleapis/build/src/apis/billingbudgets/index.js';
+import { cloudbilling } from 'googleapis/build/src/apis/cloudbilling/index.js';
 import { cloudresourcemanager } from 'googleapis/build/src/apis/cloudresourcemanager/index.js';
 import { firebase } from 'googleapis/build/src/apis/firebase/index.js';
 import { iam } from 'googleapis/build/src/apis/iam/index.js';
@@ -30,6 +32,8 @@ export declare const google: {
     analyticsdata: typeof analyticsdata;
     androidpublisher: typeof androidpublisher;
     bigquery: typeof bigquery;
+    billingbudgets: typeof billingbudgets;
+    cloudbilling: typeof cloudbilling;
     cloudresourcemanager: typeof cloudresourcemanager;
     firebase: typeof firebase;
     iam: typeof iam;

package/dist/lib/googleapis-lite.js

@@ -16,6 +16,8 @@ import { analyticsadmin } from 'googleapis/build/src/apis/analyticsadmin/index.j
 import { analyticsdata } from 'googleapis/build/src/apis/analyticsdata/index.js';
 import { androidpublisher } from 'googleapis/build/src/apis/androidpublisher/index.js';
 import { bigquery } from 'googleapis/build/src/apis/bigquery/index.js';
+import { billingbudgets } from 'googleapis/build/src/apis/billingbudgets/index.js';
+import { cloudbilling } from 'googleapis/build/src/apis/cloudbilling/index.js';
 import { cloudresourcemanager } from 'googleapis/build/src/apis/cloudresourcemanager/index.js';
 import { auth, firebase } from 'googleapis/build/src/apis/firebase/index.js';
 import { iam } from 'googleapis/build/src/apis/iam/index.js';
@@ -29,6 +31,8 @@ export const google = {
     analyticsdata,
     androidpublisher,
     bigquery,
+    billingbudgets,
+    cloudbilling,
     cloudresourcemanager,
     firebase,
     iam,

package/dist/playstore/financials.d.ts

@@ -0,0 +1,65 @@
+export type PlayFinancialReportType = 'earnings' | 'sales';
+/**
+ * 버킷 이름 해석: 명시 인자 > ~/.mimi-seed/play-financials.json.
+ *
+ * 버킷 이름은 Play Console 에만 있고 API 로 못 얻는다(개발자 계정마다 다르다).
+ * 없으면 조용히 빈 결과를 주는 대신 여기서 끊는다 — "매출 0" 과 "설정 누락" 이
+ * 구분되지 않는 게 이 도구의 가장 위험한 오답이다.
+ */
+export declare function resolveBucket(explicit?: string, packageName?: string): string;
+export interface FinancialReportObject {
+    name: string;
+    size: number;
+    updated: string;
+    /** 파일명에서 뽑은 YYYYMM. 못 뽑으면 빈 문자열. */
+    yearMonth: string;
+}
+export declare function listFinancialReports(options: {
+    packageName?: string;
+    bucket?: string;
+    reportType?: PlayFinancialReportType;
+}): Promise<{
+    bucket: string;
+    objects: FinancialReportObject[];
+}>;
+export interface EarningsSummary {
+    bucket: string;
+    files: string[];
+    rowCount: number;
+    /** 정산 통화별 순액 합계 — 수수료·세금·환불이 음수로 들어와 이미 상쇄된 값이다. */
+    netByMerchantCurrency: Record<string, number>;
+    /** Transaction Type 별 건수·금액. 'Charge' 만이 실제 구매다. */
+    byTransactionType: Record<string, {
+        count: number;
+        amount: number;
+    }>;
+    /**
+     * 상품별 집계 (Charge 행만). **통화별로 행이 갈린다** — 여러 통화를 한 숫자로 더하면
+     * IDR 1,000,000 과 KRW 3,000 이 섞여 아무 의미 없는 값이 된다.
+     */
+    byProduct: Array<{
+        productId: string;
+        title: string;
+        currency: string;
+        count: number;
+        amount: number;
+    }>;
+    /** 판독을 위해 남기는 원본 행. 기본은 생략된다. */
+    rows?: Array<Record<string, string>>;
+}
+export declare function getFinancialReport(options: {
+    yearMonth: string;
+    packageName?: string;
+    bucket?: string;
+    reportType?: PlayFinancialReportType;
+    includeRows?: boolean;
+}): Promise<EarningsSummary>;
+/**
+ * 최소 ZIP 리더 (stored + deflate).
+ *
+ * Node 에 zip 해제가 없고, 이 하나 때문에 의존성을 늘리고 싶지 않다. Play 리포트는
+ * 항상 단일/소수 CSV 엔트리라 중앙 디렉터리만 훑으면 충분하다.
+ */
+export declare function unzip(buffer: Buffer): Buffer[];
+/** 따옴표·따옴표 안 쉼표를 처리하는 최소 CSV 파서. 헤더 기준 객체 배열을 만든다. */
+export declare function parseCsv(text: string): Array<Record<string, string>>;

package/dist/playstore/financials.js

@@ -0,0 +1,319 @@
+// Google Play 재무 리포트 (Cloud Storage).
+//
+// **Play Developer API 에는 매출 엔드포인트가 없다.** purchases.* 는 구매 토큰을 이미
+// 알고 있어야 하고, Reporting API 는 vitals 뿐이다. 실제 정산 데이터는 Play Console 이
+// 매달 개발자 소유 GCS 버킷에 떨궈주는 CSV 가 유일한 소스라서, 여기서는 그걸 읽는다.
+//
+// 왜 중요한가: GA4 의 결제 이벤트는 라이선스 테스터·내부 테스트 트랙 결제를 실결제와
+// 구분하지 못한다(둘 다 install_source 가 com.android.vending 이다). 청구가 0원인
+// 테스터 주문은 **이 리포트에 아예 나타나지 않으므로**, 실매출 판별의 기준선이 된다.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { JWT } from 'google-auth-library';
+import { fetchWithTimeout, HTTP_TRANSFER_TIMEOUT_MS } from '../lib/http.js';
+import { requireServiceAccountJson } from '../helpers.js';
+const CONFIG_PATH = path.join(os.homedir(), '.mimi-seed', 'play-financials.json');
+const STORAGE_SCOPE = 'https://www.googleapis.com/auth/devstorage.read_only';
+/** 리포트 종류 → 버킷 내 접두사·파일명 규칙. */
+const REPORT_PREFIX = {
+    earnings: 'earnings/',
+    sales: 'sales/',
+};
+/**
+ * 버킷 이름 해석: 명시 인자 > ~/.mimi-seed/play-financials.json.
+ *
+ * 버킷 이름은 Play Console 에만 있고 API 로 못 얻는다(개발자 계정마다 다르다).
+ * 없으면 조용히 빈 결과를 주는 대신 여기서 끊는다 — "매출 0" 과 "설정 누락" 이
+ * 구분되지 않는 게 이 도구의 가장 위험한 오답이다.
+ */
+export function resolveBucket(explicit, packageName) {
+    const fromArg = explicit?.trim();
+    if (fromArg)
+        return normalizeBucket(fromArg);
+    let config = {};
+    try {
+        if (fs.existsSync(CONFIG_PATH))
+            config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+    }
+    catch {
+        // 손상된 설정은 없는 것으로 취급하고 아래 안내로 떨어뜨린다.
+    }
+    const stored = (packageName && config[packageName]) || config.default || config.bucket;
+    if (stored)
+        return normalizeBucket(stored);
+    throw new Error([
+        '❌ Play 재무 리포트 버킷을 몰라 — API 로는 알아낼 수 없어.',
+        '',
+        'Play Console > 다운로드 보고서 > 재무 화면 아래쪽에 있는',
+        '  gs://pubsite_prod_XXXXXXXXXXXXXXXXXXX',
+        '이 버킷 이름을 한 번만 저장해 두면 이후 생략할 수 있어:',
+        `  ${CONFIG_PATH} 에 {"default": "pubsite_prod_..."}`,
+        '패키지마다 다르면 {"<packageName>": "pubsite_prod_..."} 로 키를 나눠도 돼.',
+        '또는 이 도구의 bucket 인자로 직접 넘겨.',
+        '',
+        '⚠️ 접근 권한은 **GCP IAM 이 아니라 Play Console 권한**이다 — 아래 403 안내 참고.',
+    ].join('\n'));
+}
+function normalizeBucket(raw) {
+    return raw.replace(/^gs:\/\//, '').replace(/\/+$/, '');
+}
+/**
+ * GCS 전용 JWT.
+ *
+ * 기존 Play SA 클라이언트(getServiceAccountClient)에 storage 스코프를 얹지 않고 따로
+ * 만든다 — 그쪽은 모든 Play 도구가 공유하는 경로라, 리포트 하나 때문에 스코프를 넓히면
+ * 실패 범위가 도구 전체로 번진다.
+ */
+function storageClient(packageName) {
+    const parsed = JSON.parse(requireServiceAccountJson(packageName));
+    return new JWT({
+        email: parsed.client_email,
+        key: parsed.private_key,
+        scopes: [STORAGE_SCOPE],
+    });
+}
+async function storageFetch(client, url, timeoutMs) {
+    const token = await client.getAccessToken();
+    const response = await fetchWithTimeout(url, { headers: { Authorization: `Bearer ${token.token ?? ''}` } }, timeoutMs);
+    if (!response.ok) {
+        const body = await response.text();
+        if (response.status === 403) {
+            throw new Error([
+                '❌ 버킷 접근 거부 (403).',
+                '',
+                '⚠️ **GCP IAM 으로는 못 고친다.** pubsite_prod_* 버킷은 개발자 프로젝트가 아니라',
+                'Google 소유라, 프로젝트에 roles/storage.* 를 아무리 줘도 닿지 않는다.',
+                '접근은 오직 **Play Console 사용자 권한**으로 열린다:',
+                '',
+                '  Play Console > 사용자 및 권한 > 새 사용자 초대',
+                '  → 서비스 계정 이메일(...iam.gserviceaccount.com)을 그대로 초대하고',
+                '  → "앱 정보 보기(읽기 전용)" = 전체(Global)',
+                '  → "재무 데이터 보기" = **전체(Global)**  ← 재무 리포트는 이게 없으면 무조건 403',
+                '',
+                '반영에 몇 분 걸릴 수 있다. Play Developer API 접근(앱 게시용)과는 별개 권한이라,',
+                '릴리스가 잘 돌아간다고 해서 리포트가 열려 있는 것은 아니다.',
+                '',
+                body.slice(0, 500),
+            ].join('\n'));
+        }
+        throw new Error(`❌ Cloud Storage ${response.status}: ${body.slice(0, 500)}`);
+    }
+    return response;
+}
+export async function listFinancialReports(options) {
+    const bucket = resolveBucket(options.bucket, options.packageName);
+    const client = storageClient(options.packageName);
+    // 반드시 페이지를 끝까지 돈다. 이 버킷에는 stats/ 하위 CSV 가 수천 개 쌓여 있어서
+    // 첫 페이지만 읽으면 earnings/·sales/ 가 통째로 안 보인다 — 그런데 응답은 성공이라
+    // "그 달 리포트가 없다"는 오답으로 조용히 둔갑한다. prefix 를 줘도 마찬가지다.
+    const items = [];
+    let pageToken;
+    do {
+        const params = new URLSearchParams({ maxResults: '1000' });
+        if (options.reportType)
+            params.set('prefix', REPORT_PREFIX[options.reportType]);
+        if (pageToken)
+            params.set('pageToken', pageToken);
+        const response = await storageFetch(client, `https://storage.googleapis.com/storage/v1/b/${encodeURIComponent(bucket)}/o?${params}`);
+        const page = (await response.json());
+        items.push(...(page.items ?? []));
+        pageToken = page.nextPageToken;
+    } while (pageToken);
+    const objects = items.map((item) => ({
+        name: item.name ?? '',
+        size: Number.parseInt(item.size ?? '0', 10) || 0,
+        updated: item.updated ?? '',
+        yearMonth: /_(\d{6})[_.]/.exec(item.name ?? '')?.[1] ?? '',
+    }));
+    objects.sort((a, b) => b.name.localeCompare(a.name));
+    return { bucket, objects };
+}
+export async function getFinancialReport(options) {
+    const reportType = options.reportType ?? 'earnings';
+    const bucket = resolveBucket(options.bucket, options.packageName);
+    const client = storageClient(options.packageName);
+    const yearMonth = options.yearMonth.replace('-', '');
+    if (!/^\d{6}$/.test(yearMonth)) {
+        throw new Error('yearMonth 는 YYYYMM 또는 YYYY-MM 형식이어야 해.');
+    }
+    const { objects } = await listFinancialReports({
+        packageName: options.packageName,
+        bucket,
+        reportType,
+    });
+    // 정산 통화마다 파일이 따로 떨어지므로(earnings_YYYYMM_<id>-<currency>.zip) 한 달이
+    // 파일 하나라고 가정하면 통화 하나만 세고 나머지를 조용히 버리게 된다.
+    const targets = objects.filter((o) => o.name.includes(yearMonth));
+    if (targets.length === 0) {
+        throw new Error([
+            `❌ ${yearMonth} 의 ${reportType} 리포트가 버킷에 없어.`,
+            '',
+            'Play 재무 리포트는 **월 마감 후에야** 올라온다 — 이번 달 것은 아직 없는 게 정상이다.',
+            `버킷에 있는 파일: ${objects.slice(0, 10).map((o) => o.name).join(', ') || '(없음)'}`,
+        ].join('\n'));
+    }
+    const rows = [];
+    for (const target of targets) {
+        const response = await storageFetch(client, `https://storage.googleapis.com/storage/v1/b/${encodeURIComponent(bucket)}` +
+            `/o/${encodeURIComponent(target.name)}?alt=media`, HTTP_TRANSFER_TIMEOUT_MS);
+        const zipped = Buffer.from(await response.arrayBuffer());
+        for (const entry of unzip(zipped)) {
+            rows.push(...parseCsv(entry.toString('utf-8')));
+        }
+    }
+    return {
+        bucket,
+        files: targets.map((t) => t.name),
+        rowCount: rows.length,
+        ...summarize(rows),
+        ...(options.includeRows ? { rows } : {}),
+    };
+}
+/** earnings/sales 양쪽 컬럼명을 모두 받아, 있는 쪽으로 집계한다. */
+function summarize(rows) {
+    const netByMerchantCurrency = {};
+    const byTransactionType = {};
+    const byProductMap = new Map();
+    for (const row of rows) {
+        const currency = row['Merchant Currency'] || row['Currency of Sale'] || 'UNKNOWN';
+        const amount = toNumber(row['Amount (Merchant Currency)'] ?? row['Charged Amount'] ?? row['Item Price']);
+        const type = row['Transaction Type'] || row['Financial Status'] || 'UNKNOWN';
+        // 컬럼명이 리포트마다 다르다. earnings 는 'Product id'/'Sku Id', sales 는 **'SKU ID'**
+        // (전부 대문자). 하나라도 빠뜨리면 상품별 집계가 통째로 빈 키('')로 뭉개진다.
+        const productId = row['Product id'] || row['Product ID'] || row['SKU ID'] || row['Sku Id'] ||
+            row['Sku ID'] || row['Package ID'] || '';
+        const title = row['Product Title'] || '';
+        netByMerchantCurrency[currency] = (netByMerchantCurrency[currency] ?? 0) + amount;
+        const bucketForType = (byTransactionType[type] ??= { count: 0, amount: 0 });
+        bucketForType.count += 1;
+        bucketForType.amount += amount;
+        // 수수료·세금 행은 상품 매출이 아니다 — 상품별 집계에 섞으면 판매량이 부풀려진다.
+        if (/^charge$/i.test(type) || /^charged$/i.test(type)) {
+            const key = `${productId || title}${currency}`;
+            const entry = byProductMap.get(key) ?? { productId, title, currency, count: 0, amount: 0 };
+            entry.count += 1;
+            entry.amount += amount;
+            byProductMap.set(key, entry);
+        }
+    }
+    const round = (n) => Math.round(n * 100) / 100;
+    for (const key of Object.keys(netByMerchantCurrency)) {
+        netByMerchantCurrency[key] = round(netByMerchantCurrency[key]);
+    }
+    for (const key of Object.keys(byTransactionType)) {
+        byTransactionType[key].amount = round(byTransactionType[key].amount);
+    }
+    // 통화가 다른 행끼리는 금액 크기를 비교해도 뜻이 없으므로 통화로 먼저 묶어 정렬한다.
+    const byProduct = [...byProductMap.values()]
+        .map((p) => ({ ...p, amount: round(p.amount) }))
+        .sort((a, b) => a.currency.localeCompare(b.currency) || b.amount - a.amount);
+    return { netByMerchantCurrency, byTransactionType, byProduct };
+}
+function toNumber(value) {
+    const n = Number.parseFloat((value ?? '').replace(/[,"]/g, ''));
+    return Number.isFinite(n) ? n : 0;
+}
+/**
+ * 최소 ZIP 리더 (stored + deflate).
+ *
+ * Node 에 zip 해제가 없고, 이 하나 때문에 의존성을 늘리고 싶지 않다. Play 리포트는
+ * 항상 단일/소수 CSV 엔트리라 중앙 디렉터리만 훑으면 충분하다.
+ */
+export function unzip(buffer) {
+    const EOCD_SIG = 0x06054b50;
+    const CEN_SIG = 0x02014b50;
+    let eocd = -1;
+    for (let i = buffer.length - 22; i >= 0; i--) {
+        if (buffer.readUInt32LE(i) === EOCD_SIG) {
+            eocd = i;
+            break;
+        }
+    }
+    if (eocd < 0)
+        throw new Error('ZIP 형식이 아니야 — 재무 리포트 파일이 손상됐을 수 있어.');
+    const entryCount = buffer.readUInt16LE(eocd + 10);
+    let offset = buffer.readUInt32LE(eocd + 16);
+    const files = [];
+    for (let i = 0; i < entryCount; i++) {
+        if (buffer.readUInt32LE(offset) !== CEN_SIG)
+            break;
+        const method = buffer.readUInt16LE(offset + 10);
+        const compressedSize = buffer.readUInt32LE(offset + 20);
+        const nameLength = buffer.readUInt16LE(offset + 28);
+        const extraLength = buffer.readUInt16LE(offset + 30);
+        const commentLength = buffer.readUInt16LE(offset + 32);
+        const localOffset = buffer.readUInt32LE(offset + 42);
+        // 로컬 헤더는 중앙 디렉터리와 extra 필드 길이가 다를 수 있어 반드시 다시 읽는다.
+        const localNameLength = buffer.readUInt16LE(localOffset + 26);
+        const localExtraLength = buffer.readUInt16LE(localOffset + 28);
+        const dataStart = localOffset + 30 + localNameLength + localExtraLength;
+        const data = buffer.subarray(dataStart, dataStart + compressedSize);
+        if (method === 0)
+            files.push(Buffer.from(data));
+        else if (method === 8)
+            files.push(zlib.inflateRawSync(data));
+        else
+            throw new Error(`지원하지 않는 ZIP 압축 방식(${method})이야.`);
+        offset += 46 + nameLength + extraLength + commentLength;
+    }
+    return files;
+}
+/** 따옴표·따옴표 안 쉼표를 처리하는 최소 CSV 파서. 헤더 기준 객체 배열을 만든다. */
+export function parseCsv(text) {
+    const rows = splitCsvRows(text);
+    if (rows.length < 2)
+        return [];
+    const headers = rows[0].map((h) => h.trim());
+    return rows.slice(1)
+        .filter((cells) => cells.some((c) => c.trim().length > 0))
+        .map((cells) => {
+        const row = {};
+        headers.forEach((header, i) => {
+            row[header] = (cells[i] ?? '').trim();
+        });
+        return row;
+    });
+}
+function splitCsvRows(text) {
+    const rows = [];
+    let cells = [];
+    let field = '';
+    let inQuotes = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (inQuotes) {
+            if (ch === '"') {
+                if (text[i + 1] === '"') {
+                    field += '"';
+                    i++;
+                }
+                else
+                    inQuotes = false;
+            }
+            else
+                field += ch;
+            continue;
+        }
+        if (ch === '"')
+            inQuotes = true;
+        else if (ch === ',') {
+            cells.push(field);
+            field = '';
+        }
+        else if (ch === '\n') {
+            cells.push(field);
+            rows.push(cells);
+            cells = [];
+            field = '';
+        }
+        else if (ch !== '\r')
+            field += ch;
+    }
+    if (field.length > 0 || cells.length > 0) {
+        cells.push(field);
+        rows.push(cells);
+    }
+    return rows;
+}

package/dist/registers/appstore.js

@@ -7,6 +7,7 @@ import * as appstoreRelease from '../appstore/release.js';
 import * as appstoreDeclarations from '../appstore/declarations.js';
 import * as testflight from '../appstore/testflight.js';
 import * as previews from '../appstore/previews.js';
+import * as appstoreSales from '../appstore/sales.js';
 import { createAppleOneTimePurchase, createAppleSubscription, updateAppleProduct, deleteAppleProduct, listAppleProducts, } from '@onesub/providers';
 import { requireAppStoreCreds } from '../helpers.js';
 import { buildAppStoreReleasePlan } from '../checks/plan.js';
@@ -1492,4 +1493,59 @@ export function registerAppstoreTools(server) {
             : await previews.deletePreviewSet(setId);
         return textResult(`✅ 삭제 완료 — ${r.id}`);
     });
+    server.tool('appstore_get_sales_report', [
+        'Sales and Trends 리포트 = **실매출의 기준선** — GET /v1/salesReports (gzip TSV 를 파싱해 돌려준다).',
+        '분석 이벤트(GA4 in_app_purchase 등)로 매출을 세면 안 되는 이유가 여기 있다:',
+        'TestFlight·Xcode 설치의 결제는 **sandbox 라 청구가 0원인데도** 클라이언트에는 성공한 결제로 보여',
+        '이벤트가 그대로 나간다. 이 리포트에는 sandbox 가 애초에 들어오지 않으므로, 둘을 비교하면',
+        '"진짜 돈이 들어온 건수"가 곧바로 갈린다.',
+        '⚠️ **Developer Proceeds 는 1개당 금액이다** — 총액은 units 를 곱해야 한다(이 도구는 곱해서 준다).',
+        '⚠️ 환불은 units 가 **음수**로 들어와 합계에서 상쇄된다. 즉 합계는 순매출이다.',
+        '⚠️ 데이터가 없는 날짜는 Apple 이 404 를 주므로 datesWithoutData 로 따로 돌려준다 —',
+        '"매출 0" 과 "리포트 미생성/설정 오류"를 섞지 말 것. 당일치는 보통 아직 없다.',
+        'vendorNumber 는 ~/.mimi-seed/appstore.json 에 저장해두면 생략 가능.',
+    ].join(' '), {
+        startDate: z.string().describe('시작일 YYYY-MM-DD (DAILY 가 아니면 이 값이 곧 reportDate)'),
+        endDate: z
+            .string()
+            .optional()
+            .describe('종료일 YYYY-MM-DD (포함). DAILY 에서만 의미가 있고 최대 62일'),
+        frequency: z
+            .enum(['DAILY', 'WEEKLY', 'MONTHLY', 'YEARLY'])
+            .optional()
+            .describe('집계 단위 (기본 DAILY)'),
+        reportType: z
+            .string()
+            .optional()
+            .describe('기본 SALES. 구독 분석은 SUBSCRIPTION / SUBSCRIPTION_EVENT / SUBSCRIBER'),
+        reportSubType: z.string().optional().describe('기본 SUMMARY. 상세는 DETAILED'),
+        version: z
+            .string()
+            .optional()
+            .describe('리포트 버전 (기본 1_0). SUBSCRIPTION 계열은 1_3 등 다른 버전을 요구할 수 있다'),
+        vendorNumber: z
+            .string()
+            .optional()
+            .describe('판매자 번호. 생략 시 ~/.mimi-seed/appstore.json 의 vendorNumber 사용'),
+    }, async (args) => jsonResult(await appstoreSales.getSalesReport(args)));
+    server.tool('appstore_get_finance_report', [
+        '재무(정산) 리포트 — GET /v1/financeReports. 실제로 지급되는 금액 기준이라',
+        'Sales and Trends(판매 시점 집계)와 숫자가 다를 수 있다.',
+        '⚠️ **reportDate 는 Apple 회계월이다** — 달력월과 어긋난다(회계연도가 9월 말에 시작).',
+        '요청한 달과 다른 기간이 돌아오면 버그가 아니라 이것이다. 매출 건수를 세는 목적이면',
+        'appstore_get_sales_report(달력 날짜 기준)를 쓰는 편이 낫다.',
+        'regionCode 는 ZZ(전 지역 통합)가 기본이고, FINANCE_DETAIL 은 보통 Z1 을 쓴다.',
+        '컬럼 구성이 리포트마다 달라 파싱한 행을 그대로 돌려준다.',
+    ].join(' '), {
+        reportDate: z.string().describe('YYYY-MM (Apple 회계월)'),
+        regionCode: z.string().optional().describe('지역 코드 (기본 ZZ = 전 지역 통합)'),
+        reportType: z
+            .enum(['FINANCIAL', 'FINANCE_DETAIL'])
+            .optional()
+            .describe('기본 FINANCIAL'),
+        vendorNumber: z
+            .string()
+            .optional()
+            .describe('판매자 번호. 생략 시 ~/.mimi-seed/appstore.json 의 vendorNumber 사용'),
+    }, async (args) => jsonResult(await appstoreSales.getFinanceReport(args)));
 }

package/dist/registers/billing.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerBillingTools(server: McpServer): void;

package/dist/registers/billing.js

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+import * as billing from '../billing/tools.js';
+import { requireAuth } from '../helpers.js';
+import { CLOUD_PLATFORM_SCOPE } from '../auth/scopes.js';
+import { jsonResult } from '../lib/mcp-response.js';
+export function registerBillingTools(server) {
+    server.tool('gcp_get_billing_info', [
+        '프로젝트의 결제 상태 조회 — Blaze(결제 계정 연결) 여부와 연결된 결제 계정 ID.',
+        'Cloud Functions/Run 배포 전 필수 확인.',
+        '⚠️ Cloud Billing API 가 꺼져 있으면 403 이 난다 — 그건 "Spark 이라서"가 아니라 조회 자체가 막힌 것이다.',
+        '그 경우 firebase_enable_service(projectId, "cloudbilling.googleapis.com") 로 먼저 켠 뒤 다시 호출.',
+    ].join(' '), {
+        projectId: z.string().describe('GCP/Firebase 프로젝트 ID'),
+    }, async ({ projectId }) => {
+        const auth = await requireAuth(CLOUD_PLATFORM_SCOPE);
+        return jsonResult(await billing.getBillingInfo(auth, projectId));
+    });
+    server.tool('gcp_list_billing_projects', [
+        '결제 계정에 붙은 프로젝트 목록 = **비용 범위 확인**.',
+        '프로젝트가 2개 이상이면(shared=true) 그 계정은 공용이므로 **계정 전체 예산은 쓰지 말 것** —',
+        '기존 지출만으로 임계를 즉시 넘겨 알림이 소음이 된다. gcp_create_budget 에 projectIds 를 넘겨 범위를 좁힌다.',
+    ].join(' '), {
+        billingAccount: z
+            .string()
+            .describe('결제 계정 ID (예: 01F1F4-FD007B-2973A7 또는 billingAccounts/01F1F4-...)'),
+        quotaProjectId: z
+            .string()
+            .optional()
+            .describe('quota 주체 프로젝트 — Cloud Billing/Budget API 를 켜 둔 프로젝트 ID. 생략하면 OAuth 클라이언트 프로젝트로 quota 가 잡혀 403 이 난다(에러 메시지의 프로젝트 번호는 조회 대상이 아니라 OAuth 쪽이다).'),
+    }, async ({ billingAccount, quotaProjectId }) => {
+        const auth = await requireAuth(CLOUD_PLATFORM_SCOPE);
+        return jsonResult(await billing.listBillingProjects(auth, billingAccount, quotaProjectId));
+    });
+    server.tool('gcp_list_budgets', '결제 계정의 예산 목록 (금액·프로젝트 필터·알림 임계). 중복 생성 전 확인용.', {
+        billingAccount: z.string().describe('결제 계정 ID'),
+        quotaProjectId: z
+            .string()
+            .optional()
+            .describe('quota 주체 프로젝트 — Cloud Billing/Budget API 를 켜 둔 프로젝트 ID. 생략하면 OAuth 클라이언트 프로젝트로 quota 가 잡혀 403 이 난다(에러 메시지의 프로젝트 번호는 조회 대상이 아니라 OAuth 쪽이다).'),
+    }, async ({ billingAccount, quotaProjectId }) => {
+        const auth = await requireAuth(CLOUD_PLATFORM_SCOPE);
+        return jsonResult(await billing.listBudgets(auth, billingAccount, quotaProjectId));
+    });
+    server.tool('gcp_create_budget', [
+        '예산 + 알림 임계 생성.',
+        '⚠️ **예산은 알림만 한다. 지출을 막지 않는다.** 하드 차단은 Pub/Sub→결제해제 함수뿐이고 그건 앱을 죽인다.',
+        '실질 방어는 각 서비스의 상한(예: Cloud Functions maxInstances)이고 예산은 트립와이어다.',
+        '⚠️ GCP 에 **일 예산은 없다** — 기간은 월(기본)/분기/연/사용자지정뿐. "하루 N원"을 원하면 월 환산하거나,',
+        '실사용이 적을 때는 작은 월 예산을 알람으로 쓰는 게 더 빨리 잡힌다.',
+        'projectIds 를 반드시 고려할 것 — 공용 결제 계정에서 생략하면 알림이 소음이 된다(gcp_list_billing_projects 로 먼저 확인).',
+        '권한은 결제 계정 레벨 IAM 이라 서비스 계정 키로는 대개 403 — 사용자 OAuth 로 호출된다.',
+    ].join(' '), {
+        billingAccount: z.string().describe('결제 계정 ID'),
+        displayName: z.string().describe('예산 이름 (예: "my-app functions 감시")'),
+        amountUnits: z
+            .number()
+            .int()
+            .positive()
+            .describe('통화 단위 정수 금액. KRW 는 소수 없음 — 10000 = ₩10,000'),
+        currencyCode: z.string().optional().describe('통화 코드 (기본 KRW). 결제 계정 통화와 일치해야 한다'),
+        projectIds: z
+            .array(z.string())
+            .optional()
+            .describe('감시할 프로젝트 ID 목록. 생략하면 결제 계정 전체 — 공용 계정이면 권장하지 않음'),
+        thresholds: z
+            .array(z.number().min(0).max(1))
+            .optional()
+            .describe('알림 임계 비율 0~1 (기본 [0.5, 0.9, 1.0])'),
+        quotaProjectId: z
+            .string()
+            .optional()
+            .describe('quota 주체 프로젝트 — Cloud Billing/Budget API 를 켜 둔 프로젝트 ID. 생략하면 OAuth 클라이언트 프로젝트로 quota 가 잡혀 403 이 난다(에러 메시지의 프로젝트 번호는 조회 대상이 아니라 OAuth 쪽이다).'),
+    }, async ({ billingAccount, displayName, amountUnits, currencyCode, projectIds, thresholds, quotaProjectId, }) => {
+        const auth = await requireAuth(CLOUD_PLATFORM_SCOPE);
+        const budget = await billing.createBudget(auth, {
+            billingAccount,
+            displayName,
+            amountUnits,
+            currencyCode,
+            projectIds,
+            thresholds,
+            quotaProjectId,
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: [
+                        '✓ 예산 생성 완료',
+                        '',
+                        `**name**: \`${budget.name}\``,
+                        `**displayName**: ${budget.displayName}`,
+                        `**범위**: ${budget.projects.length ? budget.projects.join(', ') : '결제 계정 전체'}`,
+                        `**알림 임계**: ${budget.thresholds.map((t) => `${Math.round(t * 100)}%`).join(' / ')}`,
+                        '',
+                        '⚠️ 이 예산은 **알림만** 한다 — 임계를 넘어도 지출은 계속된다.',
+                    ].join('\n'),
+                },
+            ],
+        };
+    });
+}

package/dist/registers/playstore.js

@@ -7,6 +7,7 @@ import { saveServiceAccountJsonForPackage, listRegisteredServiceAccounts, delete
 import { createGoogleOneTimePurchase, createGoogleSubscription, updateGoogleProduct, deleteGoogleProduct, listGoogleProducts, } from '@onesub/providers';
 import { requirePlayStoreAuth, requireServiceAccountJson, requireAuth } from '../helpers.js';
 import { PLAY_DEVELOPER_REPORTING_SCOPE } from '../auth/scopes.js';
+import * as playFinancials from '../playstore/financials.js';
 import * as iam from '../iam/tools.js';
 import { buildPlayStoreReleasePlan } from '../checks/plan.js';
 import { validatePlayReleaseNotes, formatIssuesForUser } from '../lib/text-validators.js';
@@ -913,4 +914,45 @@ export function registerPlaystoreTools(server) {
         const r = await playstore.cancelRecoveryAction(auth, packageName, appRecoveryId);
         return textResult(`✅ 복구 액션 취소 — ${r.appRecoveryId}`);
     });
+    server.tool('playstore_list_financial_reports', [
+        'Play 재무 리포트 파일 목록 (Cloud Storage 버킷).',
+        '⚠️ **Play Developer API 에는 매출 엔드포인트가 없다.** purchases.* 는 구매 토큰을 이미 알아야 하고',
+        'Reporting API 는 vitals 뿐이다. 실제 정산 데이터는 Play Console 이 매달 개발자 소유 GCS 버킷에',
+        '떨궈주는 CSV 가 유일한 소스라, 이 도구는 그 버킷을 훑는다.',
+        '버킷 이름(gs://pubsite_prod_...)은 Play Console > 다운로드 보고서 > 재무 에만 있고 API 로 못 얻는다 —',
+        '~/.mimi-seed/play-financials.json 에 한 번 저장해두면 이후 생략 가능.',
+        '⚠️ 접근 권한은 **GCP IAM 이 아니다.** 이 버킷은 Google 소유라 프로젝트에 roles/storage.* 를 줘도 닿지 않는다 —',
+        'Play Console > 사용자 및 권한 에서 서비스 계정 이메일을 초대하고 "재무 데이터 보기"를 전체(Global)로 줘야 열린다.',
+        '앱 게시용 Play Developer API 권한과 별개라, 릴리스가 되는 계정이라고 리포트가 열려 있지는 않다.',
+        '재무 리포트는 월 마감 후에 올라오므로 이번 달 파일이 없는 것은 정상이다.',
+    ].join(' '), {
+        packageName: z.string().optional().describe('패키지명 — 패키지별 서비스 계정·버킷 설정을 고를 때 사용'),
+        bucket: z.string().optional().describe('버킷 이름 또는 gs:// URI. 생략 시 저장된 설정 사용'),
+        reportType: z
+            .enum(['earnings', 'sales'])
+            .optional()
+            .describe('생략하면 버킷 전체. earnings=정산(수수료·세금 포함), sales=주문 단위'),
+    }, async (args) => jsonResult(await playFinancials.listFinancialReports(args)));
+    server.tool('playstore_get_financial_report', [
+        'Play 재무 리포트를 내려받아 파싱·집계한다 = **Play 실매출의 기준선**.',
+        '분석 이벤트로는 라이선스 테스터·내부 테스트 결제를 실결제와 구분할 수 없다',
+        '(둘 다 install_source 가 com.android.vending 이다). 청구가 0원인 테스터 주문은',
+        '이 리포트에 **아예 나타나지 않으므로**, 여기 없으면 실매출이 아니다.',
+        'earnings: Transaction Type 이 Charge/Google fee/Tax/환불로 나뉘고 수수료·세금이 음수로 들어와',
+        'netByMerchantCurrency 는 이미 순액이다. **Charge 행만이 실제 구매다.**',
+        'sales: 주문 번호 단위라 개별 주문을 짚을 때 쓴다.',
+        '⚠️ 정산 통화마다 파일이 따로 떨어지므로 한 달치가 여러 파일일 수 있다 — 전부 합쳐서 집계한다.',
+    ].join(' '), {
+        yearMonth: z.string().describe('YYYYMM 또는 YYYY-MM'),
+        packageName: z.string().optional().describe('패키지명 — 패키지별 서비스 계정·버킷 설정을 고를 때 사용'),
+        bucket: z.string().optional().describe('버킷 이름 또는 gs:// URI. 생략 시 저장된 설정 사용'),
+        reportType: z
+            .enum(['earnings', 'sales'])
+            .optional()
+            .describe('기본 earnings(정산). 주문 단위로 보려면 sales'),
+        includeRows: z
+            .boolean()
+            .optional()
+            .describe('원본 행까지 전부 반환. 건수가 많으면 응답이 매우 커진다'),
+    }, async (args) => jsonResult(await playFinancials.getFinancialReport(args)));
 }

package/dist/server.js

@@ -3,6 +3,7 @@ import { registerFirebaseTools } from './registers/firebase.js';
 import { registerAdmobTools } from './registers/admob.js';
 import { registerPlaystoreTools } from './registers/playstore.js';
 import { registerIamTools } from './registers/iam.js';
+import { registerBillingTools } from './registers/billing.js';
 import { registerAppstoreTools } from './registers/appstore.js';
 import { registerChecksTools } from './registers/checks.js';
 import { registerAiTools } from './registers/ai.js';
@@ -38,6 +39,7 @@ export function buildServer(version) {
     registerAdmobTools(server);
     registerPlaystoreTools(server);
     registerIamTools(server);
+    registerBillingTools(server);
     registerAppstoreTools(server);
     registerChecksTools(server);
     registerAiTools(server);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yoonion/mimi-seed-mcp",
-  "version": "0.15.6",
+  "version": "0.17.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": {

package/tool-manifest.json

@@ -1,6 +1,6 @@
 {
   "$comment": "등록된 MCP 도구 + 도메인 메타데이터(label·credential·summary)의 SSOT. src/__tests__/tool-manifest.test.ts 가 실제 서버 등록 목록과 diff 하고 메타데이터 정합성을 검사한다. 도구 추가/삭제/개명 시 이 파일을 함께 갱신할 것 — 산문 문서에는 정확한 개수를 쓰지 말고 이 파일을 가리킬 것. mimi-seed://tools/catalog 리소스가 이 파일을 그대로 서빙한다.",
-  "total": 222,
+  "total": 230,
   "domains": {
     "admob": {
       "label": "AdMob",
@@ -38,7 +38,7 @@
     "appstore": {
       "label": "App Store Connect",
       "credential": "ASC API 키 (mimi-seed auth appstore)",
-      "summary": "버전·빌드 attach·What's New·스크린샷·IAP 심사 메타데이터·심사 제출",
+      "summary": "버전·빌드 attach·What's New·스크린샷·IAP 심사 메타데이터·심사 제출·매출/재무 리포트",
       "tools": [
         "appstore_list_apps",
         "appstore_verify_credentials",
@@ -100,7 +100,9 @@
         "appstore_notify_beta_testers",
         "appstore_list_previews",
         "appstore_upload_preview",
-        "appstore_delete_preview"
+        "appstore_delete_preview",
+        "appstore_get_sales_report",
+        "appstore_get_finance_report"
       ]
     },
     "auth": {
@@ -126,6 +128,17 @@
         "bigquery_auth_status"
       ]
     },
+    "billing": {
+      "label": "GCP Billing",
+      "credential": "Google OAuth",
+      "summary": "결제 상태(Blaze 여부)·비용 범위(공용 계정 판별)·예산 알림",
+      "tools": [
+        "gcp_get_billing_info",
+        "gcp_list_billing_projects",
+        "gcp_list_budgets",
+        "gcp_create_budget"
+      ]
+    },
     "checks": {
       "label": "출시 점검",
       "credential": "점검 대상 스토어의 자격증명",
@@ -274,7 +287,7 @@
     "playstore": {
       "label": "Google Play",
       "credential": "Google OAuth (CI/헤드리스는 Play 서비스 계정)",
-      "summary": "리스팅·트랙 릴리스·이미지·리뷰 답변·통계·서비스 계정 등록",
+      "summary": "리스팅·트랙 릴리스·이미지·리뷰 답변·통계·서비스 계정 등록·재무 리포트",
       "tools": [
         "playstore_get_app",
         "playstore_update_details",
@@ -312,7 +325,9 @@
         "playstore_list_recovery_actions",
         "playstore_create_recovery_action",
         "playstore_deploy_recovery_action",
-        "playstore_cancel_recovery_action"
+        "playstore_cancel_recovery_action",
+        "playstore_list_financial_reports",
+        "playstore_get_financial_report"
       ]
     },
     "threads": {