@roottale/cms-mcp 0.46.0 → 0.48.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @roottale/cms-mcp
 
+## 0.48.0
+
+### Patch Changes
+
+- a4c7070: 문서 갱신 — `blog.md`/`seo.md`에 `author_slug` 가산, 저자 링크·브레드크럼
+  (avcd 구조), 카테고리 허브 라우트(`/blog/categories/{slug}`) 필수화 안내,
+  avcd 확장 메타데이터(RSS alternate·Twitter Card·og article 확장)를 반영.
+  예시 코드에 브레드크럼·BlogPosting·카테고리 허브 라우트 사용법 추가.
+
 ## 0.46.0
 
 ### Minor Changes

package/dist/index.js

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

@@ -332,7 +332,8 @@ settings.siteProfile.defaultOgImageUrl` 순으로 우선합니다. `logo_url`·
 | `lead_kind` | | `patient`(기본) \| `sales` |
 | `_redirect_url` | | 완료 후 redirect base (allowlist 검증) |
 | `cf-turnstile-response` | | Cloudflare Turnstile 토큰. tenant-api에 `LEAD_INTAKE_TURNSTILE_SECRET_KEY`가 설정된 경우 필수 |
-| `attr_landing_path`, `attr_rt_src`, `attr_utm_source`, `attr_utm_medium`, `attr_utm_campaign`, `attr_referrer`, `attr_first_touch_at` | | 유입 어트리뷰션 — CRM에 유입 경로 표시 (`inquiries.md` 참고). 그 외 `attr_*` 키는 무시 |
+| `attr_landing_path`, `attr_rt_src`, `attr_utm_source`, `attr_utm_medium`, `attr_utm_campaign`, `attr_utm_term`, `attr_utm_content`, `attr_ad_click`, `attr_referrer`, `attr_first_touch_at`, `attr_last_touch_at`, `attr_last_touch_channel`, `attr_last_touch_source`, `attr_last_touch_medium`, `attr_last_touch_campaign`, `attr_last_touch_referrer` | | 유입 어트리뷰션 — CRM에 유입 경로 표시 (`inquiries.md` 참고). 그 외 `attr_*` 키는 무시 |
+| `attr_journey` | | 방문 여정 JSON 원문(서버 zod 검증, 최대 30항목) — CRM "방문 여정" 패널에 표시 (`inquiries.md` 참고) |
 | 기타 임의 필드 | | 최대 50개, 암호화 보관, CRM 상세 노출 |
 
 응답: `302` redirect — 성공 `?ok=1`, 실패 `?err=<code>`

package/docs/blog.md

@@ -38,6 +38,15 @@ export default function BlogPage() {
 }
 ```
 
+> **카테고리 허브 라우트(`/blog/categories/{slug}`)를 구현하세요.**
+> `showCategoryFilter` 의 카테고리 칩, `RootTaleBlogCategories`, `RootTaleBlogPost`
+> 의 `breadcrumb` 카테고리 세그먼트가 모두 기본적으로 이 경로를 링크합니다
+> (`defaultCategoryHref`). **단일 블로그 사이트도 예외가 아닙니다** — 이 라우트가
+> 없으면 카테고리 칩·브레드크럼을 클릭했을 때 404 가 됩니다. 공지·블로그처럼
+> 섹션을 나눈 사이트는 `{basePath}/categories/{slug}` 패턴(`collections.md`
+> "URL이 어떻게 정해지나" 절)을 대신 씁니다. 참조 구현은 예시 코드
+> `app/blog/categories/[slug]/page.tsx`(MCP tool `readRootTaleNextjsExampleCode`).
+
 > **공지·블로그를 나눈 사이트(ADR-0060)는 목록을 반드시 섹션으로 스코프하세요.**
 > `RootTaleBlogList` 는 기본적으로 **모든 글**을 렌더하므로, 섹션을 나눴는데
 > `collection` 을 안 주면 공지 글이 `/blog` 목록에 섞여 나옵니다. 각 목록 페이지에서
@@ -134,6 +143,46 @@ export default async function PostPage({
 경우 `@roottale/cms-core` 의 `extractFaqEntries(doc)` / `faqPageJsonLd(entries)`
 로 동일한 JSON-LD 를 생성할 수 있습니다.
 
+#### 저자 링크 + 브레드크럼 (avcd 구조)
+
+발행 글에 `author_slug`(작가 아카이브 slug)가 있으면 `RootTaleBlogPost` 가
+헤더 메타·저자 카드의 작성자 이름을 자동으로 `<a href="/blog/author/{slug}">`
+로 감쌉니다. slug 가 없는 작가는 지금처럼 plain text 로 렌더됩니다. 링크
+대상을 바꾸려면 `authorHref`:
+
+```tsx
+<RootTaleBlogPost
+  apiKey={apiKey}
+  slugOrId={slug}
+  authorHref={(slug) => `/authors/${slug}`} // 기본 /blog/author/{slug}
+/>
+```
+
+`breadcrumb` prop(opt-in, 기본 off)을 주면 시각 브레드크럼(홈 › 블로그 ›
+카테고리 › 글 제목)을 본문 위에 렌더하고, `siteUrl` 을 함께 주면
+`BreadcrumbList` JSON-LD 도 같이 emit합니다:
+
+```tsx
+<RootTaleBlogPost
+  apiKey={apiKey}
+  slugOrId={slug}
+  breadcrumb={{ siteUrl: process.env.NEXT_PUBLIC_SITE_URL }}
+  // collections 를 함께 주면 "블로그" 세그먼트가 글의 소속 섹션 basePath로
+  // 자동 해석됩니다(공지 글 → /notice). showCategory:false 로 카테고리
+  // 세그먼트 생략 가능, categoryHref로 링크 override 가능.
+/>
+```
+
+마지막 항목(카테고리 링크, `showCategory` 기본 `true`)은 `defaultCategoryHref`
+(`/blog/categories/{slug}`)를 씁니다 — **이 라우트를 구현해야 브레드크럼·
+카테고리 칩 클릭이 404 가 나지 않습니다**(아래 "카테고리 허브 라우트" 참고).
+
+> **마크업 변경 주의** — 헤더 발행일이 `<span data-rt-cms-meta="date">` 에서
+> `<time dateTime="…" data-rt-cms-meta="date">` 로 바뀌었습니다. `class`·
+> `data-rt-cms-meta` 속성은 그대로라 속성 선택자로 스타일링했다면 영향 없지만,
+> 태그명(`span`)을 직접 선택자로 쓴 고객 CSS/스크립트가 있다면 `time` 으로
+> 갱신하세요.
+
 ### 다국어 (ADR-0052 A안, W4-6 PR C1/C2)
 
 번역 사이트(어드민에서 "번역 추가"로 언어판을 만든 글)는 `RootTaleBlogList`/
@@ -229,6 +278,7 @@ export async function getPost(slug: string) {
 | `terms` | 분류 용어 배열 (`taxonomy: "category" \| "tag"`, `name`, `slug`) |
 | `featuredImageUrl` | 대표 이미지 |
 | `authorName` | 작성자 표시명 |
+| `authorSlug` | 작가 아카이브 slug(`/blog/author/{slug}`) — 미발급 작가는 `null` |
 | `metaJson` | 부가 메타 — `metaJson.seo`에 SEO 오버라이드 |
 
 ### 정적 경로 사전 생성 + 메타데이터

package/docs/inquiries.md

@@ -85,9 +85,12 @@ export async function submitContact(
 | `leadKind` | | `patient`(기본) \| `sales` |
 | `turnstileToken` | | Cloudflare Turnstile 토큰. tenant-api secret 검증을 켠 경우 전달 |
 | `extras` | | 임의 추가 항목 (최대 50개, 암호화 보관, CRM 상세에 노출) |
-| `attribution` | | 유입 first-touch — 아래 [유입 어트리뷰션](#유입-어트리뷰션-attribution) 참고 |
+| `attribution` | | 유입 first-touch/last-touch — 아래 [유입 어트리뷰션](#유입-어트리뷰션-attribution) 참고 |
+| `journey` | | 방문 여정 JSON 원문 — 아래 [방문 여정](#방문-여정-journey) 참고 |
 
 `extras`에 개인정보가 담길 수 있으므로 폼의 동의 고지에 수집 항목을 반영하세요.
+`journey`를 함께 보낼 때는 개인정보 수집·이용 동의 문구에 "사이트 이용 기록
+(방문 페이지·상호작용)"을 추가하세요.
 
 ## 유입 어트리뷰션 (`attribution`)
 
@@ -134,12 +137,33 @@ const result = await submitInquiry({
 | `landing_path` | 첫 방문 landing pathname |
 | `rt_src` | 단축링크/QR 토큰 (`roottale.link` 경유 시) |
 | `utm_source` / `utm_medium` / `utm_campaign` | UTM 파라미터 |
+| `utm_term` / `utm_content` | UTM 파라미터(세부) |
+| `ad_click` | 광고 클릭 유입 존재 플래그(boolean, true일 때만 존재) — gclid/fbclid 원값은 저장하지 않습니다 |
 | `referrer` | 외부 referrer **호스트명** (raw URL 아님) |
 | `first_touch_at` | first-touch 시각 (ISO 8601) |
+| `last_touch_at` | 가장 최근 non-direct 방문 시각(ISO 8601) — first-touch와 별개로 갱신 |
+| `last_touch_channel` | last-touch를 유발한 채널 — `rs`(단축링크/QR) \| `utm` \| `gcl` \| `rf` |
+| `last_touch_source` / `last_touch_medium` / `last_touch_campaign` / `last_touch_referrer` | last-touch 시점의 UTM/referrer |
 
 직접 HTTP 연동 시에는 같은 값을 `attr_landing_path`, `attr_rt_src`,
-`attr_utm_source`, `attr_utm_medium`, `attr_utm_campaign`, `attr_referrer`,
-`attr_first_touch_at` 폼 필드로 보내면 됩니다.
+`attr_utm_source`, `attr_utm_medium`, `attr_utm_campaign`, `attr_utm_term`,
+`attr_utm_content`, `attr_ad_click`, `attr_referrer`, `attr_first_touch_at`,
+`attr_last_touch_at`, `attr_last_touch_channel`, `attr_last_touch_source`,
+`attr_last_touch_medium`, `attr_last_touch_campaign`,
+`attr_last_touch_referrer` 폼 필드로 보내면 됩니다.
+
+## 방문 여정 (`journey`)
+
+문의 제출 직전까지의 방문 경로(페이지 이동·주요 전환 이벤트)를 CRM 상세의
+"방문 여정" 패널에서 시간순으로 확인할 수 있습니다.
+`@roottale/analytics-runtime`의 `readJourney()`로 읽은 sessionStorage 링버퍼를
+`JSON.stringify`한 문자열을 그대로 `journey` 필드(직접 HTTP는 `attr_journey`
+폼 필드)로 보내면 됩니다 — 파싱·검증은 서버가 담당합니다.
+
+의료(`medical`)·법률(`legal`) 업종 문의는 서버가 자동으로 "마일스톤
+모드"(이벤트 유형·시각만, 방문 페이지 정보 제거)로 강제 전환합니다 —
+증상·질환 관심사가 노출되지 않도록 하는 안전장치이므로 별도 설정이 필요
+없습니다.
 
 ## 에러 처리
 

package/docs/seo.md

@@ -73,12 +73,14 @@ export default sitemap;
 작가 사이트맵(`/sitemap/authors.xml`)을 만들 수 있습니다. 어드민 **설정 > 블로그 >
 사이트맵**에서 "작가 사이트맵"을 켜면 인덱스에 `authors` 섹션이 추가됩니다.
 
-```ts
+```tsx
 // app/blog/author/[slug]/page.tsx
 import { notFound } from "next/navigation";
-import { fetchAuthors } from "@roottale/cms-client/server";
+import { fetchAuthors, profilePageSchema } from "@roottale/cms-client/server";
 import { RootTaleBlogList } from "@roottale/cms-renderer-next/server";
 
+const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL!;
+
 export default async function AuthorArchive({
   params,
 }: {
@@ -89,8 +91,19 @@ export default async function AuthorArchive({
   const author = authors.find((a) => a.slug === slug);
   if (!author) notFound();
 
+  const jsonLd = profilePageSchema({
+    url: `${SITE_URL}/blog/author/${slug}`,
+    name: author.name,
+    image: author.imageUrl,
+    description: author.bio,
+  });
+
   return (
     <>
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
+      />
       <h1>{author.name}</h1>
       {author.bio ? <p>{author.bio}</p> : null}
       {/* author= 로 그 작가의 발행 글만 렌더 */}
@@ -104,6 +117,31 @@ export default async function AuthorArchive({
   (`GET /v1/cms/public/authors`).
 - `RootTaleBlogList`에 `author={slug}` 를 주면 그 작가의 글만 가져옵니다
   (`GET /v1/cms/public/posts?author={slug}`).
+- 글 상세의 `articleSchema` 에 `authorUrl: ${SITE_URL}/blog/author/${post.authorSlug}`
+  를 넘기면 글의 author 엔티티가 이 작가 페이지의 `ProfilePage.mainEntity`
+  와 같은 `@id`(`{authorUrl}#person`)로 연결됩니다.
+
+### 카테고리 허브 (`/blog/categories/{slug}`)
+
+`RootTaleBlogList`의 카테고리 칩, `RootTaleBlogCategories`, `RootTaleBlogPost`
+의 `breadcrumb` 카테고리 세그먼트가 모두 기본적으로 `/blog/categories/{slug}`
+를 링크합니다(`defaultCategoryHref`) — **단일 블로그 사이트도 이 라우트를
+구현해야** 링크가 404 나지 않습니다. 참조 구현은 예시 코드
+`app/blog/categories/[slug]/page.tsx`(MCP tool `readRootTaleNextjsExampleCode`).
+공지·블로그처럼 섹션을 나눈 사이트는 `{basePath}/categories/{slug}` 패턴
+(`collections.md` "URL이 어떻게 정해지나" 절)을 대신 씁니다.
+
+목록 페이지용 JSON-LD는 `collectionPageSchema`:
+
+```tsx
+import { collectionPageSchema } from "@roottale/cms-client/server";
+
+const jsonLd = collectionPageSchema({
+  url: `${SITE_URL}/blog/categories/${category.slug}`,
+  name: `${category.name} 글 모음`,
+  siteUrl: SITE_URL,
+});
+```
 
 ### 다국어 (hreflang) — ADR-0052 A안, 콘텐츠 다국어
 
@@ -165,8 +203,27 @@ export default function robots(): MetadataRoute.Robots {
 
 ## 브레드크럼 (BreadcrumbList)
 
-사이트 구조를 검색엔진에 전달하고 검색결과에 경로가 표시됩니다. 블로그 글
-상세에서 `breadcrumbSchema` 로 렌더하세요 (UI 브레드크럼과 구조 일치 권장):
+사이트 구조를 검색엔진에 전달하고 검색결과에 경로가 표시됩니다.
+
+**빠른 경로** — `RootTaleBlogPost` 를 쓰면 `breadcrumb` prop 하나로 시각
+브레드크럼 + `BreadcrumbList` JSON-LD 를 함께 얻습니다(opt-in, 기본 off):
+
+```tsx
+<RootTaleBlogPost
+  apiKey={apiKey}
+  slugOrId={slug}
+  breadcrumb={{ siteUrl: SITE_URL }} // siteUrl 없으면 시각 브레드크럼만
+/>
+```
+
+카테고리 세그먼트는 글의 첫 category term 을 자동으로 쓰고
+(`showCategory: false` 로 생략 가능), 링크는 `defaultCategoryHref`
+(`/blog/categories/{slug}`)를 씁니다 — `blog.md` "카테고리 허브 라우트" 참고.
+자세한 옵션(`homeLabel`/`listHref`/`categoryHref`/`collections` 연동)은
+`blog.md` "저자 링크 + 브레드크럼" 절 참고.
+
+**커스텀 경로** — 직접 마크업하는 경우 `breadcrumbSchema` 로 JSON-LD 만
+생성하세요(UI 브레드크럼과 구조 일치 권장):
 
 ```tsx
 import { breadcrumbSchema } from "@roottale/cms-client/server";
@@ -225,6 +282,29 @@ export async function generateMetadata({ params }: Props): Promise<Metadata> {
   `siteUrl`/`path` 를 안 넘기면 override 가 있을 때만 canonical 출력.
 - `seo.noindex`/`seo.nofollow` 중 하나라도 켜지면 `robots` 출력
 - `openGraph`(type:`article`·`publishedTime`·`images`) 자동 구성
+- **avcd 구조** — `siteUrl` 이 있으면 canonical 해석 성공 여부와 무관하게
+  `alternates.types["application/rss+xml"]`(기본 `/feed.xml`, `feedPath`
+  옵션으로 override)을 항상 emit합니다. `twitter`(`summary_large_image`)도
+  og 와 같은 소스(seo override → 글 값)로 항상 채워집니다 — `card`+`title`
+  은 og 이미지가 없어도 emit, `images` 는 og 이미지가 있을 때만.
+- **avcd 구조 — og article 확장** — 입력에 `modified`(→ `openGraph.modifiedTime`)·
+  `section`(→ `openGraph.section`)·`tags`(문자열 배열 → `openGraph.tags`)·
+  `authors`(저자 프로필 URL 배열 → `openGraph.authors`)를 넘기면 그대로
+  추가됩니다. 전부 선택 — 미지정/빈 배열은 생략(기존 호출부 diff 0).
+
+```tsx
+return buildPostMetadata(post, {
+  siteUrl: process.env.NEXT_PUBLIC_SITE_URL,
+  path: `/blog/${post.slug}`,
+  modified: post.modified, // updatedAt ISO
+  section: post.category || undefined,
+  tags: post.tags.map((t) => t.name),
+  authors: post.authorSlug
+    ? [`${SITE_URL}/blog/author/${post.authorSlug}`]
+    : undefined,
+  feedPath: "/feed.xml", // 기본값 — 다중 스트림이면 섹션별 피드로 override
+});
+```
 
 입력은 `{ title, description?, date?, image?, seo? }` 구조면 됩니다(`getPost`
 의 `BlogPostMeta` 호환). 원본 post 를 쓸 땐 `seo: (post.metaJson as {
@@ -372,12 +452,14 @@ const hits = await searchPosts({
 
 | 함수 | 용도 |
 |---|---|
-| `articleSchema(input)` | 블로그 글 상세 페이지 Article |
+| `articleSchema(input)` | 블로그 글 상세 페이지 Article/BlogPosting |
 | `breadcrumbSchema(items)` | 빵부스러기 |
 | `organizationSchema(input)` | 조직/사업체 |
 | `localBusinessSchema(profile, opts)` | 사업장 LocalBusiness (로컬 SEO — 아래 섹션) |
 | `websiteSchema(input)` | 웹사이트 |
 | `faqSchema(items)` | FAQ |
+| `profilePageSchema(input)` | 작가 프로필 페이지 (`/blog/author/{slug}`) |
+| `collectionPageSchema(input)` | 글 목록/카테고리 허브 (`/blog`, `/blog/categories/{slug}`) |
 
 ```tsx
 import { articleSchema } from "@roottale/cms-client/server";
@@ -396,6 +478,29 @@ const jsonLd = articleSchema({
 />;
 ```
 
+**avcd 구조 — 확장 옵션(전부 선택)**:
+
+```tsx
+const jsonLd = articleSchema({
+  type: "BlogPosting", // 기본 "Article" — 미지정 시 기존 출력 그대로
+  id: `${url}#article`, // 지정 시 @id emit
+  headline: post.title,
+  url,
+  image: post.featuredImageUrl ?? undefined,
+  imageWidth: 1200, // 둘 다 있으면 image 를 ImageObject 로 승격
+  imageHeight: 630,
+  authorName: post.authorName,
+  authorUrl: `${SITE_URL}/blog/author/${post.authorSlug}`, // author.@id 연결
+  publisherName: "예시 사이트",
+  publisherId: `${SITE_URL}#organization`,
+  section: category?.name, // → articleSection
+  inLanguage: "ko",
+});
+```
+
+`profilePageSchema`/`collectionPageSchema` 사용법은 각각 위 "작가 아카이브"·
+"카테고리 허브" 절 참고.
+
 저수준 RSS가 필요하면 `generateRssXml` / `rssItemsFromPosts`를 직접 사용할 수
 있습니다.
 

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

@@ -8,9 +8,12 @@ import {
   buildPostMetadata,
   postRedirectPath,
 } from "@roottale/cms-renderer-next/routes";
+import { articleSchema } from "@roottale/cms-client/server";
 
 import { getAllPosts, getPost } from "@/lib/blog";
 
+const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL!;
+
 export const revalidate = 1800;
 
 type Props = { params: Promise<{ slug: string }> };
@@ -24,10 +27,15 @@ export async function generateMetadata({ params }: Props): Promise<Metadata> {
   const { slug } = await params;
   const post = await getPost(slug);
   if (!post) return {};
-  // 어드민 SEO 패널(metaJson.seo) override + self-canonical 을 1줄로.
+  // 어드민 SEO 패널(metaJson.seo) override + self-canonical + avcd 구조(RSS
+  // alternate·Twitter Card·og article 확장)까지 1줄로. modified/section/tags 는
+  // 있는 만큼만 넘기면 됩니다 — 없으면 해당 필드만 생략.
   return buildPostMetadata(post, {
-    siteUrl: process.env.NEXT_PUBLIC_SITE_URL,
+    siteUrl: SITE_URL,
     path: `/blog/${post.slug}`,
+    modified: post.modified,
+    section: post.category || undefined,
+    tags: post.tags.map((t) => t.name),
   });
 }
 
@@ -39,14 +47,41 @@ export default async function PostPage({ params }: Props) {
   const redirect = postRedirectPath(post, slug);
   if (redirect) permanentRedirect(redirect);
 
+  const url = `${SITE_URL}/blog/${post.slug}`;
+  // avcd 구조 — BlogPosting + 확장 옵션(전부 선택, 있는 값만 채우면 됩니다).
+  const jsonLd = articleSchema({
+    type: "BlogPosting",
+    id: `${url}#article`,
+    headline: post.title,
+    description: post.description,
+    url,
+    image: post.image ?? undefined,
+    datePublished: post.date,
+    dateModified: post.modified,
+    authorName: post.authorName,
+    authorUrl: post.authorSlug
+      ? `${SITE_URL}/blog/author/${post.authorSlug}`
+      : undefined,
+    publisherName: "예시 사이트",
+    section: post.category || undefined,
+    inLanguage: "ko",
+  });
+
   return (
     <main>
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
+      />
       <h1>{post.title}</h1>
       <RootTaleBlogPost
         apiKey={process.env.ROOTTALE_API_KEY!}
         baseUrl={process.env.ROOTTALE_API_BASE}
         slugOrId={post.id}
         showTitle={false}
+        // opt-in — 시각 브레드크럼 + BreadcrumbList JSON-LD. siteUrl 없으면
+        // 시각 브레드크럼만(JSON-LD 미emit).
+        breadcrumb={{ siteUrl: SITE_URL }}
       />
     </main>
   );

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

@@ -0,0 +1,60 @@
+// 카테고리 허브 — RootTaleBlogList/RootTaleBlogCategories(카테고리 칩·목록)와
+// RootTaleBlogPost의 breadcrumb prop(카테고리 세그먼트) 기본 링크가 모두
+// `/blog/categories/{slug}`를 가리킵니다(defaultCategoryHref). 이 라우트가
+// 없으면 그 링크들을 클릭했을 때 404가 됩니다 — 단일 블로그 사이트도 예외
+// 아닙니다. 공지·블로그를 나눈 섹션형 사이트는 `{basePath}/categories/{slug}`
+// 패턴(collections.md 참고)을 대신 쓰세요.
+import type { Metadata } from "next";
+import Link from "next/link";
+import { notFound } from "next/navigation";
+import { collectionPageSchema } from "@roottale/cms-client/server";
+
+import { getPostsByCategory } from "@/lib/blog";
+
+const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL!;
+
+type Props = { params: Promise<{ slug: string }> };
+
+export const revalidate = 1800;
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { slug } = await params;
+  const posts = await getPostsByCategory(slug);
+  if (posts.length === 0) return { title: "카테고리" };
+  return {
+    title: `${posts[0]!.category} 글 모음`,
+    alternates: { canonical: `/blog/categories/${slug}` },
+  };
+}
+
+export default async function CategoryArchivePage({ params }: Props) {
+  const { slug } = await params;
+  const posts = await getPostsByCategory(slug);
+  if (posts.length === 0) notFound();
+
+  const categoryName = posts[0]!.category;
+  const url = `${SITE_URL}/blog/categories/${slug}`;
+  // 글 목록 페이지용 CollectionPage JSON-LD (articleSchema는 글 상세 전용).
+  const jsonLd = collectionPageSchema({
+    url,
+    name: `${categoryName} 글 모음`,
+    siteUrl: SITE_URL,
+  });
+
+  return (
+    <main>
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
+      />
+      <h1>{categoryName}</h1>
+      <ul>
+        {posts.map((post) => (
+          <li key={post.id}>
+            <Link href={`/blog/${post.slug}`}>{post.title}</Link>
+          </li>
+        ))}
+      </ul>
+    </main>
+  );
+}

package/examples/nextjs/lib/blog.ts

@@ -20,10 +20,13 @@ export interface BlogPostMeta {
   title: string;
   description: string;
   date: string; // publishedAt ISO
+  modified: string; // updatedAt ISO — avcd 구조 og:article:modified_time·dateModified
   category: string;
+  categorySlug: string; // "" = 카테고리 미지정 — /blog/categories/{slug} 허브 필터링용
   tags: { name: string; slug: string }[];
   image: string | null;
   authorName?: string;
+  authorSlug?: string | null; // /blog/author/{slug} — 미발급 작가는 null
   seo?: {
     title?: string;
     description?: string;
@@ -43,13 +46,16 @@ function toMeta(post: CmsPostContent): BlogPostMeta {
     title: post.title,
     description: post.excerpt ?? "",
     date: post.publishedAt ?? "",
+    modified: post.updatedAt,
     category: category?.name ?? "",
+    categorySlug: category?.slug ?? "",
     tags:
       post.terms
         ?.filter((t) => t.taxonomy === "tag")
         .map((t) => ({ name: t.name, slug: t.slug })) ?? [],
     image: post.featuredImageUrl ?? null,
     authorName: post.authorName ?? undefined,
+    authorSlug: post.authorSlug,
     seo: meta.seo as BlogPostMeta["seo"],
   };
 }
@@ -71,3 +77,14 @@ export async function getPost(
   if (!post) return null;
   return { ...toMeta(post), bodyJson: post.bodyJson };
 }
+
+// 카테고리 허브(`/blog/categories/{slug}`)용 — RootTaleBlogList/RootTaleBlogCategories
+// 의 기본 카테고리 링크가 이 경로를 가리키므로(defaultCategoryHref), 사이트는 이
+// 라우트를 반드시 구현해야 합니다(안 하면 카테고리 칩·브레드크럼 클릭이 404).
+// `/v1/cms/public/posts` 는 카테고리 서버 필터가 없어 클라이언트에서 거릅니다.
+export async function getPostsByCategory(
+  categorySlug: string,
+): Promise<BlogPostMeta[]> {
+  const posts = await getAllPosts();
+  return posts.filter((p) => p.categorySlug === categorySlug);
+}

package/package.json

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