UNPKG

@roottale/cms-mcp

Version:

RootTale CMS MCP server and CLI for models, entries, exposures, media, integration docs, and public API access.

288 lines (225 loc) • 13.9 kB
--- title: 시작하기 description: API 키 발급, 환경변수 설정, 패키지 설치, 첫 콘텐츠 조회 --- # 시작하기 ## 1. API 키 발급 1. 어드민(`admin.roottale.com`) 로그인 2. **설정 > 사이트 연결 키** 메뉴로 이동 3. 새 키 발급 — 권한 선택 (괄호 안은 화면에 보이는 이름): - **read** — "읽기" (기본): 공개 콘텐츠와 관리 API의 초안·예약·비공개 글, 미디어 목록을 조회할 수 있음. **완전한 읽기 전용은 아닙니다** — 상담 게시판 글 작성(`POST /v1/cms/public/inquiries`)이 이 권한으로 됩니다(사이트의 상담 폼이 동작하려면 필요). 기존 글·미디어·설정을 고치거나 지우지는 못함 - **read_write** — "읽기 + 쓰기": 위에 더해 글 작성·수정·**발행·발행 취소· 영구 삭제**, 미디어 업로드·**삭제**, 카테고리/태그 생성·**삭제**(딸린 연결까지 cascade). 유출 시 콘텐츠가 지워질 수 있는 권한입니다 - **read_write_settings** — "읽기 + 쓰기 + 설정 변경": 위에 더해 **사이트 설정 쓰기**(사업장 정보·상단 메뉴)와, 수동 갱신 API로 **설정 저장 신호(`theme.updated`) 보내기**. 뒤엣것은 사이트의 모든 페이지를 다시 만들게 하는 신호라 글쓰기 권한과 나눠 두었습니다. 어드민 화면 대신 외부 도구가 가게 이름·주소·전화번호·메뉴를 고쳐야 할 때만 선택하세요. 쓰는 방법은 [HTTP API 레퍼런스의 "설정 쓰기 API"](./api-reference.md#설정-쓰기-api) 4. 발급된 키(`rtlk_cust_` + 24자)는 **발급 직후 1회만 평문 표시**됩니다. 바로 복사해 환경변수에 저장하세요. 발급된 뒤에는 키 목록에서 각 키의 권한 이름과 **실제 scope 전체**를 확인할 수 있습니다("이 키의 권한 자세히"). 설정 변경이 가능하거나 화면이 모르는 scope가 섞인 키는 눈에 띄게 표시됩니다. 키는 사이트 단위로 스코프되어(site-scoped) 해당 사이트의 콘텐츠·웹훅 검증에만 사용됩니다. 권한별 scope는 다음과 같습니다. 넓은 권한은 좁은 권한을 그대로 포함합니다. | 권한 | scope | |---|---| | `read` | `cms:read` | | `read_write` | `cms:read` `cms:write` `post:draft:write` `post:publish` `media:write` `taxonomies:write` | | `read_write_settings` | `read_write` + `settings:write` | > `cms:read`라는 이름과 달리 이 scope 하나로 상담 게시판 글이 **생성**됩니다. > "최소 권한 = 아무것도 못 바꿈"으로 읽지 마세요. `settings:write`는 **새로 발급하는 키에만** 붙습니다. 이미 쓰고 있는 `read_write` 키는 그대로 두어도 동작이 달라지지 않고, 설정 쓰기 권한이 저절로 생기지도 않습니다. ### 발급한 뒤에 권한을 바꾸려면 — 새 키로 교체 발급된 키의 권한은 **나중에 바꿀 수 없습니다.** 예를 들어 `read_write` 키를 쓰다가 설정 쓰기가 필요해졌다면, 그 키에 권한을 더하는 것이 아니라 새 키를 발급해 교체합니다. 순서를 지키면 서비스가 끊기지 않습니다. 1. 어드민 **설정 > 사이트 연결 키**에서 원하는 권한으로 **새 키를 발급**합니다. 이름은 교체 대상과 구분되게 적으세요(예: `운영 서버 2026-07`). 목록에 붙는 권한 이름으로 어떤 키를 교체해야 하는지 찾을 수 있습니다. 2. 배포 환경의 `ROOTTALE_API_KEY`를 새 키로 바꾸고 **재배포**합니다. (환경변수만 바꾸고 재배포하지 않으면 옛 키가 계속 쓰입니다.) 3. 사이트가 정상 동작하는지 확인합니다 — 글 목록이 보이는지, 자동화가 `401 invalid_key` 없이 도는지. 4. 목록의 **최근 사용**(날짜 + 시각)이 교체 시점 이후로 갱신되지 않는지 확인한 뒤 삭제합니다. 판정 기준은 **그 키의 정상 호출 주기를 한 번 넘길 때까지 관찰** 입니다 — 하루 한 번 도는 배치라면 하루, ISR 재검증이 30분이면 30분. 배포가 여러 곳(프리뷰·스테이징·사내 도구)이면 전부 교체됐는지 함께 봅니다. 옛 키를 먼저 지우면 그 사이 요청이 `401 invalid_key`로 실패합니다. 같은 절차를 키 유출이 의심될 때도 씁니다. 다만 그때는 순서를 뒤집어, 옛 키를 먼저 삭제하고 새 키로 교체하세요 — 잠깐의 중단보다 유출된 키가 살아 있는 쪽이 위험합니다. ## 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 관리자에서 IndexNow를 켰을 때 발급된 검증 키 INDEXNOW_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` **중요**: `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 사용 시). 사이트 이미지에는 `@roottale/cms-media/react`의 `RootTaleImage`를 사용합니다. 이는 공용 네이티브 img 컴포넌트로, CF Images에서 반응형 이미지를 직접 전달합니다. 새 export는 해당 변경을 포함한 패키지 릴리스 후 사용할 수 있습니다. ```tsx import { RootTaleImage } from "@roottale/cms-media/react"; <RootTaleImage src={coverUrl} alt="대표 이미지" width={800} height={556} sizes="(max-width: 880px) calc(100vw - 36px), 840px" /> ``` 이미지 사용 사이트는 `@roottale/cms-media`를 직접 의존성으로 설치합니다. CF Flexible variants가 필요하며 `next/image`·Vercel 변환은 사용하지 않습니다. 등록된 R2·로컬 자산의 매핑은 사이트에 두고 `@roottale/cms-media/delivery`의 `createImageDelivery`로 `imageAttributes`·`fallbackSrc`만 계산합니다. CMS 저장 주소와 원본은 유지합니다. 정적 import·ref·fill·priority도 지원합니다. 기존 `CfImage`·default export는 호환성을 유지합니다. 분류 선택·공개 콘텐츠 정책 API는 SDK **0.69.0부터** 제공합니다. 이 API를 직접 사용하는 사이트는 `@roottale/cms-core`도 직접 의존성으로 설치하고 세 패키지의 버전을 맞추세요. ```bash pnpm add @roottale/cms-client@0.69.0 @roottale/cms-renderer-next@0.69.0 @roottale/cms-core@0.69.0 ``` 렌더러 스타일은 root layout에서 1회 import: ```ts // app/layout.tsx import "@roottale/cms-renderer-next/styles"; ``` 기본 본문은 720px 폭, 18px/1.7이며 768px 미만에서는 17px입니다. 글 제목은 데스크톱 44px/700/1.3, 모바일 28px/600/1.3입니다. 본문 H2/H3/H4는 데스크톱 32/24/20px, 모바일 22/20/18px입니다. 제목 아래 메타 정보 간격은 12px이며, H2 위 48px·아래 20px(모바일 16px), H3 위 32px·아래 12px, H4 위 24px·아래 8px를 사용합니다. Pretendard 가변 글꼴을 스타일 패키지에 포함합니다. 고객 글꼴은 `--rt-font-body`, 본문 폭은 `--rt-cms-measure`, 크기는 `--rt-cms-body-size`로 조정할 수 있습니다. 독립 본문은 `<div data-roottale-cms="body">`로 감싸면 같은 서식을 적용합니다. CMS 편집 화면과 같은 간격을 쓰려면 이 범위의 글자 크기·행간·문단 여백을 사이트 CSS에서 다시 덮어쓰지 않습니다. 일반 문단 뒤는 16px, 목록 항목 사이는 8px입니다. 가져온 HTML은 `.rt-imported-html` 범위를 유지해 원문의 줄·빈 문단에 기본 여백을 중복으로 더하지 않습니다. 직접 지정한 문단 여백은 유지합니다. 목록의 `li` reset도 복원하며, 제목 안의 고정 크기 마크는 제목의 반응형 크기를 따릅니다. 일반 문단의 인라인 크기·행간 설정은 데스크톱에서 유지하고, 모바일에서는 본문과 소제목의 크기·행간을 따릅니다. 색상·강조는 유지됩니다. 본문 링크의 밑줄은 hover·active·키보드 focus 때 표시되고, 동작 줄이기 설정을 존중합니다. 본문 이미지는 읽기 폭까지 표시하며 `RootTaleBlogPost`에서는 클릭·Enter·Space로 확대됩니다. 확대 화면은 2배 확대, Esc·닫기, 원래 이미지로 포커스 복귀를 지원합니다. 이미 링크나 버튼인 이미지는 기존 동작을 유지하며, `data-no-zoom`으로 제외할 수 있습니다. `data-fullsize-src`가 있으면 확대 이미지의 주소로 사용합니다. 독립 HTML·`RenderTiptap`에는 다음 클라이언트 경계를 감싸 사용합니다. ```tsx import { RootTaleImageLightbox } from "@roottale/cms-renderer-next/image-lightbox"; <div data-roottale-cms="body"> <RootTaleImageLightbox> <RenderTiptap doc={doc} /> </RootTaleImageLightbox> </div> ``` `tocPosition="sidebar"` 목차는 넓은 화면에서 고정됩니다. 모바일 목차는 접었을 때 기본 높이가 52px입니다. `--rt-cms-scroll-offset`을 헤더 높이보다 크게 지정하세요. 조상 요소의 `overflow: hidden/auto`는 별도 스크롤 기준을 만들므로 화면 기준 sticky가 필요하면 불필요한 overflow를 제거하거나 `overflow: clip`을 사용하세요. 예시 코드는 `@/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`)면 키 값/환경변수 로딩을 확인하세요. ## 5. MCP로 전체 CMS 자동화 MCP 설정의 `ROOTTALE_API_KEY`에 `full_management` 키를 넣으면 모델·필드·항목· 노출·미디어 도구를 모두 쓸 수 있습니다. 글과 이미지만 관리한다면 기존 `read_write` 키로 충분합니다. 1. `getSiteKnowledge`로 브랜드 보이스와 금지어 확인 2. `uploadCmsMedia`로 썸네일 또는 본문 삽화 업로드 3. `createCmsPost`로 Tiptap JSON 초안 생성 4. 필요하면 `setCmsPostTerms`로 카테고리·태그 연결 5. 검토 후 `publishCmsPost`로 발행 정보 모델을 새로 자동화할 때는 `createCmsContentModel` → `createCmsFieldGroup` → `createCmsPost(modelKey, fieldValues)` 순서로 진행합니다. 배너·팝업은 `listCmsExposureSlots`로 FRONT 계약을 먼저 읽고 `createCmsExposure` → `publishCmsExposure` 순서로 진행합니다. 썸네일은 업로드 응답의 `id`를 `featuredMediaId`에 넣습니다. 본문 삽화는 응답의 `url`을 Tiptap image 노드에 넣습니다. ```json { "type": "image", "attrs": { "src": "https://media.example.com/tenant/site/image.webp", "alt": "서비스 진행 과정을 설명하는 삽화", "title": null } } ``` 안전한 기본값은 초안입니다. 사용자가 즉시 발행을 명시하지 않았다면 `createCmsPost`의 `publish`를 생략하고 검토 뒤 발행하세요. ## 6. CLI로 자동화 별도 전역 설치 없이 공개 MCP 패키지의 CLI 모드를 사용할 수 있습니다. ```bash export ROOTTALE_API_KEY=rtlk_cust_xxxxxxxxxxxxxxxxxxxxxxxx npx -y @roottale/cms-mcp cli media upload ./thumbnail.webp \ --alt "글 대표 이미지" npx -y @roottale/cms-mcp cli entries create \ --title "새 글" \ --slug "new-post" \ --body-file ./post.json \ --featured-media-id "<업로드 응답의 id>" npx -y @roottale/cms-mcp cli entries publish "<글 id>" ``` 상위 `cli --help`는 `models`, `fields`, `entries`, `exposure-slots`, `exposures`, `media` 그룹을 보여줍니다. 전체 하위 명령은 다음 도움말에서 확인하세요. ```bash npx -y @roottale/cms-mcp cli entries --help npx -y @roottale/cms-mcp cli models --help npx -y @roottale/cms-mcp cli exposures --help npx -y @roottale/cms-mcp cli media --help # 특정 명령의 모든 옵션 npx -y @roottale/cms-mcp cli entries create --help npx -y @roottale/cms-mcp cli media upload --help ``` 항목 명령은 `list`, `get`, `create`, `update`, `publish`, `unpublish`, `set-terms`, `delete`, 미디어 명령은 `list`, `upload`, `update`, `delete`를 제공합니다. 내부 운영 저장소에서는 같은 기능을 `rt cms entries ...`, `rt cms media ...` 명령으로도 실행할 수 있습니다. ## 다음 단계 - 블로그 페이지 구현 → `blog.md` - 발행 즉시 사이트 반영 → `revalidation-webhooks.md` - 설정(디자인·메뉴·사업장 정보) 저장 즉시 반영 → `revalidation-webhooks.md` §1 "설정 저장" + `theme-and-settings.md` (수신 라우트의 `revalidateTag` 주입과 조회의 `tags` 를 **둘 다** 해야 합니다) - HTTP 자동화 엔드포인트 → `api-reference.md`