@roottale/cms-mcp/docs/getting-started.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: 시작하기
description: API 키 발급, 환경변수 설정, 패키지 설치, 첫 콘텐츠 조회
---

# 시작하기

## 1. API 키 발급

1. 어드민(`mysite.roottale.com`) 로그인
2. **설정 > 사이트 연결 키** 메뉴로 이동
3. 새 키 발급 — 권한 선택:
   - **read** (기본): 발행된 콘텐츠 조회만. 외부 사이트 연동은 이걸로 충분
   - **read_write**: 쓰기 포함 (자동화 서버용 — 일반 연동에는 불필요)
4. 발급된 키(`rtlk_cust_` + 24자)는 **발급 직후 1회만 평문 표시**됩니다. 바로
   복사해 환경변수에 저장하세요.

키는 사이트 단위로 스코프되어(site-scoped) 해당 사이트의 콘텐츠·웹훅 검증에만
사용됩니다.

## 2. 환경변수

```bash
# .env.local (Next.js) 또는 배포 플랫폼의 환경변수 — 반드시 서버 전용
ROOTTALE_API_KEY=rtlk_cust_xxxxxxxxxxxxxxxxxxxxxxxx

# (선택) API 베이스 오버라이드 — 기본값 https://api.roottale.com 이면 생략
# ROOTTALE_API_BASE=https://api.roottale.com

# 사이트 정식 도메인 (RSS/sitemap/canonical 생성용)
NEXT_PUBLIC_SITE_URL=https://example.com
```

**중요**: `ROOTTALE_API_KEY`는 절대 `NEXT_PUBLIC_*` 접두를 붙이지 마세요.
브라우저로 노출되면 누구나 그 키로 API를 호출할 수 있습니다.
`@roottale/cms-client`는 브라우저에서 실행되면 의도적으로 에러를 던집니다.

## 3. 패키지 설치

```bash
# Next.js 사이트
npm install @roottale/cms-client @roottale/cms-renderer-next
# 또는
pnpm add @roottale/cms-client @roottale/cms-renderer-next
```

요구사항: Node ≥ 18.18, React 19, Next.js 14+ (renderer-next 사용 시).

렌더러 스타일은 root layout에서 1회 import:

```ts
// app/layout.tsx
import "@roottale/cms-renderer-next/styles";
```

예시 코드는 `@/lib/blog` 형태의 import를 사용합니다 — `create-next-app` 기본
설정이면 그대로 동작하고, tsconfig를 직접 구성했다면 paths alias가 필요합니다:

```jsonc
// tsconfig.json > compilerOptions
"paths": { "@/*": ["./*"] }  // 또는 ["./src/*"]
```

## 4. 첫 조회 — 동작 확인

```ts
// 서버 컴포넌트, Route Handler, 또는 빌드 스크립트에서
import { fetchPosts } from "@roottale/cms-client/server";

const page = await fetchPosts({
  apiKey: process.env.ROOTTALE_API_KEY!,
  limit: 5,
  type: "post",
});
console.log(page.items.map((p) => p.slug));
```

응답이 비어 있다면 어드민에서 글이 **발행(published)** 상태인지 확인하세요.
공개 API는 발행된 콘텐츠만 반환합니다.

`401` 에러(`invalid_key`)면 키 값/환경변수 로딩을 확인하세요.

## 다음 단계

- 블로그 페이지 구현 → `blog.md`
- 발행 즉시 사이트 반영 → `revalidation-webhooks.md`