@milcho0604/velog-mcp 0.6.0 → 0.7.0

package/docs/tools.md

@@ -1,9 +1,9 @@
 # 도구 카탈로그
 
-기본 21개 + 프로필 수정 5개(설정 시).
+기본 22개 + 프로필 수정 5개(설정 시).
 
 ```
-기본 (설정 없음)         읽기 + 초안 + 비공개 발행 + 그림   도구 21개
+기본 (설정 없음)         읽기 + 초안 + 비공개 발행 + 그림   도구 22개
 VELOG_ALLOW_PUBLIC=1    공개 발행                        (파라미터만 추가)
 VELOG_ALLOW_PROFILE=1   프로필·소개글·블로그제목·SNS·사진  도구 5개 추가
 ```
@@ -33,7 +33,8 @@ VELOG_ALLOW_PROFILE=1   프로필·소개글·블로그제목·SNS·사진  도
 | `velog_publish_draft` | **필요** | **쓰기 — 초안을 발행** (`destructive`) |
 | `velog_unpublish_post` | **필요** | **쓰기 — 초안으로 되돌림** (`destructive`) |
 | `velog_update_post` | **필요** | **쓰기 — 발행글 수정** |
-| `velog_render_diagram` | 올릴 때만 | 그림 생성 (+ 업로드) |
+| `velog_render_diagram` | 올릴 때만 | 구성도·흐름도 생성 (+ 업로드) |
+| `velog_render_sequence` | 올릴 때만 | 시퀀스 다이어그램 생성 (+ 업로드) |
 | `velog_render_cover` | 올릴 때만 | 표지 생성 (+ 업로드) |
 | `velog_upload_image` | **필요** | **쓰기 — 공개 CDN 업로드** |
 
@@ -139,16 +140,19 @@ views: 16323
 
 ---
 
-## 쓰기 — 초안 전용
+## 쓰기 — 초안과 비공개가 기본
 
-> **이 서버는 글을 발행할 수 없다.** `is_temp: true` 가 상수로 박혀 있고
-> 도구 입력 스키마에 그 키가 없다. → [ADR 0002](decisions/0002-draft-only-write.md)
+> **공개 발행은 사용자만 켤 수 있다.** 기본 설정에서 이 서버가 낼 수 있는 것은
+> 초안과 **비공개 발행**까지다. 공개로 내보내려면 `VELOG_ALLOW_PUBLIC=1` 이 필요하고,
+> 모델은 그 스위치를 만질 수 없다. → [ADR 0004](decisions/0004-capability-model.md)
 
 ### `velog_create_draft`
 
-> **5분에 5건까지만** 만들 수 있다. 벨로그가 최근 5분의 공개 글 10건 초과 시
-> 그 시간대 글을 전부 비공개로 바꾸기 때문이다 — 초안도 계수에 포함된다.
-> 막히면 이유와 해제 시각을 알려준다.
+> **초안에는 우리 상한이 없다.** 벨로그의 발행 제한은 `is_private:false` 인 글만
+> 세는데 초안은 `is_private:true` 라 계수를 올리지 않는다. 상한은 공개 발행 쪽에 있다.
+> ⚠️ 다만 벨로그의 검사는 공개 여부를 보기 전에 돌아서, 이미 공개 글이 쌓여 있으면
+> 초안 요청도 벨로그 쪽 조치를 촉발할 수 있다. 이 경로에는 우리 카운터가 없어
+> 해제 시각을 계산해 주지 못한다 — 그 안내는 공개 발행 경로에만 있다.
 
 | 파라미터 | 필수 | 설명 |
 | --- | --- | --- |
@@ -176,9 +180,9 @@ views: 16323
 그래서 `velog_get_post` 로 현재 값을 읽어 바꾸지 않을 필드도 그대로 다시
 넘기는 편이 안전하다. `destructiveHint: true` 로 표시돼 있다.
 
-> ⚠️ **이미 발행된 글의 `id` 를 주면 그 글이 임시저장으로 내려가 비공개가 된다.**
-> `editPost` 는 상태를 덮어쓴다. 반드시 `velog_list_drafts` 로 확인한
-> 초안 id 만 쓸 것.
+> ⚠️ **이미 발행된 글의 `id` 는 거부한다.** `editPost` 가 상태를 덮어써서 그 글이
+> 임시저장으로 내려가기 때문에, 저장 전에 `is_temp` 를 확인하고 중단한다.
+> 발행된 글은 `velog_update_post` 로 고칠 것.
 
 ### `velog_list_drafts`
 내 임시저장 목록. 위 두 도구에 넣을 `id` 를 여기서 얻는다.
@@ -231,9 +235,10 @@ velog_publish_draft(id, is_private?)
 비공개로 내려가는* 버그를 냈다. '만들 때'는 안전한 쪽이 기본이고, '고칠 때'는
 **건드리지 않는 것**이 기본이다.
 
-> 기본 설정(공개 발행 꺼짐)에서 공개 글을 수정하면 비공개로 내려간다.
-> 공개 권한이 없는데 공개 상태를 유지시키면 그게 곧 공개 발행 권한이 되기 때문이다.
-> 공개 글을 다루려면 `VELOG_ALLOW_PUBLIC=1` 을 켤 것.
+> 기본 설정(공개 발행 꺼짐)에서는 **공개 범위를 바꿀 수단이 없다.** 공개 글은
+> 공개로, 비공개 글은 비공개로 그대로 남는다. 게이트가 막는 것은 '안 보이던 글을
+> 내보내는 것'이지 '이미 공개된 글을 내리는 것'이 아니다 — 후자는 발행이 아니라
+> 되돌리기 어려운 파괴적 변경이다. 범위를 바꾸려면 `VELOG_ALLOW_PUBLIC=1` 을 켤 것.
 
 ---
 
@@ -276,7 +281,7 @@ RSS·메일로 나가지도 않는다. 이유는 **혼동**이다: 프로필의
 
 ---
 
-## 그림 도구 3종
+## 그림 도구 4종
 
 ### `velog_render_diagram`
 
@@ -347,6 +352,87 @@ terminal network mail search retry bolt
 그림마다 톤이 달라지는 걸 막는 것과, 값이 결국 SVG 속성이 되므로 입력을 좁히는 것.
 평면(`planes`) 색만 `#rrggbb` 로 직접 지정할 수 있다.
 
+### `velog_render_sequence`
+
+시퀀스 다이어그램. **좌표를 받지 않는다** — 참가자와 순서 있는 메시지만 준다.
+
+```
+넘기는 것   participants(이름, 부제, 아이콘, 배지) / messages(from, to, kind, label) / fragments
+정해지는 것  열 간격, 행 높이, 라벨 줄바꿈, 활성 막대, 묶음 상자, 캔버스 크기
+```
+
+왜 `velog_render_diagram` 과 나눴나. 구성도는 좌표가 자유롭지만 시퀀스는 열이 참가자,
+행이 시간이라 좌표에 의미가 있다. 같은 도구에 얹으면 메시지 하나를 끼워 넣을 때마다
+그 아래 y 를 전부 다시 계산해야 한다. 기존 도구로 실제로 그려보고 확인한 것이다.
+
+- **메시지 배열 순서가 곧 시간 순서다.** 중간에 끼워 넣으면 아래가 알아서 밀린다.
+- **글자를 줄이지 않고 자리를 넓힌다.** 라벨이 두 열 사이에 안 들어가면 그 구간의
+  열 간격을 늘리고, 길면 접고, 접힌 만큼 그 행을 높인다. 한글처럼 띄어쓰기가 없는
+  긴 토큰은 글자 단위로 접는다.
+- **활성 막대는 자동이다.** `call` 이 열고 `return` 이 닫는다. 안 닫힌 것은 그
+  참가자가 마지막으로 관여한 지점까지 끈다. 겹치면 안쪽으로 계단이 진다.
+- **생명선에는 화살촉이 없다.** 이 도구를 따로 만든 이유 중 하나다 —
+  `velog_render_diagram` 은 모든 선에 화살촉을 무조건 붙인다.
+
+#### 메시지 종류 4종
+
+| `kind` | 생김새 | 쓰임 |
+| --- | --- | --- |
+| `call` (기본) | 실선 + 채운 화살촉 | 동기 호출. 활성 막대를 연다 |
+| `async` | 실선 + 열린 화살촉 | 비동기 발행 |
+| `return` | 점선 + 열린 화살촉 | 응답. 활성 막대를 닫는다 |
+| `note` | 노란 상자 | 선이 아니라 설명. 순서 안에 끼워 넣는다 |
+
+`from` 과 `to` 가 같으면 자기호출이 되어 오른쪽으로 고리를 그린다.
+`note` 는 `to` 를 생략하면 그 열 오른쪽에 붙고, 주면 두 열 사이에 걸친다.
+
+#### 묶음 상자 (`fragments`)
+
+`alt` `opt` `loop` `par` 같은 상자를 **메시지 번호 범위**(0부터, 양끝 포함)로 지정한다.
+상자는 전체 열이 아니라 **그 메시지들이 실제로 닿는 범위**만 감싼다.
+
+서로 어긋나게 겹치면 **그리기 전에 막는다.** 상자 둘이 서로를 반씩 물면 어느 쪽을
+안쪽에 그려도 한쪽이 제 메시지를 못 감싸기 때문이다. 완전히 포개거나 완전히 떨어져야 한다.
+
+#### 자가감사 5종
+
+| 항목 | 무엇을 잡나 | 어떤 계산이 틀렸다는 뜻인가 |
+| --- | --- | --- |
+| `over` | 글자가 카드, 노트, 칩, 묶음 상자 밖으로 나감 | 자동 폭 계산 |
+| `collide` | 카드끼리, 활성막대끼리, 노트가 남의 생명선을 덮음, 배지가 이름을 덮음 | 열 간격과 카드 폭 |
+| `label` | 라벨끼리 겹침, 라벨이 제 구간이나 제 행을 벗어남 | 열 간격과 행 높이 |
+| `cross` | 화살표가 카드나 노트를 관통 | 활성막대 오프셋 |
+| `frame` | 묶음 상자가 제 메시지를 다 못 감쌈 | 상자 범위 |
+
+★ 오른쪽 칸이 핵심이다. 이 감사는 **좌표를 준 사람이 실수했는지**가 아니라
+**렌더러의 배치 계산이 틀렸는지**를 본다. 그래서 통과가 곧 좋은 그림이라는 뜻은 아니다 —
+기하만 본다. 실제로 칩이 활성 막대에 가려진 결함은 감사를 통과했고 눈으로 잡았다.
+
+검출력은 변이시험으로 증명한다(`render.test.ts` S4). 배치 계산을 한 갈래씩 망가뜨려
+각각 **다른 항목**이 걸리는 것을 확인하고, 표본 네 개의 대조군이 통과하는 것까지 같이 본다.
+지금 여덟 갈래다.
+
+처음 이 시험을 돌렸을 때 두 갈래가 통과했다 — **재는 항목이 없어서** 안 걸린 것이었고,
+그때 `label` 의 '제 구간과 제 행' 검사를 뒤늦게 넣었다. 뒤이어 험한 입력을 돌려보다
+세 갈래가 더 나왔다. 이모지는 같은 `font-size` 라도 글리프가 높아서 줄높이를 상수로
+두면 **같은 라벨의 두 줄이 물린다.** 배지만 있고 아이콘이 없는 카드는 제목이 배지와
+같은 높이로 올라와 **배지가 이름을 덮는다.** 조건이 상자보다 길면 글자가 상자 밖으로 나간다.
+셋 다 고치고 변이로 남겼다.
+
+#### 입력 상한
+
+| 항목 | 상한 |
+| --- | --- |
+| 참가자 12, 메시지 200, 묶음 상자 12 | 개수 |
+| 캔버스 | 6,000px, 면적 900만px — **페이지 안에서** 걸린다 |
+| 제목 200, 부제 300, 참가자 이름과 부제 80, 배지 40, id 64 | 글자 |
+| 메시지 라벨 200, 상자 종류 16, 상자 라벨 120 | 글자 |
+
+메시지 라벨에 상한이 필요한 이유가 이 도구에서는 특히 분명하다 — 글자를 줄이는 대신
+자리를 넓히므로 **라벨 길이가 그대로 캔버스 크기가 된다.**
+
+아이콘과 톤은 `velog_render_diagram` 과 같다.
+
 ### `velog_render_cover`
 
 글 목록·SNS 미리보기용 1200×630 카드. 제목이 길면 줄바꿈하고, 3줄에도 안 들어가면

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@milcho0604/velog-mcp",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@milcho0604/velog-mcp",
-      "version": "0.6.0",
+      "version": "0.7.0",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.30.0",

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@milcho0604/velog-mcp",
-  "version": "0.6.0",
-  "description": "Velog MCP server — 읽기 전면 지원. 쓰기는 초안과 비공개 발행이 기본이고, 공개 발행은 VELOG_ALLOW_PUBLIC=1 로 사용자가 켠다.",
+  "version": "0.7.0",
+  "mcpName": "io.github.milcho0604/velog",
+  "description": "벨로그(velog.io) MCP 서버 — 조회·검색·통계는 인증 없이 동작하고, 쓰기는 초안과 비공개 발행이 기본이다. 공개 발행은 VELOG_ALLOW_PUBLIC=1 로 사용자만 켤 수 있다. 문서 없는 벨로그 GraphQL 동작을 실측해 정리했다. 런타임 의존성 2개, Node 22.18+",
   "type": "module",
   "main": "./dist/index.js",
   "bin": {
@@ -11,10 +12,13 @@
     "dist",
     "docs",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "npm-shrinkwrap.json"
   ],
-  "engines": { "node": ">=22.18.0" },
+  "engines": {
+    "node": ">=22.18.0"
+  },
   "scripts": {
     "prebuild": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "tsc -p tsconfig.build.json",
@@ -27,7 +31,7 @@
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "verify": "npm run typecheck && npm run lint && npm test && npm run build && npm run verify:dist",
-    "prepublishOnly": "npm run build && npm run verify:dist"
+    "prepublishOnly": "npm run verify"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",