@milcho0604/velog-mcp 0.4.0

package/dist/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAkBH,2CAA2C;AAC3C,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;AAEnD,SAAS,IAAI,CAAC,KAAyB;IACtC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC/B,MAAyB,OAAO,CAAC,GAAG;IAEpC,OAAO;QACN,aAAa,EAAE,IAAI,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;QAC9C,WAAW,EAAE,IAAI,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;KAC7C,CAAC;AACH,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,oBAAoB,CAAC,YAA0B;IAC9D,MAAM,KAAK,GAAG;QACb,YAAY,CAAC,aAAa;YACzB,CAAC,CAAC,yBAAyB;YAC3B,CAAC,CAAC,kBAAkB;KACrB,CAAC;IACF,IAAI,YAAY,CAAC,WAAW;QAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAEnD,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,CAAC,YAAY,CAAC,aAAa;QAAE,GAAG,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;IACtE,IAAI,CAAC,YAAY,CAAC,WAAW;QAAE,GAAG,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC;IAEtE,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAC3E,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,113 @@
+/**
+ * 벨로그 GraphQL 클라이언트.
+ *
+ * Node 24 내장 fetch 만 쓴다 — HTTP 라이브러리를 추가하지 않는다.
+ * 접속하는 호스트는 v3.velog.io 하나뿐이다 (docs/security.md).
+ */
+import { type AuthState } from './auth.ts';
+export declare const VELOG_ENDPOINT = "https://v3.velog.io/graphql";
+/**
+ * 이미지 업로드만 GraphQL 이 아니다.
+ *
+ * v3 의 mutation 23개 어디에도 업로드가 없다. 벨로그 서버는 파일을 fastify REST
+ * 라우트로 받는다 — `routes/index.mts` 가 `/api` 아래에 `/files` 를 붙이고,
+ * `routes/files/index.mts` 가 다시 `/v3` 를 붙여 아래 경로가 된다.
+ * 폼 필드 이름이 `image` 인 것도 서버 쪽 `multer.single('image')` 에서 온다.
+ */
+export declare const VELOG_UPLOAD_ENDPOINT = "https://v3.velog.io/api/files/v3/upload";
+/**
+ * 벨로그가 비정상 응답을 줬을 때. 메시지는 마스킹을 거친 뒤 담긴다.
+ *
+ * ★ 파라미터 프로퍼티(`constructor(readonly x: T)`)를 쓰지 않는다.
+ *   Node 의 타입 스트리핑은 '지우기만' 하지 코드를 생성하지 않아
+ *   ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX 로 죽는다. 같은 이유로 이 레포는
+ *   enum·namespace·데코레이터도 쓰지 않는다. (docs/architecture.md 참고)
+ */
+export interface VelogApiErrorDetail {
+    readonly status?: number;
+    /** 코드만 보관한다. 원본 응답에는 토큰이 섞일 수 있다. */
+    readonly graphqlErrorCodes?: readonly string[];
+    /**
+     * 네트워크 오류의 원인 표식 (ECONNRESET·TimeoutError 등).
+     * ★ Node 의 fetch 실패는 TypeError('fetch failed') 로 오고 진짜 원인은
+     *   cause 체인에 있다. message 만 뽑으면 'fetch failed' 만 남아 재시도 판정이
+     *   전부 실패한다 — 실측으로 확인함.
+     */
+    readonly networkCodes?: readonly string[];
+}
+/** cause 체인을 훑어 code·name 을 모은다. 토큰이 섞일 수 있는 message 는 담지 않는다. */
+export declare function collectCauseCodes(error: unknown, depth?: number): string[];
+export declare class VelogApiError extends Error {
+    readonly detail: VelogApiErrorDetail | undefined;
+    constructor(message: string, detail?: VelogApiErrorDetail);
+}
+export interface ClientOptions {
+    readonly auth: AuthState;
+    readonly endpoint?: string;
+    readonly uploadEndpoint?: string;
+    readonly timeoutMs?: number;
+    readonly fetchImpl?: typeof fetch;
+    readonly maxRetries?: number;
+    /** 테스트에서 대기를 건너뛰기 위해 주입한다. */
+    readonly sleepImpl?: (ms: number) => Promise<void>;
+    /**
+     * 인증 상태로 비-벨로그 엔드포인트에 요청하는 것을 허용한다.
+     * 가짜 fetch 로 도구를 검사하는 테스트 전용이며, 운영 경로에서는 절대 켜지 않는다.
+     */
+    readonly allowInsecureEndpoint?: boolean;
+}
+export declare function isTransient(error: unknown): boolean;
+export declare class VelogClient {
+    #private;
+    constructor(options: ClientOptions);
+    get isAuthenticated(): boolean;
+    /** 인증이 필요한 도구가 먼저 호출한다. */
+    requireAuth(toolName: string): void;
+    /**
+     * 일시적 실패는 지수 백오프로 다시 친다. 영구 오류(인증 만료·잘못된 질의)는
+     * 즉시 던진다 — 재시도해봤자 같은 답이고 사용자만 기다린다.
+     *
+     * ★ mutation 은 재시도하지 않는다. 멱등하지 않기 때문이다.
+     *   서버가 글을 만든 뒤 응답만 유실되면 재시도가 초안을 하나 더 만든다.
+     *   그냥 중복이 아니라 실제 피해로 이어진다 — mutate() 주석 참고.
+     */
+    request<T>(query: string, variables?: Record<string, unknown>): Promise<T>;
+    /**
+     * 쓰기 전용 — **재시도하지 않는다.**
+     *
+     * 벨로그는 최근 5분의 `is_private:false` 글을 세는데 `is_temp` 를 구분하지
+     * 않는다. 10개를 넘으면 최근 5분의 글을 **전부** `is_private:true` 로 바꾼다:
+     *
+     *   // apps/server/src/services/PostApiService/index.mts
+     *   const recentPostCount = await db.post.count({
+     *     where: { fk_user_id, is_private: false, released_at: { gt: 5분전 } } })
+     *   if (recentPostCount < 10) return false
+     *   await db.post.updateMany({
+     *     where: { fk_user_id, released_at: { gt: 5분전 } },   // is_private 필터 없음
+     *     data: { is_private: true } })
+     *
+     * 초안도 Prisma 기본값으로 `released_at = now()` 가 붙으므로(schema.prisma)
+     * 이 카운트에 들어간다. 즉 초안을 몰아 만들면 **같은 시간대에 발행한 진짜 글이
+     * 비공개로 내려간다.** 응답 유실로 인한 자동 재시도가 이 한계를 앞당길 수 있어
+     * 쓰기는 한 번만 친다. 실패하면 사용자가 상태를 확인하고 다시 부르게 한다.
+     */
+    mutate<T>(query: string, variables?: Record<string, unknown>): Promise<T>;
+    /**
+     * 이미지 업로드. **재시도하지 않는다.**
+     *
+     * 벨로그는 업로드 횟수를 사용자 단위로 센다 (`ImageService.detectAbuse`):
+     * 1시간 100건 초과 또는 1분 20건 이상이면 그 계정을 막고 슬랙으로 알린다.
+     * 응답만 유실됐을 때 자동 재시도하면 실제로는 두 번 올라가 이 한도를 앞당긴다.
+     * mutate() 와 같은 이유로 한 번만 친다.
+     *
+     * `refId` 를 주면 서버가 "그 글이 내 글인지" 확인한다 (남의 글이면 403).
+     * 벨로그에 몇 없는 실제 소유권 검사라 쓸 수 있으면 쓴다.
+     *
+     * @returns 업로드된 이미지의 공개 URL (`https://velog.velcdn.com/...`)
+     */
+    uploadImage(bytes: Uint8Array, filename: string, options: {
+        readonly type: 'post' | 'profile';
+        readonly contentType: string;
+        readonly refId?: string;
+    }): Promise<string>;
+}

package/dist/client.js

@@ -0,0 +1,322 @@
+/**
+ * 벨로그 GraphQL 클라이언트.
+ *
+ * Node 24 내장 fetch 만 쓴다 — HTTP 라이브러리를 추가하지 않는다.
+ * 접속하는 호스트는 v3.velog.io 하나뿐이다 (docs/security.md).
+ */
+import { AuthRequiredError, TokenStore, buildCookieHeader, parseSetCookie, } from "./auth.js";
+export const VELOG_ENDPOINT = 'https://v3.velog.io/graphql';
+/**
+ * 이미지 업로드만 GraphQL 이 아니다.
+ *
+ * v3 의 mutation 23개 어디에도 업로드가 없다. 벨로그 서버는 파일을 fastify REST
+ * 라우트로 받는다 — `routes/index.mts` 가 `/api` 아래에 `/files` 를 붙이고,
+ * `routes/files/index.mts` 가 다시 `/v3` 를 붙여 아래 경로가 된다.
+ * 폼 필드 이름이 `image` 인 것도 서버 쪽 `multer.single('image')` 에서 온다.
+ */
+export const VELOG_UPLOAD_ENDPOINT = 'https://v3.velog.io/api/files/v3/upload';
+/** cause 체인을 훑어 code·name 을 모은다. 토큰이 섞일 수 있는 message 는 담지 않는다. */
+export function collectCauseCodes(error, depth = 5) {
+    const codes = [];
+    let current = error;
+    for (let i = 0; i < depth && current; i++) {
+        if (typeof current !== 'object')
+            break;
+        const node = current;
+        if (typeof node.name === 'string')
+            codes.push(node.name);
+        if (typeof node.code === 'string')
+            codes.push(node.code);
+        current = node.cause;
+    }
+    return codes;
+}
+export class VelogApiError extends Error {
+    detail;
+    constructor(message, detail) {
+        super(message);
+        this.name = 'VelogApiError';
+        this.detail = detail;
+    }
+}
+/**
+ * 벨로그는 Prisma 커넥션 풀이 작다 (connection limit 5 / timeout 10s).
+ * 연속 호출하면 아래 오류가 실제로 뜬다 — 우리 잘못이 아니라 상대 쪽 포화다.
+ *
+ *   Timed out fetching a new connection from the connection pool
+ *
+ * 2026-07-30 실측: velog_export_posts 처럼 순차 요청이 많은 도구에서 재현.
+ * 영구 실패가 아니므로 잠깐 쉬었다 다시 친다.
+ */
+const TRANSIENT_CODES = new Set([
+    'ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'EPIPE', 'EAI_AGAIN',
+    'ENOTFOUND', 'UND_ERR_SOCKET', 'UND_ERR_CONNECT_TIMEOUT',
+    'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_BODY_TIMEOUT',
+    'TimeoutError', 'AbortError',
+]);
+export function isTransient(error) {
+    if (!(error instanceof VelogApiError))
+        return false;
+    const status = error.detail?.status;
+    if (status !== undefined && status >= 500)
+        return true;
+    // 4xx 는 다시 쳐도 같은 답이다.
+    if (status !== undefined && status < 500)
+        return false;
+    // ★ 네트워크 오류는 message 가 아니라 cause 체인의 code 로 판정한다.
+    for (const code of error.detail?.networkCodes ?? []) {
+        if (TRANSIENT_CODES.has(code))
+            return true;
+    }
+    return /connection pool|timed out|timeout|ETIMEDOUT|ECONNRESET|socket hang up/i.test(error.message);
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** 인증 만료 안내. HTTP 401 경로와 GraphQL errors 경로 둘 다에서 쓴다. */
+const AUTH_HINT = ' — access_token 이 만료됐을 수 있습니다(유효기간 1시간). 새 토큰으로 갱신하세요.';
+export class VelogClient {
+    #tokens;
+    #endpoint;
+    #uploadEndpoint;
+    #timeoutMs;
+    #fetch;
+    #maxRetries;
+    #sleep;
+    #allowInsecureEndpoint;
+    constructor(options) {
+        this.#tokens = new TokenStore(options.auth);
+        this.#endpoint = options.endpoint ?? VELOG_ENDPOINT;
+        this.#uploadEndpoint = options.uploadEndpoint ?? VELOG_UPLOAD_ENDPOINT;
+        this.#timeoutMs = options.timeoutMs ?? 20_000;
+        this.#fetch = options.fetchImpl ?? fetch;
+        this.#maxRetries = options.maxRetries ?? 2;
+        this.#sleep = options.sleepImpl ?? defaultSleep;
+        this.#allowInsecureEndpoint = options.allowInsecureEndpoint ?? false;
+    }
+    get isAuthenticated() {
+        return this.#tokens.isAuthenticated;
+    }
+    /** 인증이 필요한 도구가 먼저 호출한다. */
+    requireAuth(toolName) {
+        if (!this.#tokens.isAuthenticated)
+            throw new AuthRequiredError(toolName);
+    }
+    /**
+     * 일시적 실패는 지수 백오프로 다시 친다. 영구 오류(인증 만료·잘못된 질의)는
+     * 즉시 던진다 — 재시도해봤자 같은 답이고 사용자만 기다린다.
+     *
+     * ★ mutation 은 재시도하지 않는다. 멱등하지 않기 때문이다.
+     *   서버가 글을 만든 뒤 응답만 유실되면 재시도가 초안을 하나 더 만든다.
+     *   그냥 중복이 아니라 실제 피해로 이어진다 — mutate() 주석 참고.
+     */
+    async request(query, variables = {}) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.#maxRetries; attempt++) {
+            try {
+                return await this.#requestOnce(query, variables);
+            }
+            catch (error) {
+                lastError = error;
+                if (!isTransient(error) || attempt === this.#maxRetries)
+                    throw error;
+                await this.#sleep(500 * 2 ** attempt); // 500ms → 1s
+            }
+        }
+        throw lastError;
+    }
+    /**
+     * 쓰기 전용 — **재시도하지 않는다.**
+     *
+     * 벨로그는 최근 5분의 `is_private:false` 글을 세는데 `is_temp` 를 구분하지
+     * 않는다. 10개를 넘으면 최근 5분의 글을 **전부** `is_private:true` 로 바꾼다:
+     *
+     *   // apps/server/src/services/PostApiService/index.mts
+     *   const recentPostCount = await db.post.count({
+     *     where: { fk_user_id, is_private: false, released_at: { gt: 5분전 } } })
+     *   if (recentPostCount < 10) return false
+     *   await db.post.updateMany({
+     *     where: { fk_user_id, released_at: { gt: 5분전 } },   // is_private 필터 없음
+     *     data: { is_private: true } })
+     *
+     * 초안도 Prisma 기본값으로 `released_at = now()` 가 붙으므로(schema.prisma)
+     * 이 카운트에 들어간다. 즉 초안을 몰아 만들면 **같은 시간대에 발행한 진짜 글이
+     * 비공개로 내려간다.** 응답 유실로 인한 자동 재시도가 이 한계를 앞당길 수 있어
+     * 쓰기는 한 번만 친다. 실패하면 사용자가 상태를 확인하고 다시 부르게 한다.
+     */
+    async mutate(query, variables = {}) {
+        return this.#requestOnce(query, variables);
+    }
+    /**
+     * 이미지 업로드. **재시도하지 않는다.**
+     *
+     * 벨로그는 업로드 횟수를 사용자 단위로 센다 (`ImageService.detectAbuse`):
+     * 1시간 100건 초과 또는 1분 20건 이상이면 그 계정을 막고 슬랙으로 알린다.
+     * 응답만 유실됐을 때 자동 재시도하면 실제로는 두 번 올라가 이 한도를 앞당긴다.
+     * mutate() 와 같은 이유로 한 번만 친다.
+     *
+     * `refId` 를 주면 서버가 "그 글이 내 글인지" 확인한다 (남의 글이면 403).
+     * 벨로그에 몇 없는 실제 소유권 검사라 쓸 수 있으면 쓴다.
+     *
+     * @returns 업로드된 이미지의 공개 URL (`https://velog.velcdn.com/...`)
+     */
+    async uploadImage(bytes, filename, options) {
+        const auth = this.#tokens.state;
+        if (auth.kind !== 'authenticated')
+            throw new AuthRequiredError('velog_upload_image');
+        // GraphQL 경로와 같은 규율 — 자격증명은 벨로그 정규 주소로만 나간다.
+        const headers = { Accept: 'application/json' };
+        if (this.#uploadEndpoint === VELOG_UPLOAD_ENDPOINT) {
+            headers['Cookie'] = buildCookieHeader(auth.credentials);
+        }
+        else if (!this.#allowInsecureEndpoint) {
+            throw new VelogApiError(`이미지는 ${VELOG_UPLOAD_ENDPOINT} 로만 보낼 수 있습니다. ` +
+                '다른 주소로는 파일도 토큰도 보내지 않습니다.');
+        }
+        const form = new FormData();
+        form.append('type', options.type);
+        if (options.refId)
+            form.append('ref_id', options.refId);
+        // ★ 필드 이름은 반드시 'image'. 서버가 multer.single('image') 로 받는다.
+        //   Content-Type 헤더는 손대지 않는다 — fetch 가 multipart 경계를 붙인다.
+        form.append('image', new Blob([bytes], { type: options.contentType }), filename);
+        let response;
+        try {
+            response = await this.#fetch(this.#uploadEndpoint, {
+                method: 'POST',
+                headers,
+                body: form,
+                // 이미지는 GraphQL 질의보다 오래 걸린다. 최소 60초는 준다.
+                signal: AbortSignal.timeout(Math.max(this.#timeoutMs, 60_000)),
+            });
+        }
+        catch (cause) {
+            const reason = cause instanceof Error ? cause.message : String(cause);
+            const codes = collectCauseCodes(cause);
+            // ★ '실패'라고 단정하면 안 된다. 서버가 파일을 받아 저장한 뒤 응답만
+            //   끊겼을 수도 있다. 그 상태에서 다시 올리면 중복 업로드가 되고 한도만
+            //   깎인다. 무엇을 모르는지 그대로 알려줘야 사용자가 판단할 수 있다.
+            throw new VelogApiError(`이미지 업로드 중 통신이 끊겼습니다: ${this.#mask(reason)}` +
+                `${codes.length ? ` (${codes.join('/')})` : ''}\n` +
+                '⚠️ 올라갔는지 아닌지 알 수 없습니다. 다시 올리면 같은 그림이 두 번 저장될 수 ' +
+                '있으니(삭제 API 없음) 벨로그에서 확인한 뒤 결정하세요.', { networkCodes: codes });
+        }
+        this.#tokens.update(parseSetCookie(response.headers.get('set-cookie')));
+        if (!response.ok) {
+            const body = this.#mask(await response.text().catch(() => ''));
+            let hint = '';
+            if (response.status === 401 || response.status === 403)
+                hint = AUTH_HINT;
+            if (response.status === 429) {
+                hint =
+                    ' — 벨로그가 업로드를 일시 차단했습니다. 1시간 100건 / 1분 20건이 한도입니다.';
+            }
+            if (response.status === 413)
+                hint = ' — 파일이 너무 큽니다 (서버 상한 30MB).';
+            // ★ 5xx 는 서버가 이미 저장한 뒤 실패했을 수도 있다. 통신 단절과 같은 성격이다.
+            if (response.status >= 500) {
+                hint =
+                    '\n⚠️ 서버 오류라 저장 여부를 알 수 없습니다. 다시 올리면 중복될 수 ' +
+                        '있으니(삭제 API 없음) 벨로그에서 확인한 뒤 결정하세요.';
+            }
+            throw new VelogApiError(`이미지 업로드 HTTP ${response.status}: ${truncate(body, 300)}${hint}`, { status: response.status });
+        }
+        let payload;
+        try {
+            payload = (await response.json());
+        }
+        catch (cause) {
+            // 2xx 를 받고 본문만 못 읽은 경우다 — 서버는 이미 저장했을 가능성이 높다.
+            throw new VelogApiError('업로드 응답을 JSON 으로 읽지 못했습니다: ' +
+                this.#mask(cause instanceof Error ? cause.message : String(cause)) +
+                '\n⚠️ 서버는 200 을 줬으므로 이미 저장됐을 수 있습니다. 다시 올리기 전에 확인하세요.');
+        }
+        if (typeof payload.path !== 'string' || payload.path === '') {
+            throw new VelogApiError('업로드는 됐는데 서버가 이미지 주소를 주지 않았습니다.');
+        }
+        return payload.path;
+    }
+    async #requestOnce(query, variables) {
+        const headers = {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        };
+        // ★ 자격증명은 벨로그 정규 엔드포인트로만 보낸다.
+        //   endpoint 는 테스트 주입용 옵션인데, 임의 URL 이 들어오면 쿠키가 그
+        //   호스트로 나간다. "벨로그 외 호스트에 접속하지 않는다"는 보장을 코드로
+        //   지키려면 여기서 목적지를 확인해야 한다 — 문자열 검색 테스트로는 못 막는다.
+        const auth = this.#tokens.state;
+        if (auth.kind === 'authenticated') {
+            if (this.#endpoint === VELOG_ENDPOINT) {
+                headers['Cookie'] = buildCookieHeader(auth.credentials);
+            }
+            else if (!this.#allowInsecureEndpoint) {
+                throw new VelogApiError(`인증 요청은 ${VELOG_ENDPOINT} 로만 보낼 수 있습니다. ` +
+                    '다른 엔드포인트로는 토큰을 전송하지 않습니다.');
+            }
+        }
+        let response;
+        try {
+            response = await this.#fetch(this.#endpoint, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({ query, variables }),
+                signal: AbortSignal.timeout(this.#timeoutMs),
+            });
+        }
+        catch (cause) {
+            const reason = cause instanceof Error ? cause.message : String(cause);
+            const codes = collectCauseCodes(cause);
+            // 네트워크 예외에도 요청 정보가 실릴 수 있으므로 마스킹한다.
+            // 원인 코드를 detail 에 실어야 재시도 판정이 동작한다.
+            throw new VelogApiError(`벨로그 요청 실패: ${this.#mask(reason)}${codes.length ? ` (${codes.join('/')})` : ''}`, { networkCodes: codes });
+        }
+        // ★ 벨로그는 access_token 수명이 30분 아래로 내려가면 refresh_token 으로
+        //   재발급해 Set-Cookie 로 돌려준다 (공식 authPlugin.mts). 이걸 버리면
+        //   1시간마다 세션이 죽는다. 받아서 메모리에만 반영한다 — 디스크엔 안 쓴다.
+        //   실패 응답에도 실려 올 수 있으므로 상태 확인보다 먼저 처리한다.
+        this.#tokens.update(parseSetCookie(response.headers.get('set-cookie')));
+        if (!response.ok) {
+            const body = this.#mask(await response.text().catch(() => ''));
+            // ★ 벨로그는 만료 토큰에 HTTP 401 을 준다 (실측). GraphQL errors 경로가
+            //   아니라 여기로 떨어지므로, 만료 안내를 이쪽에도 붙여야 한다.
+            //   실사용에서 제일 흔한 오류인데 안내가 없으면 원인을 못 찾는다.
+            const hint = response.status === 401 || response.status === 403 ? AUTH_HINT : '';
+            throw new VelogApiError(`벨로그 HTTP ${response.status}: ${truncate(body, 400)}${hint}`, { status: response.status });
+        }
+        // ★ JSON 파싱 실패가 그냥 SyntaxError 로 빠지면 마스킹도 재시도 판정도 우회한다.
+        //   벨로그가 502 HTML 을 200 으로 주는 경우가 실제로 있다.
+        let payload;
+        try {
+            payload = (await response.json());
+        }
+        catch (cause) {
+            const reason = cause instanceof Error ? cause.message : String(cause);
+            throw new VelogApiError(`벨로그 응답을 JSON 으로 읽지 못했습니다: ${this.#mask(reason)}`, { networkCodes: collectCauseCodes(cause) });
+        }
+        if (payload.errors?.length) {
+            const messages = payload.errors
+                .map((e) => e.message ?? '(메시지 없음)')
+                .join(' / ');
+            const codes = payload.errors.map((e) => e.extensions?.code).filter(Boolean);
+            // 만료를 뭉뚱그리면 사용자가 원인을 못 찾는다. 별도로 짚어준다.
+            const looksUnauthenticated = codes.includes('UNAUTHENTICATED') || /not logged|unauthor/i.test(messages);
+            const hint = looksUnauthenticated ? AUTH_HINT : '';
+            // ★ 원본 payload.errors 를 그대로 담으면 토큰이 Error 객체에 남는다.
+            //   지금은 MCP SDK 가 message 만 내보내지만, 나중에 console.error(error)
+            //   나 오류 수집기를 붙이는 순간 샌다. 코드만 보관한다.
+            throw new VelogApiError(`벨로그 GraphQL 오류: ${this.#mask(messages)}${hint}`, {
+                graphqlErrorCodes: codes.filter((c) => typeof c === 'string'),
+            });
+        }
+        if (payload.data === undefined || payload.data === null) {
+            throw new VelogApiError('벨로그가 빈 응답을 반환했습니다.');
+        }
+        return payload.data;
+    }
+    #mask(text) {
+        return this.#tokens.mask(text);
+    }
+}
+function truncate(text, max) {
+    return text.length <= max ? text : `${text.slice(0, max)}…`;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/format.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 응답 정형화.
+ *
+ * MCP 도구는 결국 모델이 읽는다. 원본 JSON 을 그대로 던지면 토큰만 먹고
+ * 정작 필요한 값(제목·슬러그·조회수)은 묻힌다. 목록은 표로, 단건은 본문 위주로 낸다.
+ */
+import type { VelogPostSummary, VelogPostDetail } from './types.ts';
+export declare function postUrl(post: VelogPostSummary): string;
+/** title 도 nullable 이라 표시 전에 한 번 거른다. */
+export declare function postTitle(post: VelogPostSummary): string;
+/** 목록 — 한 줄에 하나. 모델이 훑고 고르기 좋게. */
+export declare function formatPostList(posts: readonly VelogPostSummary[], options?: {
+    readonly total?: number;
+    readonly showAuthor?: boolean;
+}): string;
+/** 단건 — 메타는 압축하고 본문을 그대로 넘긴다. */
+export declare function formatPostDetail(post: VelogPostDetail): string;
+/** MCP 도구 반환 형태. */
+export declare function textResult(text: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function errorResult(text: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};

package/dist/format.js

@@ -0,0 +1,66 @@
+/**
+ * 응답 정형화.
+ *
+ * MCP 도구는 결국 모델이 읽는다. 원본 JSON 을 그대로 던지면 토큰만 먹고
+ * 정작 필요한 값(제목·슬러그·조회수)은 묻힌다. 목록은 표로, 단건은 본문 위주로 낸다.
+ */
+export function postUrl(post) {
+    const username = post.user?.username;
+    // url_slug 는 공식 스키마상 nullable 이다.
+    const slug = post.url_slug;
+    if (!slug)
+        return `(id: ${post.id})`;
+    return username ? `https://velog.io/@${username}/${slug}` : `(url_slug: ${slug})`;
+}
+/** title 도 nullable 이라 표시 전에 한 번 거른다. */
+export function postTitle(post) {
+    return post.title?.trim() || '(제목 없음)';
+}
+function dateOnly(iso) {
+    return iso ? iso.slice(0, 10) : '—';
+}
+/** 목록 — 한 줄에 하나. 모델이 훑고 고르기 좋게. */
+export function formatPostList(posts, options = {}) {
+    if (posts.length === 0)
+        return '결과 없음';
+    const lines = posts.map((p, i) => {
+        const head = `${String(i + 1).padStart(2)}. ${postTitle(p)}`;
+        const author = options.showAuthor && p.user?.username ? `@${p.user.username} · ` : '';
+        const stats = `${author}♥${p.likes ?? 0} · 👁${p.views ?? 0} · 💬${p.comments_count ?? 0}`;
+        const tags = p.tags?.length ? ` · #${p.tags.join(' #')}` : '';
+        const priv = p.is_private ? ' · 🔒비공개' : '';
+        return `${head}\n    ${dateOnly(p.released_at)} · ${stats}${tags}${priv}\n    ${postUrl(p)}`;
+    });
+    const header = options.total !== undefined && options.total > posts.length
+        ? `총 ${options.total.toLocaleString('ko-KR')}건 중 ${posts.length}건\n\n`
+        : `${posts.length}건\n\n`;
+    return header + lines.join('\n\n');
+}
+/** 단건 — 메타는 압축하고 본문을 그대로 넘긴다. */
+export function formatPostDetail(post) {
+    const meta = [
+        `# ${postTitle(post)}`,
+        '',
+        `- URL: ${postUrl(post)}`,
+        `- 작성: ${dateOnly(post.released_at ?? post.created_at)}`,
+        `- 통계: ♥${post.likes ?? 0} · 👁${post.views ?? 0} · 💬${post.comments_count ?? 0}`,
+    ];
+    if (post.tags?.length)
+        meta.push(`- 태그: ${post.tags.map((t) => `#${t}`).join(' ')}`);
+    if (post.series?.name)
+        meta.push(`- 시리즈: ${post.series.name}`);
+    if (post.is_temp)
+        meta.push('- 상태: **임시저장(비공개)**');
+    else if (post.is_private)
+        meta.push('- 상태: 비공개');
+    meta.push(`- id: \`${post.id}\``);
+    return `${meta.join('\n')}\n\n---\n\n${post.body ?? '(본문 없음)'}`;
+}
+/** MCP 도구 반환 형태. */
+export function textResult(text) {
+    return { content: [{ type: 'text', text }] };
+}
+export function errorResult(text) {
+    return { content: [{ type: 'text', text }], isError: true };
+}
+//# sourceMappingURL=format.js.map

package/dist/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"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"}

package/dist/graphql.d.ts

@@ -0,0 +1,29 @@
+/**
+ * GraphQL 질의문 모음.
+ *
+ * 필드 선택은 docs/api-reference.md 의 실측 스키마를 따른다.
+ *
+ * ★ 한 요청에 쿼리를 여러 개 묶지 않는다.
+ *   벨로그는 Prisma 커넥션 풀이 작아(limit 5 / timeout 10s) 묶어 보내면
+ *   "Timed out fetching a new connection from the connection pool" 이 뜬다.
+ *   2026-07-30 실측: searchPosts + trendingPosts 동시 요청 시 재현됨.
+ */
+/**
+ * 목록에 쓰는 최소 필드. body 를 빼서 응답 크기를 줄인다.
+ *
+ * ★ `updated_at` 을 일부러 뺐다.
+ *   스키마상 non-nullable 인데 실제로는 null 인 글이 존재한다. 그런 글이 결과에
+ *   하나라도 섞이면 GraphQL 이 응답 전체를 거부한다:
+ *     "Cannot return null for non-nullable field Post.updated_at."
+ *   2026-07-30 실측 — searchPosts(keyword:"MCP") 에서 재현. `released_at` 만
+ *   남기면 정상. 필드 하나를 잃는 것보다 글을 통째로 못 읽는 쪽이 나쁘다.
+ */
+export declare const POST_SUMMARY_FIELDS = "\n  id\n  title\n  url_slug\n  short_description\n  thumbnail\n  likes\n  views\n  comments_count\n  released_at\n  is_private\n  tags\n  user { username profile { display_name thumbnail } }\n  series { id name url_slug }\n";
+/** 단건 조회 — 본문 포함. */
+export declare const POST_DETAIL_FIELDS = "\n  \n  id\n  title\n  url_slug\n  short_description\n  thumbnail\n  likes\n  views\n  comments_count\n  released_at\n  is_private\n  tags\n  user { username profile { display_name thumbnail } }\n  series { id name url_slug }\n\n  body\n  is_markdown\n  is_temp\n  created_at\n";
+export declare const QUERY_POST = "\n  query GetPost($input: ReadPostInput!) {\n    post(input: $input) { \n  \n  id\n  title\n  url_slug\n  short_description\n  thumbnail\n  likes\n  views\n  comments_count\n  released_at\n  is_private\n  tags\n  user { username profile { display_name thumbnail } }\n  series { id name url_slug }\n\n  body\n  is_markdown\n  is_temp\n  created_at\n }\n  }\n";
+export declare const QUERY_POSTS = "\n  query GetPosts($input: GetPostsInput!) {\n    posts(input: $input) { \n  id\n  title\n  url_slug\n  short_description\n  thumbnail\n  likes\n  views\n  comments_count\n  released_at\n  is_private\n  tags\n  user { username profile { display_name thumbnail } }\n  series { id name url_slug }\n }\n  }\n";
+export declare const QUERY_SEARCH_POSTS = "\n  query SearchPosts($input: GetSearchPostsInput!) {\n    searchPosts(input: $input) {\n      count\n      posts { \n  id\n  title\n  url_slug\n  short_description\n  thumbnail\n  likes\n  views\n  comments_count\n  released_at\n  is_private\n  tags\n  user { username profile { display_name thumbnail } }\n  series { id name url_slug }\n }\n    }\n  }\n";
+export declare const QUERY_TRENDING_POSTS = "\n  query TrendingPosts($input: TrendingPostsInput!) {\n    trendingPosts(input: $input) { \n  id\n  title\n  url_slug\n  short_description\n  thumbnail\n  likes\n  views\n  comments_count\n  released_at\n  is_private\n  tags\n  user { username profile { display_name thumbnail } }\n  series { id name url_slug }\n }\n  }\n";
+export declare const QUERY_RECENT_POSTS = "\n  query RecentPosts($input: RecentPostsInput!) {\n    recentPosts(input: $input) { \n  id\n  title\n  url_slug\n  short_description\n  thumbnail\n  likes\n  views\n  comments_count\n  released_at\n  is_private\n  tags\n  user { username profile { display_name thumbnail } }\n  series { id name url_slug }\n }\n  }\n";
+export declare const QUERY_CURRENT_USER = "\n  query CurrentUser {\n    currentUser {\n      id\n      username\n      email\n      profile { display_name short_bio thumbnail }\n    }\n  }\n";