@roottale/cms-mcp 0.44.0 → 0.45.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @roottale/cms-mcp
 
+## 0.45.0
+
+### Patch Changes
+
+- 23aa6ae: 카테고리 소속을 콘텐츠 유형 설정과 분리하고, 공개 collections 응답의 categories를 분류 원장에서 조립합니다. 사이트 내부 경로 검증을 강화하고 taxonomy.updated 집계 웹훅 계약과 연동 예제를 추가합니다.
+
+## 0.44.1
+
+### Patch Changes
+
+- 4b09885: CMS 자동화 문서의 `read` 권한 범위, R2 미디어 키 경로, CLI 하위 명령 도움말을
+  실제 동작과 맞게 바로잡았습니다.
+
 ## 0.44.0
 
 ### Minor Changes

package/README.md

@@ -59,7 +59,10 @@ npx -y @roottale/cms-mcp cli posts create \
 npx -y @roottale/cms-mcp cli posts publish "<post-id>"
 ```
 
-전체 명령은 `npx -y @roottale/cms-mcp cli --help`에서 확인할 수 있습니다.
+상위 `cli --help`는 명령 그룹만 보여줍니다. 글의 `list`, `create`, `update`,
+`publish`, `unpublish`, `set-terms`는 `cli posts --help`, 미디어의 `list`,
+`upload`, `update`, `delete`는 `cli media --help`에서 확인하세요. 각 명령의
+옵션은 `cli posts create --help`처럼 하위 명령 뒤에 `--help`를 붙이면 됩니다.
 
 ## Tools
 

package/dist/index.js

@@ -801,7 +801,7 @@ function registerTools(server) {
 }
 
 // src/server.ts
-var VERSION = true ? "0.44.0" : "dev";
+var VERSION = true ? "0.45.0" : "dev";
 var SERVER_INSTRUCTIONS = `
 roottale-cms-mcp\uB294 RootTale CMS\uB97C \uC678\uBD80 \uC0AC\uC774\uD2B8(\uC8FC\uB85C Next.js)\uC5D0 \uC5F0\uB3D9\uD558\uACE0
 \uAE00\xB7\uC378\uB124\uC77C\xB7\uBCF8\uBB38 \uC774\uBBF8\uC9C0\uB97C \uC790\uB3D9\uD654\uD558\uAE30 \uC704\uD55C \uBB38\uC11C\xB7\uC608\uC2DC \uCF54\uB4DC\xB7API tool\uC744 \uC81C\uACF5\uD569\uB2C8\uB2E4.

package/docs/api-reference.md

@@ -12,8 +12,9 @@ description: 공개 API raw 엔드포인트 — JS 외 스택이나 저수준
 `@roottale/cms-client`를 사용하세요. 글쓰기·미디어 자동화는 아래 HTTP API,
 MCP tool 또는 공개 CLI를 사용합니다.
 
-글쓰기·미디어 자동화는 `read_write` API 키가 필요합니다. 공개 콘텐츠 조회만
-필요하면 `read` 키를 사용하세요.
+글쓰기·미디어 자동화는 `read_write` API 키가 필요합니다. `read` 키는
+읽기 전용이며 공개 콘텐츠뿐 아니라 관리 API의 초안·예약·비공개 글과
+미디어 목록도 조회할 수 있습니다.
 
 ## 관리 API 빠른 흐름
 
@@ -109,7 +110,7 @@ curl -X PUT "$UPLOAD_URL" \
 
 ```json
 {
-  "r2_key": "tenant-id/site-id/...",
+  "r2_key": "tenants/<tenant-id>/sites/<site-id>/media/...",
   "original_name": "hero.webp",
   "content_type": "image/webp",
   "size_bytes": 482031,
@@ -118,7 +119,8 @@ curl -X PUT "$UPLOAD_URL" \
 }
 ```
 
-서버가 R2 객체의 tenant 경로, 크기, 형식을 검증한 뒤 미디어를 등록합니다.
+`r2_key`는 1단계 응답값을 바꾸지 말고 그대로 보냅니다. 서버가 R2 객체의
+tenant/site 경로, 크기, 형식을 검증한 뒤 미디어를 등록합니다.
 응답의 `id`는 글의 `featured_media_id`에, `url`은 Tiptap image 노드의
 `attrs.src`에 사용합니다.
 

package/docs/collections.md

@@ -80,12 +80,13 @@ export const COLLECTIONS: RouteCollection[] = [
 |---|---|---|
 | 무엇 | 글이 사는 곳 (공지 / 블로그) | 섹션 안의 세부 분류 (칼럼 / 소식) |
 | 글당 | **딱 하나** (배타적) | 0개 이상 (선택·복수) |
-| 정하는 곳 | 글쓰기 "어디에 올릴까요?" | 글쓰기 주제 칩 / 설정 > 분류 |
+| 정하는 곳 | 글쓰기 "어디에 올릴까요?" | 글 > 분류 > 카테고리 / 글쓰기 주제 칩 |
 | 저장 | `post.collection_key` | 글의 category terms |
 | 라우팅 | basePath 결정 (`/notice`) | 아카이브만 (`/blog/categories/칼럼`) |
 
 > 이전 버전은 *카테고리로 섹션을 추론*했지만, 지금은 섹션이 글에 **명시**됩니다.
-> 카테고리는 더 이상 어느 섹션에 속하는지를 결정하지 않습니다(주제 아카이브 전용).
+> 카테고리는 글의 섹션을 결정하지 않습니다. 카테고리 자체에는 사용할 섹션을
+> 연결할 수 있고, 글에서는 그 섹션에 연결된 카테고리만 주제로 고릅니다.
 
 ## 어드민에서 설정 (`admin.roottale.com`)
 
@@ -97,16 +98,20 @@ export const COLLECTIONS: RouteCollection[] = [
 | key | 안정 식별자 (`notice`, `blog`) — 사이트 코드와 맞물리므로 보통 고정 |
 | 라벨 | 메뉴·작성 화면 표시 이름 (공지/블로그) |
 | basePath | URL 앞부분 (`/notice`, `/blog`) |
-| 주제 | 이 섹션이 제공하는 카테고리(아카이브 범위). 비우면 주제 없음 |
 | feed / archives / og | RSS 포함 / 주제 아카이브 / 동적 OG |
 | 글별 상세 페이지 (`detail`) | 기본 켜짐. 끄면 목록 전용(상세 URL 없음) — 아래 "목록 전용 유형" 참고 |
 | 순서 | 메뉴·표시 순서 |
 
 **섹션을 하나도 안 만들면 단일 블로그(`/blog`)** 로 동작합니다(설정 전 기본값).
 
+카테고리 소속은 **글 > 분류 > 카테고리**에서 정합니다. 카테고리를 만들거나
+편집할 때 콘텐츠 유형을 하나 고르면, 공개 `collections[].categories`에도 그
+유형의 주제로 나타납니다. 콘텐츠 유형 설정과 카테고리 소속을 서로 다른 화면에서
+동시에 바꿔도 JSON 배열을 덮어쓰지 않도록 별도 데이터로 저장됩니다.
+
 ### ⚠️ basePath는 "라우트가 있어야" 동작합니다 (데이터=DB, 라우트=코드)
 
-basePath·라벨·주제·플래그는 어드민에서 바꾸면 sitemap·feed·라우팅이 즉시 따라갑니다.
+basePath·라벨·플래그는 어드민에서 바꾸면 sitemap·feed·라우팅이 즉시 따라갑니다.
 **단 basePath에 해당하는 페이지 파일이 사이트에 있어야** 실제로 열립니다:
 
 - `/notice`·`/blog`처럼 **이미 라우트가 있는 경로**는 어드민만으로 자유롭게 편집 → 동작.
@@ -118,7 +123,8 @@ basePath·라벨·주제·플래그는 어드민에서 바꾸면 sitemap·feed·
 
 글쓰기 화면 맨 위 **"어디에 올릴까요?"**에서 공지/블로그 카드를 고릅니다 — 이게 글의
 섹션(`collection_key`)이 됩니다. 그 아래 **주제**는 고른 섹션의 카테고리만 보입니다
-(블로그면 칼럼·소식 등). 주제는 선택이며, **설정 > 분류**(taxonomy)에서 미리 만들어 둡니다.
+(블로그면 칼럼·소식 등). 주제는 선택이며, **글 > 분류 > 카테고리**에서 미리 만들어
+콘텐츠 유형에 연결합니다.
 
 ## 사이트 연동 코드
 
@@ -192,6 +198,9 @@ export const GET = createFeedRoute({ apiKey, siteUrl, title, collections: getCol
 공개 엔드포인트: `GET /v1/cms/public/collections` (블로그 조회와 같은 API 키).
 응답은 `RouteCollection`과 구조 호환이라 그대로 넘길 수 있습니다. 매 요청 fetch를 피하려면
 사이트 경계에서 캐시하세요(예: Next `fetch(url, { next: { revalidate: 300 } })`).
+`categories`는 콘텐츠 유형 설정 JSON이 아니라 카테고리의 현재 소속을 기준으로
+서버가 조립하므로, 카테고리 이름 변경·삭제·이동이 즉시 반영됩니다. 빈 배열은
+catch-all이 아니라 **그 유형에 연결된 카테고리가 없음**을 뜻합니다.
 
 ### 섹션 목록 페이지 (공지/블로그 분리 렌더)
 

package/docs/getting-started.md

@@ -10,7 +10,8 @@ description: API 키 발급, 환경변수 설정, 패키지 설치, 첫 콘텐
 1. 어드민(`admin.roottale.com`) 로그인
 2. **설정 > 사이트 연결 키** 메뉴로 이동
 3. 새 키 발급 — 권한 선택:
-   - **read** (기본): 발행된 콘텐츠 조회만. 외부 사이트 연동은 이걸로 충분
+   - **read** (기본): 읽기 전용. 공개 콘텐츠와 관리 API의
+     초안·예약·비공개 글, 미디어 목록을 조회할 수 있음
    - **read_write**: 글 작성·수정·발행, 카테고리/태그, 미디어 업로드 포함
 4. 발급된 키(`rtlk_cust_` + 24자)는 **발급 직후 1회만 평문 표시**됩니다. 바로
    복사해 환경변수에 저장하세요.
@@ -127,6 +128,21 @@ npx -y @roottale/cms-mcp cli posts create \
 npx -y @roottale/cms-mcp cli posts publish "<글 id>"
 ```
 
+상위 `cli --help`는 `posts`, `media` 그룹만 보여줍니다. 전체 하위 명령은
+다음 도움말에서 확인하세요.
+
+```bash
+npx -y @roottale/cms-mcp cli posts --help
+npx -y @roottale/cms-mcp cli media --help
+
+# 특정 명령의 모든 옵션
+npx -y @roottale/cms-mcp cli posts create --help
+npx -y @roottale/cms-mcp cli media upload --help
+```
+
+글 명령은 `list`, `create`, `update`, `publish`, `unpublish`, `set-terms`,
+미디어 명령은 `list`, `upload`, `update`, `delete`를 제공합니다.
+
 내부 운영 저장소에서는 같은 기능을 `rt cms posts ...`,
 `rt cms media ...` 명령으로도 실행할 수 있습니다.
 

package/docs/revalidation-webhooks.md

@@ -60,7 +60,7 @@ URL을 비우고 저장하면 웹훅이 비활성화됩니다.
 
 - 게시물 생성/발행/수정/삭제/발행 취소
 - 게시물의 카테고리·태그 변경 (블로그 카드의 카테고리 라벨이 바뀌므로)
-- 분류(taxonomy) 용어 삭제 (해당 용어를 참조하던 발행 글 전부)
+- 분류(taxonomy) 용어 생성/수정/순서 변경/삭제
 - 블로그 표시 설정 변경 (TOC, 작성자/발행일, 작성자 카드)
 - 디자인 토큰 변경
 - 수동 revalidation API 호출
@@ -74,6 +74,11 @@ URL을 비우고 저장하면 웹훅이 비활성화됩니다.
 - 상세 페이지는 현재 slug + payload의 `paths` 힌트 경로 모두 revalidate
 - 홈에 최신 글 섹션이 있으면 `alsoRevalidate`에 `/` 포함
 
+분류 변경은 `taxonomy.updated` 이벤트 **한 번**으로 전달됩니다. payload의
+`paths`에는 영향을 받는 글 상세 경로와 카테고리 모음 경로가 중복 없이 들어갑니다.
+연결된 글마다 웹훅을 따로 보내지 않으므로, 카테고리 하나를 바꿔도 수십 번 재검증되는
+문제가 없습니다.
+
 ## 저수준 검증 — verifyRootTaleWebhook
 
 `createRevalidateRoute`를 못 쓰는 환경(다른 프레임워크 등)은
@@ -92,8 +97,12 @@ export async function POST(request: Request) {
   if (!result.ok) {
     return Response.json({ reason: result.reason }, { status: 401 });
   }
-  // result.event: "post.published" | "post.updated" | "post.deleted"
-  // result.payload.paths: 갱신할 root-relative 경로 배열
+  const payload = JSON.parse(rawBody) as { paths?: unknown };
+  const paths = Array.isArray(payload.paths)
+    ? payload.paths.filter((path): path is string => typeof path === "string")
+    : [];
+  // result.event: "post.published" | "post.updated" | "post.deleted" | "taxonomy.updated"
+  for (const path of paths) revalidatePath(path);
   return Response.json({ ok: true });
 }
 ```

package/examples/nextjs/app/api/revalidate/route.ts

@@ -5,8 +5,9 @@ import { createRevalidateRoute } from "@roottale/cms-renderer-next/routes";
 
 function revalidateBlogPath(path: string): void {
   revalidatePath(path);
-  // 카테고리/태그 인덱스 같은 동적 경로가 있으면 함께 무효화
-  // if (path === "/blog/categories") revalidatePath("/blog/categories/[category]", "page");
+  if (path === "/blog/categories") {
+    revalidatePath("/blog/categories/[category]", "page");
+  }
 }
 
 export const POST = createRevalidateRoute({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roottale/cms-mcp",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "type": "module",
   "description": "RootTale CMS MCP server and CLI for post publishing, media uploads, integration docs, and public API access.",
   "bin": {