@roottale/cms-mcp 0.58.0 → 0.59.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @roottale/cms-mcp
 
+## 0.59.0
+
+### Minor Changes
+
+- c4099f2: 관련 콘텐츠(공통 필드) — 편집자가 어드민에서 유형 상관없이 고른 발행 글이 글 목록·상세·미리보기
+  응답 `related_posts` 로 내려온다(제목·주소·유형·요약·대표이미지·발행일, 고른 순서).
+  - cms-client: `CmsPostContent.relatedPosts?: CmsRelatedPost[]` + 와이어 매핑(구 서버는 빈 배열)
+  - cms-renderer-next: `RootTaleBlogPost` 가 편집자 선택이 있으면 그것을 그리고(저장 주소로 링크),
+    없을 때만 `relatedPostsCount` 자동 추천(같은 카테고리 최신)
+  - cms-mcp 문서: 공개 `related_posts` 필드, 관리 `PATCH /v1/cms/posts/{post_id}/related`, blog.md 안내
+
+### Patch Changes
+
+- c0b3679: 공통 블록 배치 규칙의 유형 키를 컬렉션(`collectionKey`)에서 콘텐츠 모델(`modelKey`)로 바꾼다
+  (ADR-0109 Amendment 1 · ADR-0105). `SitePatternPlacementRule.modelKey`,
+  `findSitePatternPlacementRule`/`setSitePatternPlacementRule`/`resolvePatternSlots` 가 `modelKey` 를
+  받는다. 저장된 옛 규칙의 `collectionKey` 필드는 `readSitePatternPlacements` 가 `modelKey` 로 읽는다.
+  공개 API 응답 모양(`pattern_slots`)은 그대로이며, 계산 근거가 글의 `model_key` 로 바뀐다 —
+  컬렉션 설정이 없는 사이트 글·2단계 분류 모델(FAQ)·모델 key 와 컬렉션 key 가 다른 글도 유형별
+  규칙을 받는다. cms-mcp `api-reference.md` 의 `pattern_slots` 설명을 맞춘다.
+- a9e3fc1: 발행 웹훅 문서: 알림 주소를 따로 적지 않는다 — 어드민 사이트 정보의 공개 도메인·스테이징 주소에서
+  `https://<도메인>/api/revalidate` 가 자동으로 정해지고 운영·스테이징 스위치로 켜고 끈다
+  (`revalidation-webhooks.md` §2·문제 해결 표).
+- 960677c: 발행 웹훅 문서: 주소가 바뀐 글(slug 변경·카테고리 이동)은 `paths` 에 옛 상세 주소도 함께 온다
+  (`revalidation-webhooks.md` §글 웹훅의 paths). 수신 측은 옛 주소 캐시와 옛 주소를 참조하던
+  페이지를 같은 요청에서 갱신할 수 있다.
+
 ## 0.58.0
 
 ### Minor Changes

package/dist/index.js

@@ -1559,7 +1559,7 @@ function registerTools(server) {
 }
 
 // src/server.ts
-var VERSION = true ? "0.58.0" : "dev";
+var VERSION = true ? "0.59.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

@@ -88,6 +88,19 @@ curl https://api.roottale.com/v1/cms/posts \
 {"taxonomy":"category","term_ids":["term-id-1","term-id-2"]}
 ```
 
+### PATCH /v1/cms/posts/{post_id}/related
+
+글의 **관련 콘텐츠**(어드민 편집기 "관련 콘텐츠" 패널과 같은 원장)를 전체 교체합니다.
+유형(모델)과 상관없이 같은 사이트의 글을 순서대로 최대 10개. 자기 자신·중복은 무시되고,
+다른 사이트 글은 400. 발행 글이면 `post.updated` 웹훅이 나갑니다.
+
+```json
+{"related_post_ids":["post-id-1","post-id-2"]}
+```
+
+응답은 `related_posts`(발행 여부 무관, 순서대로, `status` 포함)입니다. 공개 응답에는 그중
+**발행 글만** `related_posts` 로 나갑니다(아래 글 목록·상세 참고).
+
 ### GET /v1/cms/posts
 
 초안·예약·비공개·발행 글을 조회합니다. 쿼리는 `limit`, `cursor`, `type`,
@@ -296,10 +309,23 @@ tenant/site 경로, 크기, 형식을 검증한 뒤 미디어를 등록합니다
 > [콘텐츠 유형 (Collections)](./collections.md).
 
 `pattern_slots` = 공통 블록 자리별 블록 key(자리 key → `GET /patterns` 의 `key` 또는
-`null`). 어드민 배치 규칙을 서버가 이 글의 `collection_key`에 맞춰 계산한 결과이며,
+`null`). 어드민 배치 규칙을 서버가 이 글의 `model_key`(콘텐츠 모델)에 맞춰 계산한 결과이며,
 선언된 자리(현재 `post_footer` = 글 하단)는 항상 키로 존재합니다. 글 상세·미리보기
 응답에도 같은 필드가 붙습니다 → 아래 `GET /v1/cms/public/patterns` 참고.
 
+`related_posts` = 편집자가 어드민 "관련 콘텐츠"에서 고른 글(유형 무관), 고른 순서, **발행 글만**.
+각 항목은 `{ id, title, slug, path, type, model_key, collection_key, excerpt, featured_media_url,
+published_at }` 로 카드 하나를 그릴 만큼만 담습니다. 목록·상세·미리보기 응답에 모두 붙습니다
+(구 서버는 미포함 → 빈 배열로 취급). 비어 있으면 사이트가 "같은 카테고리 최신 글" 같은
+자동 추천을 채우면 됩니다 — `@roottale/cms-renderer-next` 의 `RootTaleBlogPost` 는 편집자 선택이
+있으면 그것을, 없으면 `relatedPostsCount` 만큼 자동 추천을 그립니다.
+
+```json
+{ "related_posts": [ { "id": "…", "title": "…", "slug": "…", "path": "/faq/headache/migraine/…",
+                       "type": "post", "model_key": "faq", "collection_key": "faq",
+                       "excerpt": "…", "featured_media_url": null, "published_at": "…" } ] }
+```
+
 `author_profile_id`는 사이트 공통 공개 작성자 ID입니다. 이름·사진·소개·작가 주소는
 같은 원장의 `author_name`·`author_image_url`·`author_bio`·`author_slug`로
 제공됩니다. 기존 `author_id`는 하위 호환용이므로 새 연동에서는 공개 작성자

package/docs/blog.md

@@ -136,6 +136,10 @@ export default async function PostPage({
 카테고리가 있으면 H1 위에 링크로 표시됩니다. 메타 줄에는 발행일이 명시되고,
 수정일의 달력 날짜가 발행일과 다를 때만 수정일을 따로 표시합니다.
 
+편집자가 어드민 "관련 콘텐츠"에서 글을 골라 두면(유형 무관, 최대 10개) `RootTaleBlogPost` 는
+`relatedPostsCount` 와 무관하게 **그 글들을 고른 순서대로** 글 하단에 그립니다(발행 글만, 저장된
+공개 주소로 링크). 고른 것이 없을 때만 아래 자동 추천이 동작합니다.
+
 `relatedPostsCount`(기본 0=off)를 주면 글 하단에 **같은 카테고리 최근 글**을 N개
 `<nav class="rt-cms-related">` 로 노출합니다(현재 글 제외, 발행일 내림차순).
 제목은 `relatedPostsTitle`(기본 "관련 글"), 링크는 목록과 동일하게 `postHref`

package/docs/revalidation-webhooks.md

@@ -117,15 +117,17 @@ const menu = await fetchMenu({ apiKey, slug: "primary", tags: [MENUS_CACHE_TAG]
 > 어드민에도 오류가 안 뜨기 때문에, 이 누락은 "가끔 늦게 반영된다"로만 보입니다.
 > 응답 본문의 `revalidated.requestedTags`가 빈 배열이면 주입이 빠진 것입니다.
 
-## 2. 어드민에 웹훅 URL 등록
+## 2. 어드민에서 알림 보낼 주소 확인
 
-1. 어드민 **내 사이트 > (사이트 선택)** 페이지로 이동
-2. "글 발행 후 사이트 자동 갱신" 카드에서:
-   - **자동 갱신 URL**: `https://<사이트 도메인>/api/revalidate`
-   - **활성화** 체크
-3. 저장 — ES256 키페어가 자동 발급됩니다 (고객 측 보관 항목 없음)
+웹훅 주소는 따로 적지 않습니다. 어드민 **설정 > 사이트 정보**의 **공개 도메인**과
+**스테이징 주소**에서 `https://<도메인>/api/revalidate` 가 자동으로 정해지고, 사이트를
+만들거나 도메인을 바꾸면 알림 주소도 같이 따라갑니다(스테이징 주소를 지우면 그 목적지도
+사라집니다). 켜고 끄기는 **설정 > 발행 알림 기록(Webhook)** 또는 **내 사이트 > (사이트
+선택)** 의 "글 발행 후 사이트 자동 갱신" 카드에서 운영·스테이징 스위치로 합니다.
+처음 켤 때 ES256 키페어가 자동 발급됩니다(고객 측 보관 항목 없음).
 
-URL을 비우고 저장하면 웹훅이 비활성화됩니다.
+`/api/revalidate` 가 아닌 경로나 임시 미리보기 배포처럼 규칙 밖 주소가 필요하면 같은
+카드의 **다른 주소 추가**로 직접 등록할 수 있습니다.
 
 ### 주소는 "실제로 서비스되는 주소" 여야 합니다
 
@@ -134,10 +136,11 @@ URL을 비우고 저장하면 웹훅이 비활성화됩니다.
 그대로 실패합니다 — 화면에는 아무 오류가 안 뜨고, 발행한 글만 조용히 늦게
 반영됩니다.
 
-- 사이트 도메인을 바꿨다면 **이 URL도 같이 바꾸세요**. 옛 주소가 새 주소로
-  넘어가도록 해 뒀더라도 웹훅에는 소용이 없습니다.
-- `example.com` 이 `www.example.com` 으로 넘어가는 구성이라면 **넘어간 뒤의
-  주소**(`https://www.example.com/api/revalidate`)를 등록하세요.
+- 사이트 도메인을 바꿨다면 **사이트 정보의 공개 도메인을 실제 주소로 고치세요** —
+  알림 주소는 거기서 자동으로 따라갑니다. 옛 주소가 새 주소로 넘어가도록 해 뒀더라도
+  웹훅에는 소용이 없습니다.
+- `example.com` 이 `www.example.com` 으로 넘어가는 구성이라면 공개 도메인을 **넘어간
+  뒤의 주소**(`www.example.com`)로 두세요.
 
 ### Cloudflare를 쓴다면 SSL 모드가 Flexible이면 안 됩니다
 
@@ -206,6 +209,9 @@ curl -sI -X POST https://<사이트 도메인>/api/revalidate
   `{유형 주소}/categories/{카테고리}`
 - **유형을 옮긴 글**은 옮기기 전·후 주소가 함께 옵니다 — 옮기기 전 목록에서도
   글이 빠져야 하기 때문입니다
+- **주소가 바뀐 글**(slug 변경·카테고리 이동 등으로 상세 주소가 옮겨진 글)은 **옛 상세
+  주소도 함께** 옵니다 — 옛 주소의 캐시가 비워져 바로 새 주소로 이동하고, 옛 주소를
+  참조하던 페이지도 같이 갱신할 수 있게 하기 위해서입니다
 
 주소가 안 나오는 경우도 있습니다.
 
@@ -319,8 +325,8 @@ Content-Type: application/json
 
 | 증상 | 확인 |
 |---|---|
-| 발행해도 사이트 미반영 | 어드민의 자동 갱신 URL·활성화 체크, 배포 도메인 일치 여부 |
-| 전송 기록이 `308`·`301` | 등록한 주소가 다른 주소로 넘어가고 있습니다. 넘어간 뒤의 주소를 등록하세요. 이동 주소가 요청 주소와 같으면 Cloudflare SSL 모드가 Flexible입니다(위 §2 참고) |
+| 발행해도 사이트 미반영 | 어드민 발행 알림 화면의 운영·스테이징 스위치가 켜져 있는지, 사이트 정보의 도메인이 실제 배포 도메인과 같은지 |
+| 전송 기록이 `308`·`301` | 알림 주소가 다른 주소로 넘어가고 있습니다. 사이트 정보의 공개 도메인을 넘어간 뒤의 주소로 고치세요. 이동 주소가 요청 주소와 같으면 Cloudflare SSL 모드가 Flexible입니다(위 §2 참고) |
 | 401 `invalid_signature` | `ROOTTALE_API_KEY`가 해당 사이트 스코프 키인지 |
 | 401 `timestamp_out_of_window` | 서버 시계 동기화 (NTP) |
 | 일부 페이지만 갱신 | `alsoRevalidate`·동적 경로 콜백 누락 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roottale/cms-mcp",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "type": "module",
   "description": "RootTale CMS MCP server and CLI for models, entries, exposures, media, integration docs, and public API access.",
   "bin": {