@milcho0604/velog-mcp 0.4.0

package/README.md

@@ -0,0 +1,381 @@
+# velog-mcp
+
+[![Node](https://img.shields.io/badge/node-%3E%3D24-brightgreen)](https://nodejs.org)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![Runtime deps](https://img.shields.io/badge/runtime%20deps-2-lightgrey)](package.json)
+
+An MCP server for [Velog](https://velog.io), the Korean developer blogging platform.
+Read your blog, draft posts, publish them, and back everything up — from Claude or any
+MCP client.
+
+**[한국어 문서 →](README.ko.md)**
+
+---
+
+## Why another one?
+
+Two Velog MCP servers already exist. This one differs in three ways.
+
+**1. Publishing is a permission, not a default.**
+Out of the box the server can create drafts and publish **privately**. Public
+publishing requires you to set an environment variable. The model cannot flip that
+switch — only you can, in your MCP config.
+
+**2. Every quirk is measured, not assumed.**
+Velog's GraphQL API is undocumented. This repo records what it *actually* does,
+verified against [velog-io/velog](https://github.com/velog-io/velog) source and live
+calls. Six server-side quirks are written up in
+[docs/api-reference.md](docs/api-reference.md) — including one that silently returns an
+empty list, and one that can turn your published posts private.
+
+**3. Two runtime dependencies.** `@modelcontextprotocol/sdk` and `zod`. HTTP, test
+runner, and TypeScript execution all come from Node 24 itself.
+
+---
+
+## Install
+
+Requires **Node.js 24 or newer**.
+
+### As a Claude Code plugin (recommended)
+
+```bash
+/plugin marketplace add milcho0604/velog-mcp
+/plugin install velog@milcho
+```
+
+Installation asks for four values. **Leave them all blank and it still installs,
+running read-only.**
+
+| Prompt | If left blank |
+| --- | --- |
+| Velog refresh token | Read-only (browse, search, stats still work) |
+| Allow public publishing | Drafts and private publishing only |
+| Allow profile edits | Profile tools stay off |
+| Chrome path | Found automatically in standard locations |
+
+**The token goes into the macOS Keychain**, not into a settings file in plaintext.
+Only values declared `sensitive: true` reach the Keychain, and a test enforces
+that declaration (P7).
+
+Change values later with `/plugin manage`.
+
+### From source
+
+```bash
+git clone https://github.com/milcho0604/velog-mcp.git
+cd velog-mcp
+npm install && npm run build
+```
+
+## Configure
+
+Add this to your MCP client config (`claude_desktop_config.json`, `.mcp.json`, …):
+
+```json
+{
+  "mcpServers": {
+    "velog": {
+      "command": "node",
+      "args": ["/absolute/path/to/velog-mcp/dist/index.js"],
+      "env": {
+        "VELOG_REFRESH_TOKEN": "your_refresh_token"
+      }
+    }
+  }
+}
+```
+
+With the Claude Code CLI:
+
+```bash
+claude mcp add velog -- node /absolute/path/to/velog-mcp/dist/index.js
+# then add the "env" block to the entry it created
+```
+
+### Getting your token
+
+Velog has no public write API, so the server authenticates with your browser session
+cookie.
+
+1. Log in at [velog.io](https://velog.io)
+2. Open DevTools (`F12`) → **Application** → **Cookies** → `https://velog.io`
+3. Copy the value of **`refresh_token`**
+
+**`VELOG_REFRESH_TOKEN` alone is enough.** Velog's server reissues the short-lived
+`access_token` on its own ([`authPlugin.mts`](https://github.com/velog-io/velog/blob/main/apps/server/src/common/plugins/global/authPlugin.mts)),
+and this server picks the refreshed cookie out of the response. One paste lasts
+**30 days**.
+
+`VELOG_ACCESS_TOKEN` also works but expires in about an hour by itself.
+
+> Tokens are read from the environment only. They are never written to disk, and the
+> server never reads your browser's cookie database or your OS keychain.
+> Whatever you put in your MCP config file does live there in plain text, though —
+> that file is yours to protect.
+
+**Without a token the server still starts**, read-only. Public posts, search, trending,
+and blog stats all work unauthenticated.
+
+---
+
+## Permissions
+
+| Environment | What you get |
+| --- | --- |
+| *(nothing set)* | Read everything · create drafts · **publish privately** · draw and upload images — 21 tools |
+| `VELOG_ALLOW_PUBLIC=1` | …plus **public publishing** (adds an `is_private` parameter) |
+| `VELOG_ALLOW_PROFILE=1` | …plus **profile editing** (adds 5 tools) |
+
+The two switches are independent — enable either, both, or neither.
+
+```json
+"env": {
+  "VELOG_REFRESH_TOKEN": "...",
+  "VELOG_ALLOW_PUBLIC": "1",
+  "VELOG_ALLOW_PROFILE": "1"
+}
+```
+
+Accepted as "on": `1`, `true`, `yes`, `on`. Anything else is off — a typo won't quietly
+enable it.
+
+When public publishing is off, the `is_private` parameter **does not exist** on any
+tool, so the model has no way to ask for it. When it's on, `is_private` appears and
+still defaults to `true`.
+
+### Why private-by-default
+
+Not caution for its own sake. Velog's rate limiter counts only `is_private: false`
+posts:
+
+```ts
+// apps/server/src/services/PostApiService/index.mts
+count({ where: { fk_user_id, is_private: false, released_at: { gt: fiveMinutesAgo } } })
+if (count >= 10) {
+  updateMany({ where: { fk_user_id, released_at: { gt: fiveMinutesAgo } },
+               data: { is_private: true } })   // flips *everything* recent to private
+}
+```
+
+Private posts don't **increment** that count. But `isPostLimitReached()` runs
+unconditionally, *before* privacy is examined — so if ten public posts already exist in
+the last five minutes, even a private draft request can trigger the sweep. "Doesn't
+increment" is not "can't trigger." That's why write retries stay disabled and the local
+limiter stays in place.
+
+Public posts do increment it, and once a post is public it has already gone out through
+RSS, search indexes, and subscriber email, none of which a delete reaches. That
+asymmetry is what deserves an explicit opt-in.
+
+Full reasoning: [docs/security.md](docs/security.md)
+
+---
+
+## Tools
+
+21 tools. Only 9 of them change anything on Velog.
+
+### Reading — no auth required
+
+| Tool | Purpose |
+| --- | --- |
+| `velog_get_post` | Read one post, body included |
+| `velog_list_posts` | A user's posts, optionally filtered by tag |
+| `velog_search_posts` | Keyword search; pass `username` to search inside one blog |
+| `velog_trending_posts` | Trending by `day` / `week` / `month` / `year` |
+| `velog_recent_posts` | Newest posts across Velog |
+| `velog_get_user` | Profile, follower counts, bio |
+| `velog_list_series` | A user's series, with post counts and IDs |
+| `velog_user_tags` | Tags a user writes about, with counts |
+
+### Reading — auth required
+
+| Tool | Purpose |
+| --- | --- |
+| `velog_whoami` | Which account the token belongs to (also a token health check) |
+| `velog_list_drafts` | Your saved drafts, with IDs |
+
+### Derived — things Velog doesn't provide
+
+| Tool | Purpose |
+| --- | --- |
+| `velog_blog_stats` | Aggregate views/likes/comments, top posts, per-year and per-tag breakdown |
+| `velog_export_posts` | Save posts as Markdown files with YAML front matter |
+
+### Writing
+
+| Tool | Effect |
+| --- | --- |
+| `velog_create_draft` | Save a draft. Never publishes, under any configuration |
+| `velog_update_draft` | Replace a draft **entirely** — omitted fields are reset |
+| `velog_publish_post` | Publish a new post |
+| `velog_publish_draft` | Publish an existing draft, reusing its stored body |
+| `velog_unpublish_post` | Send a published post back to drafts |
+| `velog_update_post` | Edit a published post — omitted fields are **kept** |
+
+> `velog_update_draft` resets what you omit; `velog_update_post` preserves it.
+> The asymmetry is deliberate — see [docs/tools.md](docs/tools.md).
+
+Tools that take a `username` — `velog_list_drafts`, `velog_blog_stats`,
+`velog_export_posts`, `velog_search_posts` — fall back to your own account when you
+omit it.
+
+### Diagrams and images
+
+| Tool | Effect |
+| --- | --- |
+| `velog_render_diagram` | Draw an architecture/flow diagram and upload it |
+| `velog_render_cover` | Draw a 1200×630 cover card for a post |
+| `velog_upload_image` | Upload a local image file, get the Markdown back |
+
+You describe **what exists and what flows where**; the renderer owns everything else —
+palette, spacing, text measurement, corner rounding, canvas size. That is deliberate: a
+diagram redrawn from scratch each time looks different each time.
+
+Every measurement is real. Node widths and line breaks come from the browser's
+`getBBox()`, never from a character count — with mixed Korean and English text, counting
+characters is wrong every time. The canvas is sized *after* drawing, from the content's
+bounding box, so a diagram cannot be clipped.
+
+Then it audits itself and reports five classes of defect:
+
+```
+text spilling outside its card · letter-spacing squeezed to fit
+a line crossing (or hiding behind) a node
+two lines overlapping · two nodes overlapping · a label sitting on a card
+```
+
+**If the audit finds anything, nothing is uploaded — and there is no flag to turn that
+off.** Velog has no delete-image API and every upload counts against your quota, so a
+flawed diagram is worth redrawing rather than shipping. An override that the model can
+set itself is not a safeguard (same reasoning as the publishing switch in
+[ADR 0004](docs/decisions/0004-capability-model.md)). If you really want a flawed
+diagram online, render with `upload: false`, look at the PNG, then pass its path to
+`velog_upload_image`.
+
+Icons are 28 built-in glyphs (`server`, `database`, `cloud`, `clock`, `alert`, …) drawn
+from primitive shapes. Nothing is fetched — the renderer runs with DNS disabled.
+
+**Requires Chrome** (or any Chromium-based browser: Edge, Brave, Chromium). It is found
+automatically on macOS/Linux/Windows; set `VELOG_CHROME_PATH` if yours lives elsewhere.
+Only `velog_render_diagram` and `velog_render_cover` need it — `velog_upload_image`
+just reads a local file, so it and the other 18 tools work without a browser.
+
+**Cost, measured:** one diagram is ~1 GB peak across 9–11 Chrome processes for 3–4
+seconds, then back to zero. That's Chrome's floor, not our content. Coordinates, text
+lengths and array sizes are all bounded, and the canvas cap (6000px / 9M px) is enforced
+**inside the page** — a browser commits to a surface the moment it receives width and
+height, so checking after the fact is too late. Renders are
+**serialized** — MCP clients call tools in parallel, and without that a five-diagram
+request would mean 45 Chrome processes and 6 GB. Serialized, four concurrent requests
+still peak at one render's worth. Ten renders in a row show no accumulation.
+
+### Profile editing — `VELOG_ALLOW_PROFILE=1`
+
+Five more tools appear: `velog_update_profile` (display name, bio),
+`velog_update_about`, `velog_update_blog_title`, `velog_update_social_links`,
+`velog_update_profile_image`. Without the flag they aren't registered at all.
+
+The gate isn't about danger — these are reversible, affect only your own account, and
+aren't distributed anywhere. It's about **confusion**: a profile's `short_bio` and a
+post's `short_description` sound alike. "Fix my description" is ambiguous, and with the
+switch off a wrong guess can't reach your profile.
+
+`velog_update_profile` **keeps what you omit.** Velog's `UpdateProfileInput` requires
+both `display_name` and `short_bio`, so sending one alone would blank the other — the
+tool reads your current values and fills them in.
+
+---
+
+## Usage
+
+Once it's configured, just talk to your MCP client.
+
+```
+"Draft a Velog post about the bug I fixed today"
+   → writes Markdown, saves it as a draft, hands back the edit URL
+
+"What did I write about HTTP/2 last year?"
+   → searches inside your own posts
+
+"Show my top 10 posts by views, and which tags get read most"
+   → walks your whole blog and aggregates
+
+"Back up all my posts to ~/blog-backup"
+   → writes .md files with front matter
+
+"Publish that draft"
+   → private by default; public only with VELOG_ALLOW_PUBLIC=1
+
+"Draw how the request flows from the LB through the workers to Redis"
+   → renders a diagram, audits it, uploads it, hands back the Markdown line
+
+"Make a cover image for this post"
+   → 1200×630 card; pass the URL to velog_update_post's thumbnail
+```
+
+Your MCP client asks for approval before each tool call, and irreversible tools carry
+`destructiveHint`, so nothing gets published without you seeing it first.
+
+### Exported file format
+
+```yaml
+---
+title: "Post title"
+date: 2022-12-31T18:32:39.790Z
+slug: "url-slug"
+url: "https://velog.io/@username/url-slug"
+tags: ["tag1", "tag2"]
+likes: 260
+views: 16323
+---
+
+Post body in Markdown…
+```
+
+---
+
+## Development
+
+```bash
+npm test              # node:test, runs .ts directly — no jest, no ts-node
+npm run typecheck     # includes tests — they used to be excluded, which hid real errors
+npm run lint          # typescript-eslint, type-aware
+npm run build         # tsconfig.build.json (tests excluded from dist)
+npm run schema:dump   # dump Velog's current GraphQL schema
+```
+
+276 tests. `src/__tests__/safety.test.ts` pins the security invariants (A1–A11),
+`render.test.ts` pins the drawing ones (R1–R23), and `plugin.test.ts` pins the
+packaging ones (P1–P26) — if any fails, find out why instead of working around it.
+
+Every guard here was checked by **breaking it on purpose**: 54 mutations against the
+source, plus 12 against the publish gate itself (`scripts/gate-mutation.sh`), each of
+which must make exactly one check fail. A test that still passes with the guard removed
+is not a test. Several in this repo did pass at first, and that is how they got fixed.
+
+## Documentation
+
+| Document | Contents |
+| --- | --- |
+| [docs/PRD.md](docs/PRD.md) | Goals, non-goals, success criteria |
+| [docs/architecture.md](docs/architecture.md) | Layering, and the TypeScript subset Node's type stripping allows |
+| [docs/api-reference.md](docs/api-reference.md) | Measured Velog GraphQL schema and server quirks |
+| [docs/security.md](docs/security.md) | Token handling, capability model, what's deliberately unimplemented |
+| [docs/tools.md](docs/tools.md) | Full tool catalog with gotchas |
+| [docs/decisions/](docs/decisions/) | Architecture decision records |
+
+## Notes
+
+This talks to Velog's internal GraphQL API, which is undocumented and can change
+without warning. When something breaks, run `npm run schema:dump` and diff it against
+`docs/api-reference.md` — that's the fastest way to find what moved.
+
+Velog's [terms of service](https://velog.io/policy/terms) contain no clause restricting
+automated access. Using your own token to manage your own posts stays within scope, and
+your posts remain yours (Article 5).
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 토큰 취급 — 환경변수로만 읽고, 디스크에 쓰지 않고, 로그에 싣지 않는다.
+ *
+ * 설계 근거: docs/decisions/0003-token-env-only.md
+ * 이 파일에는 fs 를 import 하지 않는다. 토큰이 파일로 나갈 경로 자체를 없앤다.
+ *
+ * ★ 벨로그 서버가 토큰을 알아서 갱신한다 (공식 소스 authPlugin.mts 확인):
+ *   - access_token 수명이 30분 미만이면 refresh_token 으로 재발급
+ *   - access_token 이 없거나 깨져도 refresh_token 이 있으면 복구
+ *   - 새 토큰은 응답의 Set-Cookie 로 온다
+ *   그래서 (1) refresh_token 만 있어도 인증이 되고
+ *         (2) Set-Cookie 를 받아 메모리에 반영하면 세션이 안 끊긴다.
+ *   여전히 디스크에는 쓰지 않는다 — 프로세스 수명만큼만 산다.
+ */
+export interface Credentials {
+    readonly accessToken: string | undefined;
+    readonly refreshToken: string | undefined;
+}
+/**
+ * 인증 상태. 토큰이 없는 것은 에러가 아니라 상태다 —
+ * 공개 글 조회·검색·트렌딩은 인증 없이 동작한다.
+ */
+export type AuthState = {
+    readonly kind: 'anonymous';
+} | {
+    readonly kind: 'authenticated';
+    readonly credentials: Credentials;
+};
+export declare function readAuthFromEnv(env?: NodeJS.ProcessEnv): AuthState;
+/** 벨로그는 쿠키 헤더로 인증한다. 없는 토큰은 싣지 않는다. */
+export declare function buildCookieHeader(credentials: Credentials): string;
+/**
+ * 응답의 Set-Cookie 에서 갱신된 토큰을 뽑는다.
+ *
+ * 서버가 재발급하면 여기로 온다. 값이 없으면 undefined 를 돌려
+ * 호출부가 기존 토큰을 유지하게 한다.
+ */
+export declare function parseSetCookie(header: string | null): Partial<Credentials>;
+/**
+ * 현재 유효한 토큰을 들고 있는 저장소. 서버가 갱신해주면 여기에 반영한다.
+ *
+ * 메모리에만 있다. 디스크·키체인·브라우저 어디에도 쓰지 않는다.
+ */
+export declare class TokenStore {
+    #private;
+    constructor(initial: AuthState);
+    get state(): AuthState;
+    get isAuthenticated(): boolean;
+    /** Set-Cookie 로 받은 새 토큰을 반영한다. 바뀐 게 있으면 true. */
+    update(incoming: Partial<Credentials>): boolean;
+    /** 지금까지 본 모든 토큰을 문자열에서 가린다. */
+    mask(text: string): string;
+}
+/** 쓰기 도구가 인증을 요구할 때 쓰는 에러. */
+export declare class AuthRequiredError extends Error {
+    constructor(toolName: string);
+}

package/dist/auth.js

@@ -0,0 +1,124 @@
+/**
+ * 토큰 취급 — 환경변수로만 읽고, 디스크에 쓰지 않고, 로그에 싣지 않는다.
+ *
+ * 설계 근거: docs/decisions/0003-token-env-only.md
+ * 이 파일에는 fs 를 import 하지 않는다. 토큰이 파일로 나갈 경로 자체를 없앤다.
+ *
+ * ★ 벨로그 서버가 토큰을 알아서 갱신한다 (공식 소스 authPlugin.mts 확인):
+ *   - access_token 수명이 30분 미만이면 refresh_token 으로 재발급
+ *   - access_token 이 없거나 깨져도 refresh_token 이 있으면 복구
+ *   - 새 토큰은 응답의 Set-Cookie 로 온다
+ *   그래서 (1) refresh_token 만 있어도 인증이 되고
+ *         (2) Set-Cookie 를 받아 메모리에 반영하면 세션이 안 끊긴다.
+ *   여전히 디스크에는 쓰지 않는다 — 프로세스 수명만큼만 산다.
+ */
+export function readAuthFromEnv(env = process.env) {
+    const accessToken = env['VELOG_ACCESS_TOKEN']?.trim() || undefined;
+    const refreshToken = env['VELOG_REFRESH_TOKEN']?.trim() || undefined;
+    // 둘 중 하나만 있어도 인증을 시도한다. 서버가 refresh_token 으로 복구해준다.
+    if (!accessToken && !refreshToken)
+        return { kind: 'anonymous' };
+    return { kind: 'authenticated', credentials: { accessToken, refreshToken } };
+}
+/** 벨로그는 쿠키 헤더로 인증한다. 없는 토큰은 싣지 않는다. */
+export function buildCookieHeader(credentials) {
+    const parts = [];
+    if (credentials.accessToken)
+        parts.push(`access_token=${credentials.accessToken}`);
+    if (credentials.refreshToken)
+        parts.push(`refresh_token=${credentials.refreshToken}`);
+    return parts.join('; ');
+}
+/**
+ * 응답의 Set-Cookie 에서 갱신된 토큰을 뽑는다.
+ *
+ * 서버가 재발급하면 여기로 온다. 값이 없으면 undefined 를 돌려
+ * 호출부가 기존 토큰을 유지하게 한다.
+ */
+export function parseSetCookie(header) {
+    if (!header)
+        return {};
+    const out = {};
+    // fetch 는 여러 Set-Cookie 를 콤마로 합쳐 준다. 쿠키 값 자체에는 콤마가
+    // 오지 않으므로 이름=값 패턴만 훑는 편이 안전하다.
+    for (const match of header.matchAll(/(access_token|refresh_token)=([^;,\s]*)/g)) {
+        const [, name, value] = match;
+        if (!value)
+            continue; // 로그아웃 시 빈 값으로 지우는 경우는 무시한다
+        if (name === 'access_token')
+            out.accessToken = value;
+        else
+            out.refreshToken = value;
+    }
+    return out;
+}
+/**
+ * 현재 유효한 토큰을 들고 있는 저장소. 서버가 갱신해주면 여기에 반영한다.
+ *
+ * 메모리에만 있다. 디스크·키체인·브라우저 어디에도 쓰지 않는다.
+ */
+export class TokenStore {
+    #state;
+    /** 마스킹 대상. 갱신 전 토큰도 계속 가려야 해서 누적한다. */
+    #seen = new Set();
+    constructor(initial) {
+        this.#state = initial;
+        this.#remember(initial);
+    }
+    get state() {
+        return this.#state;
+    }
+    get isAuthenticated() {
+        return this.#state.kind === 'authenticated';
+    }
+    /** Set-Cookie 로 받은 새 토큰을 반영한다. 바뀐 게 있으면 true. */
+    update(incoming) {
+        if (this.#state.kind !== 'authenticated')
+            return false;
+        if (!incoming.accessToken && !incoming.refreshToken)
+            return false;
+        const current = this.#state.credentials;
+        const next = {
+            accessToken: incoming.accessToken ?? current.accessToken,
+            refreshToken: incoming.refreshToken ?? current.refreshToken,
+        };
+        if (next.accessToken === current.accessToken &&
+            next.refreshToken === current.refreshToken) {
+            return false;
+        }
+        this.#state = { kind: 'authenticated', credentials: next };
+        this.#remember(this.#state);
+        return true;
+    }
+    /** 지금까지 본 모든 토큰을 문자열에서 가린다. */
+    mask(text) {
+        let masked = text;
+        for (const secret of this.#seen) {
+            masked = masked.split(secret).join('***REDACTED***');
+        }
+        return masked.replace(/(access_token|refresh_token)=[^;\s"']+/g, '$1=***REDACTED***');
+    }
+    #remember(state) {
+        if (state.kind !== 'authenticated')
+            return;
+        for (const secret of [
+            state.credentials.accessToken,
+            state.credentials.refreshToken,
+        ]) {
+            // 너무 짧은 값을 치환하면 본문이 훼손된다. 토큰은 항상 이보다 길다.
+            if (secret && secret.length >= 8)
+                this.#seen.add(secret);
+        }
+    }
+}
+/** 쓰기 도구가 인증을 요구할 때 쓰는 에러. */
+export class AuthRequiredError extends Error {
+    constructor(toolName) {
+        super(`${toolName} 은(는) 인증이 필요합니다. ` +
+            'VELOG_ACCESS_TOKEN 또는 VELOG_REFRESH_TOKEN 환경변수를 설정하세요. ' +
+            '(velog.io 로그인 → F12 → Application → Cookies) ' +
+            'refresh_token 만 넣어도 서버가 access_token 을 재발급합니다(유효기간 30일).');
+        this.name = 'AuthRequiredError';
+    }
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

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

package/dist/capabilities.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 기능 범위 — 사용자가 환경변수로 정한다.
+ *
+ * 설계 원칙: **모델은 이 값을 바꿀 수 없다.** MCP 설정 파일을 손대는 사람만
+ * 바꿀 수 있고, 이는 토큰을 넣는 것과 같은 신뢰 경계다. 도구 파라미터로
+ * 노출하면 모델이 스스로 권한을 올릴 수 있게 되므로 그렇게 하지 않는다.
+ *
+ * 왜 '비공개 발행'이 기본인가 — 벨로그 실측에 근거가 있다:
+ *
+ *   // apps/server/src/services/PostApiService/index.mts
+ *   count({ where: { fk_user_id, is_private: false, released_at: { gt: 5분전 } } })
+ *
+ * 계수 대상이 `is_private: false` 뿐이다. 즉 **비공개 글은 이 카운터를 올리지
+ * 않는다.**
+ *
+ * ⚠️ 다만 '올리지 않는다'와 '유발하지 않는다'는 다르다. 처음엔 이걸 혼동해
+ * "비공개면 위험이 원천 소멸"이라고 잘못 적었다. 실제 서버 코드는:
+ *
+ *   const isPublish = !data.is_temp && !data.is_private
+ *   const isLimit = await this.isPostLimitReached(signedUserId)   // ← 무조건 실행
+ *
+ * 공개 여부를 보기 **전에** 검사를 돌린다. 그래서 이미 최근 5분에 공개 글이
+ * 10건 쌓여 있으면, 다음 요청이 비공개 초안 생성이어도 그 시점에 최근 글 전체가
+ * 비공개로 바뀐다. 그 10건은 사용자가 웹에서 직접 올린 것일 수도 있어 우리
+ * 카운터로는 못 본다.
+ *
+ * 정리하면 — 비공개로 두는 것은 **위험을 줄이지만 없애지는 못한다.**
+ * 그래서 쓰기 무재시도와 자체 상한을 함께 유지한다.
+ *
+ * 공개 발행만 다르다. RSS·검색·구독 메일로 나간 뒤에는 지워도 회수가 안 되고,
+ * 벨로그 계수에도 잡힌다. 그래서 이것만 명시적 opt-in 으로 둔다.
+ */
+export interface Capabilities {
+    /** 공개 발행 (`is_private: false`). VELOG_ALLOW_PUBLIC=1 */
+    readonly publicPublish: boolean;
+    /**
+     * 프로필 수정 (이름·한줄소개·소개글·블로그제목·SNS링크·프로필사진).
+     * VELOG_ALLOW_PROFILE=1
+     *
+     * 위험해서 막는 게 아니다 — 전부 되돌릴 수 있고 본인 계정에만 영향이며
+     * RSS·메일로 나가지도 않는다. 게이트를 둔 이유는 **혼동 위험**이다:
+     * 프로필의 `short_bio` 와 글의 `short_description` 은 이름이 비슷하다.
+     * "소개 좀 고쳐줘" 가 어느 쪽인지 모호할 때, 스위치가 꺼져 있으면
+     * 모델이 프로필을 건드릴 수 없으므로 잘못 짚어도 사고가 안 난다.
+     */
+    readonly editProfile: boolean;
+}
+export declare function readCapabilities(env?: NodeJS.ProcessEnv): Capabilities;
+/** 기동 로그용 한 줄 요약. 사용자가 지금 뭐가 열렸는지 즉시 알 수 있어야 한다. */
+export declare function describeCapabilities(capabilities: Capabilities): string;

package/dist/capabilities.js

@@ -0,0 +1,60 @@
+/**
+ * 기능 범위 — 사용자가 환경변수로 정한다.
+ *
+ * 설계 원칙: **모델은 이 값을 바꿀 수 없다.** MCP 설정 파일을 손대는 사람만
+ * 바꿀 수 있고, 이는 토큰을 넣는 것과 같은 신뢰 경계다. 도구 파라미터로
+ * 노출하면 모델이 스스로 권한을 올릴 수 있게 되므로 그렇게 하지 않는다.
+ *
+ * 왜 '비공개 발행'이 기본인가 — 벨로그 실측에 근거가 있다:
+ *
+ *   // apps/server/src/services/PostApiService/index.mts
+ *   count({ where: { fk_user_id, is_private: false, released_at: { gt: 5분전 } } })
+ *
+ * 계수 대상이 `is_private: false` 뿐이다. 즉 **비공개 글은 이 카운터를 올리지
+ * 않는다.**
+ *
+ * ⚠️ 다만 '올리지 않는다'와 '유발하지 않는다'는 다르다. 처음엔 이걸 혼동해
+ * "비공개면 위험이 원천 소멸"이라고 잘못 적었다. 실제 서버 코드는:
+ *
+ *   const isPublish = !data.is_temp && !data.is_private
+ *   const isLimit = await this.isPostLimitReached(signedUserId)   // ← 무조건 실행
+ *
+ * 공개 여부를 보기 **전에** 검사를 돌린다. 그래서 이미 최근 5분에 공개 글이
+ * 10건 쌓여 있으면, 다음 요청이 비공개 초안 생성이어도 그 시점에 최근 글 전체가
+ * 비공개로 바뀐다. 그 10건은 사용자가 웹에서 직접 올린 것일 수도 있어 우리
+ * 카운터로는 못 본다.
+ *
+ * 정리하면 — 비공개로 두는 것은 **위험을 줄이지만 없애지는 못한다.**
+ * 그래서 쓰기 무재시도와 자체 상한을 함께 유지한다.
+ *
+ * 공개 발행만 다르다. RSS·검색·구독 메일로 나간 뒤에는 지워도 회수가 안 되고,
+ * 벨로그 계수에도 잡힌다. 그래서 이것만 명시적 opt-in 으로 둔다.
+ */
+/** '켠다'로 인정하는 값. 오타로 조용히 켜지지 않게 좁게 받는다. */
+const TRUTHY = new Set(['1', 'true', 'yes', 'on']);
+function flag(value) {
+    return TRUTHY.has((value ?? '').trim().toLowerCase());
+}
+export function readCapabilities(env = process.env) {
+    return {
+        publicPublish: flag(env['VELOG_ALLOW_PUBLIC']),
+        editProfile: flag(env['VELOG_ALLOW_PROFILE']),
+    };
+}
+/** 기동 로그용 한 줄 요약. 사용자가 지금 뭐가 열렸는지 즉시 알 수 있어야 한다. */
+export function describeCapabilities(capabilities) {
+    const parts = [
+        capabilities.publicPublish
+            ? '읽기 + 초안 + 발행(공개/비공개 선택)'
+            : '읽기 + 초안 + 비공개 발행',
+    ];
+    if (capabilities.editProfile)
+        parts.push('프로필 수정');
+    const off = [];
+    if (!capabilities.publicPublish)
+        off.push('공개 발행=VELOG_ALLOW_PUBLIC');
+    if (!capabilities.editProfile)
+        off.push('프로필 수정=VELOG_ALLOW_PROFILE');
+    return parts.join(' + ') + (off.length ? ` (꺼짐: ${off.join(', ')})` : '');
+}
+//# sourceMappingURL=capabilities.js.map