@roottale/cms-mcp 0.35.0 → 0.36.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @roottale/cms-mcp
 
+## 0.36.0
+
+### Patch Changes
+
+- 1fe867f: 문서 갱신 — 블로그 설정 응답의 글 하단 CTA(`post_cta`)와 사이트 SEO 기본값
+  (`site_profile`: 설명·로고·파비콘·기본 OG)을 api-reference / blog 가이드에 반영.
+  CTA 는 `RootTaleBlogPost` 가 본문 끝에 자동 렌더하고, `site_profile` 은 외부
+  사이트가 head + OG 폴백으로 사용한다.
+
 ## 0.35.0
 
 ### Minor Changes

package/dist/index.js

@@ -279,7 +279,7 @@ function registerTools(server2) {
 }
 
 // src/server.ts
-var VERSION = true ? "0.35.0" : "dev";
+var VERSION = true ? "0.36.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\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

@@ -113,16 +113,29 @@ fallback 네비를 렌더하세요 (`menus.md` 참고).
 
 ## GET /v1/cms/public/blog-settings
 
-블로그 표시 설정 (TOC·작성자·발행일·작성자 카드, 저자 프로필).
+블로그 표시 설정 (TOC·작성자·발행일·작성자 카드, 저자 프로필, 글 하단 CTA).
+`post_cta` 는 admin 에서 활성화하고 버튼 문구·링크를 채웠을 때만 객체이며,
+그 외에는 `null`. `RootTaleBlogPost` 가 본문 끝에 자동으로 렌더하므로 별도
+연동 코드는 필요 없다.
 
 ```json
 { "show_table_of_contents": false, "show_author": true, "show_date": true,
   "show_author_card": true, "toc_title": null,
   "author_profile_name": null, "author_profile_bio": null,
   "author_profile_image_url": null, "author_profile_image_radius": "circle",
+  "site_profile": { "site_description": null, "logo_url": null,
+    "favicon_url": null, "default_og_image_url": null },
+  "post_cta": { "title": "상담이 필요하신가요?", "description": "첫 상담은 무료입니다.",
+    "button_label": "상담 문의하기", "button_href": "/contact" },
   "updated_at": null }
 ```
 
+`site_profile` 은 사이트 공통 SEO 값. `default_og_image_url`(1200×630 권장)은
+글에 대표/OG 이미지가 없을 때 SNS 공유 썸네일 폴백으로 쓰세요 —
+`generateMetadata` 에서 `post.seo?.ogImage ?? post.featured_media_url ??
+settings.siteProfile.defaultOgImageUrl` 순으로 우선합니다. `logo_url`·
+`favicon_url`·`site_description` 은 사이트 `<head>` 에 적용합니다.
+
 ## GET /v1/cms/public/site-knowledge
 
 사이트 지식 — 브랜드 보이스(어조·톤·화자) + 용어 규칙(금지어·교정어). AI

package/docs/blog.md

@@ -38,6 +38,22 @@ export default function BlogPage() {
 }
 ```
 
+> **공지·블로그를 나눈 사이트(ADR-0060)는 목록을 반드시 섹션으로 스코프하세요.**
+> `RootTaleBlogList` 는 기본적으로 **모든 글**을 렌더하므로, 섹션을 나눴는데
+> `collection` 을 안 주면 공지 글이 `/blog` 목록에 섞여 나옵니다. 각 목록 페이지에서
+> `collection`+`collections` 를 넘겨 그 섹션 글만 보이게 하세요(글 링크도 소속 섹션
+> basePath 로 자동 라우팅). 단일 블로그 사이트는 지금처럼 안 줘도 됩니다.
+>
+> ```tsx
+> import { COLLECTIONS } from "@/lib/collections"; // collections.md 참고
+> // app/notice/page.tsx
+> <RootTaleBlogList apiKey={apiKey} collection="notice" collections={COLLECTIONS} />
+> // app/blog/page.tsx
+> <RootTaleBlogList apiKey={apiKey} collection="blog" collections={COLLECTIONS} showCategoryFilter />
+> ```
+>
+> 자세한 내용은 `collections.md` 참고.
+
 ### 상세 페이지
 
 ```tsx
@@ -65,7 +81,9 @@ export default async function PostPage({
 ```
 
 목차(ToC)·작성자 카드·발행일 표시는 어드민의 블로그 표시 설정으로도 제어됩니다
-(`theme-and-settings.md` 참고).
+(`theme-and-settings.md` 참고). 어드민 설정 > 블로그에서 **글 하단 CTA**(제목·설명·
+버튼)를 켜면 `RootTaleBlogPost` 가 모든 글 본문 끝에 같은 CTA 블록을 자동으로
+렌더합니다 — 별도 연동 코드는 필요 없습니다.
 
 #### 목차 블록 (본문 임의 위치)
 
@@ -147,6 +165,7 @@ export async function getPost(slug: string) {
 ```tsx
 // app/blog/[slug]/page.tsx (커스텀 UI 버전)
 import type { Metadata } from "next";
+import { buildPostMetadata } from "@roottale/cms-renderer-next/routes";
 import { getAllPosts, getPost } from "@/lib/blog";
 
 export async function generateStaticParams() {
@@ -162,18 +181,27 @@ export async function generateMetadata({
   const { slug } = await params;
   const post = await getPost(slug);
   if (!post) return {};
-  // 어드민 글 에디터의 SEO 패널 값(metaJson.seo)을 우선 적용
-  const seo = (post.metaJson as { seo?: Record<string, string | boolean> })?.seo;
-  return {
-    title: (seo?.title as string) || post.title,
-    description: (seo?.description as string) || post.excerpt,
-    ...(seo?.noindex || seo?.nofollow
-      ? { robots: { index: !seo?.noindex, follow: !seo?.nofollow } }
-      : {}),
-  };
+  // 어드민 글 에디터의 SEO 패널(metaJson.seo) override 적용 + self-canonical.
+  // canonical/robots/openGraph 분기를 직접 안 써도 한 곳도 빠뜨리지 않습니다.
+  return buildPostMetadata(post, {
+    siteUrl: process.env.NEXT_PUBLIC_SITE_URL,
+    path: `/blog/${post.slug}`,
+  });
 }
 ```
 
+`buildPostMetadata(post, opts)`는 어드민 SEO 패널 값을 Next `Metadata`로
+한 줄 변환합니다:
+
+- `seo.title`/`seo.description`/`seo.ogImage` 가 있으면 우선, 없으면 글 값으로 fallback
+- `seo.canonical` override → 없으면 `siteUrl`+`path` 로 self-canonical 자동 생성
+- `seo.noindex`/`seo.nofollow` 중 하나라도 켜지면 `robots` 출력
+- `openGraph`(article·publishedTime·images) 자동 구성
+
+입력은 `{ title, description?, date?, image?, seo? }` 형태면 되고
+(`getPost` 의 `BlogPostMeta` 가 그대로 호환), 원본 post 를 쓸 땐
+`seo: (post.metaJson as { seo?: ... }).seo` 로 넘기세요.
+
 SEO 오버라이드 필드: `title`, `description`, `canonical`, `ogImage`,
 `noindex`, `nofollow`.
 

package/docs/collections.md

@@ -152,6 +152,47 @@ export const GET = createFeedRoute({ apiKey, siteUrl, title, collections: getCol
 응답은 `RouteCollection`과 구조 호환이라 그대로 넘길 수 있습니다. 매 요청 fetch를 피하려면
 사이트 경계에서 캐시하세요(예: Next `fetch(url, { next: { revalidate: 300 } })`).
 
+### 섹션 목록 페이지 (공지/블로그 분리 렌더)
+
+각 섹션 목록은 `RootTaleBlogList` 에 **`collection`+`collections`** 를 넘겨 그 섹션
+글만 보이게 합니다. **이걸 안 주면 컴포넌트가 전체 글을 렌더**하므로 공지 글이
+`/blog` 목록에 섞여 들어옵니다(섹션을 나눈 사이트의 가장 흔한 버그). `collections`
+를 주면 글 링크도 소속 섹션 basePath 로 자동 라우팅됩니다(공지→`/notice/{slug}`).
+
+```tsx
+import { RootTaleBlogList } from "@roottale/cms-renderer-next/server";
+import { COLLECTIONS } from "@/lib/collections"; // 위 "방식 A" 의 상수
+
+// app/notice/page.tsx — 공지 게시판
+export default function NoticePage() {
+  return (
+    <RootTaleBlogList
+      apiKey={process.env.ROOTTALE_API_KEY!}
+      collection="notice"
+      collections={COLLECTIONS}
+    />
+  );
+}
+
+// app/blog/page.tsx — 블로그
+export default function BlogPage() {
+  return (
+    <RootTaleBlogList
+      apiKey={process.env.ROOTTALE_API_KEY!}
+      collection="blog"
+      collections={COLLECTIONS}
+      showCategoryFilter
+    />
+  );
+}
+```
+
+`RootTaleBlogCategories` 도 같은 `collection`+`collections` 를 받아 그 섹션의 주제만
+집계합니다. 카테고리 칩/사이드바를 섹션별로 나눌 때 쓰세요.
+
+> 동적 basePath(어드민에서 자유 편집)나 catch-all 라우트를 쓰면 `collection` 값을
+> 요청 경로에서 판정해 넘기세요(아래 "동적 basePath" 참고).
+
 ### 상세 페이지 가드 (섹션 누출 차단)
 
 상세 라우트는 글이 그 섹션 소속인지 확인해 다른 섹션 글이 새는 것을 막습니다.
@@ -165,6 +206,23 @@ const post = await getPost(slug);
 if (!post || resolvePostCollection(post, COLLECTIONS)?.key !== "blog") notFound();
 ```
 
+### 상세 페이지 메타데이터 (canonical 공지/블로그 구분)
+
+상세 라우트의 `generateMetadata` 도 `collections` 를 넘겨야 canonical 이 글의
+섹션에 맞게 나옵니다. `path` 를 `/blog/...` 로 하드코딩하면 공지 글이 잘못된
+블로그 canonical 을 갖게 됩니다.
+
+```ts
+import { buildPostMetadata } from "@roottale/cms-renderer-next/routes";
+// app/blog/[slug]/page.tsx (공지면 app/notice/[slug])
+return buildPostMetadata(post, {
+  siteUrl: process.env.NEXT_PUBLIC_SITE_URL,
+  collections: COLLECTIONS, // 글의 collectionKey 로 /notice·/blog canonical 자동 해석
+});
+```
+
+자세한 동작은 `seo.md` 의 "글 메타데이터 → 공지·블로그 다중 스트림" 참고.
+
 ### revalidate
 
 ```ts

package/docs/seo.md

@@ -114,6 +114,68 @@ const crumbs = breadcrumbSchema([
 발행 웹훅의 `alsoRevalidate`에 `/feed.xml`, `/sitemap.xml`을 포함해 글 변경
 시 함께 갱신하세요 (`revalidation-webhooks.md` 참고).
 
+## 글 메타데이터 (canonical·robots·OG)
+
+블로그 글 상세의 `generateMetadata` 에서 어드민 SEO 패널(`metaJson.seo`) 값을
+`buildPostMetadata` 로 한 줄 변환합니다. canonical/robots/openGraph 분기를
+직접 쓰면 한 곳이라도 빠뜨려 SEO 가 새기 쉬운데(특히 noindex 누락·canonical
+미설정), 이 헬퍼로 표준화합니다.
+
+```tsx
+// app/blog/[slug]/page.tsx
+import type { Metadata } from "next";
+import { buildPostMetadata } from "@roottale/cms-renderer-next/routes";
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { slug } = await params;
+  const post = await getPost(slug);
+  if (!post) return {};
+  return buildPostMetadata(post, {
+    siteUrl: process.env.NEXT_PUBLIC_SITE_URL, // self-canonical 기본값 origin
+    path: `/blog/${post.slug}`, // 현재 slug 기준
+  });
+}
+```
+
+- `seo.title`/`seo.description`/`seo.ogImage` override → 없으면 글 값 fallback
+- canonical: `seo.canonical` override → 없으면 `siteUrl`+`path` 로 **self-canonical
+  자동 생성**(모든 글이 자기 자신을 가리키는 canonical 을 갖도록 — 권장).
+  `siteUrl`/`path` 를 안 넘기면 override 가 있을 때만 canonical 출력.
+- `seo.noindex`/`seo.nofollow` 중 하나라도 켜지면 `robots` 출력
+- `openGraph`(type:`article`·`publishedTime`·`images`) 자동 구성
+
+입력은 `{ title, description?, date?, image?, seo? }` 구조면 됩니다(`getPost`
+의 `BlogPostMeta` 호환). 원본 post 를 쓸 땐 `seo: (post.metaJson as {
+seo?: PostSeoOverrides }).seo` 로 넘기세요. `path` 는 redirect 후의 **현재
+slug**(`post.slug`) 기준으로 주세요(아래 301 참고).
+
+### 공지·블로그 다중 스트림 (ADR-0060)
+
+섹션을 나눈 사이트(공지 `/notice` + 블로그 `/blog`)는 `path` 를 직접 쓰지 말고
+**`collections` 를 넘기세요.** 글의 `collectionKey` 로 소속 섹션 basePath 를 찾아
+canonical 을 **공지/블로그로 구분**해 해석합니다(공지 글 → `/notice/{slug}`, 블로그
+글 → `/blog/{slug}`). `path` 를 `/blog/...` 로 하드코딩하면 공지 글이 잘못된
+블로그 canonical 을 갖게 됩니다.
+
+```tsx
+import { buildPostMetadata } from "@roottale/cms-renderer-next/routes";
+import { COLLECTIONS } from "@/lib/collections"; // collections.md 참고
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { slug } = await params;
+  const post = await getPost(slug);
+  if (!post) return {};
+  return buildPostMetadata(post, {
+    siteUrl: process.env.NEXT_PUBLIC_SITE_URL,
+    collections: COLLECTIONS, // collectionKey 로 /notice·/blog 자동 구분
+  });
+}
+```
+
+`post.collectionKey`(공개 API의 `collection_key`)가 어느 섹션에도 안 맞으면
+canonical 을 생략합니다(섹션 없는 글은 상세·sitemap에서 제외되는 규칙과 동일).
+단일 블로그 사이트는 기존처럼 `path: "/blog/" + post.slug` 만 주면 됩니다.
+
 ## slug 변경 시 301 리다이렉트
 
 글 slug를 바꿔도 옛 URL이 깨지지 않습니다. API가 slug history로 글을 찾아

package/examples/nextjs/app/blog/[slug]/page.tsx

@@ -4,7 +4,10 @@
 import type { Metadata } from "next";
 import { notFound, permanentRedirect } from "next/navigation";
 import { RootTaleBlogPost } from "@roottale/cms-renderer-next/server";
-import { postRedirectPath } from "@roottale/cms-renderer-next/routes";
+import {
+  buildPostMetadata,
+  postRedirectPath,
+} from "@roottale/cms-renderer-next/routes";
 
 import { getAllPosts, getPost } from "@/lib/blog";
 
@@ -21,24 +24,11 @@ export async function generateMetadata({ params }: Props): Promise<Metadata> {
   const { slug } = await params;
   const post = await getPost(slug);
   if (!post) return {};
-  const seo = post.seo;
-  const title = seo?.title || post.title;
-  const description = seo?.description || post.description;
-  return {
-    title,
-    description,
-    ...(seo?.canonical ? { alternates: { canonical: seo.canonical } } : {}),
-    ...(seo?.noindex || seo?.nofollow
-      ? { robots: { index: !seo?.noindex, follow: !seo?.nofollow } }
-      : {}),
-    openGraph: {
-      type: "article",
-      title,
-      description,
-      publishedTime: post.date,
-      ...(post.image ? { images: [{ url: seo?.ogImage || post.image, alt: title }] } : {}),
-    },
-  };
+  // 어드민 SEO 패널(metaJson.seo) override + self-canonical 을 1줄로.
+  return buildPostMetadata(post, {
+    siteUrl: process.env.NEXT_PUBLIC_SITE_URL,
+    path: `/blog/${post.slug}`,
+  });
 }
 
 export default async function PostPage({ params }: Props) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roottale/cms-mcp",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "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": {