@yoonion/mimi-seed-mcp 0.3.9 → 0.3.11

package/dist/auth/cli.js

@@ -1,40 +1,246 @@
 #!/usr/bin/env node
-import { login, getStoredTokens } from './google-auth.js';
-import { MIMI_SEED_CLIENT_ID, MIMI_SEED_CLIENT_SECRET } from './constants.js';
 import readline from 'node:readline';
-const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-const ask = (q) => new Promise((r) => rl.question(q, r));
-async function main() {
-    console.log('');
-    console.log('  ☕ Mimi Seed — Google 계정 연결');
-    console.log('');
-    const existing = getStoredTokens();
-    if (existing) {
-        console.log('  ✅ 이미 연결되어 있어.');
-        console.log('');
-        const answer = await ask('  다시 연결할래? (y/N): ');
-        if (answer.toLowerCase() !== 'y') {
-            rl.close();
-            return;
+import open from 'open';
+import { startAuth, getStoredTokens, ensureFreshAccessToken, } from './google-auth.js';
+import { AuthError, classifyError } from './errors.js';
+import { MIMI_SEED_CLIENT_ID, MIMI_SEED_CLIENT_SECRET } from './constants.js';
+const args = process.argv.slice(2);
+const hasFlag = (name) => args.includes(`--${name}`);
+const flagValue = (name) => {
+    const i = args.indexOf(`--${name}`);
+    if (i < 0)
+        return undefined;
+    const v = args[i + 1];
+    return v && !v.startsWith('--') ? v : undefined;
+};
+function err(msg) {
+    process.stderr.write(msg + '\n');
+}
+function printHelp() {
+    err(`
+  ☕ mimi-seed-auth — Google OAuth 인증 CLI
+
+  사용법:
+    mimi-seed-auth                  # 로그인 (이미 있으면 자동 refresh 시도)
+    mimi-seed-auth --refresh        # refresh_token으로 갱신만 시도 (브라우저 X)
+    mimi-seed-auth --status         # 현재 토큰 상태 출력
+    mimi-seed-auth --logout         # 토큰 삭제
+
+  옵션:
+    --no-browser     URL 자동 오픈 안 함 (직접 복붙)
+    --timeout <초>   콜백 대기 시간 (기본 600)
+    --force          기존 토큰 무시하고 강제 재로그인
+    --help           이 도움말
+`);
+}
+function fmtRemaining(ms) {
+    if (ms <= 0)
+        return '만료됨';
+    const min = Math.round(ms / 60000);
+    if (min < 60)
+        return `${min}분 남음`;
+    const hr = Math.round(min / 60);
+    if (hr < 48)
+        return `${hr}시간 남음`;
+    return `${Math.round(hr / 24)}일 남음`;
+}
+function printAuthError(p) {
+    err(`     코드: ${p.code}`);
+    err(`     ${p.message}`);
+    if (p.hint)
+        err(`     → ${p.hint}`);
+    if (p.cause && process.env.DEBUG)
+        err(`     (cause: ${p.cause})`);
+}
+async function cmdStatus() {
+    err('');
+    err('  ☕ Mimi Seed — 인증 상태');
+    err('');
+    const r = await ensureFreshAccessToken();
+    switch (r.status) {
+        case 'fresh':
+            err(`  ✅ 연결됨 — 토큰 유효 (${fmtRemaining(r.msUntilExpiry)})`);
+            err('');
+            return 0;
+        case 'refreshed':
+            err(`  ✅ 연결됨 — refresh_token으로 갱신 (${fmtRemaining(r.msUntilExpiry)})`);
+            err('');
+            return 0;
+        case 'expired_refresh_failed':
+            err('  ⚠️  토큰 만료 + 자동 갱신 실패');
+            printAuthError(r.error);
+            err('');
+            return 2;
+        case 'unauthenticated':
+            err('  ❌ 연결된 계정 없음.');
+            printAuthError(r.error);
+            err('');
+            return 1;
+    }
+}
+async function cmdRefresh() {
+    err('');
+    err('  🔄 refresh_token으로 갱신 시도 중...');
+    err('');
+    const r = await ensureFreshAccessToken(0); // 무조건 갱신 시도
+    switch (r.status) {
+        case 'fresh':
+            err(`  ✅ 토큰 유효 — 갱신 불필요 (${fmtRemaining(r.msUntilExpiry)})`);
+            err('');
+            return 0;
+        case 'refreshed':
+            err(`  ✅ 갱신 완료 (${fmtRemaining(r.msUntilExpiry)})`);
+            err('');
+            return 0;
+        case 'expired_refresh_failed':
+            err('  ❌ refresh 실패');
+            printAuthError(r.error);
+            err('');
+            return 2;
+        case 'unauthenticated':
+            err('  ❌ 저장된 토큰 없음.');
+            printAuthError(r.error);
+            err('');
+            return 1;
+    }
+}
+async function cmdLogout() {
+    const fs = await import('node:fs');
+    const path = await import('node:path');
+    const os = await import('node:os');
+    const tokenPath = path.join(os.homedir(), '.mimi-seed', 'tokens.json');
+    err('');
+    if (fs.existsSync(tokenPath)) {
+        fs.rmSync(tokenPath, { force: true });
+        err('  ✅ 토큰 삭제 완료.');
+    }
+    else {
+        err('  (이미 삭제된 상태)');
+    }
+    err('');
+    return 0;
+}
+async function cmdLogin() {
+    const noBrowser = hasFlag('no-browser');
+    const force = hasFlag('force');
+    const timeoutSec = parseInt(flagValue('timeout') ?? '600', 10);
+    err('');
+    err('  ☕ Mimi Seed — Google 계정 연결');
+    err('');
+    // 1) 기존 토큰이 있으면 silent refresh 먼저 시도
+    if (!force) {
+        const existing = getStoredTokens();
+        if (existing) {
+            err('  🔍 기존 토큰 검사 중...');
+            const r = await ensureFreshAccessToken();
+            if (r.status === 'fresh' || r.status === 'refreshed') {
+                const label = r.status === 'fresh' ? '유효함' : 'refresh_token으로 갱신 완료';
+                err(`  ✅ 이미 연결됨 (${label}, ${fmtRemaining(r.msUntilExpiry)}).`);
+                err('');
+                const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+                const answer = await new Promise((res) => rl.question('  다시 로그인할래? (y/N): ', res));
+                rl.close();
+                if (answer.toLowerCase() !== 'y') {
+                    err('');
+                    return 0;
+                }
+            }
+            else if (r.status === 'expired_refresh_failed') {
+                err(`  ⚠️  토큰 만료 + 자동 갱신 실패 [${r.error.code}] — 재로그인 진행.`);
+                if (r.error.cause && process.env.DEBUG)
+                    err(`     cause: ${r.error.cause}`);
+            }
         }
     }
-    console.log('');
-    console.log('  🌐 브라우저 열게. Google 계정으로 로그인해줘.');
-    console.log('');
+    // 2) OAuth 콜백 서버 + URL 발급
+    err('');
+    err('  🌐 OAuth 콜백 서버 시작: http://localhost:9876/callback');
+    let url;
+    let wait;
     try {
-        await login(MIMI_SEED_CLIENT_ID, MIMI_SEED_CLIENT_SECRET);
-        console.log('');
-        console.log('  ✅ 연결 완료!');
-        console.log('');
-        console.log('  이제 Claude Code에서 이렇게 쓸 수 있어:');
-        console.log('    "내 Firebase 프로젝트 보여줘"');
-        console.log('    "새 Android 앱 등록해줘"');
-        console.log('    "google-services.json 다운로드해줘"');
-        console.log('');
-    }
-    catch (err) {
-        console.error('  ❌ 연결 실패:', err);
-    }
-    rl.close();
-}
-main();
+        const r = startAuth(MIMI_SEED_CLIENT_ID, MIMI_SEED_CLIENT_SECRET, {
+            timeoutMs: timeoutSec * 1000,
+        });
+        url = r.url;
+        wait = r.wait;
+    }
+    catch (e) {
+        err('  ❌ 콜백 서버 시작 실패');
+        printAuthError(classifyError(e, { phase: 'login' }));
+        err('');
+        return 1;
+    }
+    // 3) 브라우저 열기 (or URL 출력)
+    if (noBrowser) {
+        err('');
+        err('  📋 아래 URL을 브라우저에 직접 붙여넣으세요:');
+        err('');
+        err('     ' + url);
+        err('');
+    }
+    else {
+        err('  🌐 기본 브라우저 자동 열기...');
+        try {
+            await open(url);
+            err('     (실패 시 --no-browser 로 URL 직접 받기)');
+        }
+        catch (e) {
+            err('  ⚠️  브라우저 자동 열기 실패: ' + (e instanceof Error ? e.message : String(e)));
+            err('  📋 직접 열어주세요:');
+            err('     ' + url);
+        }
+    }
+    // 4) 콜백 대기
+    err(`  ⏳ Google 승인 대기 중... (timeout ${timeoutSec}s)`);
+    // 진행 표시기 — 사용자에게 살아있다는 신호 전달
+    const ticker = setInterval(() => process.stderr.write('.'), 5000);
+    try {
+        await wait;
+    }
+    catch (e) {
+        clearInterval(ticker);
+        err('');
+        err('  ❌ 인증 실패');
+        if (e instanceof AuthError) {
+            printAuthError(e.payload);
+        }
+        else {
+            printAuthError(classifyError(e, { phase: 'login' }));
+        }
+        err('');
+        return 1;
+    }
+    clearInterval(ticker);
+    err('');
+    err('');
+    err('  ✅ 연결 완료!');
+    err('');
+    err('  이제 Claude Code에서 이렇게 쓸 수 있어:');
+    err('    "내 Firebase 프로젝트 보여줘"');
+    err('    "새 Android 앱 등록해줘"');
+    err('    "google-services.json 다운로드해줘"');
+    err('');
+    return 0;
+}
+async function main() {
+    if (hasFlag('help') || hasFlag('h')) {
+        printHelp();
+        process.exit(0);
+    }
+    let code;
+    if (hasFlag('status'))
+        code = await cmdStatus();
+    else if (hasFlag('refresh'))
+        code = await cmdRefresh();
+    else if (hasFlag('logout'))
+        code = await cmdLogout();
+    else
+        code = await cmdLogin();
+    process.exit(code);
+}
+main().catch((e) => {
+    err('');
+    err('  ❌ 예외: ' + (e instanceof Error ? e.message : String(e)));
+    err('');
+    process.exit(1);
+});

package/dist/auth/errors.d.ts

@@ -0,0 +1,24 @@
+export type AuthErrorCode = 'UNAUTHENTICATED' | 'NO_REFRESH_TOKEN' | 'INVALID_GRANT' | 'INVALID_CLIENT' | 'UNAUTHORIZED_CLIENT' | 'REFRESH_NETWORK_ERROR' | 'REFRESH_UNKNOWN' | 'CALLBACK_PORT_IN_USE' | 'CALLBACK_TIMEOUT' | 'BROWSER_OPEN_FAILED' | 'USER_DENIED' | 'CODE_EXCHANGE_FAILED' | 'TOKEN_RESPONSE_INVALID';
+export interface AuthErrorPayload {
+    code: AuthErrorCode;
+    message: string;
+    hint?: string;
+    retriable: boolean;
+    needsReauth: boolean;
+    cause?: string;
+}
+export declare class AuthError extends Error {
+    payload: AuthErrorPayload;
+    constructor(payload: AuthErrorPayload);
+}
+interface ClassifyContext {
+    phase: 'refresh' | 'login';
+}
+/**
+ * 임의의 에러 객체를 AuthErrorPayload로 분류.
+ * Google OAuth 응답 형태:
+ *   { error: 'invalid_grant', error_description: '...' }
+ * googleapis 라이브러리는 e.response?.data?.error 또는 e.message에 코드 포함.
+ */
+export declare function classifyError(e: unknown, ctx: ClassifyContext): AuthErrorPayload;
+export {};

package/dist/auth/errors.js

@@ -0,0 +1,152 @@
+// Auth 에러 코드 — CLI/MCP/스크립트 모두 같은 코드를 보고 분기할 수 있도록
+// 단일 source of truth.
+export class AuthError extends Error {
+    payload;
+    constructor(payload) {
+        super(`[${payload.code}] ${payload.message}`);
+        this.payload = payload;
+        this.name = 'AuthError';
+    }
+}
+/**
+ * 임의의 에러 객체를 AuthErrorPayload로 분류.
+ * Google OAuth 응답 형태:
+ *   { error: 'invalid_grant', error_description: '...' }
+ * googleapis 라이브러리는 e.response?.data?.error 또는 e.message에 코드 포함.
+ */
+export function classifyError(e, ctx) {
+    const raw = describeError(e);
+    const oauthCode = extractOAuthErrorCode(e, raw);
+    // Google OAuth 표준 에러 코드 매핑
+    if (oauthCode === 'invalid_grant') {
+        return {
+            code: 'INVALID_GRANT',
+            message: 'refresh_token이 더 이상 유효하지 않습니다 (revoke 또는 만료).',
+            hint: 'mimi-seed-auth 로 재로그인하세요.',
+            retriable: false,
+            needsReauth: true,
+            cause: raw,
+        };
+    }
+    if (oauthCode === 'invalid_client') {
+        return {
+            code: 'INVALID_CLIENT',
+            message: 'OAuth client_id/secret이 토큰 발급 당시와 일치하지 않습니다.',
+            hint: '일반적으로 발생하지 않음. 환경변수 MIMI_SEED_GOOGLE_CLIENT_ID/SECRET 오버라이드 사용 시 ' +
+                '동일 값으로 다시 발급받으세요.',
+            retriable: false,
+            needsReauth: true,
+            cause: raw,
+        };
+    }
+    if (oauthCode === 'unauthorized_client') {
+        return {
+            code: 'UNAUTHORIZED_CLIENT',
+            message: 'OAuth client에 부여되지 않은 grant_type 또는 scope입니다.',
+            hint: 'mimi-seed-auth 로 새로운 동의를 받으세요.',
+            retriable: false,
+            needsReauth: true,
+            cause: raw,
+        };
+    }
+    if (oauthCode === 'access_denied') {
+        return {
+            code: 'USER_DENIED',
+            message: '브라우저에서 Google 동의를 거부했습니다.',
+            hint: '다시 시도하고 모든 권한에 동의해주세요.',
+            retriable: true,
+            needsReauth: true,
+            cause: raw,
+        };
+    }
+    // 네트워크 / 시스템 레벨
+    if (isNetworkError(e, raw)) {
+        return {
+            code: 'REFRESH_NETWORK_ERROR',
+            message: '구글 토큰 엔드포인트(oauth2.googleapis.com)에 연결할 수 없습니다.',
+            hint: '인터넷 연결, 프록시, 방화벽을 확인하세요.',
+            retriable: true,
+            needsReauth: false,
+            cause: raw,
+        };
+    }
+    if (isPortInUseError(e, raw)) {
+        return {
+            code: 'CALLBACK_PORT_IN_USE',
+            message: 'OAuth 콜백 포트 9876이 이미 사용 중입니다.',
+            hint: '해당 포트를 점유 중인 프로세스를 종료하거나 잠시 후 다시 시도하세요.',
+            retriable: true,
+            needsReauth: false,
+            cause: raw,
+        };
+    }
+    if (/timeout/i.test(raw) && ctx.phase === 'login') {
+        return {
+            code: 'CALLBACK_TIMEOUT',
+            message: '시간 내 Google 콜백을 받지 못했습니다.',
+            hint: '브라우저에서 동의 안 하셨거나 자동 열기 실패. ' +
+                '`mimi-seed-auth --no-browser`로 URL을 직접 받아 다른 환경에서 여세요.',
+            retriable: true,
+            needsReauth: false,
+            cause: raw,
+        };
+    }
+    // 분류 안 됨
+    return {
+        code: ctx.phase === 'refresh' ? 'REFRESH_UNKNOWN' : 'CODE_EXCHANGE_FAILED',
+        message: '인증 처리 중 알 수 없는 오류가 발생했습니다.',
+        hint: '재시도 후 동일하면 mimi-seed-auth 로 재로그인하세요.',
+        retriable: true,
+        needsReauth: ctx.phase === 'refresh',
+        cause: raw,
+    };
+}
+function describeError(e) {
+    if (e instanceof Error)
+        return e.message;
+    if (typeof e === 'string')
+        return e;
+    try {
+        return JSON.stringify(e);
+    }
+    catch {
+        return String(e);
+    }
+}
+/**
+ * googleapis OAuth 에러는 다양한 위치에 코드가 박혀 있다:
+ *   - e.response?.data?.error
+ *   - e.response?.data?.error_description
+ *   - e.message (e.g. "invalid_grant")
+ *   - e.code (네트워크: 'ENOTFOUND', 'ECONNREFUSED')
+ */
+function extractOAuthErrorCode(e, raw) {
+    if (e && typeof e === 'object') {
+        // @ts-expect-error — 런타임 shape 검사
+        const dataErr = e.response?.data?.error;
+        if (typeof dataErr === 'string')
+            return dataErr;
+    }
+    // message에 'invalid_grant' 같은 표준 코드가 박혀 있는 경우
+    const m = raw.match(/\b(invalid_grant|invalid_client|invalid_request|unauthorized_client|access_denied|unsupported_grant_type)\b/);
+    return m?.[1];
+}
+function isNetworkError(e, raw) {
+    if (e && typeof e === 'object') {
+        // @ts-expect-error — runtime shape 검사
+        const code = e.code;
+        if (typeof code === 'string' && /^(ENOTFOUND|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|ECONNRESET)$/.test(code)) {
+            return true;
+        }
+    }
+    return /ENOTFOUND|ECONNREFUSED|ETIMEDOUT|getaddrinfo|network/i.test(raw);
+}
+function isPortInUseError(e, raw) {
+    if (e && typeof e === 'object') {
+        // @ts-expect-error — runtime shape 검사
+        const code = e.code;
+        if (code === 'EADDRINUSE')
+            return true;
+    }
+    return /EADDRINUSE|address already in use|포트 9876/i.test(raw);
+}

package/dist/auth/google-auth.d.ts

@@ -1,3 +1,4 @@
+import { type AuthErrorPayload } from './errors.js';
 export interface StoredTokens {
     access_token: string;
     refresh_token: string;
@@ -34,3 +35,28 @@ export declare function startAuth(clientId: string, clientSecret: string, option
  * startAuth() 래퍼 — CLI에서 사용.
  */
 export declare function login(clientId: string, clientSecret: string): Promise<StoredTokens>;
+export type RefreshStatus = {
+    status: 'fresh';
+    tokens: StoredTokens;
+    msUntilExpiry: number;
+} | {
+    status: 'refreshed';
+    tokens: StoredTokens;
+    msUntilExpiry: number;
+} | {
+    status: 'expired_refresh_failed';
+    tokens: StoredTokens;
+    error: AuthErrorPayload;
+} | {
+    status: 'unauthenticated';
+    error: AuthErrorPayload;
+};
+/**
+ * 저장된 access_token이 만료/곧만료면 refresh_token으로 silent 갱신 시도.
+ * - 갱신 성공 시 tokens.json 업데이트
+ * - refresh_token 자체가 invalid한 경우 'expired_refresh_failed' 반환
+ * - 토큰 자체가 없으면 'unauthenticated'
+ *
+ * MCP 도구와 CLI 양쪽에서 공유.
+ */
+export declare function ensureFreshAccessToken(marginMs?: number): Promise<RefreshStatus>;

package/dist/auth/google-auth.js

@@ -4,6 +4,8 @@ import open from 'open';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import { MIMI_SEED_CLIENT_ID, MIMI_SEED_CLIENT_SECRET } from './constants.js';
+import { AuthError, classifyError } from './errors.js';
 const SCOPES = [
     'https://www.googleapis.com/auth/firebase',
     'https://www.googleapis.com/auth/cloud-platform',
@@ -117,6 +119,7 @@ export function startAuth(clientId, clientSecret, options = {}) {
         prompt: 'consent',
     });
     const wait = new Promise((resolve, reject) => {
+        const rejectAuth = (e) => reject(new AuthError(classifyError(e, { phase: 'login' })));
         const server = http.createServer(async (req, res) => {
             try {
                 const url = new URL(req.url, `http://localhost:9876`);
@@ -125,15 +128,58 @@ export function startAuth(clientId, clientSecret, options = {}) {
                     res.end();
                     return;
                 }
+                // Google이 동의 거부 시 ?error=access_denied 로 콜백
+                const errParam = url.searchParams.get('error');
+                if (errParam) {
+                    res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+                    res.end(`<html><body><h2>❌ 인증 거부됨 (${errParam})</h2></body></html>`);
+                    try {
+                        server.close();
+                    }
+                    catch { /* noop */ }
+                    activeAuthServer = null;
+                    rejectAuth(new Error(errParam));
+                    return;
+                }
                 const code = url.searchParams.get('code');
                 if (!code) {
                     res.writeHead(400);
                     res.end('No code');
                     return;
                 }
-                const { tokens } = await oauth2Client.getToken(code);
+                let tokenResponse;
+                try {
+                    tokenResponse = await oauth2Client.getToken(code);
+                }
+                catch (e) {
+                    res.writeHead(500);
+                    res.end('Code exchange failed');
+                    try {
+                        server.close();
+                    }
+                    catch { /* noop */ }
+                    activeAuthServer = null;
+                    rejectAuth(e);
+                    return;
+                }
+                const tokens = tokenResponse.tokens;
                 if (!tokens.access_token || !tokens.refresh_token) {
-                    throw new Error('Token response missing required fields');
+                    res.writeHead(500);
+                    res.end('Token response invalid');
+                    try {
+                        server.close();
+                    }
+                    catch { /* noop */ }
+                    activeAuthServer = null;
+                    reject(new AuthError({
+                        code: 'TOKEN_RESPONSE_INVALID',
+                        message: 'Google 응답에 access_token 또는 refresh_token이 누락되었습니다.',
+                        hint: 'OAuth 동의 화면에서 모든 권한에 동의했는지 확인하세요.',
+                        retriable: true,
+                        needsReauth: true,
+                        cause: JSON.stringify({ has_access: !!tokens.access_token, has_refresh: !!tokens.refresh_token }),
+                    }));
+                    return;
                 }
                 const stored = {
                     access_token: tokens.access_token,
@@ -156,18 +202,21 @@ export function startAuth(clientId, clientSecret, options = {}) {
                 resolve(stored);
             }
             catch (err) {
-                res.writeHead(500);
-                res.end('Auth error');
+                try {
+                    res.writeHead(500);
+                    res.end('Auth error');
+                }
+                catch { /* noop — already responded */ }
                 try {
                     server.close();
                 }
                 catch { /* noop */ }
                 activeAuthServer = null;
-                reject(err);
+                rejectAuth(err);
             }
         });
         server.on('error', (err) => {
-            reject(new Error(`포트 9876이 이미 사용 중이거나 에러: ${err.message}`));
+            rejectAuth(err);
         });
         server.listen(9876, () => {
             activeAuthServer = server;
@@ -180,7 +229,7 @@ export function startAuth(clientId, clientSecret, options = {}) {
                 }
                 catch { /* noop */ }
                 activeAuthServer = null;
-                reject(new Error(`Auth timeout (${Math.round(timeoutMs / 1000)}s).`));
+                rejectAuth(new Error(`Auth timeout (${Math.round(timeoutMs / 1000)}s).`));
             }
         }, timeoutMs);
     });
@@ -196,3 +245,72 @@ export async function login(clientId, clientSecret) {
     open(url);
     return wait;
 }
+/**
+ * 저장된 access_token이 만료/곧만료면 refresh_token으로 silent 갱신 시도.
+ * - 갱신 성공 시 tokens.json 업데이트
+ * - refresh_token 자체가 invalid한 경우 'expired_refresh_failed' 반환
+ * - 토큰 자체가 없으면 'unauthenticated'
+ *
+ * MCP 도구와 CLI 양쪽에서 공유.
+ */
+export async function ensureFreshAccessToken(marginMs = 60_000) {
+    const tokens = getStoredTokens();
+    if (!tokens) {
+        return {
+            status: 'unauthenticated',
+            error: {
+                code: 'UNAUTHENTICATED',
+                message: '저장된 인증 토큰이 없습니다.',
+                hint: 'mimi-seed-auth 로 로그인하세요.',
+                retriable: false,
+                needsReauth: true,
+            },
+        };
+    }
+    const now = Date.now();
+    const msUntilExpiry = (tokens.expiry_date ?? 0) - now;
+    if (tokens.expiry_date && msUntilExpiry > marginMs) {
+        return { status: 'fresh', tokens, msUntilExpiry };
+    }
+    if (!tokens.refresh_token) {
+        return {
+            status: 'expired_refresh_failed',
+            tokens,
+            error: {
+                code: 'NO_REFRESH_TOKEN',
+                message: '저장된 토큰에 refresh_token이 없습니다 (offline_access 미발급).',
+                hint: 'mimi-seed-auth 로 재로그인하면 prompt=consent로 새 refresh_token이 발급됩니다.',
+                retriable: false,
+                needsReauth: true,
+            },
+        };
+    }
+    // refresh 시도 — credentials.json 우선, 없으면 내장 클라이언트 사용
+    const stored = getStoredCredentials();
+    const clientId = stored?.clientId ?? MIMI_SEED_CLIENT_ID;
+    const clientSecret = stored?.clientSecret ?? MIMI_SEED_CLIENT_SECRET;
+    const client = createOAuth2Client(clientId, clientSecret);
+    client.setCredentials({ refresh_token: tokens.refresh_token });
+    try {
+        const { credentials } = await client.refreshAccessToken();
+        const refreshed = {
+            access_token: credentials.access_token ?? tokens.access_token,
+            refresh_token: credentials.refresh_token ?? tokens.refresh_token,
+            token_type: credentials.token_type ?? tokens.token_type ?? 'Bearer',
+            expiry_date: credentials.expiry_date ?? Date.now() + 3600_000,
+        };
+        saveTokens(refreshed);
+        return {
+            status: 'refreshed',
+            tokens: refreshed,
+            msUntilExpiry: refreshed.expiry_date - Date.now(),
+        };
+    }
+    catch (e) {
+        return {
+            status: 'expired_refresh_failed',
+            tokens,
+            error: classifyError(e, { phase: 'refresh' }),
+        };
+    }
+}

package/dist/checks/plan.d.ts

@@ -0,0 +1,20 @@
+import type { OAuth2Client } from 'google-auth-library';
+export type StepState = 'done' | 'pending' | 'blocked';
+export interface PlanStep {
+    state: StepState;
+    title: string;
+    detail?: string;
+    tool?: string;
+    irreversible?: boolean;
+}
+export declare function buildPlayStoreReleasePlan(opts: {
+    auth: OAuth2Client;
+    packageName: string;
+    versionCode?: string;
+    track: 'production' | 'beta' | 'alpha' | 'internal';
+    language: string;
+}): Promise<string>;
+export declare function buildAppStoreReleasePlan(opts: {
+    appId: string;
+    versionString?: string;
+}): Promise<string>;

package/dist/checks/plan.js

@@ -0,0 +1,258 @@
+// Release Plan — Play Store / App Store 배포 사전 점검 + AI에게 TodoWrite 지시
+//
+// 이 모듈은 read-only.
+// 실행 도구(playstore_submit_release, appstore_submit_for_review 등)는 호출하지 않고,
+// 현재 상태를 조사해서 markdown 체크리스트로 변환한다.
+// AI 에이전트가 응답을 받아 TodoWrite로 사용자에게 제시한 뒤,
+// 단계별로 기존 *_update_*, *_submit_*, *_check_* 도구를 호출하도록 유도한다.
+import { publisher, withEdit } from '../playstore/tools.js';
+import { apiGet } from '../appstore/tools.js';
+import { checkPlayStoreRisks, checkAppStoreRisks } from './risks.js';
+const TODO_DIRECTIVE = [
+    '📋 [AI 지시 — 호출자 에이전트 전용]',
+    '',
+    '이 응답은 배포 플랜입니다. 다음 절차를 반드시 따르세요:',
+    '',
+    '1. 아래 체크리스트의 미완료(◻︎) 항목을 TodoWrite 도구로 사용자에게 먼저 보여주세요.',
+    '2. 사용자가 진행에 명시적으로 동의하기 전엔 ⚠️ 비가역 도구를 호출하지 마세요',
+    '   (playstore_submit_release status=completed, playstore_promote_release status=completed,',
+    '    appstore_submit_for_review).',
+    '3. 한 단계 끝날 때마다 TodoWrite로 해당 항목을 completed로 표시하세요.',
+    '4. 항목 옆에 "도구:" 가 표기된 경우, 그 도구를 직접 호출해서 단계를 실행하세요.',
+    '',
+].join('\n');
+function fmtState(s) {
+    return s === 'done' ? '☑︎' : s === 'blocked' ? '⛔' : '◻︎';
+}
+function risksToSteps(risks, toolHint) {
+    return risks.map((r) => ({
+        state: 'blocked',
+        title: `[${r.code}] ${r.title}`,
+        detail: r.detail + (r.fixUrl ? `  → ${r.fixUrl}` : ''),
+        tool: r.level === 'blocker' ? toolHint : undefined,
+    }));
+}
+function renderPlan(ctx, steps) {
+    const blocked = steps.filter((s) => s.state === 'blocked').length;
+    const pending = steps.filter((s) => s.state === 'pending').length;
+    const done = steps.filter((s) => s.state === 'done').length;
+    const lines = [];
+    lines.push(TODO_DIRECTIVE);
+    lines.push(`🎯 ${ctx.platform} 배포 플랜`);
+    lines.push('');
+    lines.push(`  대상: ${ctx.identity}`);
+    lines.push(`  버전: ${ctx.version}`);
+    if (ctx.track)
+        lines.push(`  트랙: ${ctx.track}`);
+    lines.push('');
+    lines.push(`  진행률: ☑︎ ${done}  ◻︎ ${pending}  ⛔ ${blocked}`);
+    if (blocked > 0) {
+        lines.push(`  ⚠️  블로커 ${blocked}건 — 먼저 해결해야 제출 가능`);
+    }
+    lines.push('');
+    lines.push('체크리스트 (TodoWrite로 사용자에게 제시):');
+    lines.push('');
+    for (const s of steps) {
+        const irr = s.irreversible ? ' ⚠️ 비가역' : '';
+        lines.push(`${fmtState(s.state)} ${s.title}${irr}`);
+        if (s.detail)
+            lines.push(`     ${s.detail}`);
+        if (s.tool)
+            lines.push(`     도구: ${s.tool}`);
+    }
+    lines.push('');
+    lines.push('—');
+    lines.push('TodoWrite로 위 미완료 항목을 등록한 후, 사용자 확인을 받고 도구를 단계별로 호출하세요.');
+    return lines.join('\n');
+}
+// ─── Play Store ──────────────────────────────────────────────────────
+export async function buildPlayStoreReleasePlan(opts) {
+    const { auth, packageName, versionCode, track, language } = opts;
+    const steps = [];
+    // 1) 인증 + 트랙 / 빌드 상태 조회 (단일 edit session)
+    let trackInfo = {
+        hasTargetVersion: false,
+    };
+    let listingPresent = false;
+    try {
+        await withEdit(auth, packageName, async (editId) => {
+            const [tracks, listing] = await Promise.all([
+                publisher().edits.tracks.list({ auth, packageName, editId }).catch(() => null),
+                publisher().edits.listings.get({ auth, packageName, editId, language }).catch(() => null),
+            ]);
+            const targetTrack = tracks?.data?.tracks?.find((t) => t.track === track);
+            const release = targetTrack?.releases?.[0];
+            const codes = release?.versionCodes ?? [];
+            trackInfo = {
+                hasTargetVersion: versionCode ? codes.includes(versionCode) : codes.length > 0,
+                latestVersionCode: codes[codes.length - 1],
+                releaseStatus: release?.status ?? undefined,
+            };
+            listingPresent = !!listing?.data?.title;
+            return null;
+        });
+        steps.push({ state: 'done', title: 'Google Play 인증 + 트랙 조회 성공' });
+    }
+    catch (e) {
+        steps.push({
+            state: 'blocked',
+            title: 'Google Play 인증 또는 트랙 조회 실패',
+            detail: e instanceof Error ? e.message : String(e),
+            tool: 'mimi_seed_auth_status',
+        });
+        return renderPlan({ platform: 'Play Store', identity: packageName, version: versionCode ?? 'latest', track }, steps);
+    }
+    // 2) 빌드 도착 확인
+    if (trackInfo.hasTargetVersion) {
+        steps.push({
+            state: 'done',
+            title: `${track} 트랙에 versionCode ${versionCode ?? trackInfo.latestVersionCode} 도착 확인`,
+            detail: `현재 release status: ${trackInfo.releaseStatus ?? 'unknown'}`,
+        });
+    }
+    else {
+        steps.push({
+            state: 'blocked',
+            title: versionCode
+                ? `${track} 트랙에 versionCode ${versionCode} 없음`
+                : `${track} 트랙에 release 없음`,
+            detail: 'Gradle / Fastlane / Play Console 업로드를 먼저 완료하세요.',
+            tool: 'playstore_list_tracks',
+        });
+    }
+    // 3) 메타데이터 / 스크린샷 / 정책 위험 점검
+    const risks = await checkPlayStoreRisks(auth, packageName, language);
+    if (risks.length === 0) {
+        steps.push({
+            state: 'done',
+            title: '제출 위험 점검 통과 (블로커 0)',
+        });
+    }
+    else {
+        const blockers = risks.filter((r) => r.level === 'blocker');
+        const warnings = risks.filter((r) => r.level === 'warning');
+        steps.push({
+            state: blockers.length > 0 ? 'blocked' : 'pending',
+            title: `제출 위험 ${risks.length}건 (블로커 ${blockers.length} / 경고 ${warnings.length})`,
+            detail: '아래 항목을 개별 수정 후 다시 plan 호출 권장',
+            tool: 'playstore_check_submission_risks',
+        });
+        steps.push(...risksToSteps(blockers, 'playstore_update_listing'));
+        steps.push(...risksToSteps(warnings, 'playstore_update_listing'));
+    }
+    // 4) 릴리즈 노트
+    steps.push({
+        state: 'pending',
+        title: `릴리즈 노트 등록/갱신 (${language})`,
+        detail: 'AI 노트 초안 + 사용자 확인 후 적용',
+        tool: 'playstore_update_release_notes (또는 playstore_update_latest_release_notes)',
+    });
+    // 5) 제출
+    const canSubmit = !risks.some((r) => r.level === 'blocker') && trackInfo.hasTargetVersion;
+    steps.push({
+        state: canSubmit ? 'pending' : 'blocked',
+        title: `${track} 트랙 release status 변경 (draft → completed)`,
+        detail: canSubmit
+            ? '⚠️ 비가역에 가까움. 사용자 명시 동의 필수.'
+            : '블로커 해결 후 가능',
+        tool: 'playstore_submit_release',
+        irreversible: true,
+    });
+    return renderPlan({ platform: 'Play Store', identity: packageName, version: versionCode ?? 'latest', track }, steps);
+}
+// ─── App Store ────────────────────────────────────────────────────────
+export async function buildAppStoreReleasePlan(opts) {
+    const { appId, versionString } = opts;
+    const steps = [];
+    // 1) 편집 가능한 버전 조회
+    let versionId;
+    let versionState;
+    let buildAttached = false;
+    try {
+        const versions = await apiGet(`/apps/${appId}/appStoreVersions`, {
+            'filter[appStoreState]': 'PREPARE_FOR_SUBMISSION,WAITING_FOR_REVIEW,DEVELOPER_REJECTED',
+            ...(versionString ? { 'filter[versionString]': versionString } : {}),
+            limit: '5',
+        }).catch(() => null);
+        if (versions?.data?.length) {
+            versionId = versions.data[0].id;
+            versionState = versions.data[0].attributes?.appStoreState;
+            steps.push({
+                state: 'done',
+                title: `편집 가능한 버전 발견 (${versions.data[0].attributes?.versionString}, state=${versionState})`,
+            });
+            // build attached?
+            const build = await apiGet(`/appStoreVersions/${versionId}/build`).catch(() => null);
+            buildAttached = !!build?.data?.id;
+            if (buildAttached) {
+                steps.push({ state: 'done', title: '버전에 빌드 연결됨' });
+            }
+            else {
+                steps.push({
+                    state: 'blocked',
+                    title: '버전에 빌드 미연결',
+                    detail: 'TestFlight 빌드 처리 완료 후 App Store Connect에서 연결하거나 API로 attach.',
+                    tool: 'appstore_list_builds',
+                });
+            }
+        }
+        else {
+            steps.push({
+                state: 'blocked',
+                title: versionString
+                    ? `편집 가능한 ${versionString} 버전 없음`
+                    : '편집 가능한 버전 없음',
+                detail: 'App Store Connect에서 새 버전을 생성하세요.',
+            });
+        }
+    }
+    catch (e) {
+        steps.push({
+            state: 'blocked',
+            title: 'App Store 인증 또는 버전 조회 실패',
+            detail: e instanceof Error ? e.message : String(e),
+            tool: 'mimi_seed_auth_status',
+        });
+        return renderPlan({ platform: 'App Store', identity: appId, version: versionString ?? 'latest' }, steps);
+    }
+    // 2) 메타데이터 / 스크린샷 / 정책 위험 점검
+    const risks = await checkAppStoreRisks(appId);
+    if (risks.length === 0) {
+        steps.push({ state: 'done', title: '제출 위험 점검 통과 (블로커 0)' });
+    }
+    else {
+        const blockers = risks.filter((r) => r.level === 'blocker');
+        const warnings = risks.filter((r) => r.level === 'warning');
+        steps.push({
+            state: blockers.length > 0 ? 'blocked' : 'pending',
+            title: `제출 위험 ${risks.length}건 (블로커 ${blockers.length} / 경고 ${warnings.length})`,
+            tool: 'appstore_check_submission_risks',
+        });
+        steps.push(...risksToSteps(blockers, 'appstore_update_localization'));
+        steps.push(...risksToSteps(warnings, 'appstore_update_localization'));
+    }
+    // 3) What's New / promotional text / reviewer notes
+    steps.push({
+        state: 'pending',
+        title: "What's New (릴리즈 노트) 등록/갱신",
+        detail: '버전별 로컬라이제이션마다 입력',
+        tool: 'appstore_update_whats_new',
+    });
+    steps.push({
+        state: 'pending',
+        title: 'Promotional Text / Description / Keywords 검토',
+        tool: 'appstore_update_localization',
+    });
+    // 4) 제출
+    const canSubmit = versionId && buildAttached && !risks.some((r) => r.level === 'blocker');
+    steps.push({
+        state: canSubmit ? 'pending' : 'blocked',
+        title: '심사 제출 (reviewSubmissions v2)',
+        detail: canSubmit
+            ? '⚠️ 비가역. 제출 후 메타/빌드 변경 불가 (REJECTED 시 재편집).'
+            : '블로커 해결 후 가능',
+        tool: versionId ? `appstore_submit_for_review (versionId=${versionId})` : 'appstore_submit_for_review',
+        irreversible: true,
+    });
+    return renderPlan({ platform: 'App Store', identity: appId, version: versionString ?? 'latest' }, steps);
+}

package/dist/index.js

@@ -2,7 +2,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-import { getAuthenticatedClient, getStoredTokens, startAuth } from './auth/google-auth.js';
+import { getAuthenticatedClient, startAuth, ensureFreshAccessToken } from './auth/google-auth.js';
 import { getServiceAccountClient, getServiceAccountJson } from './auth/playstore-auth.js';
 import { getAppStoreCredentials } from './appstore/auth.js';
 import { createGoogleOneTimePurchase, createGoogleSubscription, updateGoogleProduct, deleteGoogleProduct, listGoogleProducts, createAppleOneTimePurchase, createAppleSubscription, updateAppleProduct, deleteAppleProduct, listAppleProducts, } from '@onesub/providers';
@@ -14,6 +14,7 @@ import * as appstore from './appstore/tools.js';
 import * as appstoreScreenshots from './appstore/screenshots.js';
 import * as iam from './iam/tools.js';
 import { checkPlayStoreRisks, checkAppStoreRisks, formatRisks } from './checks/risks.js';
+import { buildPlayStoreReleasePlan, buildAppStoreReleasePlan } from './checks/plan.js';
 import { validateAppStoreScreenshots, validatePlayStoreScreenshots, formatValidationResults } from './checks/screenshots.js';
 import { generateReleaseNotesFromCommits, formatGeneratedNotes } from './ai/notes.js';
 import { generateReviewReply, formatReviewReply } from './ai/review.js';
@@ -1042,6 +1043,42 @@ server.tool('appstore_delete_product', '⚠️ 비가역. App Store IAP 상품
     }
     return { content: [{ type: 'text', text: `✓ ${productId} 삭제 완료` }] };
 });
+// --- 배포 플랜 (read-only, AI에게 TodoWrite 지시) ---
+server.tool('playstore_plan_release', [
+    'Google Play 배포 플랜 — 인증/빌드/메타데이터/스크린샷/정책 위험을 한 번에 점검하고',
+    '체크리스트로 반환합니다 (read-only, 아무것도 변경하지 않음).',
+    '⚠️ AI 호출자 지시: 응답을 받으면 미완료 항목을 반드시 TodoWrite로 사용자에게 먼저 보여주고,',
+    '사용자 동의 후 단계별로 기존 도구(playstore_update_listing, playstore_update_release_notes,',
+    'playstore_submit_release 등)를 호출하세요. submit_release(status=completed)는 비가역이므로 반드시 명시 동의 필요.',
+].join(' '), {
+    packageName: z.string().describe('Android 패키지명 (예: gg.pryzm.coffee)'),
+    versionCode: z.string().optional().describe('확인할 versionCode. 미지정 시 트랙 최신 release 검사'),
+    track: z.enum(['production', 'beta', 'alpha', 'internal']).optional().describe('대상 트랙 (기본: production)'),
+    language: z.string().optional().describe('점검할 리스팅 언어 (기본: ko-KR)'),
+}, async ({ packageName, versionCode, track, language }) => {
+    const auth = requirePlayStoreAuth();
+    const text = await buildPlayStoreReleasePlan({
+        auth,
+        packageName,
+        versionCode,
+        track: track ?? 'production',
+        language: language ?? 'ko-KR',
+    });
+    return { content: [{ type: 'text', text }] };
+});
+server.tool('appstore_plan_release', [
+    'App Store 배포 플랜 — 편집 가능한 버전/빌드 attach/메타/스크린샷/정책 위험을 한 번에 점검하고',
+    '체크리스트로 반환합니다 (read-only).',
+    '⚠️ AI 호출자 지시: 응답의 미완료 항목을 반드시 TodoWrite로 사용자에게 먼저 보여주고,',
+    '사용자 동의 후 단계별로 기존 도구(appstore_update_localization, appstore_update_whats_new,',
+    'appstore_submit_for_review 등)를 호출하세요. submit_for_review는 비가역이므로 반드시 명시 동의 필요.',
+].join(' '), {
+    appId: z.string().describe('App Store 앱 ID (appstore_list_apps 결과의 id)'),
+    versionString: z.string().optional().describe('대상 버전 (예: 1.3.0). 미지정 시 가장 최근 편집 가능 버전'),
+}, async ({ appId, versionString }) => {
+    const text = await buildAppStoreReleasePlan({ appId, versionString });
+    return { content: [{ type: 'text', text }] };
+});
 // --- App Store 심사 제출 (Submit for Review) ---
 server.tool('appstore_submit_for_review', [
     'App Store 버전을 심사에 제출 — 새 reviewSubmissions API 사용 (옛 /appStoreVersionSubmissions는 2024-01 deprecated).',
@@ -1130,34 +1167,43 @@ server.tool('mimi_seed_auth_start', [
             }],
     };
 });
-server.tool('mimi_seed_auth_status', 'Mimi Seed MCP 인증 상태 확인', {}, async () => {
-    const client = getAuthenticatedClient();
-    if (!client) {
-        return {
-            content: [{
-                    type: 'text',
-                    text: '❌ 인증되지 않음.\n\n터미널에서 실행:\n  npx -y @yoonion/mimi-seed-mcp mimi-seed-auth',
-                }],
-        };
-    }
-    const tokens = getStoredTokens();
-    if (tokens?.expiry_date) {
-        const now = Date.now();
-        const msUntilExpiry = tokens.expiry_date - now;
-        if (msUntilExpiry <= 0) {
+server.tool('mimi_seed_auth_status', 'Mimi Seed MCP 인증 상태 확인 (만료 시 refresh_token으로 자동 갱신 시도)', {}, async () => {
+    const r = await ensureFreshAccessToken();
+    switch (r.status) {
+        case 'unauthenticated':
             return {
-                content: [{ type: 'text', text: '⚠️ 토큰 만료. 다시 인증 필요.\n\n터미널에서 실행:\n  npx -y @yoonion/mimi-seed-mcp mimi-seed-auth' }],
+                content: [{
+                        type: 'text',
+                        text: `❌ [${r.error.code}] ${r.error.message}\n` +
+                            (r.error.hint ? `→ ${r.error.hint}\n\n` : '\n') +
+                            '터미널에서 실행:\n  npx -y @yoonion/mimi-seed-mcp mimi-seed-auth',
+                    }],
             };
+        case 'fresh': {
+            const min = Math.round(r.msUntilExpiry / 60000);
+            return { content: [{ type: 'text', text: `✅ 인증 유효 (${min}분 남음).` }] };
         }
-        if (msUntilExpiry <= 30 * 60 * 1000) {
+        case 'refreshed': {
+            const min = Math.round(r.msUntilExpiry / 60000);
             return {
-                content: [{ type: 'text', text: '⚠️ 토큰 곧 만료. 자동 갱신 예정.' }],
+                content: [{
+                        type: 'text',
+                        text: `✅ 토큰 만료 → refresh_token으로 자동 갱신 완료 (${min}분 남음).`,
+                    }],
             };
         }
+        case 'expired_refresh_failed':
+            return {
+                content: [{
+                        type: 'text',
+                        text: `⚠️ 토큰 만료 + 자동 갱신 실패\n` +
+                            `   코드: ${r.error.code}\n` +
+                            `   ${r.error.message}\n` +
+                            (r.error.hint ? `   → ${r.error.hint}\n` : '') +
+                            '\n터미널에서 재로그인:\n  npx -y @yoonion/mimi-seed-mcp mimi-seed-auth',
+                    }],
+            };
     }
-    return {
-        content: [{ type: 'text', text: '✅ 인증 완료.' }],
-    };
 });
 // ══════════════════════════════════════════════════
 // 제출 위험 점검 (Submission Risk Check)

package/package.json

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