@roottale/cms-mcp 0.34.0 → 0.34.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @roottale/cms-mcp
 
+## 0.34.1
+
+### Patch Changes
+
+- ff6eec1: docs: 콘텐츠 유형(Collections) 문서를 M4 최종 모델로 갱신
+
+  섹션은 글의 `collection_key`로 정해지고 카테고리는 섹션 안의 주제(아카이브)라는
+  최종 모델 반영. catch-all·first-wins·"카테고리로 섹션 추론" 등 제거된 동작 설명을
+  삭제. collections.md 전면 개정 + api-reference 에 `collection_key` 필드 + seo.md
+  교차링크 정정.
+
 ## 0.34.0
 
 ### Patch Changes

package/dist/index.js

@@ -279,7 +279,7 @@ function registerTools(server2) {
 }
 
 // src/server.ts
-var VERSION = true ? "0.34.0" : "dev";
+var VERSION = true ? "0.34.1" : "dev";
 var SERVER_INSTRUCTIONS = `
 roottale-cms-mcp\uB294 RootTale CMS\uB97C \uC678\uBD80 \uC0AC\uC774\uD2B8(\uC8FC\uB85C Next.js)\uC5D0 \uC5F0\uB3D9\uD558\uAE30 \uC704\uD55C
 \uD1B5\uD569 \uBB38\uC11C\xB7\uC608\uC2DC \uCF54\uB4DC\xB7\uACF5\uAC1C API \uC870\uD68C tool\uC744 \uC81C\uACF5\uD569\uB2C8\uB2E4.

package/docs/api-reference.md

@@ -25,6 +25,7 @@ JS/TS 스택은 raw 호출 대신 `@roottale/cms-client`를 사용하세요 —
 ```json
 {
   "items": [ { "id": "…", "slug": "…", "title": "…", "body_json": {…},
+               "collection_key": "blog",
                "terms": [{ "taxonomy": "category", "name": "…", "slug": "…" }],
                "published_at": "…" } ],
   "has_more": false,
@@ -32,6 +33,10 @@ JS/TS 스택은 raw 호출 대신 `@roottale/cms-client`를 사용하세요 —
 }
 ```
 
+> `collection_key` = 글이 속한 섹션(콘텐츠 유형). 섹션 라우팅(`/notice`·`/blog`)의 근거이며,
+> 미설정이면 `null`. 카테고리(`terms`)는 섹션 안의 주제로 아카이브에만 쓰입니다 →
+> [콘텐츠 유형 (Collections)](./collections.md).
+
 ## GET /v1/cms/public/posts/{identifier}
 
 글 1개 — `identifier`는 slug 또는 UUID. 미발행/없는 글은 `404`.

package/docs/collections.md

@@ -1,78 +1,95 @@
 ---
 title: 콘텐츠 유형 (Collections) — 공지·블로그 URL 분리
-description: 같은 글 풀을 공지 게시판(/notice)·블로그(/blog) 등 여러 스트림으로 나누는 법. URL 구조, 어드민 설정, 연동 코드, slug·301·OG.
+description: 같은 글 풀을 공지 게시판(/notice)·블로그(/blog) 등 여러 섹션으로 나누는 법. 섹션=글의 collection_key, 카테고리=섹션 안의 주제. URL 구조, 어드민 설정, 연동 코드, slug·301·OG.
 ---
 
 # 콘텐츠 유형 (Collections)
 
-하나의 글 목록을 **여러 스트림**으로 나눠 서로 다른 URL·레이아웃으로 보여주는 기능입니다.
-가장 흔한 형태는 **공지 게시판(`/notice`) + 블로그(`/blog`)** 분리입니다. 어느 글이 어느
-스트림에 속할지는 그 글의 **카테고리**로 정해집니다.
+하나의 글 목록을 **여러 섹션(stream)**으로 나눠 서로 다른 URL·레이아웃으로 보여주는
+기능입니다. 가장 흔한 형태는 **공지 게시판(`/notice`) + 블로그(`/blog`)** 분리입니다.
+
+> **핵심 모델 (2024 ADR-0060 Amendment 1):**
+> 글은 **하나의 섹션**에 속하고(`collection_key`), 그 안에서 여러 **주제**(category)를
+> 가질 수 있습니다. 섹션은 글쓰기 화면의 **"어디에 올릴까요?"**에서 고르고, 주제는
+> 섹션 안의 세부 분류(예: 블로그의 *칼럼*·*소식*)입니다.
 
 ## URL이 어떻게 정해지나
 
-> **글의 URL = 그 글이 속한 스트림의 `basePath` + `/{slug}`**
+> **글의 URL = 그 글이 속한 섹션의 `basePath` + `/{slug}`** — 섹션은 글의 `collection_key`로 정해집니다.
 
-| 글의 카테고리 | 속하는 스트림 | URL |
+| 글의 섹션 (`collection_key`) | basePath | URL |
 |---|---|---|
-| `notice` | 공지 (basePath `/notice`) | `/notice/{slug}` |
-| `column` · `news` | 블로그 (basePath `/blog`) | `/blog/{slug}` |
+| `notice` (공지) | `/notice` | `/notice/{slug}` |
+| `blog` (블로그) | `/blog` | `/blog/{slug}` |
 
-예: `notice` 카테고리 글 "개강안내" → `https://내사이트/notice/개강안내`
-`column` 카테고리 글 "비문학공부법" → `https://내사이트/blog/비문학공부법`
+예: 섹션이 `notice`인 글 "개강안내" → `https://내사이트/notice/개강안내`
+섹션이 `blog`인 글 "비문학공부법" → `https://내사이트/blog/비문학공부법`
 
-스트림별로 함께 만들어지는 경로:
+섹션별로 함께 만들어지는 경로:
 
 | 경로 | 설명 |
 |---|---|
-| `{basePath}` | 스트림 목록 (예: `/notice`, `/blog`) |
+| `{basePath}` | 섹션 목록 (예: `/notice`, `/blog`) |
 | `{basePath}/{slug}` | 글 상세 |
-| `{basePath}/categories/{slug}` | 카테고리 아카이브 (`archives` 켠 스트림만) |
-| `/feed.xml` | RSS — `feed` 켠 스트림들의 통합 피드 |
-| `/sitemap.xml` | 글마다 **소속 스트림 basePath로** 정확히 매핑 |
+| `{basePath}/categories/{slug}` | **주제** 아카이브 (`archives` 켠 섹션만) |
+| `/feed.xml` | RSS — `feed` 켠 섹션들의 통합 피드 |
+| `/sitemap.xml` | 글마다 **소속 섹션 basePath로** 정확히 매핑 |
 | `{basePath}/{slug}/opengraph-image` | 글별 동적 OG 카드 (배선 시) |
 
 규칙:
 
 - **slug은 한글 그대로** 됩니다(예: `/blog/비문학독해`). 내부적으로 percent-encoding.
-- **같은 글이 두 스트림에 안 뜸**: 공지 글을 `/blog/개강안내`로 열면 404, 반대도 404(가드).
-- **글이 어느 스트림에도 안 속하면**(분류 전용 카테고리 등) sitemap·feed에서 제외됩니다.
-- 한 글이 여러 스트림 카테고리를 동시에 가지면 **선언 순서가 빠른 스트림**이 이깁니다(first-wins).
+- **같은 글이 두 섹션에 안 뜸**: 공지 글을 `/blog/개강안내`로 열면 404, 반대도 404(가드).
+- **섹션(`collection_key`)이 없는 글**은 sitemap·상세 라우트에서 제외됩니다.
+
+## 섹션 vs 주제 (자주 헷갈리는 부분)
+
+| | 섹션 (collection) | 주제 (category) |
+|---|---|---|
+| 무엇 | 글이 사는 곳 (공지 / 블로그) | 섹션 안의 세부 분류 (칼럼 / 소식) |
+| 글당 | **딱 하나** (배타적) | 0개 이상 (선택·복수) |
+| 정하는 곳 | 글쓰기 "어디에 올릴까요?" | 글쓰기 주제 칩 / 설정 > 분류 |
+| 저장 | `post.collection_key` | 글의 category terms |
+| 라우팅 | basePath 결정 (`/notice`) | 아카이브만 (`/blog/categories/칼럼`) |
+
+> 이전 버전은 *카테고리로 섹션을 추론*했지만, 지금은 섹션이 글에 **명시**됩니다.
+> 카테고리는 더 이상 어느 섹션에 속하는지를 결정하지 않습니다(주제 아카이브 전용).
 
 ## 어드민에서 설정 (`mysite.roottale.com`)
 
-**설정 > 콘텐츠 유형** 에서 스트림을 정의합니다. 각 스트림은:
+**설정 > 콘텐츠 유형** 에서 섹션을 정의합니다. 빈 상태의 "공지 + 블로그 한 번에 만들기"
+버튼으로 표준 두 섹션을 한 번에 만들 수 있습니다. 각 섹션은:
 
 | 항목 | 의미 |
 |---|---|
-| key | 안정 식별자 (`notice`, `blog`) |
+| key | 안정 식별자 (`notice`, `blog`) — 사이트 코드와 맞물리므로 보통 고정 |
 | 라벨 | 메뉴·작성 화면 표시 이름 (공지/블로그) |
 | basePath | URL 앞부분 (`/notice`, `/blog`) |
-| 카테고리 | 이 스트림에 속하는 카테고리 slug들. **비우면 catch-all**(나머지 전부) |
-| feed / archives / og | RSS 포함 / 카테고리 아카이브 / 동적 OG |
-| 순서 | 위에서부터 우선순위 |
+| 주제 | 이 섹션이 제공하는 카테고리(아카이브 범위). 비우면 주제 없음 |
+| feed / archives / og | RSS 포함 / 주제 아카이브 / 동적 OG |
+| 순서 | 메뉴·표시 순서 |
 
-**비우면 단일 블로그(`/blog`)** 로 동작합니다(설정 전 기본값).
+**섹션을 하나도 안 만들면 단일 블로그(`/blog`)** 로 동작합니다(설정 전 기본값).
 
 ### ⚠️ basePath는 "라우트가 있어야" 동작합니다 (데이터=DB, 라우트=코드)
 
-basePath·라벨·카테고리·플래그는 어드민에서 바꾸면 sitemap·feed·라우팅이 즉시 따라갑니다.
+basePath·라벨·주제·플래그는 어드민에서 바꾸면 sitemap·feed·라우팅이 즉시 따라갑니다.
 **단 basePath에 해당하는 페이지 파일이 사이트에 있어야** 실제로 열립니다:
 
 - `/notice`·`/blog`처럼 **이미 라우트가 있는 경로**는 어드민만으로 자유롭게 편집 → 동작.
 - basePath를 **완전히 새 경로**(예: `/news`)로 바꾸면 sitemap엔 `/news/{slug}`가 나가지만
-  사이트에 `app/news/[slug]` 라우트가 없으면 **404**. 이 경우 개발자가 라우트를 먼저 추가해야
-  합니다. (새 basePath도 코드 수정 없이 동작시키려면 catch-all 동적 라우트를 쓰면 됩니다 — 아래.)
+  사이트에 `app/news/[slug]` 라우트가 없으면 **404**. 개발자가 라우트를 먼저 추가해야
+  합니다. (새 basePath도 코드 수정 없이 동작시키려면 catch-all 동적 라우트 — 아래.)
 
-### 카테고리 만들기
+### 글을 섹션에 올리기
 
-각 스트림의 카테고리(`notice`, `column`, `news` 등)는 **설정 > 카테고리**(taxonomy)에서
-만들고, 글 작성 화면에서 글에 붙입니다. 작성 화면에는 *"이 글은 → /notice 에 게시됩니다"*
-표시가 떠서 어느 스트림으로 가는지 바로 확인됩니다.
+글쓰기 화면 맨 위 **"어디에 올릴까요?"**에서 공지/블로그 카드를 고릅니다 — 이게 글의
+섹션(`collection_key`)이 됩니다. 그 아래 **주제**는 고른 섹션의 카테고리만 보입니다
+(블로그면 칼럼·소식 등). 주제는 선택이며, **설정 > 분류**(taxonomy)에서 미리 만들어 둡니다.
 
 ## 사이트 연동 코드
 
-스트림 선언을 route 팩토리에 넘기면 sitemap·feed·revalidate가 거기서 파생됩니다. 두 가지
+섹션 선언을 route 팩토리에 넘기면 sitemap·feed·revalidate가 거기서 파생됩니다. 두 가지
 방식이 있습니다.
 
 ### 방식 A — 코드 상수 (간단, 고정)
@@ -81,17 +98,21 @@ basePath·라벨·카테고리·플래그는 어드민에서 바꾸면 sitemap·
 import type { RouteCollection } from "@roottale/cms-renderer-next/routes";
 
 export const COLLECTIONS: RouteCollection[] = [
-  { key: "notice", basePath: "/notice", categories: ["notice"] },
+  { key: "notice", basePath: "/notice", categories: [] },        // 주제 없는 게시판
   {
     key: "blog",
     basePath: "/blog",
-    categories: ["column", "news"], // 또는 [] = catch-all(공지 외 전부)
+    categories: ["column", "news"], // 이 섹션의 주제(아카이브 범위)
     feed: true,
     archives: true,
   },
 ];
 ```
 
+> `categories`는 이제 **그 섹션이 제공하는 주제 목록**(아카이브 `/blog/categories/{slug}`
+> 생성 범위)입니다. 섹션 소속은 글의 `collection_key`로 정해지므로, 이 배열은 라우팅
+> 소유권이 아닙니다.
+
 ```ts
 // app/sitemap.ts
 import { createSitemap } from "@roottale/cms-renderer-next/routes";
@@ -107,7 +128,7 @@ export const GET = createFeedRoute({ apiKey, siteUrl, title, collections: COLLEC
 ### 방식 B — 어드민에서 동적 로드 (운영자가 직접 편집)
 
 상수 대신 **어드민 "콘텐츠 유형"** 값을 `fetchCollections()`로 가져와 팩토리에 **resolver
-함수**로 넘깁니다. 운영자가 어드민에서 스트림을 바꾸면 사이트가 따라갑니다.
+함수**로 넘깁니다. 운영자가 어드민에서 섹션을 바꾸면 사이트가 따라갑니다.
 
 ```ts
 import { fetchCollections } from "@roottale/cms-client/server";
@@ -131,9 +152,11 @@ export const GET = createFeedRoute({ apiKey, siteUrl, title, collections: getCol
 응답은 `RouteCollection`과 구조 호환이라 그대로 넘길 수 있습니다. 매 요청 fetch를 피하려면
 사이트 경계에서 캐시하세요(예: Next `fetch(url, { next: { revalidate: 300 } })`).
 
-### 상세 페이지 가드 (스트림 누출 차단)
+### 상세 페이지 가드 (섹션 누출 차단)
 
-상세 라우트는 글이 그 스트림 소속인지 확인해 다른 스트림 글이 새는 것을 막습니다.
+상세 라우트는 글이 그 섹션 소속인지 확인해 다른 섹션 글이 새는 것을 막습니다.
+`resolvePostCollection`은 글의 `collectionKey`로 섹션을 해석합니다(공개 API가 글마다
+`collection_key`를 내려줍니다 → `cms-client`의 `CmsPostContent.collectionKey`).
 
 ```ts
 import { resolvePostCollection } from "@roottale/cms-renderer-next/routes";
@@ -149,7 +172,7 @@ import { createRevalidateRoute } from "@roottale/cms-renderer-next/routes";
 export const POST = createRevalidateRoute({ apiKey, revalidate, collections: COLLECTIONS });
 ```
 
-각 스트림 basePath(+ `archives`면 `/categories`)와 `/feed.xml`·`/sitemap.xml`·`/llms.txt`를
+각 섹션 basePath(+ `archives`면 `/categories`)와 `/feed.xml`·`/sitemap.xml`·`/llms.txt`를
 자동 무효화합니다. resolver가 실패하면 잘못된 경로를 추측하지 않고 불변 경로만 갱신하며
 응답에 `warning`을 노출합니다.
 
@@ -173,41 +196,7 @@ export default createPostOgImage(
 
 > Astro 사이트는 `@roottale/cms-renderer-astro`에서 동일한 `resolvePostCollection`/
 > `resolvePostPath`/`RouteCollection`을 import 하고 `renderBlogList({ collections })`로
-> 링크를 스트림별로 라우팅합니다(동등 surface).
-
-## catch-all 스트림
-
-블로그 카테고리가 계속 늘어나는 사이트는, 블로그를 **`categories: []`(빈 배열) = catch-all**로
-두면 됩니다 — 공지로 분류되지 않은 글을 전부 흡수합니다. catch-all은 **맨 뒤**에 두세요
-(선언 순서가 우선순위라, 뒤에 둔 스트림은 도달 못 합니다).
-
-```ts
-[
-  { key: "notice", basePath: "/notice", categories: ["notice"] },
-  { key: "blog", basePath: "/blog", categories: [], feed: true }, // 나머지 전부
-]
-```
-
-## 명시 섹션 — `collection_key` (권장)
-
-공개 API의 글(post) 응답에는 글이 속한 섹션을 직접 가리키는 **`collection_key`**
-필드가 포함됩니다. 어드민 글쓰기에서 "어디에 올릴까요?"로 고른 섹션이 이 값으로
-저장됩니다. `cms-client`의 `CmsPostContent.collectionKey`로 받습니다.
-
-`resolvePostCollection(post, collections)`는 **`collectionKey`가 있으면 그것을
-우선** 사용하고(일치하는 섹션이 있을 때), 없으면 기존처럼 글의 카테고리 slug로
-섹션을 파생합니다. 즉:
-
-- 신규 글: `collectionKey`로 섹션이 명확히 결정됩니다(카테고리는 순수 "주제"로만 쓰임).
-- 구 글/구 서버: `collection_key`가 없으므로 카테고리 파생으로 **그대로 동작**(하위호환).
-
-```ts
-// 소비자 코드는 동일 — resolver가 collectionKey 를 우선 사용.
-const c = resolvePostCollection(post, collections);
-```
-
-> 마이그레이션 중에는 두 방식이 공존합니다. `collection_key`가 채워진 글은 카테고리와
-> 무관하게 그 섹션으로 라우팅되고, 비어 있는 글은 카테고리로 판정됩니다.
+> 링크를 섹션별로 라우팅합니다(동등 surface).
 
 ## slug 변경과 301
 
@@ -218,15 +207,16 @@ const c = resolvePostCollection(post, collections);
 
 basePath를 **코드 수정 없이 어드민에서 자유롭게** 바꾸고 싶으면, 정적 `app/notice/[slug]`
 대신 **catch-all 동적 라우트** `app/[stream]/[slug]/page.tsx`(또는 `app/[...path]`)를 두고,
-그 안에서 collections를 읽어 요청 경로가 어떤 스트림 basePath인지 판정해 렌더합니다. 그러면
+그 안에서 collections를 읽어 요청 경로가 어떤 섹션 basePath인지 판정해 렌더합니다. 그러면
 어드민에서 basePath를 `/news`로 바꿔도 동작합니다. 트레이드오프: 정적 라우트보다 캐시·타입
-안전성이 떨어지므로, 스트림 구조가 자주 바뀌는 사이트에만 권장합니다.
+안전성이 떨어지므로, 섹션 구조가 자주 바뀌는 사이트에만 권장합니다.
 
 ## 자주 막히는 곳
 
-- **글이 안 보여요** → 그 글에 스트림 카테고리(`notice`/`column`/`news` 등)가 붙어 있는지 확인.
-  어드민 콘텐츠 유형이 비어 있으면 사이트는 코드 기본값으로만 동작합니다.
-- **404가 떠요** → 공지 글을 `/blog/...`로(또는 그 반대로) 열면 가드가 막습니다. 올바른 스트림
+- **글이 안 보여요** → 글에 **섹션(`collection_key`)**이 지정됐는지 확인. 글쓰기 "어디에
+  올릴까요?"에서 섹션을 골라야 합니다. (섹션 없는 글은 sitemap·상세에서 제외.)
+- **404가 떠요** → 공지 글을 `/blog/...`로(또는 그 반대로) 열면 가드가 막습니다. 올바른 섹션
   basePath로 접근하세요. basePath를 바꿨다면 사이트에 그 라우트 파일이 있는지 확인.
-- **sitemap에 글이 빠졌어요** → 그 글이 어느 스트림에도 안 속하면(상세 라우트 없는 분류 전용)
-  의도적으로 제외됩니다.
+- **주제 아카이브가 비어요** → 그 주제(카테고리)가 섹션의 `categories`(주제 목록)에 있고
+  `archives`가 켜져 있는지 확인.
+- **sitemap에 글이 빠졌어요** → 그 글에 섹션이 없으면 의도적으로 제외됩니다.

package/docs/seo.md

@@ -53,10 +53,11 @@ export default createSitemap(
 
 ## 다중 스트림 (collections) — 공지·블로그 분리
 
-같은 글 풀을 공지 게시판(`/notice`) + 블로그(`/blog`) 등 여러 스트림으로 나눠 서로 다른
-URL·레이아웃으로 보여줄 수 있습니다. URL 구조·어드민 설정·연동 코드(코드 상수 vs 어드민
-fetch)·가드·catch-all·동적 basePath는 별도 문서 [콘텐츠 유형 (Collections)](./collections.md)
-에 정리되어 있습니다. 여기 sitemap/feed 예시도 `collections`를 넘기면 스트림별로 파생됩니다.
+같은 글 풀을 공지 게시판(`/notice`) + 블로그(`/blog`) 등 여러 섹션으로 나눠 서로 다른
+URL·레이아웃으로 보여줄 수 있습니다. 섹션은 글의 `collection_key`로 정해지고, 카테고리는
+섹션 안의 주제(아카이브)입니다. URL 구조·어드민 설정·연동 코드(코드 상수 vs 어드민
+fetch)·가드·동적 basePath는 별도 문서 [콘텐츠 유형 (Collections)](./collections.md)
+에 정리되어 있습니다. 여기 sitemap/feed 예시도 `collections`를 넘기면 섹션별로 파생됩니다.
 
 ## robots.txt
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roottale/cms-mcp",
-  "version": "0.34.0",
+  "version": "0.34.1",
   "type": "module",
   "description": "RootTale CMS integration MCP server — bundled integration docs, Next.js example code, and public API lookup tools. Run with: npx @roottale/cms-mcp",
   "bin": {