# @roottale/cms-mcp

RootTale CMS 연동 MCP 서버 + CLI — AI 코딩 에이전트(Claude Code, Cursor
등)와 자동화 스크립트가 RootTale CMS의 모델·필드·항목·노출·미디어를 관리하고 외부
사이트에 연동할 수 있게 합니다.

번들 내용:

- **통합 문서** (`docs/`) — 시작하기, 블로그, 발행 웹훅, 상담문의, SEO,
  테마/설정, HTTP API 레퍼런스
- **Next.js 예시 코드** (`examples/nextjs/`) — 블로그 목록/상세, revalidate
  라우트, RSS/사이트맵, 상담문의 서버 액션 등 완전한 연동 1세트
- **CMS 자동화 tool** — 모델·필드 그룹·페이지·글·정보·배너·팝업·미디어 전체 관리
- **SEO 분석 tool** — Google Search Console 상위 검색어, 글별 SEO·가독성
  분석, 발행 글 점수 필터
- **공개 CLI** — 같은 기능을 `npx @roottale/cms-mcp cli ...`로 실행

## 설정

```json
{
  "mcpServers": {
    "roottale-cms": {
      "command": "npx",
      "args": ["-y", "@roottale/cms-mcp"],
      "env": {
        "ROOTTALE_API_KEY": "rtlk_cust_..."
      }
    }
  }
}
```

`ROOTTALE_API_KEY`는 문서·예시 코드 tool만 쓸 때는 생략할 수 있습니다.
콘텐츠 조회에는 `read`, 글쓰기·발행·미디어 업로드에는 `read_write`, 모델·필드·
노출까지 모두 관리하려면 `full_management` 키가
필요합니다. 키 발급: 어드민(`admin.roottale.com`) **설정 > 사이트 연결 키**.

Claude Code:

```bash
claude mcp add roottale-cms -- npx -y @roottale/cms-mcp
```

## CLI 빠른 시작

```bash
export ROOTTALE_API_KEY=rtlk_cust_...

# 본문 삽화/썸네일 업로드
npx -y @roottale/cms-mcp cli media upload ./hero.webp \
  --alt "서비스 소개 대표 이미지"

# 반환된 media id를 썸네일로 연결해 초안 생성
npx -y @roottale/cms-mcp cli entries create \
  --title "자동화로 작성한 글" \
  --slug "automated-post" \
  --body-file ./post.json \
  --featured-media-id "<media-id>"

npx -y @roottale/cms-mcp cli entries publish "<post-id>"
```

상위 `cli --help`는 명령 그룹만 보여줍니다. 전체 리소스는 `models`, `fields`,
`entries`, `exposure-slots`, `exposures`, `media`입니다. 항목의 `list`, `get`,
`create`, `update`, `publish`, `unpublish`, `set-terms`, `delete`는
`cli entries --help`, 미디어의 `list`,
`upload`, `update`, `delete`는 `cli media --help`에서 확인하세요. 각 명령의
옵션은 `cli posts create --help`처럼 하위 명령 뒤에 `--help`를 붙이면 됩니다.

## Tools

| Tool | 설명 |
|---|---|
| `listRootTaleDocs` | 통합 문서 목록 (경로·제목·설명) |
| `readRootTaleDoc` | 문서 1개 읽기 |
| `searchRootTaleDocs` | 문서 전체 정규식 검색 |
| `readRootTaleNextjsExampleCode` | Next.js 연동 예시 코드 전체 |
| `listPublishedPosts` | 공개 API로 발행 글 목록 조회 (키 필요) |
| `getPublishedPost` | 공개 API로 발행 글 1개 조회 (키 필요) |
| `getSiteKnowledge` | 브랜드 보이스·용어 규칙 조회 |
| `listCmsContentModels` 등 | 콘텐츠 모델 조회·생성·수정·상태 변경·삭제 |
| `listCmsFieldGroups` 등 | 모델별 필드 그룹 조회·생성·수정·상태 변경·삭제 |
| `listManagedCmsPosts` | 초안·예약·발행 페이지·글·정보 목록 조회 |
| `getManagedCmsPost` | 관리용 항목 원문 조회 |
| `createCmsPost` | Tiptap JSON으로 글 작성 |
| `updateCmsPost` | 글 제목·본문·요약·썸네일·예약 시각 수정 |
| `publishCmsPost` | 글 즉시 발행 |
| `unpublishCmsPost` | 발행 글을 초안으로 전환 |
| `deleteCmsPost` | 항목 휴지통 이동 또는 영구 삭제 |
| `setCmsPostTerms` | 카테고리 또는 태그 연결 교체 |
| `listCmsExposureSlots` | FRONT 노출 슬롯 계약 조회 |
| `listCmsExposures` 등 | 배너·팝업 캠페인 조회·생성·수정·발행·보관 |
| `listCmsMedia` | 미디어 라이브러리 조회 |
| `uploadCmsMedia` | 로컬 이미지/PDF 업로드 및 media id 발급 |
| `updateCmsMedia` | 대체 텍스트·캡션 수정 |
| `deleteCmsMedia` | 미디어 삭제 |
| `getTopSeoKeywords` | Google Search Console 상위 검색어 조회 |
| `analyzeCmsPostSeo` | ROOT-ADMIN과 같은 규칙으로 글 SEO·가독성 분석 |
| `getCmsPostSeoScores` | 발행 글의 최신 SEO 점수·등급 조회 |
| `listCmsMetadata` | 메타데이터 대상 검색·페이지 조회 |
| `getCmsMetadata` | 직접 설정·자동값·지원 필드·수정 버전 조회 |
| `updateCmsMetadata` | Pro/Premium 메타데이터 부분 변경·자동값 복귀 |

## 사람용 문서 (브라우저 열람)

- **공식 문서 사이트**: <https://roottale.com/docs> — 본 패키지의 `docs/` 를
  렌더한 것 (release 시 자동 갱신)
- 원문 파일: <https://unpkg.com/browse/@roottale/cms-mcp@latest/docs/>
- 예시 코드: <https://unpkg.com/browse/@roottale/cms-mcp@latest/examples/nextjs/>

로컬 설치본에서는 `node_modules/@roottale/cms-mcp/docs/` 를 직접 열면 됩니다.

## License

Proprietary (UNLICENSED). RootTale 고객 계약 하에 제공됩니다.
