@roottale/cms-mcp 0.53.0 → 0.55.0

package/docs/theme-and-settings.md

@@ -1,9 +1,9 @@
 ---
-title: 테마·블로그 표시·분석 태그 설정
-description: 어드민에서 관리하는 디자인 토큰, 블로그 표시 옵션, 분석 태그를 사이트에서 조회
+title: 테마·블로그 표시·ROOT-ANALYTICS 설정
+description: 어드민에서 관리하는 디자인 토큰, 블로그 표시 옵션, ROOT-ANALYTICS 설정을 사이트에서 조회
 ---
 
-# 테마·블로그 표시·분석 태그 설정
+# 테마·블로그 표시·ROOT-ANALYTICS 설정
 
 어드민에서 설정한 값을 공개 API로 조회해 사이트에 반영합니다. 모두
 `@roottale/cms-client/server`에서 제공하며 같은 API 키를 사용합니다.
@@ -179,10 +179,10 @@ if (business) {
 > 반환합니다. 전화·주소만 채우고 이름을 비워두면 **나머지 입력이 전부 무시**되니
 > 고객 안내 시 이름을 필수로 안내하세요.
 
-## 분석 태그 — fetchAnalyticsConfig
+## ROOT-ANALYTICS 설정 — fetchAnalyticsConfig
 
-어드민에서 등록한 외부 분석 태그(GA4, Microsoft Clarity, Meta Pixel, 네이버)
-설정을 조회해 사이트에 주입합니다.
+ROOT-ADMIN에서 등록한 외부 태그(GA4, Microsoft Clarity, Meta Pixel, 네이버)와
+ROOT-ANALYTICS 사이트 ID를 조회해 고객 사이트에 연결합니다.
 
 ```ts
 import { fetchAnalyticsConfig } from "@roottale/cms-client/server";
@@ -197,9 +197,9 @@ const config = await fetchAnalyticsConfig({
 `enabled: true`인 태그만 렌더링하세요. 태그 ID는 어드민에서 변경될 수
 있으므로 하드코딩하지 말고 본 API로 조회하는 것을 권장합니다.
 
-## 조회수 / first-party 비콘
+## ROOT-ANALYTICS 조회수·first-party 비콘
 
-RootTale 비콘은 쿠키리스 first-party 분석(방문수·클릭)과 **글별 조회수**를
+ROOT-ANALYTICS 비콘은 쿠키리스 first-party 분석(페이지·클릭)과 **글별 조회수**를
 수집합니다. **API 키 하나로** 동작합니다 — 별도 사이트 ID 환경변수가 필요 없습니다.
 `fetchAnalyticsConfig`가 돌려주는 `siteId`를 비콘에 그대로 넘기세요.
 
@@ -240,10 +240,21 @@ export async function generateMetadata({ params }): Promise<Metadata> {
 > `@roottale/cms-client/server`의 `contentIdMeta(post.id)`가 같은 `<meta>` 태그
 > 문자열을 만들어 줍니다.
 
-수집은 익명·쿠키리스이며 비콘은 클릭(`data-track`)과 pageview만 보냅니다. 봇
-트래픽은 서버에서 제외됩니다. 공개 사이트에 "조회 N"을 표시하는 옵션은 어드민의
+수집은 익명·쿠키리스이며 비콘은 pageview와 명시한 행동 이벤트를 보냅니다. Next.js
+SPA 전환과 섹션·스크롤·읽기·폼 감지는 `@roottale/analytics-runtime/next` 어댑터로
+연결합니다. 봇 트래픽은 서버에서 제외됩니다. 공개 사이트에 "조회 N"을 표시하는 옵션은 어드민의
 사이트 설정에서 켤 수 있습니다(켜면 글 응답에 `view_count`가 포함됩니다).
 
+저장 위치는 데이터 성격에 따라 나뉩니다.
+
+| 데이터 | 저장 위치 |
+|---|---|
+| 페이지·클릭·섹션 이벤트 | Cloudflare Analytics Engine `cms_site_events` |
+| 글 누적 조회수 | 사이트별 Durable Object SQLite, PostgreSQL `posts.view_count` 미러 |
+| 첫·마지막 유입 | 브라우저 `localStorage._rt_attr`(30일) |
+| 현재 방문 여정 | 브라우저 `sessionStorage._rt_journey`(최대 30건) |
+| 문의에 귀속된 유입·여정 | PostgreSQL `inquiries.attribution`, `inquiries.journey` |
+
 ## 사이트 지식 — 브랜드 보이스 (AI 에이전트용)
 
 이 사이트의 **브랜드 보이스**(어조·톤·화자)와 **용어 규칙**(금지어·교정어)을

package/examples/nextjs/app/preview/post/[id]/page.tsx

@@ -0,0 +1,70 @@
+// 글 미리보기 — ROOT-ADMIN 편집기의 '미리보기'·'공유 링크'가 여는 주소.
+// 관리자 발급 토큰(1시간, 글 1건 전용)으로 편집 중인 내용을 받아 발행 글과
+// **같은 템플릿**(RootTaleBlogPost)으로 그린다 → 미리보기 = 발행 결과.
+// 라우트를 배포한 뒤 관리자 설정 › 외부 연결 › "글 미리보기 여는 곳"에서
+// "홈페이지에서 열기"를 켜면 편집기가 이 주소를 연다.
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import {
+  fetchPostPreview,
+  isPreviewExpiredError,
+} from "@roottale/cms-client/server";
+import {
+  RootTaleBlogPost,
+  RootTalePreviewNotice,
+} from "@roottale/cms-renderer-next/server";
+import { buildPreviewMetadata } from "@roottale/cms-renderer-next/routes";
+
+// 초안이 ISR·CDN 에 남으면 안 된다 — 항상 동적 렌더.
+export const dynamic = "force-dynamic";
+export const revalidate = 0;
+
+type Props = {
+  params: Promise<{ id: string }>;
+  searchParams: Promise<{ token?: string }>;
+};
+
+function loadPreview(token: string) {
+  return fetchPostPreview({
+    apiKey: process.env.ROOTTALE_API_KEY!,
+    baseUrl: process.env.ROOTTALE_API_BASE,
+    token,
+  });
+}
+
+export async function generateMetadata({ searchParams }: Props): Promise<Metadata> {
+  const { token } = await searchParams;
+  const post = token ? await loadPreview(token).catch(() => null) : null;
+  // 항상 noindex/nofollow — 초안이 색인되거나 발행 주소와 중복되면 안 된다.
+  return buildPreviewMetadata({ title: post?.title });
+}
+
+export default async function PostPreviewPage({ params, searchParams }: Props) {
+  const { id } = await params;
+  const { token } = await searchParams;
+  if (!token) notFound(); // 주소만으로는 아무것도 보이지 않는다.
+
+  let expiresAt: string | undefined;
+  try {
+    const post = await loadPreview(token);
+    if (!post || post.id !== id) notFound(); // 토큰은 글 1건 전용
+    expiresAt = post.preview.expiresAt;
+  } catch (error) {
+    if (!isPreviewExpiredError(error)) throw error; // 만료는 컴포넌트가 안내
+  }
+
+  return (
+    <main className="container">
+      <RootTalePreviewNotice expiresAt={expiresAt} />
+      {/* 발행 글 상세(app/blog/[slug]/page.tsx)와 같은 props 를 쓰되
+          slugOrId 대신 previewToken 만 넘긴다. */}
+      <RootTaleBlogPost
+        apiKey={process.env.ROOTTALE_API_KEY!}
+        baseUrl={process.env.ROOTTALE_API_BASE}
+        previewToken={token}
+        relatedPostsCount={3}
+        breadcrumb={{ siteUrl: process.env.NEXT_PUBLIC_SITE_URL }}
+      />
+    </main>
+  );
+}

package/examples/nextjs/app/search/page.tsx

@@ -0,0 +1,64 @@
+// 사이트 통합 검색 — 고객 브라우저가 아니라 이 Server Component가 CMS API를 호출한다.
+import type { Metadata } from "next";
+import Link from "next/link";
+
+import {
+  fetchCollections,
+  resolveSearchHitPath,
+  searchPosts,
+} from "@roottale/cms-client/server";
+
+export const metadata: Metadata = {
+  title: "사이트 검색",
+  robots: { index: false, follow: true },
+};
+
+interface Props {
+  searchParams: Promise<{ q?: string | string[] }>;
+}
+
+export default async function SearchPage({ searchParams }: Props) {
+  const { q = "" } = await searchParams;
+  const query = (typeof q === "string" ? q : q[0] ?? "").trim();
+  const apiKey = process.env.ROOTTALE_API_KEY!;
+  const baseUrl = process.env.ROOTTALE_API_BASE;
+  const [hits, collections] = query
+    ? await Promise.all([
+        searchPosts({ apiKey, baseUrl, query, type: "all", limit: 20 }),
+        fetchCollections({ apiKey, baseUrl }).catch(() => []),
+      ])
+    : [[], []];
+
+  return (
+    <main>
+      <h1>사이트 검색</h1>
+      <form action="/search" method="get" role="search">
+        <label htmlFor="site-search">검색어</label>
+        <input
+          defaultValue={query}
+          id="site-search"
+          maxLength={100}
+          name="q"
+          required
+          type="search"
+        />
+        <button type="submit">검색</button>
+      </form>
+      {query ? <p>검색 결과 {hits.length}건</p> : <p>검색어를 입력해 주세요.</p>}
+      <ul>
+        {hits.map((hit) => {
+          const href = resolveSearchHitPath(hit, collections);
+          if (!href) return null;
+          return (
+            <li key={hit.id}>
+              <Link href={href}>
+                <h2>{hit.title}</h2>
+                {hit.excerpt ? <p>{hit.excerpt}</p> : null}
+              </Link>
+            </li>
+          );
+        })}
+      </ul>
+    </main>
+  );
+}

package/examples/nextjs/components/global-popup.tsx

@@ -0,0 +1,13 @@
+import { RootTaleExposureSlot } from "@roottale/cms-renderer-next/server";
+
+export async function GlobalPopup({ path }: { path: string }) {
+  return (
+    <RootTaleExposureSlot
+      apiKey={process.env.ROOTTALE_API_KEY!}
+      slotKey="global-popup"
+      path={path}
+      allowedVariants={["card", "image-card"]}
+      revalidate={60}
+    />
+  );
+}

package/examples/nextjs/lib/blog.ts

@@ -3,6 +3,7 @@
 import {
   BLOG_SETTINGS_CACHE_TAG,
   fetchBlogSettings,
+  fetchCategoryCounts,
   fetchPost,
   type CmsPostContent,
 } from "@roottale/cms-client/server";
@@ -31,6 +32,7 @@ export interface BlogPostMeta {
   categorySlug: string; // "" = 카테고리 미지정 — /blog/categories/{slug} 허브 필터링용
   tags: { name: string; slug: string }[];
   image: string | null;
+  authorProfileId?: string | null;
   authorName?: string;
   authorSlug?: string | null; // /blog/author/{slug} — 미발급 작가는 null
   seo?: {
@@ -60,6 +62,7 @@ function toMeta(post: CmsPostContent): BlogPostMeta {
         ?.filter((t) => t.taxonomy === "tag")
         .map((t) => ({ name: t.name, slug: t.slug })) ?? [],
     image: post.featuredImageUrl ?? null,
+    authorProfileId: post.authorProfileId,
     authorName: post.authorName ?? undefined,
     authorSlug: post.authorSlug,
     seo: meta.seo as BlogPostMeta["seo"],
@@ -96,6 +99,25 @@ export async function getPostsByCategory(
   return posts.filter((p) => p.categorySlug === categorySlug);
 }
 
+// 카테고리 허브의 소개문·검색 문구·공유 이미지는 카테고리 집계 응답에 함께 옵니다.
+// 구버전 API와 이미지 미설정을 고려해 nullable 값으로 다룹니다.
+export async function getCategoryArchiveMeta(categorySlug: string) {
+  const { categories } = await fetchCategoryCounts({
+    apiKey: getApiKey(),
+    baseUrl,
+    excludeCollections: true,
+  });
+  const category = categories.find((item) => item.slug === categorySlug);
+  if (!category) return null;
+  return {
+    title: category.seoTitle ?? `${category.name} 글 모음`,
+    description: category.seoDescription ?? category.description,
+    image: category.imageUrl
+      ? { url: category.imageUrl, alt: category.imageAlt ?? category.name }
+      : null,
+  };
+}
+
 // 색인 위생 — 어드민 "내 사이트 > 카테고리 > 검색에 이 분류 페이지 노출" 을 켠
 // 분류인지. 켜지 않은 분류의 모음 페이지는 noindex + 사이트맵 제외가 됩니다
 // (seo.md "색인 위생" 절).

package/examples/nextjs/lib/content-models.ts

@@ -0,0 +1,12 @@
+import { fetchContentModels, fetchPosts } from "@roottale/cms-client/server";
+
+const apiKey = process.env.ROOTTALE_API_KEY!;
+
+export async function getTeamMembers() {
+  const models = await fetchContentModels({ apiKey });
+  const model = models.models.find((candidate) => candidate.key === "team-member");
+  if (!model || model.preset !== "entity") return [];
+
+  const response = await fetchPosts({ apiKey, modelKey: model.key, limit: 100 });
+  return response.items;
+}

package/examples/nextjs/middleware.ts

@@ -2,7 +2,8 @@
 //
 // 글 슬러그 변경 자동 301 은 글 라우트에서 처리되지만(blog 예시 참고), 글이
 // 아닌 임의 경로(`/old-event → /promo`)는 라우팅 이전 단계인 미들웨어에서만
-// 가로챌 수 있다. 규칙은 자동 캐시되고, API 실패 시 트래픽을 막지 않는다.
+// 가로챌 수 있다. 규칙은 자동 캐시되고, API 실패 시 stale 캐시를
+// 우선 사용한다. 캐시가 없거나 순환 규칙이면 트래픽을 막지 않는다.
 import { NextResponse } from "next/server";
 import { createRedirectMiddleware } from "@roottale/cms-renderer-next/routes";
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@roottale/cms-mcp",
-  "version": "0.53.0",
+  "version": "0.55.0",
   "type": "module",
-  "description": "RootTale CMS MCP server and CLI for post publishing, media uploads, integration docs, and public API access.",
+  "description": "RootTale CMS MCP server and CLI for models, entries, exposures, media, integration docs, and public API access.",
   "bin": {
     "roottale-cms-mcp": "dist/index.js"
   },