@yoonion/mimi-seed-mcp 0.15.6 → 0.16.0

package/README.md

@@ -75,7 +75,7 @@ export ANTHROPIC_API_KEY=sk-ant-...
 
 ---
 
-## 제공 도구 (150+ 개 · 20개 영역)
+## 제공 도구 (150+ 개 · 21개 영역)
 
 | 영역 | 도구 수 | 주요 도구 |
 |------|---------|-----------|
@@ -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,7 @@ 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` |
 | 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/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/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/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.16.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": 226,
   "domains": {
     "admob": {
       "label": "AdMob",
@@ -126,6 +126,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": "점검 대상 스토어의 자격증명",