@roottale/cms-mcp 0.36.0 → 0.39.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @roottale/cms-mcp
 
+## 0.39.0
+
+### Patch Changes
+
+- chore: linked cms-\* 그룹 버전 정렬 — cms-media(0.27.0)·cms-mcp(0.37.0) 이
+  부분 릴리스로 그룹(0.38.0)에서 드리프트. 6개 linked 패키지를 한 릴리스에 묶어
+  공통 버전으로 재정렬한다.
+
+## 0.37.0
+
+### Minor Changes
+
+- de62ad1: 작가 아카이브 페이지 + 작가 사이트맵 (blanche식 /blog/author/{slug})
+  - `fetchAuthors()` 추가 (`GET /v1/cms/public/authors`) — slug가 있고 발행 글이 1건
+    이상인 작가 목록(slug·이름·이미지·소개·글 수·최근 수정일). 어드민 **설정 > 팀**에서
+    작가 slug를 발급한다(site 내 unique).
+  - `RootTaleBlogList` 에 `author` prop, `fetchPosts` 에 `author` 옵션 추가 —
+    `GET /v1/cms/public/posts?author={slug}` 로 그 작가의 발행 글만 렌더(작가 아카이브용).
+  - `createSitemapIndex` 에 `authors` 하위 사이트맵(`/sitemap/authors.xml`) 추가 — 어드민
+    **설정 > 블로그 > 사이트맵**의 "작가 사이트맵"(`authors`) 토글이 켜졌을 때만 인덱스에
+    포함. `authorBasePath` 옵션(기본 `/blog/author`)으로 경로 커스터마이즈.
+  - starter 에 `app/blog/author/[slug]/page.tsx` 추가 + cms-mcp seo.md 문서 갱신.
+
+- c77238d: 사이트맵 다국어 hreflang (스캐폴딩)
+  - `createSitemapIndex` 가 사이트맵 설정의 `locales`(예 `["ko","ja","en"]`)가 있으면
+    모든 섹션(static/blog/categories/authors) entry 에 `alternates.languages`(hreflang)
+    를 단다. 첫 로케일 = 기본(현 URL) + `x-default`, 나머지는 path-prefix(`/ja/...`).
+    어드민 **설정 > 블로그 > 사이트맵** 의 "다국어 로케일"에서 입력.
+  - 같은 slug + 언어 접두사 1:1 을 가정하는 스캐폴딩 — 실제 per-locale 페이지 서빙은
+    사이트 책임(번역 콘텐츠 모델 도입 시 재방문). 비우면 단일 언어(기본).
+  - 어드민 사이트맵 카드에 "작가 사이트맵"(authors) 토글도 노출 — 작가 사이트맵을
+    UI 에서 켤 수 있다.
+
+- 36e2dae: 사이트맵 인덱스 분리 + 블로그 이미지 색인 (blanche식)
+  - `createSitemapIndex(config, staticRoutes, opts)` 추가 — Next 16 `generateSitemaps`
+    로 `/sitemap.xml`(인덱스) + `/sitemap/static.xml`·`/sitemap/blog.xml`·
+    `/sitemap/categories.xml` 하위 사이트맵으로 분리. 50k URL/50MB 한도 확장 + 검색엔진
+    섹션별 크롤. 소비자는 `export { generateSitemaps }; export default sitemap;`.
+  - 블로그 글 entry 에 대표 이미지(`featuredImageUrl`)를 `<image:image>` 로 색인 —
+    어드민 **설정 > 블로그 > 사이트맵**의 토글(`blogImages`)로 제어. `RootTaleBlogSettings.sitemap`
+    (`/v1/cms/public/blog-settings` 응답)에 사이트맵 정책(`blogImages`/`locales`/`authors`) 추가.
+  - `changeFrequency`/`priority` 는 더 이상 emit 하지 않음(Google 무시 — `loc`+`lastmod` +이미지만). 레거시 `createSitemap`(단일 평면)은 deprecate 되었으나 하위호환 유지.
+
 ## 0.36.0
 
 ### Patch Changes

package/dist/index.js

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

@@ -115,10 +115,13 @@ export const COLLECTIONS: RouteCollection[] = [
 
 ```ts
 // app/sitemap.ts
-import { createSitemap } from "@roottale/cms-renderer-next/routes";
-export default createSitemap({ apiKey, siteUrl, title, collections: COLLECTIONS }, [
-  /* 정적 경로 */
-]);
+import { createSitemapIndex } from "@roottale/cms-renderer-next/routes";
+const { generateSitemaps, sitemap } = createSitemapIndex(
+  { apiKey, siteUrl, title, collections: COLLECTIONS },
+  [ /* 정적 경로 */ ],
+);
+export { generateSitemaps };
+export default sitemap;
 
 // app/feed.xml/route.ts
 export const dynamic = "force-dynamic";
@@ -144,7 +147,12 @@ async function getCollections(): Promise<RouteCollection[]> {
   }
 }
 
-export default createSitemap({ apiKey, siteUrl, title, collections: getCollections }, [ ]);
+const { generateSitemaps, sitemap } = createSitemapIndex(
+  { apiKey, siteUrl, title, collections: getCollections },
+  [ ],
+);
+export { generateSitemaps };
+export default sitemap;
 export const GET = createFeedRoute({ apiKey, siteUrl, title, collections: getCollections });
 ```
 

package/docs/seo.md

@@ -29,13 +29,18 @@ export const GET = createFeedRoute({
 
 ## 사이트맵
 
+`createSitemapIndex`는 **사이트맵 인덱스**(`/sitemap.xml`)와 섹션별 하위 사이트맵
+(`/sitemap/static.xml`·`/sitemap/blog.xml`·`/sitemap/categories.xml`)을 만듭니다.
+하나의 거대한 파일 대신 섹션별로 나뉘어 검색엔진이 더 잘 크롤하고, 50,000 URL/50MB
+한도에도 안전합니다. 발행 글·카테고리는 자동 포함됩니다.
+
 ```ts
 // app/sitemap.ts
-import { createSitemap } from "@roottale/cms-renderer-next/routes";
+import { createSitemapIndex } from "@roottale/cms-renderer-next/routes";
 
 const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL!;
 
-export default createSitemap(
+const { generateSitemaps, sitemap } = createSitemapIndex(
   {
     apiKey: process.env.ROOTTALE_API_KEY!,
     apiBase: process.env.ROOTTALE_API_BASE,
@@ -43,14 +48,77 @@ export default createSitemap(
     title: "예시 사이트",
   },
   [
-    // 정적 경로 — 발행 글 URL은 자동 추가됨
-    { url: SITE_URL, changeFrequency: "weekly", priority: 1.0 },
-    { url: `${SITE_URL}/blog`, changeFrequency: "weekly", priority: 0.7 },
-    { url: `${SITE_URL}/contact`, changeFrequency: "monthly", priority: 0.9 },
+    // 정적 경로 — 발행 글·카테고리 URL은 자동 추가됨
+    { url: SITE_URL },
+    { url: `${SITE_URL}/blog` },
+    { url: `${SITE_URL}/contact` },
   ],
 );
+
+// Next 16: 인덱스를 만들려면 generateSitemaps·default 를 둘 다 export.
+export { generateSitemaps };
+export default sitemap;
 ```
 
+- **블로그 이미지 색인** — 글에 대표 이미지가 있으면 `<image:image>`로 함께 색인합니다.
+  어드민 **설정 > 블로그 > 사이트맵**에서 켜고 끌 수 있어요(기본 켜짐).
+- `changeFrequency`/`priority`는 Google이 무시하므로 더 이상 내보내지 않습니다(`loc` +
+  `lastmod` + 이미지만).
+- 단일 평면 사이트맵이 필요하면 레거시 `createSitemap`(default export 하나)도 그대로
+  동작하지만, 신규 사이트는 `createSitemapIndex`를 권장합니다.
+
+### 작가 아카이브 (`/blog/author/{slug}`)
+
+어드민 **설정 > 팀**에서 작가에게 주소(slug)를 발급하면, 그 작가의 글 모음 페이지와
+작가 사이트맵(`/sitemap/authors.xml`)을 만들 수 있습니다. 어드민 **설정 > 블로그 >
+사이트맵**에서 "작가 사이트맵"을 켜면 인덱스에 `authors` 섹션이 추가됩니다.
+
+```ts
+// app/blog/author/[slug]/page.tsx
+import { notFound } from "next/navigation";
+import { fetchAuthors } from "@roottale/cms-client/server";
+import { RootTaleBlogList } from "@roottale/cms-renderer-next/server";
+
+export default async function AuthorArchive({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const authors = await fetchAuthors({ apiKey: process.env.ROOTTALE_API_KEY! });
+  const author = authors.find((a) => a.slug === slug);
+  if (!author) notFound();
+
+  return (
+    <>
+      <h1>{author.name}</h1>
+      {author.bio ? <p>{author.bio}</p> : null}
+      {/* author= 로 그 작가의 발행 글만 렌더 */}
+      <RootTaleBlogList apiKey={process.env.ROOTTALE_API_KEY!} author={slug} />
+    </>
+  );
+}
+```
+
+- `fetchAuthors()` 는 slug가 있고 발행 글이 1건 이상인 작가만 반환합니다
+  (`GET /v1/cms/public/authors`).
+- `RootTaleBlogList`에 `author={slug}` 를 주면 그 작가의 글만 가져옵니다
+  (`GET /v1/cms/public/posts?author={slug}`).
+
+### 다국어 (hreflang)
+
+번역 페이지가 있는 사이트는 어드민 **설정 > 블로그 > 사이트맵**의 "다국어 로케일"에
+언어 코드를 입력하면(예: `ko, ja, en`), 사이트맵의 모든 항목에 `hreflang` 대체 언어
+링크(`<xhtml:link rel="alternate">`)가 붙습니다.
+
+- **첫 번째** 로케일이 기본 언어(현재 URL 그대로) + `x-default`.
+- 나머지는 **경로 접두사**로 매핑됩니다 — `ko`가 기본이면 `ja`는
+  `/ja/blog/{slug}`, `en`은 `/en/blog/{slug}`.
+- 같은 slug에 언어 접두사만 붙는 1:1 구조를 가정합니다. **실제 번역 페이지를
+  그 경로(`/ja/...`)에 서빙하는 것은 사이트 쪽 책임**입니다 — 사이트맵은 검색엔진에
+  대체 언어를 알릴 뿐입니다.
+- 비워두면 단일 언어로 동작합니다(기본).
+
 ## 다중 스트림 (collections) — 공지·블로그 분리
 
 같은 글 풀을 공지 게시판(`/notice`) + 블로그(`/blog`) 등 여러 섹션으로 나눠 서로 다른

package/docs/theme-and-settings.md

@@ -88,6 +88,53 @@ const config = await fetchAnalyticsConfig({
 `enabled: true`인 태그만 렌더링하세요. 태그 ID는 어드민에서 변경될 수
 있으므로 하드코딩하지 말고 본 API로 조회하는 것을 권장합니다.
 
+## 조회수 / first-party 비콘
+
+RootTale 비콘은 쿠키리스 first-party 분석(방문수·클릭)과 **글별 조회수**를
+수집합니다. **API 키 하나로** 동작합니다 — 별도 사이트 ID 환경변수가 필요 없습니다.
+`fetchAnalyticsConfig`가 돌려주는 `siteId`를 비콘에 그대로 넘기세요.
+
+```tsx
+// app/layout.tsx (Next.js) — 서버 컴포넌트
+import { renderBeaconScript } from "@roottale/analytics-runtime";
+import { fetchAnalyticsConfig } from "@roottale/cms-client/server";
+
+const cfg = await fetchAnalyticsConfig({ apiKey: process.env.ROOTTALE_API_KEY! });
+// ...<body> 안에:
+<script
+  dangerouslySetInnerHTML={{
+    __html: renderBeaconScript({
+      collectUrl: "https://api.roottale.com/v1/collect",
+      siteId: cfg.siteId, // ← API 키에서 유도. 별도 env 불필요.
+    }),
+  }}
+/>
+```
+
+**글별 조회수**가 정확히 집계되려면, 글 상세 페이지가 자신의 글 ID를
+`<meta name="rt:content-id">`로 노출해야 합니다. 비콘이 이 값을 읽어 조회를 해당
+글에 귀속시킵니다(URL·경로가 바뀌어도 안정적).
+
+```tsx
+// app/blog/[slug]/page.tsx — generateMetadata
+export async function generateMetadata({ params }): Promise<Metadata> {
+  const post = await fetchPost({ apiKey: process.env.ROOTTALE_API_KEY!, slugOrId: slug });
+  return {
+    title: post.title,
+    other: { "rt:content-id": post.id }, // ← 조회수 식별자
+  };
+}
+```
+
+> `@roottale/cms-renderer-next`의 `buildPostMetadata(post, …)`를 쓰면 이 meta가
+> **자동으로** 들어갑니다(별도 작업 불필요). 프레임워크 무관 환경(Astro 등)에서는
+> `@roottale/cms-client/server`의 `contentIdMeta(post.id)`가 같은 `<meta>` 태그
+> 문자열을 만들어 줍니다.
+
+수집은 익명·쿠키리스이며 비콘은 클릭(`data-track`)과 pageview만 보냅니다. 봇
+트래픽은 서버에서 제외됩니다. 공개 사이트에 "조회 N"을 표시하는 옵션은 어드민의
+사이트 설정에서 켤 수 있습니다(켜면 글 응답에 `view_count`가 포함됩니다).
+
 ## 사이트 지식 — 브랜드 보이스 (AI 에이전트용)
 
 이 사이트의 **브랜드 보이스**(어조·톤·화자)와 **용어 규칙**(금지어·교정어)을

package/examples/nextjs/app/api/revalidate/route.ts

@@ -13,8 +13,18 @@ export const POST = createRevalidateRoute({
   apiKey: process.env.ROOTTALE_API_KEY!,
   apiBase: process.env.ROOTTALE_API_BASE,
   revalidate: revalidateBlogPath,
-  // 홈에 최신 글 섹션이 있으면 "/" 포함 — 글 변경 시 홈도 함께 갱신
-  alsoRevalidate: ["/feed.xml", "/sitemap.xml", "/blog", "/"],
+  // 사이트맵 인덱스 + 분리된 하위 사이트맵(static/blog/categories)을 모두 무효화.
+  // 홈에 최신 글 섹션이 있으면 "/" 포함 — 글 변경 시 홈도 함께 갱신.
+  alsoRevalidate: [
+    "/feed.xml",
+    "/sitemap.xml",
+    "/sitemap/static.xml",
+    "/sitemap/blog.xml",
+    "/sitemap/categories.xml",
+    "/sitemap/authors.xml",
+    "/blog",
+    "/",
+  ],
 });
 
 export function GET(): Response {

package/examples/nextjs/app/sitemap.ts

@@ -1,19 +1,20 @@
-// 사이트맵 — 정적 경로 + 발행 글 URL 자동 포함.
-import { createSitemap } from "@roottale/cms-renderer-next/routes";
+// 사이트맵 — 인덱스 분리(/sitemap.xml → /sitemap/static.xml·blog·categories).
+// 정적 경로 + 발행 글·카테고리 자동 포함. 블로그 글 대표 이미지는 admin 토글에 따라
+// <image:image> 로 함께 색인(어드민 설정 > 블로그 > 사이트맵).
+import { createSitemapIndex } from "@roottale/cms-renderer-next/routes";
 
 const SITE_URL =
   process.env.NEXT_PUBLIC_SITE_URL?.replace(/\/$/, "") || "https://example.com";
 
-export default createSitemap(
+const { generateSitemaps, sitemap } = createSitemapIndex(
   {
     apiKey: process.env.ROOTTALE_API_KEY!,
     apiBase: process.env.ROOTTALE_API_BASE,
     siteUrl: SITE_URL,
     title: "예시 사이트",
   },
-  [
-    { url: SITE_URL, changeFrequency: "weekly", priority: 1.0 },
-    { url: `${SITE_URL}/blog`, changeFrequency: "weekly", priority: 0.7 },
-    { url: `${SITE_URL}/contact`, changeFrequency: "monthly", priority: 0.9 },
-  ],
+  [{ url: SITE_URL }, { url: `${SITE_URL}/blog` }, { url: `${SITE_URL}/contact` }],
 );
+
+export { generateSitemaps };
+export default sitemap;

package/package.json

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