@roottale/cms-mcp 0.22.0

package/docs/theme-and-settings.md

@@ -0,0 +1,64 @@
+---
+title: 테마·블로그 표시·분석 태그 설정
+description: 어드민에서 관리하는 디자인 토큰, 블로그 표시 옵션, 분석 태그를 사이트에서 조회
+---
+
+# 테마·블로그 표시·분석 태그 설정
+
+어드민에서 설정한 값을 공개 API로 조회해 사이트에 반영합니다. 모두
+`@roottale/cms-client/server`에서 제공하며 같은 API 키를 사용합니다.
+
+## 디자인 토큰 — fetchTheme
+
+```ts
+import { fetchTheme } from "@roottale/cms-client/server";
+
+const theme = await fetchTheme({ apiKey: process.env.ROOTTALE_API_KEY! });
+// theme.colors / theme.fonts / theme.radius — 어드민에서 설정한 토큰만 포함
+```
+
+토큰을 CSS 변수로 매핑해 렌더러 스타일과 사이트 스타일을 일치시킬 수
+있습니다. 토큰 변경 시에도 발행 웹훅이 발송되어 캐시가 갱신됩니다.
+
+## 블로그 표시 설정 — fetchBlogSettings
+
+어드민의 블로그 표시 옵션(TOC 노출, 작성자/발행일 표시, 작성자 카드, 저자
+프로필)을 조회합니다.
+
+```ts
+import {
+  fetchBlogSettings,
+  resolvePostDisplay,
+  DEFAULT_BLOG_SETTINGS,
+} from "@roottale/cms-client/server";
+
+const settings = await fetchBlogSettings({
+  apiKey: process.env.ROOTTALE_API_KEY!,
+});
+// showTableOfContents, showAuthor, showDate, showAuthorCard,
+// tocTitle, authorProfileName / Bio / ImageUrl 등
+
+// 글 단위 오버라이드(metaJson)와 합성해 최종 표시값 계산
+const display = resolvePostDisplay(settings, post);
+```
+
+`RootTaleBlogPost` 컴포넌트를 쓰면 이 설정이 자동 반영됩니다 — 커스텀 UI를
+만들 때만 직접 조회하면 됩니다.
+
+## 분석 태그 — fetchAnalyticsConfig
+
+어드민에서 등록한 외부 분석 태그(GA4, Microsoft Clarity, Meta Pixel, 네이버)
+설정을 조회해 사이트에 주입합니다.
+
+```ts
+import { fetchAnalyticsConfig } from "@roottale/cms-client/server";
+
+const config = await fetchAnalyticsConfig({
+  apiKey: process.env.ROOTTALE_API_KEY!,
+});
+// config.tags: { provider: "ga4" | "clarity" | "meta_pixel" | "naver",
+//                id: string, enabled: boolean }[]
+```
+
+`enabled: true`인 태그만 렌더링하세요. 태그 ID는 어드민에서 변경될 수
+있으므로 하드코딩하지 말고 본 API로 조회하는 것을 권장합니다.

package/examples/nextjs/app/.well-known/roottale.json/route.ts

@@ -0,0 +1,4 @@
+// RootTale fleet 프로브 — 운영 측이 배포 버전·헬스를 확인하는 well-known 라우트.
+import { createFleetInfoRoute } from "@roottale/cms-renderer-next/routes";
+
+export const GET = createFleetInfoRoute({ site: "example" });

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

@@ -0,0 +1,22 @@
+// RootTale 발행 웹훅 수신 — ES256 서명 검증 후 Next.js 캐시 revalidate.
+// 어드민 "내 사이트 > 배포"에 https://<도메인>/api/revalidate 로 등록한다.
+import { revalidatePath } from "next/cache";
+import { createRevalidateRoute } from "@roottale/cms-renderer-next/routes";
+
+function revalidateBlogPath(path: string): void {
+  revalidatePath(path);
+  // 카테고리/태그 인덱스 같은 동적 경로가 있으면 함께 무효화
+  // if (path === "/blog/categories") revalidatePath("/blog/categories/[category]", "page");
+}
+
+export const POST = createRevalidateRoute({
+  apiKey: process.env.ROOTTALE_API_KEY!,
+  apiBase: process.env.ROOTTALE_API_BASE,
+  revalidate: revalidateBlogPath,
+  // 홈에 최신 글 섹션이 있으면 "/" 포함 — 글 변경 시 홈도 함께 갱신
+  alsoRevalidate: ["/feed.xml", "/sitemap.xml", "/blog", "/"],
+});
+
+export function GET(): Response {
+  return new Response("Method Not Allowed", { status: 405 });
+}

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

@@ -0,0 +1,54 @@
+// 블로그 상세 페이지 — 본문은 RootTaleBlogPost(블록 JSON 렌더러)에 위임,
+// 메타데이터는 어드민 SEO 패널(metaJson.seo) 값을 우선 적용.
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import { RootTaleBlogPost } from "@roottale/cms-renderer-next/server";
+
+import { getAllPosts, getPost } from "@/lib/blog";
+
+export const revalidate = 1800;
+
+type Props = { params: Promise<{ slug: string }> };
+
+export async function generateStaticParams() {
+  const posts = await getAllPosts();
+  return posts.map((p) => ({ slug: p.slug }));
+}
+
+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 ? { robots: { index: false, follow: true } } : {}),
+    openGraph: {
+      type: "article",
+      title,
+      description,
+      publishedTime: post.date,
+      ...(post.image ? { images: [{ url: seo?.ogImage || post.image, alt: title }] } : {}),
+    },
+  };
+}
+
+export default async function PostPage({ params }: Props) {
+  const { slug } = await params;
+  const post = await getPost(slug);
+  if (!post) notFound();
+
+  return (
+    <main>
+      <RootTaleBlogPost
+        apiKey={process.env.ROOTTALE_API_KEY!}
+        baseUrl={process.env.ROOTTALE_API_BASE}
+        slugOrId={post.id}
+      />
+    </main>
+  );
+}

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

@@ -0,0 +1,34 @@
+// 블로그 목록 페이지 — 30분 ISR은 fallback일 뿐, 정상 갱신은 발행 웹훅.
+import Link from "next/link";
+
+import { getAllPosts } from "@/lib/blog";
+
+export const revalidate = 1800;
+
+export const metadata = {
+  title: "블로그",
+  description: "최신 소식과 인사이트",
+};
+
+export default async function BlogPage() {
+  const posts = await getAllPosts();
+  return (
+    <main>
+      <h1>블로그</h1>
+      <ul>
+        {posts.map((post) => (
+          <li key={post.id}>
+            <Link href={`/blog/${post.slug}`}>
+              {post.category && <span>{post.category}</span>}
+              <h2>{post.title}</h2>
+              <p>{post.description}</p>
+              <time dateTime={post.date}>
+                {new Date(post.date).toLocaleDateString("ko-KR")}
+              </time>
+            </Link>
+          </li>
+        ))}
+      </ul>
+    </main>
+  );
+}

package/examples/nextjs/app/feed.xml/route.ts

@@ -0,0 +1,15 @@
+// RSS 2.0 피드 — 발행된 글 자동 포함.
+import { createFeedRoute } from "@roottale/cms-renderer-next/routes";
+
+export const dynamic = "force-dynamic";
+
+const SITE_URL =
+  process.env.NEXT_PUBLIC_SITE_URL?.replace(/\/$/, "") || "https://example.com";
+
+export const GET = createFeedRoute({
+  apiKey: process.env.ROOTTALE_API_KEY!,
+  apiBase: process.env.ROOTTALE_API_BASE,
+  siteUrl: SITE_URL,
+  title: "예시 사이트 블로그",
+  description: "최신 소식과 인사이트",
+});

package/examples/nextjs/app/sitemap.ts

@@ -0,0 +1,19 @@
+// 사이트맵 — 정적 경로 + 발행 글 URL 자동 포함.
+import { createSitemap } from "@roottale/cms-renderer-next/routes";
+
+const SITE_URL =
+  process.env.NEXT_PUBLIC_SITE_URL?.replace(/\/$/, "") || "https://example.com";
+
+export default createSitemap(
+  {
+    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 },
+  ],
+);

package/examples/nextjs/lib/actions/submit-contact.ts

@@ -0,0 +1,50 @@
+// 상담문의 폼 → RootTale CRM. 블로그와 같은 API 키로 테넌트가 식별된다.
+// 클라이언트 폼에서 useActionState(submitContact, { status: "idle" })로 연결.
+"use server";
+
+import { submitInquiry } from "@roottale/cms-client/server";
+
+export interface ContactState {
+  status: "idle" | "success" | "error";
+  message?: string;
+  errors?: Partial<Record<"name" | "phone" | "privacyConsent", string>>;
+}
+
+export async function submitContact(
+  _prevState: ContactState,
+  formData: FormData,
+): Promise<ContactState> {
+  const name = (formData.get("name") as string | null)?.trim() ?? "";
+  const phone = (formData.get("phone") as string | null)?.trim() ?? "";
+  const field = (formData.get("field") as string | null)?.trim() ?? "";
+  const message = (formData.get("message") as string | null)?.trim() ?? "";
+  const privacyConsent = formData.get("privacyConsent") !== null;
+
+  const errors: ContactState["errors"] = {};
+  if (!name) errors.name = "이름을 입력해주세요.";
+  if (!phone || phone.length < 7) errors.phone = "연락처를 입력해주세요.";
+  if (!privacyConsent) errors.privacyConsent = "개인정보 수집·이용에 동의해주세요.";
+  if (Object.keys(errors).length > 0) {
+    return { status: "error", message: "필수 항목을 입력해주세요.", errors };
+  }
+
+  const result = await submitInquiry({
+    apiKey: process.env.ROOTTALE_API_KEY!,
+    baseUrl: process.env.ROOTTALE_API_BASE,
+    fields: {
+      vertical: "consulting", // 사이트 업종에 맞게: consulting | medical | tax | legal
+      contactName: name,
+      businessName: name, // 사업체명 미수집 폼이면 이름으로 대체
+      email: `noemail-${Date.now()}@example.invalid`, // 이메일 미수집 폼 placeholder
+      phone,
+      consultationField: field || undefined,
+      message: message || undefined,
+      privacyConsent: true, // 사용자가 명시 동의한 경우에만
+    },
+  });
+
+  if (result.ok) {
+    return { status: "success", message: "상담 문의가 접수되었습니다." };
+  }
+  return { status: "error", message: result.message };
+}

package/examples/nextjs/lib/blog.ts

@@ -0,0 +1,72 @@
+// RootTale CMS 블로그 데이터 레이어 — 서버 전용.
+// 사이트 UI에 맞는 메타 형태로 변환하는 wrapper. API 키는 env에서만 읽는다.
+import {
+  fetchPosts,
+  fetchPost,
+  type CmsPostContent,
+} from "@roottale/cms-client/server";
+
+function getApiKey(): string {
+  const key = process.env.ROOTTALE_API_KEY;
+  if (!key) throw new Error("ROOTTALE_API_KEY is not set");
+  return key;
+}
+
+const baseUrl = process.env.ROOTTALE_API_BASE;
+
+export interface BlogPostMeta {
+  id: string;
+  slug: string;
+  title: string;
+  description: string;
+  date: string; // publishedAt ISO
+  category: string;
+  tags: { name: string; slug: string }[];
+  image: string | null;
+  authorName?: string;
+  seo?: {
+    title?: string;
+    description?: string;
+    canonical?: string;
+    ogImage?: string;
+    noindex?: boolean;
+  };
+}
+
+function toMeta(post: CmsPostContent): BlogPostMeta {
+  const category = post.terms?.find((t) => t.taxonomy === "category");
+  const meta = (post.metaJson ?? {}) as Record<string, unknown>;
+  return {
+    id: post.id,
+    slug: post.slug,
+    title: post.title,
+    description: post.excerpt ?? "",
+    date: post.publishedAt ?? "",
+    category: category?.name ?? "",
+    tags:
+      post.terms
+        ?.filter((t) => t.taxonomy === "tag")
+        .map((t) => ({ name: t.name, slug: t.slug })) ?? [],
+    image: post.featuredImageUrl ?? null,
+    authorName: post.authorName ?? undefined,
+    seo: meta.seo as BlogPostMeta["seo"],
+  };
+}
+
+export async function getAllPosts(): Promise<BlogPostMeta[]> {
+  const page = await fetchPosts({
+    apiKey: getApiKey(),
+    baseUrl,
+    type: "post",
+    limit: 100,
+  });
+  return page.items.map(toMeta);
+}
+
+export async function getPost(
+  slug: string,
+): Promise<(BlogPostMeta & { bodyJson: unknown }) | null> {
+  const post = await fetchPost({ apiKey: getApiKey(), baseUrl, slugOrId: slug });
+  if (!post) return null;
+  return { ...toMeta(post), bodyJson: post.bodyJson };
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@roottale/cms-mcp",
+  "version": "0.22.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": {
+    "roottale-cms-mcp": "dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist/",
+    "docs/",
+    "examples/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "roottale",
+    "cms",
+    "mcp",
+    "integration",
+    "docs"
+  ],
+  "license": "UNLICENSED",
+  "homepage": "https://github.com/RootTale/roottale-platform/tree/main/packages/cms-mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RootTale/roottale-platform.git",
+    "directory": "packages/cms-mcp"
+  }
+}