@milcho0604/velog-mcp 0.4.0

package/dist/types.d.ts

@@ -0,0 +1,42 @@
+/** 벨로그 응답 타입. docs/api-reference.md 의 실측 스키마 기준. */
+export interface VelogUserProfile {
+    display_name?: string | null;
+    short_bio?: string | null;
+    thumbnail?: string | null;
+}
+export interface VelogUser {
+    id?: string;
+    username?: string;
+    email?: string | null;
+    profile?: VelogUserProfile | null;
+}
+export interface VelogSeries {
+    id?: string;
+    name?: string;
+    url_slug?: string;
+}
+export interface VelogPostSummary {
+    id: string;
+    title?: string | null;
+    url_slug?: string | null;
+    short_description?: string | null;
+    thumbnail?: string | null;
+    likes?: number | null;
+    views?: number | null;
+    comments_count?: number | null;
+    released_at?: string | null;
+    is_private?: boolean | null;
+    tags?: string[] | null;
+    user?: VelogUser | null;
+    series?: VelogSeries | null;
+}
+export interface VelogPostDetail extends VelogPostSummary {
+    body?: string | null;
+    is_markdown?: boolean | null;
+    is_temp?: boolean | null;
+    created_at?: string | null;
+}
+export interface SearchPostsResult {
+    count: number;
+    posts: VelogPostSummary[];
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+/** 벨로그 응답 타입. docs/api-reference.md 의 실측 스키마 기준. */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,oDAAoD"}

package/docs/PRD.md

@@ -0,0 +1,146 @@
+# velog-mcp 기획서
+
+- 작성: 2026-07-30
+- 상태: 초안 (v0.1 구현과 함께 갱신)
+
+## 1. 배경
+
+Velog 에 글을 쓰는 일이 늘었는데, 초안 작성이 항상 **에디터 창에서 시작**한다.
+자료는 터미널·레포·이슈 트래커에 있고 글은 브라우저에 있으니 왕복이 생긴다.
+
+MCP 로 벨로그를 붙이면 이 왕복이 사라진다. 다만 붙이는 순간 **AI 가 내 블로그에
+쓰기 권한을 갖는다**. 그래서 이 프로젝트의 설계 질문은 "무엇을 할 수 있게 할까"
+가 아니라 **"무엇을 못 하게 못 박을까"** 였다.
+
+## 2. 문제 정의
+
+기존 구현 두 개를 조사한 결과 (2026-07-30 기준):
+
+| | `velog-mcp` (stoneHee99) | `velog-mcp-claude` (seongwon030) |
+| --- | --- | --- |
+| ⭐ | 7 | 6 |
+| 주간 다운로드 | 32 | 46 |
+| 마지막 갱신 | 2026-04-24 | 2026-04-28 |
+| 발행 | `write_post` 한 번에 **즉시 게시** | `publishPost` 별도 (양호) |
+| 삭제 | `delete_post` 노출 | `deletePost` 노출 |
+| 인증 | **macOS 키체인에서 Chrome 암호키 추출** 후 쿠키 DB 복호화 | 토큰 붙여넣기 |
+| npm ↔ 소스 | 일치 | **npm 0.10.0 vs 소스 0.20.0** (10버전 뒤처짐) |
+
+정리하면 세 가지가 걸렸다.
+
+1. **되돌릴 수 없는 동작이 노출돼 있다.** 발행과 삭제가 도구 목록에 있으면,
+   모델이 판단을 한 번 잘못하는 것만으로 공개 게시나 글 소실이 일어난다.
+2. **인증이 과하다.** `security find-generic-password -s "Chrome Safe Storage"` 로
+   Chrome 마스터 키를 가져오는 코드가 상주한다. 현재 SQL 은 `.velog.io` 의 토큰
+   2개로 정확히 한정돼 있어 결백하지만, 그 키를 쥔 코드가 항상 돌 이유는 없다.
+3. **공급망이 얇다.** 개인 1인 유지보수 + 주간 40회 내외 다운로드 + 3개월 정지.
+   `npx -y` 로 최신을 끌어오는 설정이면 업데이트 한 번에 코드가 바뀐다.
+
+## 3. 목표
+
+**G1. 되돌릴 수 없는 동작을 코드에서 없앤다.**
+정책이나 프롬프트가 아니라 **구현 부재**로 보장한다. 발행 mutation 을 호출하는
+코드가 레포에 존재하지 않으면 모델이 아무리 원해도 발행할 수 없다.
+
+**G2. 읽기는 아끼지 않는다.**
+조회·검색·통계는 실수해도 되돌릴 게 없다. 여기서는 기능을 넓게 가져간다.
+
+**G3. 토큰을 최소로 다룬다.**
+환경변수로만 받고, 디스크에 쓰지 않고, 브라우저·키체인을 건드리지 않고,
+로그·에러 메시지에 실리지 않게 한다.
+
+**G4. 스키마 근거를 남긴다.**
+벨로그 GraphQL 은 비공식이라 언제든 바뀐다. introspection 실측 결과를
+`docs/api-reference.md` 에 날짜와 함께 박아두고, 깨졌을 때 diff 로 찾게 한다.
+
+## 4. 비목표 (하지 않는 것)
+
+- **발행**: `is_temp: false` 로 글을 공개하는 기능. 사람이 벨로그에서 누른다.
+- **삭제**: 글·시리즈·댓글 삭제. 실수의 대가가 비대칭적으로 크다.
+- **소셜 행위**: 좋아요·팔로우·댓글 작성. 남의 타임라인에 내 이름으로 흔적을
+  남기는 일은 자동화 대상이 아니다.
+- **계정 조작**: `unregister`(탈퇴)·프로필/이메일 변경. introspection 에 보이지만
+  구현하지 않는다.
+- **다중 계정**: 계정 하나만 다룬다.
+- **오프라인 캐시·동기화**: 벨로그가 원본(single source of truth)이다.
+
+## 5. 사용자 시나리오
+
+**S1. 자료에서 초안으로**
+> "이번 prom-client 기여 건으로 글 초안 잡아줘"
+→ 대화 맥락으로 마크다운을 만들고 `velog_create_draft` 로 임시저장.
+사용자는 벨로그에서 열어 고치고 직접 발행한다.
+
+**S2. 내 글 되짚기**
+> "작년에 쓴 HTTP/2 글 어디였지"
+→ `velog_search_posts(username=…)` 로 찾아 본문까지 읽어온다.
+
+**S3. 블로그 현황 파악**
+> "내 글 중에 조회수 높은 순으로"
+→ `velog_blog_stats` 가 `likes`·`views` 를 집계해 표로 준다.
+
+**S4. 백업**
+> "내 글 전부 마크다운으로 내려받아"
+→ `velog_export_posts` 가 로컬 디렉터리에 파일로 쓴다.
+
+**S5. 초안 이어쓰기**
+> "어제 잡아둔 초안 이어서 마무리하자"
+→ `velog_list_drafts` → `velog_update_draft`.
+
+## 6. 성공 기준
+
+| # | 기준 | 검증 방법 |
+| --- | --- | --- |
+| A1 | 발행 mutation 호출 코드가 **0곳** | `grep -r "is_temp.*false"` 결과 없음 + 테스트로 고정 |
+| A2 | 삭제·소셜·계정 mutation 미구현 | 도구 목록 스냅샷 테스트 |
+| A3 | 토큰이 디스크·로그에 안 남음 | 파일 쓰기 없음 검증 + 에러 마스킹 테스트 |
+| A4 | 토큰 없이도 공개 조회 동작 | 무인증 통합 테스트 |
+| A5 | 런타임 의존성 ≤ 2 | `package.json` 검사 |
+| A6 | 스키마 변경 감지 | introspection diff 스크립트 |
+
+## 7. 범위 (v0.1)
+
+### 읽기 — 인증 불필요
+`velog_get_post` · `velog_list_posts` · `velog_search_posts` ·
+`velog_trending_posts` · `velog_recent_posts` · `velog_get_user` ·
+`velog_list_series` · `velog_get_series` · `velog_get_tag` ·
+`velog_user_tags` · `velog_trending_writers`
+
+### 읽기 — 인증 필요
+`velog_current_user` · `velog_list_drafts` · `velog_reading_list` ·
+`velog_feed` · `velog_notifications`
+
+### 쓰기 — 초안 한정
+`velog_create_draft` · `velog_update_draft`
+
+### 파생 기능 (API 단순 중계가 아닌 것)
+`velog_blog_stats` — 내 글의 `views`/`likes`/`comments_count` 집계
+`velog_export_posts` — 글을 프론트매터 붙인 마크다운 파일로 저장
+
+## 8. 위험과 대응
+
+| 위험 | 대응 |
+| --- | --- |
+| 비공식 API 라 예고 없이 깨짐 | 스키마 실측을 문서로 고정 + diff 스크립트. 깨지면 어디가 바뀌었는지 즉시 나옴 |
+| `access_token` 1시간 만료 | 만료를 **에러로 명확히** 알린다. 자동 갱신은 refresh 토큰을 상시 쓰게 하므로 v0.1 범위 밖 |
+| 대량 호출로 이용약관 8조(정상 운영 방해) 저촉 | 페이지네이션 상한 + `export` 는 순차 호출 |
+| 모델이 초안을 남발 | 초안은 벨로그에서 일괄 삭제 가능. 되돌릴 수 있는 실수만 허용한다는 설계 그대로 |
+
+## 9. 법적 검토 (2026-07-30 확인)
+
+- **이용약관** ([velog.io/policy/terms](https://velog.io/policy/terms)):
+  자동화·크롤링·스크래핑·역설계에 대한 **명시 금지 조항 없음**. 제8조(이용제한)는
+  "정상적인 서비스 운영 방해"와 "권한을 넘어선 접근"을 다룬다. 본인 계정 토큰으로
+  본인 글을 다루는 것은 권한 내 행위.
+- **게시물 저작권** (제5조 1항): 회원에게 귀속. 내 글은 내 것.
+- **API 재구현**: `v3.velog.io/graphql` 스키마는 벨로그 소유이며, 본 구현은
+  벨로그의 **introspection 응답에서 직접** 도출했다. 기존 두 패키지의 소스를
+  옮겨오지 않았다. 인터페이스 재구현이 저작권 침해가 아니라는 점은
+  Google v. Oracle (2021) 로 확립.
+
+## 10. 열린 질문
+
+- npm 배포 여부. 패키지명 `velog-mcp` 는 선점돼 있어 스코프명
+  `@milcho0604/velog-mcp` 를 잡아둠. 공개 배포는 v0.1 안정화 후 판단.
+- `refresh_token` 자동 갱신을 넣을 것인가. 편의 ↔ 상시 보관 위험의 교환.
+- 이미지 업로드(`uploadImage`) 지원 여부. 초안에 이미지가 필요하면 결국 든다.

package/docs/api-reference.md

@@ -0,0 +1,329 @@
+# 벨로그 GraphQL 스키마 실측 기록
+
+- 측정: **2026-07-30**
+- 방법: 엔드포인트에 introspection 질의 직접 전송 (인증 불필요)
+- 출처: 벨로그 서버 응답. 타사 구현 소스를 참조하지 않았다
+- **교차검증**: 벨로그 공식 오픈소스 [velog-io/velog](https://github.com/velog-io/velog)
+  (⭐207, 2025-10-24) 의 `apps/server/src/graphql/Post.gql` 및
+  `apps/server/src/services/PostService/index.ts` 와 대조 — 아래 표시된 항목 일치 확인
+
+> 비공식 API 다. 벨로그가 예고 없이 바꿀 수 있다.
+> 무언가 깨지면 **먼저 이 문서와 현재 스키마를 diff** 하라.
+
+## 엔드포인트
+
+| URL | introspection | 비고 |
+| --- | --- | --- |
+| `https://v3.velog.io/graphql` | **열림** | 현행. 이 프로젝트가 쓰는 곳 |
+| `https://v2.velog.io/graphql` | 막힘 | `GRAPHQL_VALIDATION_FAILED` 반환 |
+
+v2 응답 원문:
+```
+GraphQL introspection is not allowed by Apollo Server, but the query
+contained __schema or __type.
+```
+
+재확인 명령:
+
+```bash
+curl -s -X POST https://v3.velog.io/graphql \
+  -H 'Content-Type: application/json' \
+  -d '{"query":"{ __schema { queryType { name } mutationType { name } } }"}'
+```
+
+## 인증
+
+쿠키 헤더로 전달한다. 공개 조회는 인증 없이 된다.
+
+```
+Cookie: access_token=<...>; refresh_token=<...>
+```
+
+| 토큰 | 유효기간 |
+| --- | --- |
+| `access_token` | 1시간 |
+| `refresh_token` | 30일 |
+
+## Mutation — 전체 23개
+
+`*` = 이 프로젝트가 구현하는 것. 나머지는 **의도적으로 미구현** (사유는 `security.md`)
+
+```
+* writePost(input: WritePostInput)          글 작성 (초안=is_temp:true / 발행=false)
+* editPost(input: EditPostInput)            글 수정·발행·발행취소
+* updateProfile / updateAbout               프로필·소개글  ┐ VELOG_ALLOW_PROFILE=1
+* updateVelogTitle / updateSocialInfo       제목·SNS링크    │ 일 때만 도구로 노출
+* updateThumbnail                           프로필 사진    ┘
+
+  likePost / unlikePost                     ✗ 소셜 행위
+  follow / unfollow                         ✗ 소셜 행위
+  sendMail                                  ✗ 메일 발송
+  createNotification                        ✗ 알림 생성
+  readNotification / readAllNotifications   ✗ 상태 변경
+  removeAllNotifications                    ✗ 되돌릴 수 없음
+  updateNotNoticeNotification               ✗ 상태 변경
+  updateEmailRules                          ✗ 계정 설정
+  initiateChangeEmail / confirmChangeEmail  ✗ 계정 설정
+  acceptIntegration                         ✗ 계정 설정
+  logout                                    ✗ 세션 파괴
+  unregister                                ✗✗ 계정 탈퇴. 절대 노출 금지
+```
+
+> `deletePost` 는 v3 mutation 목록에 **없다**. 삭제는 다른 경로인 듯하나
+> 어차피 구현하지 않으므로 조사하지 않았다.
+
+### 이미지 업로드는 GraphQL 이 아니다
+
+mutation 23개 어디에도 업로드가 없다. 벨로그는 파일을 fastify REST 라우트로 받는다.
+경로는 공식 소스에서 세 겹으로 조립된다:
+
+```
+routes/index.mts        fastify.register(api,        { prefix: '/api'   })
+routes/files/index.mts  fastify.register(v3,         { prefix: '/v3'    })   ← files 아래
+routes/index.mts        fastify.register(filesRoute, { prefix: '/files' })
+→ POST https://v3.velog.io/api/files/v3/upload
+```
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 폼 필드 | `image` (파일) · `type` · `ref_id?` | `multer.single('image')` |
+| `type` | `post` \| `profile` (+ 컨트롤러는 `book` 도 허용) | `filesController.upload` |
+| 응답 | `{ path: "https://velog.velcdn.com/..." }` | `B2ManagerService.upload` |
+| 크기 상한 | **30MB** | `multer({limits:{fileSize:1024*1024*30}})` |
+| 남용 차단 | 1시간 100건 초과 · 1분 20건 이상 → **429** | `ImageService.detectAbuse` |
+| 인증 | 쿠키 (GraphQL 과 동일) | `authGuardPlugin` |
+
+★ `type:'post'` + `ref_id` 를 주면 서버가 **그 글이 내 글인지 확인한다**:
+
+```ts
+if (type === 'post' && !!ref_id) {
+  const post = await this.postService.findById(ref_id)
+  if (post?.fk_user_id !== signedUserId) throw new ForbiddenError("Can't access the post")
+}
+```
+
+`editPost` 에는 없는 소유권 검사가 여기엔 있다. 쓸 수 있으면 쓰는 게 낫다.
+
+**이미지 삭제 API 는 없다.** 올린 건 못 지운다.
+
+실측 (2026-07-31, 실계정):
+```
+POST /api/files/v3/upload  →  200 {"path":"https://velog.velcdn.com/images/milcho0604/post/…/image.png"}
+GET  그 주소 (무인증)       →  200 image/png · 147,485 bytes · 2168×1106
+```
+
+### WritePostInput (11필드) — ✅ 공식 소스와 일치
+
+`velog-io/velog` 의 `apps/server/src/graphql/Post.gql` 원문과 대조했고 필드·필수여부가
+전부 같다. introspection 실측이 정확했음이 확인됐다.
+
+```
+* title          String        필수
+* body           String        필수 — 마크다운 본문
+* tags           [String]      필수 — 빈 배열 허용. 생략하면 조용히 실패한다
+* is_markdown    Boolean       필수 — true
+* is_temp        Boolean       필수 — ★ true=임시저장, false=발행
+* is_private     Boolean       필수
+* url_slug       String        필수
+* meta           JSON          필수 — 빈 객체 허용
+  thumbnail      String        선택
+  series_id      ID            선택
+  token          String        선택
+```
+
+### EditPostInput (12필드)
+
+`WritePostInput` 과 동일하되 맨 앞에 `id: ID!` 가 붙는다.
+
+## Query — 전체 24개
+
+```
+읽기 (무인증 가능)
+  post(input: ReadPostInput)                글 하나
+  posts(input: GetPostsInput)               글 목록
+  recentPosts(input: RecentPostsInput)      최신
+  trendingPosts(input: TrendingPostsInput)  트렌딩
+  searchPosts(input: GetSearchPostsInput)   검색
+  user(input: GetUserInput)                 사용자
+  series(input: GetSeriesInput)             시리즈 하나
+  seriesList(input: GetSeriesListInput)     시리즈 목록
+  tag(name: String)                         태그
+  userTags(input: UserTagsInput)            사용자 태그
+  trendingWriters(input: TrendingWritersInput)
+  velogConfig(input: GetVelogConfigInput)
+
+읽기 (인증 필요)
+  currentUser()                             로그인 확인용
+  isLogged()
+  feedPosts(input: FeedPostsInput)          구독 피드
+  readingList(input: ReadingListInput)      읽기목록
+  notifications(input: NotificationsInput)
+  notNoticeNotificationCount()
+  followers / followings(input: GetFollowInput)
+
+미사용
+  ads / restoreToken / unregisterToken / checkEmailExists
+```
+
+### 주요 입력 타입
+
+```
+ReadPostInput          id? / username? / url_slug?
+GetPostsInput          cursor? / username? / temp_only? / tag? / limit?
+                       └ temp_only:true = 내 임시글 목록 (인증 필요)
+GetSearchPostsInput    keyword* / offset? / limit? / username?
+TrendingPostsInput     offset? / limit? / timeframe?
+GetUserInput           id? / username?
+```
+
+## Post 타입 (27필드)
+
+```
+id  title  body  short_description  thumbnail
+is_markdown  is_temp  is_private
+url_slug  fk_user_id  original_post_id
+likes  views  comments_count            ← 통계 도구가 쓰는 것
+created_at  updated_at  released_at  last_read_at
+meta  user  comments  tags  series
+is_liked  is_followed  linked_posts  recommended_posts
+```
+
+`likes` / `views` / `comments_count` 가 Post 에 직접 붙어 있어 별도 통계 API 없이
+집계할 수 있다. `velog_blog_stats` 가 이걸 쓴다.
+
+## User 타입 (14필드)
+
+```
+id  username  email  created_at  updated_at
+is_certified  is_trusted  is_followed
+profile(UserProfile)  velog_config(VelogConfig)
+series_list  user_meta  followers_count  followings_count
+```
+
+## 공식 소스로 확인한 서버 동작
+
+`velog-io/velog` 를 읽어 확인한 것들. 우리 대응 코드의 근거다.
+
+### `updated_at` 이 왜 응답 전체를 죽이나
+
+```graphql
+# apps/server/src/graphql/Post.gql
+type Post {
+  created_at:  Date!    # non-null
+  updated_at:  Date!    # non-null  ← 여기
+  released_at: Date     # nullable
+}
+```
+
+**스키마는 non-null 로 선언했는데 실제 DB 에 null 인 행이 있다.** GraphQL 규약상
+non-null 필드에 null 이 오면 그 필드만 비우는 게 아니라 상위 객체를, 리스트 안이면
+응답 전체를 무효화한다. 그래서 글 하나 때문에 검색 결과 전부가 날아간다.
+`released_at` 은 nullable 이라 안전 — 우리가 이쪽만 쓰는 이유다.
+
+### 커서가 고착되는 조건
+
+```ts
+// apps/server/src/services/PostService/index.ts
+const cursorData = cursor ? await ...findUnique({ fk_post_id: cursor }) : null
+const cursorQueryOption = cursorData
+  ? { released_at: { lt: cursorData.created_at }, id: { not: cursorData.id } }
+  : {}                                    // ★ 못 찾으면 필터 없음
+take: limit
+```
+
+**커서 id 를 서버가 못 찾으면 필터가 통째로 빠져 1페이지를 다시 준다.**
+그대로 두면 같은 50편을 무한히 재수집한다. `fetchAllPosts` 가 id 중복 제거와
+커서 반복 감지를 하는 이유가 이것이다 (`src/tools/stats.ts`).
+
+또한 서버가 `limit > 100` 을 `BadRequestError` 로 막는다. 우리 도구는 50 을
+상한으로 두므로 걸리지 않는다.
+
+### ★ 소유권 검사가 없는 두 곳
+
+**① `editPost` 는 글 소유자를 확인하지 않는다.**
+
+```ts
+// initializePostProcess
+if (type === 'write') { ... fk_user_id: signedUserId ... }   // 생성은 내 것으로
+if (type === 'edit')  { post = findUnique({ where: { id } }) } // ← 소유자 비교 없음
+```
+
+공개 글은 누구나 id 로 조회할 수 있으므로 **남의 글을 수정·비공개화할 수 있다.**
+
+**② 시리즈도 '처음 붙일 때'는 확인하지 않는다.**
+
+```ts
+if (!prevSeriesPost && series_id) {
+  await this.seriesService.appendToSeries(series_id, post.id)   // ← 검사 없음
+}
+if (prevSeriesPost && prevSeriesPost.fk_series_id !== series_id) {
+  if (series_id) {
+    await this.checkSeriesOwnership(series_id, userId)          // ← 여기만 검사
+```
+
+`velog_list_series` 로 남의 공개 시리즈 id 를 얻을 수 있으므로, **내 글을 남의
+시리즈에 붙일 수 있다.** 글 소유권 검사로는 못 막는다 — 글은 내 것이기 때문이다.
+
+→ 우리 쪽 대응: `src/ownership.ts` 의 `assertOwned` / `assertOwnsSeries`.
+   `safety.test.ts` 의 A8·A11 이 모든 호출 경로에 적용됐는지 소스를 읽어 강제한다.
+
+### 발행 제한 검사는 공개 여부보다 먼저 돈다
+
+```ts
+const isPublish = !data.is_temp && !data.is_private
+const isLimit = await this.isPostLimitReached(signedUserId)   // ← 무조건 실행
+```
+
+`is_private:true` 글은 카운터를 **올리지 않지만**, 그 글을 만드는 요청이 이미 쌓인
+카운트에 대한 파괴 동작(최근 5분 글 전부 비공개)을 **촉발할 수 있다.**
+'올리지 않는다'와 '유발하지 않는다'는 다르다.
+
+## 실계정 왕복 검증 (2026-07-31)
+
+희생용 초안 하나로 전 경로를 돌고 필드 보존을 확인했다.
+
+```
+create_draft → update_draft → publish_draft(비공개) → update_post → unpublish_post
+```
+
+| 단계 | is_temp | is_private | 본문 | 태그 | 시리즈 | 판정 |
+| --- | --- | --- | --- | --- | --- | --- |
+| 생성 | true | true | 249자 | 2개 | **없음** | series_id 를 줬는데 안 붙음 |
+| update_draft | true | true | 249자 | 2개 | **DataBase** | 여기서 붙음 |
+| publish_draft | **false** | true | 249자 | 2개 | DataBase | 내용 전부 유지 |
+| update_post | false | true | 249자 | 2개 | DataBase | title 외 전부 유지 |
+| unpublish | **true** | **true** | 249자 | 2개 | DataBase | 내용 전부 유지 |
+
+**1→2 행이 위 D7 함정의 실물 증거다.** `create_draft` 에 `series_id` 를 줬는데
+붙지 않았고, 같은 값으로 `update_draft` 를 부르자 붙었다. 도구가 이 사실을 응답에
+경고로 알리는 것도 확인했다.
+
+`unpublish` 가 `is_private:true` 로 되돌리는 것도 확인 — 공개 상태를 유지했다면
+그 초안이 다시 벨로그 계수 대상이 됐을 것이다.
+
+남의 시리즈(@velopert) id 로 `update_draft` 를 부르면 거부된다:
+```
+series_id=96ffa520-… 는 @milcho0604 의 시리즈가 아닙니다
+```
+
+### `meta` 보존 — 실데이터로 확인
+
+왕복 초안의 `meta` 가 `{}` 라 처음엔 검증이 약했다. 그래서 벨로그 웹이 하는 것과
+같은 형태로 값을 직접 심고 다시 확인했다.
+
+```
+심기      {"cover":"none","short_description":"이 값이 보존돼야 한다"}
+update_draft 로 제목만 변경
+결과      {"cover":"none","short_description":"이 값이 보존돼야 한다"}   ← 그대로
+```
+
+`meta: {}` 를 보내던 시절이었다면 여기서 `short_description` 이 사라졌을 것이다.
+
+## 스키마 변경 감지
+
+```bash
+npm run schema:dump          # 현재 스키마를 덤프
+git diff docs/api-reference.md
+```
+
+깨졌을 때 "어디가" 바뀌었는지 이 diff 로 찾는다.

package/docs/architecture.md

@@ -0,0 +1,112 @@
+# 구조
+
+## 전체 흐름
+
+```
+MCP 클라이언트 (Claude 등)
+      │  stdio (JSON-RPC)
+      ▼
+   index.ts ─────────── createServer(client)
+      │                    도구 등록만 한다. 로직 없음
+      ├── tools/posts.ts      글 조회
+      ├── tools/discover.ts   검색·트렌딩·최신
+      ├── tools/profile.ts    사용자·시리즈·태그
+      ├── tools/stats.ts      통계 (집계)
+      ├── tools/export.ts     마크다운 백업 (파일 씀)
+      └── tools/drafts.ts     ★ 유일한 쓰기 경로
+      │
+      ▼
+   client.ts ─────────── VelogClient.request()
+      │                    재시도 · 마스킹 · 타임아웃
+      ├── auth.ts           환경변수 → 쿠키 헤더
+      └── graphql.ts        질의문 (필드 선택)
+      │
+      ▼  HTTPS POST
+   https://v3.velog.io/graphql
+```
+
+## 레이어 규칙
+
+| 레이어 | 하는 일 | 하면 안 되는 일 |
+| --- | --- | --- |
+| `index.ts` | 도구 등록, stdio 연결 | 비즈니스 로직 |
+| `tools/*` | 입력 검증(zod), 질의 호출, 출력 정형화 | fetch 직접 호출 |
+| `client.ts` | HTTP, 재시도, 오류 변환, 마스킹 | 도구별 지식 |
+| `auth.ts` | 토큰 읽기·헤더 생성·마스킹 | **파일 접근 (금지)** |
+| `graphql.ts` | 질의문 상수 | 실행 |
+
+`tools/*` 가 `fetch` 를 직접 부르면 마스킹과 재시도를 우회하게 된다.
+반드시 `client.request()` 를 통한다.
+
+## 이 레포가 쓰지 않는 TypeScript 문법
+
+Node 24 는 `.ts` 를 **타입 스트리핑**으로 직접 실행한다. 지우기만 하고 코드를
+생성하지 않으므로, 변환이 필요한 문법은 `ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX` 로
+죽는다. 실제로 겪은 것:
+
+```ts
+// ✗ 파라미터 프로퍼티 — 필드 대입 코드를 '생성'해야 하므로 불가
+class E extends Error {
+  constructor(readonly detail?: Detail) { super(); }
+}
+
+// ○ 명시 필드
+class E extends Error {
+  readonly detail: Detail | undefined;
+  constructor(detail?: Detail) { super(); this.detail = detail; }
+}
+```
+
+같은 이유로 **`enum`·`namespace`·데코레이터**도 쓰지 않는다.
+(`const enum` 은 물론이고 일반 `enum` 도 런타임 객체를 생성해야 한다.)
+
+대신 얻는 것: `tsx`·`ts-node`·`jest`·`babel` 이 전부 불필요하다.
+테스트는 `node --test src/__tests__/*.test.ts` 로 소스에서 바로 돈다.
+
+## 빌드
+
+```
+src/*.ts  ──tsc──▶  dist/*.js
+```
+
+소스는 `'./auth.ts'` 로 import 하고, `rewriteRelativeImportExtensions` 가
+빌드 시 `'./auth.js'` 로 바꾼다. 그래서 **테스트는 빌드 없이** 돌고
+**배포본은 정상 ESM** 이 된다.
+
+## 벨로그 API 를 다룰 때 지킬 것
+
+실측으로 확인한 상대 쪽 특성이다. 어기면 조용히 깨진다.
+
+**1. 한 요청에 쿼리를 묶지 않는다.**
+Prisma 커넥션 풀이 작다 (limit 5 / timeout 10s). `searchPosts + trendingPosts`
+동시 요청에서 재현됨.
+
+**2. `updated_at` 을 질의하지 않는다.**
+스키마는 non-nullable 인데 실제 null 인 글이 있다. 하나만 섞여도 응답 전체가
+거부된다 (`Cannot return null for non-nullable field Post.updated_at`).
+
+**3. 목록 응답은 `limit` 보다 적을 수 있다.**
+조회 후 일부 글이 사후 필터링된다. `count` 는 필터 이전 총계다.
+페이지네이션은 반환 건수가 아니라 `offset + limit` 로 넘긴다.
+
+**4. 5xx·커넥션풀 오류는 재시도한다. 인증 만료·4xx 는 즉시 던진다.**
+`isTransient()` 가 판정한다.
+
+**5. 순차 반복 호출에는 간격을 둔다.**
+`export` 는 글마다 250ms 쉰다.
+
+## 테스트
+
+```
+src/__tests__/auth.test.ts     토큰 취급·마스킹
+src/__tests__/client.test.ts   재시도·오류 변환 (가짜 fetch 주입)
+src/__tests__/slug.test.ts     슬러그 생성
+src/__tests__/safety.test.ts   ★ 안전 불변식 (PRD 성공기준)
+```
+
+`safety.test.ts` 는 소스 전체를 읽어 금지 패턴 부재를 단언하고, 실제 MCP
+세션(`InMemoryTransport`)을 띄워 도구 목록과 입력 스키마를 검사한다.
+**이 파일이 깨지면 우회하지 말고 왜 깨졌는지부터 볼 것.**
+
+네트워크를 타는 테스트는 두지 않았다. 벨로그가 느리거나 막히면 CI 가 흔들린다.
+실 API 검증은 개발 중 수동으로 한다 (`npm run schema:dump` 포함).