@roottale/cms-mcp 0.44.1 → 0.46.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @roottale/cms-mcp
 
+## 0.46.0
+
+### Minor Changes
+
+- 69f7d52: 콘텐츠 유형(Collection)에 **주소 없는 유형**(`basePath: ""`)을 지원합니다(ADR-0060). 강사·리뷰처럼 페이지 안에서 불러와 쓰는 콘텐츠는 이제 라우트 없이 운영할 수 있습니다 — `resolvePostUrl`/`resolvePostPath`는 이런 유형의 글에 항상 `null`을 반환하고, `validateCollections`는 basePath 형식·중복 검사를 건너뜁니다(여러 개 공존 허용). 외부 사이트는 posts API의 `collectionKey` 필터로 내용만 가져다 페이지 안에서 렌더하면 됩니다(`RootTaleBlogList`를 임베디드로 쓸 때는 자체 `postHref` 제공 권장). 소속 판정(`resolvePostCollection`)은 영향 없음 — key만으로 소속이 성립합니다. 기존 유형(basePath 있는 유형)은 동작 변화가 없습니다.
+
+## 0.45.0
+
+### Patch Changes
+
+- 23aa6ae: 카테고리 소속을 콘텐츠 유형 설정과 분리하고, 공개 collections 응답의 categories를 분류 원장에서 조립합니다. 사이트 내부 경로 검증을 강화하고 taxonomy.updated 집계 웹훅 계약과 연동 예제를 추가합니다.
+
 ## 0.44.1
 
 ### Patch Changes

package/dist/index.js

@@ -801,7 +801,7 @@ function registerTools(server) {
 }
 
 // src/server.ts
-var VERSION = true ? "0.44.1" : "dev";
+var VERSION = true ? "0.46.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/collections.md

@@ -42,6 +42,38 @@ description: 같은 글 풀을 공지 게시판(/notice)·블로그(/blog) 등
 - **같은 글이 두 섹션에 안 뜸**: 공지 글을 `/blog/개강안내`로 열면 404, 반대도 404(가드).
 - **섹션(`collection_key`)이 없는 글**은 sitemap·상세 라우트에서 제외됩니다.
 
+## 주소 없는 유형 (`base_path: ""`) — 페이지 안에서만 쓰는 콘텐츠
+
+강사·리뷰처럼 **독립된 URL이 없고 홈페이지의 다른 페이지 안에서 불러와 쓰는**
+콘텐츠는 섹션의 **주소 경로를 비워두면** 됩니다. `base_path`가 빈 문자열이면:
+
+- `resolvePostUrl`/`resolvePostPath` (cms-core) 가 이 섹션 글에 대해 항상
+  **`null`** 을 반환 — `detail: false`(목록 전용) 여부와 무관합니다.
+- 라우트·sitemap·feed·`/{basePath}/categories/{slug}` 아카이브를 **일절
+  파생하지 않습니다**. `createSitemapIndex`/`createFeedRoute` 등 route 팩토리에
+  넘겨도 이 섹션의 글은 조용히 빠집니다(에러 아님).
+- 소속 판정(`resolvePostCollection`)은 영향 없습니다 — 글은 여전히 이 섹션에
+  속하고, 글쓰기 화면의 "어디에 올릴까요?" 에도 그대로 나타납니다. **주소와
+  소속은 별개**입니다.
+- 외부 사이트는 이 유형의 내용을 **posts API의 `collectionKey` 필터**
+  (`fetchPosts({ collectionKey: "instructors" })`)로 가져와 원하는 페이지 안에서
+  직접 렌더합니다. `RootTaleBlogList` 를 이 유형에 임베디드로 쓸 때는 자체
+  `postHref` 를 제공하세요 — 컴포넌트의 기본 링크 로직은 이 유형의 글에 목록
+  페이지 폴백조차 만들지 않습니다(목록 페이지 자체가 없으므로).
+
+```ts
+export const COLLECTIONS: RouteCollection[] = [
+  { key: "blog", basePath: "/blog", categories: ["column", "news"], feed: true, archives: true },
+  // 주소 없음 — 강사 소개는 /about 페이지 안에서 fetchPosts 로 불러와 렌더.
+  { key: "instructors", basePath: "", categories: [] },
+];
+```
+
+어드민 "콘텐츠 유형" 편집기에서는 **주소 경로 칸을 비워두면** 됩니다 — 비우면
+자동으로 RSS 피드·카테고리 모음·공유 미리보기 이미지·글별 상세 페이지 토글이
+꺼지고 비활성화됩니다(주소가 없으니 의미가 없는 기능들). 카드에는 "주소 없음"
+표시가 붙습니다.
+
 ## 목록 전용 유형 (`detail: false`) — 상세 페이지 없음
 
 글별 상세 라우트를 만들지 않고 **목록 화면에서만 보여주는** 섹션을 만들 수 있습니다.
@@ -80,12 +112,13 @@ export const COLLECTIONS: RouteCollection[] = [
 |---|---|---|
 | 무엇 | 글이 사는 곳 (공지 / 블로그) | 섹션 안의 세부 분류 (칼럼 / 소식) |
 | 글당 | **딱 하나** (배타적) | 0개 이상 (선택·복수) |
-| 정하는 곳 | 글쓰기 "어디에 올릴까요?" | 글쓰기 주제 칩 / 설정 > 분류 |
+| 정하는 곳 | 글쓰기 "어디에 올릴까요?" | 글 > 분류 > 카테고리 / 글쓰기 주제 칩 |
 | 저장 | `post.collection_key` | 글의 category terms |
 | 라우팅 | basePath 결정 (`/notice`) | 아카이브만 (`/blog/categories/칼럼`) |
 
 > 이전 버전은 *카테고리로 섹션을 추론*했지만, 지금은 섹션이 글에 **명시**됩니다.
-> 카테고리는 더 이상 어느 섹션에 속하는지를 결정하지 않습니다(주제 아카이브 전용).
+> 카테고리는 글의 섹션을 결정하지 않습니다. 카테고리 자체에는 사용할 섹션을
+> 연결할 수 있고, 글에서는 그 섹션에 연결된 카테고리만 주제로 고릅니다.
 
 ## 어드민에서 설정 (`admin.roottale.com`)
 
@@ -96,17 +129,21 @@ export const COLLECTIONS: RouteCollection[] = [
 |---|---|
 | key | 안정 식별자 (`notice`, `blog`) — 사이트 코드와 맞물리므로 보통 고정 |
 | 라벨 | 메뉴·작성 화면 표시 이름 (공지/블로그) |
-| basePath | URL 앞부분 (`/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 +155,8 @@ basePath·라벨·주제·플래그는 어드민에서 바꾸면 sitemap·feed·
 
 글쓰기 화면 맨 위 **"어디에 올릴까요?"**에서 공지/블로그 카드를 고릅니다 — 이게 글의
 섹션(`collection_key`)이 됩니다. 그 아래 **주제**는 고른 섹션의 카테고리만 보입니다
-(블로그면 칼럼·소식 등). 주제는 선택이며, **설정 > 분류**(taxonomy)에서 미리 만들어 둡니다.
+(블로그면 칼럼·소식 등). 주제는 선택이며, **글 > 분류 > 카테고리**에서 미리 만들어
+콘텐츠 유형에 연결합니다.
 
 ## 사이트 연동 코드
 
@@ -192,6 +230,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이 아니라 **그 유형에 연결된 카테고리가 없음**을 뜻합니다.
 
 ### 섹션 목록 페이지 (공지/블로그 분리 렌더)
 
@@ -351,4 +392,9 @@ basePath를 **코드 수정 없이 어드민에서 자유롭게** 바꾸고 싶
   basePath로 접근하세요. basePath를 바꿨다면 사이트에 그 라우트 파일이 있는지 확인.
 - **주제 아카이브가 비어요** → 그 주제(카테고리)가 섹션의 `categories`(주제 목록)에 있고
   `archives`가 켜져 있는지 확인.
-- **sitemap에 글이 빠졌어요** → 그 글에 섹션이 없으면 의도적으로 제외됩니다.
+- **sitemap에 글이 빠졌어요** → 그 글에 섹션이 없거나, 소속 섹션의 `base_path`가
+  빈 값(주소 없는 유형)이면 의도적으로 제외됩니다.
+- **`RootTaleBlogList` 카드를 눌렀는데 이상한 곳으로 가요** → 그 글의 섹션이
+  주소 없는 유형이면 목록 페이지가 없어 기본 링크 로직이 레거시 `/blog/{slug}`
+  로 폴백합니다. 이 유형은 `RootTaleBlogList` 로 임베디드 렌더하지 말고
+  `fetchPosts({ collectionKey })` 로 직접 페이지에 꽂아 쓰세요.

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.1",
+  "version": "0.46.0",
   "type": "module",
   "description": "RootTale CMS MCP server and CLI for post publishing, media uploads, integration docs, and public API access.",
   "bin": {