@roottale/cms-mcp 0.37.0 → 0.41.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @roottale/cms-mcp
 
+## 0.41.0
+
+### Patch Changes
+
+- 22abf18: docs: 폐기된 `@roottale/cms-renderer-astro` 안내 제거 (ADR-0066 v4.2 Astro 표면 삭제 반영) — overview 패키지 표·blog 관련글·collections 라우팅 문단
+- 9f246f4: 목차(TOC) 사이드바 배치 opt-in — 넓은 화면에서 본문 오른쪽 sticky 목차.
+
+  블로그 설정 `toc_position`(`"inline"` | `"sidebar"`) 추가. 기본은 기존과 동일한
+  `"inline"`(본문 위 접이식). `"sidebar"` 선택 시:
+  - 넓은 화면(본문 컬럼 ≥ 60rem)에서 본문 오른쪽에 스크롤을 따라오는 sticky 목차.
+  - 좁은 화면은 CSS 컨테이너 쿼리로 자동 인라인(본문 위)로 폴백 — 마크업 동일.
+  - 뷰포트가 아닌 **본문 컬럼 폭** 기준(`@container`)이라 임베드 위치·주변
+    레이아웃과 무관하게 안전.
+
+  `RootTaleBlogPost`는 배치를 자동 반영하므로 고객 연동 코드 변경은 불필요.
+  `RootTaleBlogSettings` / `ResolvedPostDisplay` 에 `tocPosition` 필드 추가
+  (cms-client). 어드민 "블로그 설정 → 목차 위치" 에서 선택.
+
+  공개 API `GET /v1/cms/public/blog-settings` 응답에 `toc_position` 필드 추가
+  (cms-mcp api-reference 문서 동반 갱신).
+
+## 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

package/dist/index.js

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

@@ -116,11 +116,13 @@ fallback 네비를 렌더하세요 (`menus.md` 참고).
 블로그 표시 설정 (TOC·작성자·발행일·작성자 카드, 저자 프로필, 글 하단 CTA).
 `post_cta` 는 admin 에서 활성화하고 버튼 문구·링크를 채웠을 때만 객체이며,
 그 외에는 `null`. `RootTaleBlogPost` 가 본문 끝에 자동으로 렌더하므로 별도
-연동 코드는 필요 없다.
+연동 코드는 필요 없다. `toc_position` 은 목차 배치(`"inline"`=본문 위 접이식,
+`"sidebar"`=넓은 화면에서 본문 오른쪽 sticky, 좁은 화면은 자동 인라인)로,
+렌더러가 알아서 반영하므로 연동 코드 변경은 불필요하다.
 
 ```json
 { "show_table_of_contents": false, "show_author": true, "show_date": true,
-  "show_author_card": true, "toc_title": null,
+  "show_author_card": true, "toc_title": null, "toc_position": "inline",
   "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,

package/docs/blog.md

@@ -75,11 +75,18 @@ export default async function PostPage({
       slugOrId={slug}
       showTableOfContents
       tableOfContentsTitle="목차"
+      relatedPostsCount={3}
     />
   );
 }
 ```
 
+`relatedPostsCount`(기본 0=off)를 주면 글 하단에 **같은 카테고리 최근 글**을 N개
+`<nav class="rt-cms-related">` 로 노출합니다(현재 글 제외, 발행일 내림차순).
+제목은 `relatedPostsTitle`(기본 "관련 글"), 링크는 목록과 동일하게 `postHref`
+또는 `collections` 로 라우팅됩니다. 현재 글에 카테고리가 없거나 후보가 없으면
+렌더되지 않습니다.
+
 목차(ToC)·작성자 카드·발행일 표시는 어드민의 블로그 표시 설정으로도 제어됩니다
 (`theme-and-settings.md` 참고). 어드민 설정 > 블로그에서 **글 하단 CTA**(제목·설명·
 버튼)를 켜면 `RootTaleBlogPost` 가 모든 글 본문 끝에 같은 CTA 블록을 자동으로
@@ -97,6 +104,22 @@ export default async function PostPage({
 블록을 본문에 직접 배치할 때는 상단 자동 ToC 와 중복되지 않도록
 `showTableOfContents` 를 생략(기본 `false`)하는 것을 권장합니다.
 
+#### FAQ 블록 (자주 묻는 질문 + 구조화데이터)
+
+어드민 에디터의 슬래시 메뉴 `/FAQ` 로 **FAQ 블록**(`roottale/faq`)을 삽입하면,
+발행 시 `RootTaleBlogPost` / `renderBlogPost` 가 자동으로:
+
+- `<details class="rt-cms-faq-item"><summary class="rt-cms-faq-q">질문</summary>
+  <div class="rt-cms-faq-a">답변</div></details>` 아코디언(JS 0)을 그리고,
+- 글 단위 **`FAQPage` JSON-LD**(`<script type="application/ld+json">`)를 본문 끝에
+  1개 삽입합니다 — 구글 FAQ 리치결과/AI 검색 인용 대상.
+
+별도 연동·키 없이 동작하며, 업그레이드 후 기존 글에 FAQ 블록이 있으면 즉시
+반영됩니다. 스타일은 `cms-public.css` 의 `.rt-cms-faq*` 클래스가 테마 토큰
+(`--rt-color-*`)을 따르므로 추가 CSS 없이 적용됩니다. 직접 렌더 경로를 쓰는
+경우 `@roottale/cms-core` 의 `extractFaqEntries(doc)` / `faqPageJsonLd(entries)`
+로 동일한 JSON-LD 를 생성할 수 있습니다.
+
 ### 고정 페이지 (회사소개 등)
 
 어드민의 고정 페이지(`type: "page"`)는 `RootTalePage`로 렌더링합니다 — 블로그

package/docs/collections.md

@@ -260,10 +260,6 @@ export default createPostOgImage(
 );
 ```
 
-> Astro 사이트는 `@roottale/cms-renderer-astro`에서 동일한 `resolvePostCollection`/
-> `resolvePostPath`/`RouteCollection`을 import 하고 `renderBlogList({ collections })`로
-> 링크를 섹션별로 라우팅합니다(동등 surface).
-
 ## slug 변경과 301
 
 글의 slug(`/{slug}` 부분)는 글 편집 화면에서 바꿉니다. 바꾼 뒤 옛 slug로 들어오면 `postRedirectPath`로

package/docs/overview.md

@@ -38,8 +38,7 @@ RootTale CMS는 어드민(`mysite.roottale.com`)에서 콘텐츠를 작성·발
 |---|---|
 | [`@roottale/cms-client`](https://www.npmjs.com/package/@roottale/cms-client) | 서버 전용 fetch 클라이언트 — 글/테마/설정 조회, 문의 접수, 웹훅 검증 (raw) |
 | [`@roottale/cms-renderer-next`](https://www.npmjs.com/package/@roottale/cms-renderer-next) | Next.js(RSC) 렌더러 — 블로그 컴포넌트, revalidate/RSS/sitemap 라우트 팩토리 |
-| [`@roottale/cms-renderer-astro`](https://www.npmjs.com/package/@roottale/cms-renderer-astro) | Astro 렌더러 |
-| [`@roottale/cms-core`](https://www.npmjs.com/package/@roottale/cms-core) | 블록 JSON 공통 코어 (렌더러들이 의존) |
+| [`@roottale/cms-core`](https://www.npmjs.com/package/@roottale/cms-core) | 블록 JSON 공통 코어 (렌더러가 의존) |
 | `@roottale/cms-mcp` | 본 MCP 서버 — 통합 문서·예시 코드·API 조회 tool |
 
 ## 문서 맵

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/package.json

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