@yoonion/mimi-seed-mcp 0.10.2 → 0.11.0

package/README.md

@@ -108,6 +108,7 @@ MCP 클라이언트(Claude Code, Codex 등)에서 슬래시 커맨드로 바로
 
 | 커맨드 | 설명 |
 |--------|------|
+| `/mimi-seed:getting-started` | 처음 사용자 온보딩 — 연결 스캔 → 능력 투어 → 첫 읽기 전용 액션 |
 | `/mimi-seed:deploy` | 블로커 점검 → 릴리즈 노트 생성 → 스토어 적용을 한 번에 |
 | `/mimi-seed:health` | 인증 상태 + 앱 출시 준비도 빠른 요약 |
 | `/mimi-seed:review-inbox` | 미답변 리뷰 조회 → AI 답변 초안 생성 |
@@ -117,7 +118,8 @@ MCP 클라이언트(Claude Code, Codex 등)에서 슬래시 커맨드로 바로
 | URI | 설명 |
 |-----|------|
 | `mimi-seed://auth/status` | Google OAuth 토큰 상태 (JSON) |
-| `mimi-seed://agent/guide` | 에이전트 역할 정의 — 출시 워크플로우·주의사항 (Markdown) |
+| `mimi-seed://agent/guide` | 에이전트 운영 규약 전문 — deferred 도구 로딩·`select:` 배치·호출 순서·안전수칙 (Markdown) |
+| `mimi-seed://tools/catalog` | 도메인별 전체 도구 목록 + 필요 자격증명 + 요약 (JSON) — "뭘 할 수 있어?"의 런타임 답 |
 
 ---
 

package/assets/agent-guide.md

@@ -0,0 +1,239 @@
+# Agent Guide — Driving Mimi Seed from an AI
+
+> How an AI coding agent (Claude Code, Codex, Cursor, …) should call the Mimi Seed
+> MCP tools correctly. If you are an agent and a user asks you to do app-store /
+> Firebase / AdMob / CI work through `@yoonion/mimi-seed-mcp`, read this first.
+
+The human-facing install + feature docs live in [`README.md`](../README.md). This file
+is the **operational contract for agents**: how tools load, what order to call them in,
+and which actions are irreversible.
+
+> **Building or modifying the SDK itself?** The structural companion to this guide — architecture, the full tool
+> catalog, the auth/credential model, and pitfalls — lives in the domain ontology under
+> [`docs/domain/`](domain/_index.md). This guide is *how to call* the tools; the ontology is *how they're built*.
+
+---
+
+## 0. The one thing that trips every agent: deferred tools
+
+Mimi Seed exposes **150+ MCP tools** across 18 domains (full inventory:
+[`docs/domain/tool-catalog.md`](domain/tool-catalog.md)). Harnesses that lazy-load large tool catalogs —
+**Claude Code most notably** — register these tools as **deferred**: the tool *names*
+are visible (in a system reminder), but the **input schemas are not loaded**. If you
+call a deferred tool directly, it fails with `InputValidationError` ("schema not
+loaded"), and it is easy to wrongly conclude "this tool doesn't exist."
+
+**Always load the schema before the first call.** In Claude Code:
+
+```
+ToolSearch(query="select:<tool_name>[,<tool_name>...]")
+```
+
+- Batch every tool you expect to use in one `select:` call — schemas stay loaded for
+  the rest of the session.
+- If `select:` returns no match, fall back to a keyword search
+  (`ToolSearch(query="playstore release promote")`) — exact names sometimes differ.
+- Only if a tool is absent from the deferred list **and** unsearchable is it truly
+  unregistered. Then check the MCP server is connected (see §2), do **not** silently
+  pivot to raw `curl` / `fastlane`.
+
+Other harnesses (Codex with the bundled plugin, Claude Desktop) typically expose the
+tools directly — but the *call order* and *safety rules* below still apply.
+
+### Ready-made `select:` batches
+
+| Goal | `ToolSearch` query |
+|------|--------------------|
+| First contact / "what's connected?" | `select:mimi_seed_status,mimi_seed_auth_status,mimi_seed_auth_start,mimi_seed_remote_sync_credentials` |
+| Play Store release | `select:playstore_get_app,playstore_list_tracks,playstore_update_latest_release_notes,playstore_promote_release,playstore_submit_release,playstore_check_submission_risks,playstore_plan_release` |
+| Play Store listing + images | `select:playstore_get_listing,playstore_update_listing,playstore_upload_image,playstore_list_images,playstore_replace_images,playstore_delete_all_images` |
+| App Store / TestFlight | `select:appstore_list_apps,appstore_list_versions,appstore_create_version,appstore_get_metadata,appstore_update_whats_new,appstore_list_builds,appstore_attach_latest_build,appstore_submit_for_review,appstore_check_submission_risks,appstore_plan_release` |
+| App Store screenshots | `select:appstore_list_app_info_localizations,appstore_get_metadata,appstore_list_screenshots,appstore_upload_screenshot,appstore_delete_screenshot_set,screenshot_validate` |
+| App Store IAP review metadata | `select:appstore_list_apps,appstore_list_products,appstore_update_product_review_note,appstore_upload_product_review_screenshot` |
+| Release notes from commits | `select:generate_release_notes_from_commits,playstore_update_release_notes,appstore_update_whats_new` |
+| Firebase setup | `select:firebase_list_projects,firebase_get_project,firebase_create_project,firebase_create_android_app,firebase_create_ios_app,firebase_get_android_config,firebase_enable_common_services` |
+| AdMob | `select:admob_list_accounts,admob_list_apps,admob_create_ad_unit,admob_list_ad_units,admob_get_today_earnings,admob_get_report` |
+| Jenkins credentials + jobs | `select:jenkins_status,jenkins_save_config,jenkins_list_credentials,jenkins_create_credential,jenkins_upload_keystore,jenkins_upload_playstore_sa,jenkins_list_jobs,jenkins_get_job_config,jenkins_create_job,jenkins_update_job` |
+| CI (GitHub/GitLab) | `select:ci_save_config,ci_list_workflows,ci_trigger_build,ci_get_build_status,ci_list_recent_builds` |
+| Service account end-to-end | `select:iam_create_service_account,iam_create_key,iam_add_iam_policy_binding,playstore_register_service_account,playstore_verify_service_account` |
+
+---
+
+## 1. Always start with `mimi_seed_status`
+
+Before any task, call **`mimi_seed_status`** — the setup doctor. It scans your service
+credentials (Google OAuth · Play SA · App Store · Jenkins · CI · Google Ads · Facebook · Instagram ·
+Threads · BigQuery) and returns a ✅/❌ report plus the exact next tool to call for anything
+missing. This avoids a late `401`/`403` deep into a workflow.
+
+> If the repo has a **`.mimi-seed.json`** manifest at its root, `mimi_seed_status` (and
+> `mimi-seed doctor`) additionally report **which project-required services this teammate is
+> missing** + the precise fix command — use that section to onboard a new teammate.
+> **BigQuery** can be satisfied per-machine (`mimi-seed-bigquery-auth`) **or** workspace-wide:
+> a workspace admin registers a shared service account once and every member queries via the
+> **Remote MCP** with no personal key (`register_integration(provider="bigquery", …)`).
+
+If auth is missing or expired, the shortest path for a human is **`mimi-seed setup`** — one guided pass over
+every credential, which also tells them where to obtain each token
+([`credentials.md`](credentials.md)). Per-credential fixes:
+
+| Service | Fix |
+|---------|-----|
+| Google (Firebase/AdMob/Play/Ads/GSC/GA4/IAM/BigQuery) | tool `mimi_seed_auth_start` → give the user the OAuth URL, **or** `mimi-seed auth login` |
+| App Store Connect | `mimi-seed auth appstore` → verify with `appstore_verify_credentials` |
+| Play service account | `mimi-seed auth playstore`, or register per-package with `playstore_register_service_account`. **Optional** — the OAuth token carries `androidpublisher`, so this is only needed for headless/CI |
+| BigQuery | `mimi-seed auth bigquery` (optional — OAuth works too) |
+| Jenkins | `mimi-seed auth jenkins` (probes the server before saving) |
+| GitHub / GitLab CI | `mimi-seed auth ci` |
+| Google Ads | `mimi-seed auth googleads` — needs the `adwords` OAuth scope; an old token may need `mimi-seed auth login --force` |
+| Facebook / Instagram / Threads | `mimi-seed auth facebook` / `mimi-seed auth instagram` / `mimi-seed auth threads` |
+
+`mimi-seed auth meta` opens the combined social setup entry point when the user wants to review or reconnect
+all three Meta platforms in one pass.
+
+Each `mimi-seed auth <cred>` wraps the matching `npx -y @yoonion/mimi-seed-mcp mimi-seed-*-auth` binary, so
+either form works.
+
+For Facebook, Instagram, and Threads, `mimi-seed setup` reads the saved expiry estimate. Expired tokens and
+tokens with seven days or less remaining are automatically put back into the setup plan. A live Meta rejection
+(including OAuth code 190) returns the exact `mimi-seed auth <platform>` recovery command instead of a raw error.
+For an unexpired Threads long-lived token, `threads_refresh_token` (also the default path in `mimi-seed auth
+threads`) refreshes it without asking the user to paste a replacement. Expired or revoked tokens still require a
+new authorization.
+
+---
+
+## 2. Auth & credential model
+
+Credentials live under `~/.mimi-seed/` (legacy `~/.preseed/` is still read):
+
+| File | Used for |
+|------|----------|
+| `tokens.json` | Google OAuth (Firebase, AdMob, Play Developer API, IAM, BigQuery) |
+| `appstore.json` | App Store Connect API key (JWT) |
+| `play-service-accounts/<packageName>.json` | **per-package** Play service account |
+| `play-service-account.json` | default/legacy Play SA (fallback when no per-package match) |
+| `bigquery-service-account.json` | BigQuery SA (exempt from Workspace reauth; OAuth is the fallback) |
+| `jenkins.json`, `ci.json` | Jenkins / GitHub-GitLab CI connection |
+| `google-ads.json` | Google Ads developer token + customer id |
+| `facebook.json`, `instagram.json`, `threads.json` | Page / account access tokens for the social post tools (Threads is a separate Meta account/token) |
+
+Notes that matter in practice:
+
+- **Per-package Play SA wins over the default.** Different apps can use SAs from
+  different GCP projects. `playstore_list_service_accounts` shows the mapping.
+- The Play SA's **GCP project must have the Android Publisher API enabled**, or every
+  `playstore_*` call returns `403`.
+- AI features (`generate_release_notes_from_commits`, `generate_review_reply`) need
+  `ANTHROPIC_API_KEY` in the environment.
+
+---
+
+## 3. Tool catalog (by domain)
+
+Full schemas load on demand via `ToolSearch`. These are representative tools, not a full list — the exact
+per-domain inventory is [`docs/domain/tool-catalog.md`](domain/tool-catalog.md).
+
+| Domain | Representative tools |
+|--------|----------------------|
+| **Google Play** | `playstore_get_app` · `playstore_get_listing` · `playstore_update_listing` · `playstore_list_tracks` · `playstore_update_latest_release_notes` · `playstore_promote_release` · `playstore_submit_release` · `playstore_upload_image` · `playstore_replace_images` · `playstore_check_submission_risks` · `playstore_get_statistics` · `playstore_reply_review` · `playstore_register_service_account` |
+| **App Store Connect** | `appstore_list_apps` · `appstore_list_versions` · `appstore_create_version` · `appstore_update_whats_new` · `appstore_update_localization` · `appstore_list_builds` · `appstore_attach_latest_build` · `appstore_upload_screenshot` · `appstore_submit_for_review` · `appstore_cancel_review` · `appstore_list_beta_groups` · `appstore_reply_review` |
+| **Firebase** | `firebase_create_project` · `firebase_create_android_app` · `firebase_create_ios_app` · `firebase_get_android_config` · `firebase_enable_service` · `firebase_enable_common_services` · `firebase_list_*_apps` |
+| **AdMob** | `admob_create_app` · `admob_create_ad_unit` · `admob_list_ad_units` · `admob_get_today_earnings` · `admob_get_report` |
+| **CI/CD** | `ci_trigger_build` · `ci_get_build_status` · `ci_list_workflows` (**GitHub Actions / GitLab only**) |
+| **Jenkins** (credentials + jobs) | `jenkins_status` · `jenkins_save_config` · `jenkins_create_credential` · `jenkins_upload_keystore` · `jenkins_upload_playstore_sa` · `jenkins_create_job` · `jenkins_update_job` |
+| **Google Cloud IAM** | `iam_create_service_account` · `iam_create_key` · `iam_add_iam_policy_binding` |
+| **BigQuery** | `bigquery_run_query` · `bigquery_list_datasets` · `bigquery_get_table_schema` |
+| **Search Console** | `gsc_inspect_url` · `gsc_search_analytics` · `gsc_submit_sitemap` |
+| **Facebook / Instagram / Threads** | `facebook_post_photo` · `instagram_post_carousel` · `threads_post` · `threads_refresh_token` |
+| **Checks** | `playstore_check_submission_risks` · `appstore_check_submission_risks` · `screenshot_validate` · `release_status` |
+| **AI / Auth** | `generate_release_notes_from_commits` · `generate_review_reply` · `mimi_seed_status` · `mimi_seed_auth_start` · `mimi_seed_auth_status` · `mimi_seed_remote_sync_credentials` |
+
+---
+
+## 4. Workflows (call sequences)
+
+### Play Store release / promote
+1. `playstore_list_tracks` — see current track/version state.
+2. `playstore_check_submission_risks` (or `playstore_plan_release`) — surface blockers.
+3. Write missing listing/notes (`playstore_update_listing`, `playstore_update_latest_release_notes`, `playstore_upload_image`).
+4. `playstore_promote_release` / `playstore_submit_release` — **confirm first** (see §5).
+
+### App Store TestFlight → review
+1. `appstore_list_apps` → `appstore_list_versions` (or `appstore_create_version`).
+2. `appstore_list_builds` → `appstore_attach_latest_build` (only `processingState=VALID`).
+3. `appstore_update_whats_new`, screenshots if needed.
+4. `appstore_check_submission_risks` → `appstore_submit_for_review` — **confirm first**.
+
+### Release notes from git
+`generate_release_notes_from_commits` (pass commit array + locales) → review with user →
+`playstore_update_release_notes` / `appstore_update_whats_new`.
+
+> **Mimi Seed does not compile app binaries.** It manages metadata, store releases, and
+> CI/Jenkins *credentials and job definitions* — not Xcode/Gradle builds. To produce an
+> `.ipa`/`.aab`, use EAS, Xcode, or a CI/Jenkins job. There is **no `jenkins_trigger_build`
+> tool**; trigger a Jenkins job via its REST API and use the `jenkins_*` tools for
+> credentials and job configs.
+
+---
+
+## 5. Safety — irreversible actions need explicit confirmation
+
+Never run these without the user's go-ahead in the same turn:
+
+| Action | Why |
+|--------|-----|
+| `playstore_submit_release` / `playstore_promote_release` with `status=completed` | Starts Google review / full rollout. Near-irreversible. |
+| `appstore_submit_for_review` | Submits to Apple review. |
+| `appstore_delete_screenshot_set`, `playstore_delete_all_images` | Deletes assets. |
+| `playstore_delete_product`, `jenkins_delete_credential`, `firebase_delete_*_app` | Destructive. |
+
+General rules:
+- Run `*_check_submission_risks` / `*_plan_release` **before** submitting, and show
+  blockers to the user as a checklist first.
+- Pass file paths as **absolute paths**; never load image bytes into the conversation.
+- Prefer `status=draft` while iterating; flip to `completed` only on explicit request.
+
+---
+
+## 6. Known gotchas (learned the hard way)
+
+- **Draft-app track constraint (Play).** Until an app has its first non-internal
+  publish, only the **`internal`** track can be `completed`. `alpha`/`beta`/`production`
+  reject anything but `draft` → error: *"Only releases with status draft may be created
+  on draft app."* Closed/open testing also needs the **App Content** declarations
+  (content rating, data safety, target audience) which are **Console-only** — the API
+  cannot set them.
+- **A `403` on one write but not another is usually NOT a permissions gap.** Every
+  `playstore_*` write resolves the same credential (`requirePlayStoreAuth`), so if
+  `playstore_upload_image` succeeds but `playstore_update_listing` returns `403`, the
+  account's permissions are fine. Read the **raw Google reason** surfaced in the error
+  (app state, policy, or an operation-specific restriction) instead of blindly
+  "granting permission" — the friendly 403 message now includes that reason.
+- **Play edits overwrite un-published Console changes.** Committing *any* Play
+  Developer API edit (image upload, listing update, release) discards listing/release
+  changes you saved-but-didn't-publish in the Play Console UI. Google's own docs warn
+  against editing the same app with both tools at once. Do all listing writes via the
+  API, or finish & publish your Console edits first — never interleave them.
+- **`ci_*` is GitHub/GitLab only.** It does not trigger Jenkins builds.
+- **Reward/cash-out apps** are a sensitive Play category — flag policy implications to
+  the user, but it does not block test-track distribution.
+
+---
+
+## 7. Slash commands & MCP resources
+
+Available in any MCP client as native slash commands:
+
+- `/mimi-seed:getting-started` — first-run onboarding: status scan → capability tour → first read-only action
+- `/mimi-seed:deploy` — blockers → release notes → apply to stores
+- `/mimi-seed:health` — auth status + readiness summary
+- `/mimi-seed:review-inbox` — fetch unanswered reviews → draft replies
+
+MCP resources: `mimi-seed://auth/status` (live token state) · `mimi-seed://agent/guide`
+(this guide, served over MCP) · `mimi-seed://tools/catalog` (the full tool inventory by
+domain, with the credential each domain needs — read it to answer "what can Mimi Seed do?").
+
+---
+
+_Keep this guide in sync with `README.md`'s tool list and the `skills/` directory._

package/dist/instagram/api.js

@@ -66,6 +66,23 @@ export async function fetchUserId(accessToken) {
     }
     return id;
 }
+// 이미지/캐러셀 컨테이너는 Meta 서버 처리가 끝난 뒤에만 publish 할 수 있다.
+// 완료 전에 media_publish 를 호출하면 code 9007/2207027 이 반환된다.
+async function waitForContainer(cfg, containerId) {
+    const MAX_ATTEMPTS = 20;
+    const INTERVAL_MS = 3000; // 최대 ~60초 대기
+    for (let i = 0; i < MAX_ATTEMPTS; i++) {
+        const { status_code, status } = await igFetch(cfg.accessToken, `/${containerId}`, { fields: 'status_code,status', access_token: cfg.accessToken });
+        const current = status_code ?? status;
+        if (current === 'FINISHED')
+            return;
+        if (current === 'ERROR' || current === 'EXPIRED') {
+            throw new Error(`Instagram 미디어 처리 실패 (${current}).`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, INTERVAL_MS));
+    }
+    throw new Error('Instagram 미디어 처리 대기 시간 초과 (60초). 잠시 후 다시 시도하세요.');
+}
 async function fetchPermalink(cfg, mediaId) {
     try {
         const meta = await igFetch(cfg.accessToken, `/${mediaId}`, { fields: 'permalink', access_token: cfg.accessToken });
@@ -95,6 +112,8 @@ export async function postCarousel(cfg, imageUrls, caption) {
         const child = await igFetch(cfg.accessToken, `/${cfg.userId}/media`, { image_url: url, is_carousel_item: 'true', access_token: cfg.accessToken }, 'POST');
         childIds.push(child.id);
     }
+    for (const childId of childIds)
+        await waitForContainer(cfg, childId);
     // Step 2: carousel container 생성
     const carousel = await igFetch(cfg.accessToken, `/${cfg.userId}/media`, {
         media_type: 'CAROUSEL',
@@ -102,6 +121,7 @@ export async function postCarousel(cfg, imageUrls, caption) {
         caption,
         access_token: cfg.accessToken,
     }, 'POST');
+    await waitForContainer(cfg, carousel.id);
     // Step 3: publish
     const published = await igFetch(cfg.accessToken, `/${cfg.userId}/media_publish`, { creation_id: carousel.id, access_token: cfg.accessToken }, 'POST');
     return {

package/dist/prompts.js

@@ -1,5 +1,24 @@
 import { z } from 'zod';
 export function registerPrompts(server) {
+    server.prompt('getting-started', '처음 사용자 온보딩 — 연결 스캔 → 뭘 할 수 있는지 → 첫 안전한 액션까지', {}, async () => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: [
+                        '나는 mimi-seed 를 처음 써봐. 온보딩을 도와줘.',
+                        '',
+                        '진행 순서:',
+                        '1. mimi_seed_status 호출 — 연결 상태 스캔 (Claude Code 라면 먼저 ToolSearch(query="select:mimi_seed_status") 로 schema 로드)',
+                        '2. 리소스 mimi-seed://tools/catalog 를 읽고 뭘 할 수 있는지 도메인별로 간단히 요약 (150+ 도구)',
+                        '3. 내 목표를 물어봐: ① 스토어 출시/운영 ② Firebase/AdMob 설정 ③ 분석(GA4/Search Console/Ads/BigQuery) ④ 소셜 포스팅 ⑤ CI/Jenkins',
+                        '4. 목표에 필요한 자격증명이 ❌ 면: 터미널에서 `npx mimi-seed setup` 실행을 안내 (대화형이므로 네가 대신 실행하지 말 것)',
+                        '5. 자격증명이 준비되면 목표에 맞는 첫 읽기 전용 액션을 실행해서 보여줘 (예: playstore_list_tracks · appstore_list_apps · firebase_list_projects · admob_list_accounts)',
+                        '6. 다음 단계 제안: /mimi-seed:deploy · /mimi-seed:health · /mimi-seed:review-inbox, 심화 규약은 mimi-seed://agent/guide',
+                    ].join('\n'),
+                },
+            }],
+    }));
     server.prompt('deploy', '앱 출시 전 체크 → 릴리즈 노트 생성 → 스토어 적용까지 한 번에 진행', {
         packageName: z.string().optional().describe('Android 패키지명 (Play Store 출시 시)'),
         appId: z.string().optional().describe('App Store 앱 ID (iOS 출시 시)'),
@@ -34,7 +53,7 @@ export function registerPrompts(server) {
                         '현재 Mimi Seed 연결 상태와 앱 출시 준비도를 요약해줘.',
                         '',
                         '확인 순서:',
-                        '1. mimi_seed_status 호출 — 9개 서비스 전체 연결 상태 스캔',
+                        '1. mimi_seed_status 호출 — 전체 서비스 연결 상태 스캔',
                         '2. ❌ 필수 항목(Google OAuth / Play SA / App Store)이 있으면 먼저 설정 안내',
                         '3. firebase_list_projects 로 연결된 Firebase 프로젝트 확인 (OAuth 연결 시)',
                         '4. playstore_check_submission_risks / appstore_check_submission_risks 로 블로커 점검',

package/dist/registers/auth.js

@@ -111,7 +111,7 @@ export function registerAuthTools(server) {
     // ── 전체 연결 상태 진단 ────────────────────────────────────────────────────
     server.tool('mimi_seed_status', [
         '⭐ 새 세션을 시작하거나 "뭐가 연결됐지?" 라는 질문엔 이 도구를 먼저 호출하세요.',
-        '10개 서비스(Google OAuth / Play SA / App Store / Jenkins / CI / Google Ads / Facebook / Instagram / Threads / BigQuery)',
+        '전체 서비스(Google OAuth / Play SA / App Store / Jenkins / CI / Google Ads / Facebook / Instagram / Threads / BigQuery)',
         '설정 상태를 한 번에 스캔해 ✅ / ❌ 트래픽 라이트 리포트와 번호 매긴 다음 단계를 반환합니다.',
         '미설정 서비스마다 어떤 도구를 호출하면 되는지 구체적으로 알려줍니다.',
     ].join(' '), {}, async () => {

package/dist/resources.d.ts

@@ -1,2 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/** tool-manifest.json 의 형태. 테스트들도 이 타입을 import 해 캐스트 드리프트를 막는다. */
+export type ToolManifest = {
+    total: number;
+    domains: Record<string, string[]>;
+};
 export declare function registerResources(server: McpServer): void;

package/dist/resources.js

@@ -1,4 +1,121 @@
+import { readFileSync } from 'node:fs';
 import { ensureFreshAccessToken } from './auth/google-auth.js';
+// assets/agent-guide.md = docs/agent-guide.md 의 배포용 사본 (npm 배포본에는 docs/ 가 없다).
+// 갱신은 `npm run plugin:sync`, 드리프트는 prompts-resources.test.ts 가 잡는다.
+// 읽기 실패는 정상 설치에서 불가능하다(files 화이트리스트에 포함) — 그래서 폴백은 가이드
+// 요약본이 아니라 "깨진 설치" 신호 + 원본 포인터만 담는다. 요약본을 하나 더 관리하지 않는다.
+const AGENT_GUIDE_FALLBACK = [
+    '# Mimi Seed agent guide — 자산 누락 (degraded)',
+    '',
+    '⚠️ 이 설치본에서 assets/agent-guide.md 를 읽지 못했습니다 — 패키지가 손상됐습니다.',
+    '`npx -y @yoonion/mimi-seed-mcp` 재설치(필요 시 npx 캐시 정리) 후 새 세션을 여세요.',
+    '',
+    '가이드 전문: https://github.com/jeonghwanko/mimi-seed-sdk/blob/main/docs/agent-guide.md',
+    '최소 안전수칙: 스토어 제출·승격·삭제·공개 게시는 사용자 명시 동의 없이 실행하지 않는다.',
+].join('\n');
+function readPackageAsset(relativePath) {
+    try {
+        // src/ 와 dist/ 모두 패키지 루트 바로 아래라 ../ 가 같은 곳을 가리킨다 (index.ts 의 package.json 읽기와 동일 패턴).
+        return readFileSync(new URL(relativePath, import.meta.url), 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/** 도메인 id → 라벨·필요 자격증명·한줄 요약. 키 집합은 tool-manifest.json 의 domains 와
+ *  일치해야 한다 (prompts-resources.test.ts 가 강제) — 도메인을 추가하면 여기도 추가할 것. */
+const DOMAIN_SUMMARY = {
+    playstore: {
+        label: 'Google Play',
+        credential: 'Google OAuth (CI/헤드리스는 Play 서비스 계정)',
+        summary: '리스팅·트랙 릴리스·이미지·리뷰 답변·통계·서비스 계정 등록',
+    },
+    appstore: {
+        label: 'App Store Connect',
+        credential: 'ASC API 키 (mimi-seed auth appstore)',
+        summary: '버전·빌드 attach·What\'s New·스크린샷·IAP 심사 메타데이터·심사 제출',
+    },
+    firebase: {
+        label: 'Firebase',
+        credential: 'Google OAuth',
+        summary: '프로젝트/앱 생성·설정 파일 다운로드·서비스 활성화',
+    },
+    admob: {
+        label: 'AdMob',
+        credential: 'Google OAuth',
+        summary: '앱·광고 단위 생성, 오늘 수익·기간 리포트',
+    },
+    iam: {
+        label: 'Google Cloud IAM',
+        credential: 'Google OAuth',
+        summary: '서비스 계정 생성·키 발급·IAM 정책 바인딩',
+    },
+    bigquery: {
+        label: 'BigQuery',
+        credential: 'Google OAuth (또는 BigQuery 서비스 계정)',
+        summary: '쿼리 실행·데이터셋/테이블/스키마 조회',
+    },
+    ga4: {
+        label: 'Google Analytics 4',
+        credential: 'Google OAuth',
+        summary: '계정/속성·데이터 스트림 관리, 리포트 실행',
+    },
+    gsc: {
+        label: 'Search Console',
+        credential: 'Google OAuth',
+        summary: 'URL 검사·검색 성과 분석·사이트맵 제출',
+    },
+    googleads: {
+        label: 'Google Ads',
+        credential: 'Google Ads 설정 (mimi-seed auth googleads, adwords 스코프)',
+        summary: '캠페인 목록·캠페인/UAC 리포트',
+    },
+    ci: {
+        label: 'CI (GitHub Actions / GitLab)',
+        credential: 'GitHub/GitLab 토큰 (mimi-seed auth ci)',
+        summary: '워크플로 조회·빌드 트리거/상태/취소 — Jenkins 빌드는 대상 아님',
+    },
+    jenkins: {
+        label: 'Jenkins',
+        credential: 'Jenkins URL + API 토큰 (mimi-seed auth jenkins)',
+        summary: '크리덴셜·keystore 업로드·잡 생성/수정 — 빌드 트리거 도구는 없음',
+    },
+    android: {
+        label: 'Android 서명',
+        credential: '없음 (로컬 파일 작업)',
+        summary: 'keystore 생성·서명 설정·Jenkins 로 Play SA 업로드',
+    },
+    facebook: {
+        label: 'Facebook',
+        credential: 'Facebook 페이지 토큰 (mimi-seed auth facebook)',
+        summary: '페이지 텍스트/사진/링크 포스팅',
+    },
+    instagram: {
+        label: 'Instagram',
+        credential: 'Instagram 토큰 (mimi-seed auth instagram)',
+        summary: '사진·캐러셀·릴스 포스팅',
+    },
+    threads: {
+        label: 'Threads',
+        credential: 'Threads 토큰 (mimi-seed auth threads)',
+        summary: '텍스트/이미지 포스팅·토큰 갱신',
+    },
+    checks: {
+        label: '출시 점검',
+        credential: '점검 대상 스토어의 자격증명',
+        summary: '제출 전 위험 점검·스크린샷 규격 검증·릴리스 상태',
+    },
+    ai: {
+        label: 'AI 생성',
+        credential: 'ANTHROPIC_API_KEY 환경변수',
+        summary: '커밋 기반 릴리스 노트·리뷰 답변 초안 생성',
+    },
+    auth: {
+        label: '연결/진단',
+        credential: '없음 (이것이 셋업 도구)',
+        summary: '전체 연결 상태 스캔(mimi_seed_status)·OAuth 시작·원격 크리덴셜 동기화',
+    },
+};
 export function registerResources(server) {
     server.resource('auth-status', 'mimi-seed://auth/status', { description: 'Google OAuth 인증 상태 — fresh / refreshed / expired / unauthenticated', mimeType: 'application/json' }, async () => {
         const r = await ensureFreshAccessToken();
@@ -17,35 +134,56 @@ export function registerResources(server) {
                 }],
         };
     });
-    server.resource('agent-guide', 'mimi-seed://agent/guide', { description: 'Mimi Seed 에이전트 역할 정의 — 출시 워크플로우 · 주의사항 · 슬래시 커맨드', mimeType: 'text/markdown' }, async () => ({
+    server.resource('agent-guide', 'mimi-seed://agent/guide', {
+        description: 'Mimi Seed 에이전트 운영 규약 전문 (docs/agent-guide.md) — deferred 도구 로딩·ToolSearch select: 배치·호출 순서·비가역 액션 안전수칙',
+        mimeType: 'text/markdown',
+    }, async () => ({
         contents: [{
                 uri: 'mimi-seed://agent/guide',
                 mimeType: 'text/markdown',
-                text: [
-                    '# Mimi Seed — 앱 출시·운영 Agent',
-                    '',
-                    '당신은 Mimi Seed MCP를 통해 인디 개발자의 앱 출시와 운영을 돕는 에이전트입니다.',
-                    'Google Play · App Store · Firebase · AdMob · CI/CD · BigQuery를 직접 제어하는 150+ 도구를 사용할 수 있습니다.',
-                    '',
-                    '## 출시 요청 처리 순서',
-                    '',
-                    '1. **항상** `playstore_check_submission_risks` / `appstore_check_submission_risks` 로 블로커 먼저 확인',
-                    '2. 릴리즈 노트: `generate_release_notes_from_commits` → 검토 → 적용',
-                    '3. **쓰기 작업**(submit, apply, reply 등)은 반드시 사용자 명시 동의 후 실행',
-                    '4. 완료 후 결과 요약 제공',
-                    '',
-                    '## 슬래시 커맨드',
-                    '',
-                    '- `/mimi-seed:deploy` — 전체 출시 파이프라인',
-                    '- `/mimi-seed:health` — 연결·인증 상태 빠른 확인',
-                    '- `/mimi-seed:review-inbox` — 미답변 리뷰 조회 + 답변 생성',
-                    '',
-                    '## 주의사항',
-                    '',
-                    '- `playstore_submit_release(status=completed)` — 비가역, 반드시 명시 동의 필요',
-                    '- `appstore_submit_for_review` — 비가역, 반드시 명시 동의 필요',
-                    '- `playstore_reply_review` — 공개 게시, 반드시 검토 후 동의 필요',
-                ].join('\n'),
+                text: readPackageAsset('../assets/agent-guide.md') ?? AGENT_GUIDE_FALLBACK,
             }],
     }));
+    server.resource('tools-catalog', 'mimi-seed://tools/catalog', {
+        description: '150+ 도구 전체 카탈로그 — 도메인별 도구 목록·필요 자격증명·한줄 요약. "mimi-seed 로 뭘 할 수 있어?" 에는 이 리소스를 읽고 답하세요.',
+        mimeType: 'application/json',
+    }, async () => {
+        // LLM 이 읽는 페이로드라 compact 로 직렬화한다 (pretty 들여쓰기는 ~40% 바이트 낭비).
+        let payload;
+        try {
+            const raw = readFileSync(new URL('../tool-manifest.json', import.meta.url), 'utf8');
+            const manifest = JSON.parse(raw);
+            if (typeof manifest?.total !== 'number' || typeof manifest?.domains !== 'object' || manifest.domains === null) {
+                throw new Error('tool-manifest.json 의 형태가 예상과 다릅니다');
+            }
+            payload = JSON.stringify({
+                total: manifest.total,
+                deferredHint: 'Claude Code 에서는 도구 schema 가 lazy 로드됩니다 — 호출 전 ToolSearch(query="select:<tool,...>") 로 선로드하세요. 상세: mimi-seed://agent/guide',
+                domains: Object.entries(manifest.domains).map(([id, tools]) => ({
+                    id,
+                    label: DOMAIN_SUMMARY[id]?.label ?? id,
+                    credential: DOMAIN_SUMMARY[id]?.credential ?? '알 수 없음',
+                    summary: DOMAIN_SUMMARY[id]?.summary ?? '',
+                    toolCount: tools.length,
+                    tools,
+                })),
+            });
+        }
+        catch (e) {
+            // 가짜 성공(빈 카탈로그)을 서빙하지 않는다 — 깨진 설치임을 명시적으로 알린다.
+            payload = JSON.stringify({
+                error: 'tool-manifest.json 을 읽지 못했습니다 — 패키지가 손상됐습니다. `npx -y @yoonion/mimi-seed-mcp` 재설치 후 새 세션을 여세요.',
+                detail: e instanceof Error ? e.message : String(e),
+                total: null,
+                domains: [],
+            });
+        }
+        return {
+            contents: [{
+                    uri: 'mimi-seed://tools/catalog',
+                    mimeType: 'application/json',
+                    text: payload,
+                }],
+        };
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yoonion/mimi-seed-mcp",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "Mimi Seed MCP server — Firebase + AdMob + Google Play + App Store management for Claude Code / Codex / Cursor / any MCP client.",
   "type": "module",
   "bin": {
@@ -18,6 +18,8 @@
   },
   "files": [
     "dist",
+    "assets",
+    "tool-manifest.json",
     "LICENSE"
   ],
   "scripts": {
@@ -26,7 +28,7 @@
     "auth": "tsx src/auth/cli.ts",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "tsc"
+    "prepublishOnly": "node ../../scripts/sync-agent-guide.mjs --check && tsc"
   },
   "keywords": [
     "mcp",

package/tool-manifest.json

@@ -0,0 +1,205 @@
+{
+  "$comment": "등록된 MCP 도구의 SSOT. src/__tests__/tool-manifest.test.ts 가 실제 서버 등록 목록과 diff 하여 강제한다. 도구 추가/삭제/개명 시 이 파일을 함께 갱신할 것 — 산문 문서에는 정확한 개수를 쓰지 말고 이 파일을 가리킬 것.",
+  "total": 163,
+  "domains": {
+    "admob": [
+      "admob_list_accounts",
+      "admob_list_apps",
+      "admob_list_ad_units",
+      "admob_get_today_earnings",
+      "admob_get_report",
+      "admob_create_app",
+      "admob_create_ad_unit"
+    ],
+    "ai": [
+      "generate_release_notes_from_commits",
+      "generate_review_reply"
+    ],
+    "android": [
+      "android_signing_setup",
+      "android_generate_keystore",
+      "jenkins_upload_playstore_sa"
+    ],
+    "appstore": [
+      "appstore_list_apps",
+      "appstore_verify_credentials",
+      "appstore_get_app",
+      "appstore_list_versions",
+      "appstore_create_version",
+      "appstore_attach_build",
+      "appstore_attach_latest_build",
+      "appstore_get_metadata",
+      "appstore_update_localization",
+      "appstore_list_screenshots",
+      "appstore_upload_screenshot",
+      "appstore_delete_screenshot",
+      "appstore_delete_screenshot_set",
+      "appstore_update_whats_new",
+      "appstore_update_review_notes",
+      "appstore_get_review_notes",
+      "appstore_list_builds",
+      "appstore_list_beta_groups",
+      "appstore_get_app_info",
+      "appstore_list_app_info_localizations",
+      "appstore_update_app_info_localization",
+      "appstore_create_app_info_localization",
+      "appstore_list_reviews",
+      "appstore_reply_review",
+      "appstore_create_inapp_purchase",
+      "appstore_create_subscription",
+      "appstore_list_products",
+      "appstore_update_product_review_note",
+      "appstore_upload_product_review_screenshot",
+      "appstore_update_product",
+      "appstore_delete_product",
+      "appstore_plan_release",
+      "appstore_submit_for_review",
+      "appstore_cancel_review"
+    ],
+    "auth": [
+      "mimi_seed_status",
+      "mimi_seed_auth_start",
+      "mimi_seed_auth_status",
+      "mimi_seed_remote_sync_credentials"
+    ],
+    "bigquery": [
+      "bigquery_run_query",
+      "bigquery_list_datasets",
+      "bigquery_list_tables",
+      "bigquery_get_table_schema",
+      "bigquery_auth_status"
+    ],
+    "checks": [
+      "playstore_check_submission_risks",
+      "appstore_check_submission_risks",
+      "screenshot_validate",
+      "release_status"
+    ],
+    "ci": [
+      "ci_save_config",
+      "ci_list_workflows",
+      "ci_trigger_build",
+      "ci_get_build_status",
+      "ci_list_recent_builds",
+      "ci_cancel_build"
+    ],
+    "facebook": [
+      "facebook_save_config",
+      "facebook_list_pages",
+      "facebook_get_page",
+      "facebook_post_photo",
+      "facebook_post_multi_photo",
+      "facebook_current_config"
+    ],
+    "firebase": [
+      "firebase_list_projects",
+      "firebase_get_project",
+      "firebase_create_project",
+      "firebase_list_android_apps",
+      "firebase_create_android_app",
+      "firebase_get_android_config",
+      "firebase_delete_android_app",
+      "firebase_list_ios_apps",
+      "firebase_create_ios_app",
+      "firebase_get_ios_config",
+      "firebase_delete_ios_app",
+      "firebase_list_web_apps",
+      "firebase_create_web_app",
+      "firebase_get_web_config",
+      "firebase_delete_web_app",
+      "firebase_enable_service",
+      "firebase_enable_common_services",
+      "firebase_list_enabled_services",
+      "firebase_link_analytics",
+      "firebase_get_analytics_details"
+    ],
+    "ga4": [
+      "ga4_list_account_summaries",
+      "ga4_list_properties",
+      "ga4_create_property",
+      "ga4_create_data_stream",
+      "ga4_list_data_streams",
+      "ga4_run_report"
+    ],
+    "googleads": [
+      "googleads_save_config",
+      "googleads_list_campaigns",
+      "googleads_get_campaign_report",
+      "googleads_get_uac_report",
+      "googleads_list_accessible_customers",
+      "googleads_config_status"
+    ],
+    "gsc": [
+      "gsc_list_sites",
+      "gsc_list_sitemaps",
+      "gsc_get_sitemap",
+      "gsc_submit_sitemap",
+      "gsc_inspect_url",
+      "gsc_search_analytics"
+    ],
+    "iam": [
+      "iam_list_service_accounts",
+      "iam_create_service_account",
+      "iam_list_keys",
+      "iam_create_key",
+      "iam_add_iam_policy_binding"
+    ],
+    "instagram": [
+      "instagram_save_config",
+      "instagram_get_account",
+      "instagram_post_image",
+      "instagram_post_carousel"
+    ],
+    "jenkins": [
+      "jenkins_status",
+      "jenkins_save_config",
+      "jenkins_list_credentials",
+      "jenkins_create_credential",
+      "jenkins_upload_keystore",
+      "jenkins_delete_credential",
+      "jenkins_list_jobs",
+      "jenkins_get_job_config",
+      "jenkins_create_job",
+      "jenkins_update_job"
+    ],
+    "playstore": [
+      "playstore_get_app",
+      "playstore_update_details",
+      "playstore_get_listing",
+      "playstore_update_listing",
+      "playstore_list_tracks",
+      "playstore_get_statistics",
+      "playstore_list_images",
+      "playstore_upload_image",
+      "playstore_delete_all_images",
+      "playstore_replace_images",
+      "playstore_update_release_notes",
+      "playstore_update_latest_release_notes",
+      "playstore_list_reviews",
+      "playstore_reply_review",
+      "playstore_list_inapp_products",
+      "playstore_list_subscriptions",
+      "playstore_create_onetime_product",
+      "playstore_create_subscription",
+      "playstore_verify_service_account",
+      "playstore_register_service_account",
+      "playstore_list_service_accounts",
+      "playstore_delete_service_account",
+      "playstore_plan_release",
+      "playstore_submit_release",
+      "playstore_promote_release",
+      "playstore_list_products",
+      "playstore_update_product",
+      "playstore_delete_product",
+      "setup_playstore_connection"
+    ],
+    "threads": [
+      "threads_save_config",
+      "threads_refresh_token",
+      "threads_get_account",
+      "threads_post",
+      "threads_post_carousel",
+      "threads_current_config"
+    ]
+  }
+}