@yoonion/mimi-seed-mcp 0.3.8 → 0.3.10

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/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';
@@ -1007,6 +1007,9 @@ server.tool('appstore_update_product', 'App Store IAP 상품의 reference name
     productType: z.enum(['subscription', 'consumable', 'non_consumable']).describe('상품 유형'),
     name: z.string().describe('새 reference name'),
 }, async ({ appId, bundleId, productId, productType, name }) => {
+    if (!appId && !bundleId) {
+        throw new Error('appId 또는 bundleId 중 하나는 반드시 제공해야 합니다.');
+    }
     const creds = requireAppStoreCreds();
     const result = await updateAppleProduct({
         appId, bundleId, productId, productType, name,
@@ -1023,6 +1026,9 @@ server.tool('appstore_delete_product', '⚠️ 비가역. App Store IAP 상품
     productId: z.string().describe('상품 ID'),
     productType: z.enum(['subscription', 'consumable', 'non_consumable']).describe('상품 유형'),
 }, async ({ appId, bundleId, productId, productType }) => {
+    if (!appId && !bundleId) {
+        throw new Error('appId 또는 bundleId 중 하나는 반드시 제공해야 합니다.');
+    }
     const creds = requireAppStoreCreds();
     const result = await deleteAppleProduct({
         appId, bundleId, productId, productType,
@@ -1124,34 +1130,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.8",
+  "version": "0.3.10",
   "description": "Mimi Seed MCP server — Firebase + AdMob + Google Play + App Store management for Claude Code / Cursor / any MCP client.",
   "type": "module",
   "bin": {