@roottale/cms-mcp/docs/overview.md

RootTale CMS integration MCP server — bundled integration docs, Next.js example code, and public API lookup tools. Run with: npx @roottale/cms-mcp

---
title: RootTale CMS 연동 개요
description: 연동 아키텍처, 단일 API 키 모델, 패키지 구성, 문서 맵
---

# RootTale CMS 연동 개요

RootTale CMS는 어드민(`mysite.roottale.com`)에서 콘텐츠를 작성·발행하고, 외부
고객 사이트(자체 도메인의 Next.js/Astro 등)가 공개 API(`api.roottale.com`)로
콘텐츠를 가져가는 헤드리스 구조입니다.

```
어드민 (mysite.roottale.com)            고객 사이트 (예: example.com)
  글 작성·발행 ──────────┐
                         ▼
              api.roottale.com  ◀── Bearer rtlk_cust_* ── 콘텐츠/설정 조회
                         │
  발행 웹훅 (ES256 서명) ─┴──────────▶ POST /api/revalidate → 캐시 즉시 갱신
```

## 단일 API 키 모델

연동 전체가 **API 키 하나(`rtlk_cust_*`)** 로 동작합니다:

| 기능 | 같은 키 하나로 |
|---|---|
| 블로그 글 목록/상세 조회 | `fetchPosts` / `fetchPost` |
| 발행 웹훅 서명 검증 | `createRevalidateRoute` (JWKS 공개키 — 별도 secret 보관 불필요) |
| 상담문의(리드) 접수 | `submitInquiry` — 키가 테넌트를 식별 |
| 테마·블로그 표시·분석 태그 설정 조회 | `fetchTheme` / `fetchBlogSettings` / `fetchAnalyticsConfig` |

키는 **서버 전용**입니다. 브라우저로 노출되면 안 됩니다(`NEXT_PUBLIC_*` 금지).
`@roottale/cms-client`는 브라우저에서 import 시 의도적으로 throw 합니다.

## 패키지 구성 (npm public)

| 패키지 | 역할 |
|---|---|
| [`@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-mcp` | 본 MCP 서버 — 통합 문서·예시 코드·API 조회 tool |

## 문서 맵

| 문서 | 내용 |
|---|---|
| `getting-started.md` | API 키 발급, 환경변수, 패키지 설치, 첫 조회 |
| `blog.md` | 블로그 목록/상세 페이지 구현 (컴포넌트 또는 직접 fetch) |
| `revalidation-webhooks.md` | 발행 웹훅으로 near-real-time 캐시 갱신 |
| `inquiries.md` | 상담문의(리드) 폼 연동 |
| `menus.md` | 메뉴(네비게이션) — 어드민 "디자인 > 메뉴" 트리를 헤더/푸터에 렌더 |
| `seo.md` | RSS 피드, 사이트맵, JSON-LD, 동적 OG 이미지, 공개 검색, fleet 프로브 |
| `theme-and-settings.md` | 디자인 토큰, 블로그 표시 설정, 분석 태그 |
| `api-reference.md` | HTTP API 레퍼런스 (비 JS 스택용 raw 엔드포인트) |

## 권장 연동 순서

1. `getting-started.md` — 키 발급 + 환경 설정
2. `blog.md` — `/blog` 목록·상세 페이지
3. `revalidation-webhooks.md` — 웹훅 등록 (발행 → 즉시 반영)
4. `seo.md` — RSS·사이트맵·동적 OG 이미지
5. `inquiries.md` — 상담문의 폼 (선택)
6. `menus.md` — 어드민 관리 네비게이션 (선택)