@roottale/cms-mcp 0.41.1 → 0.42.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @roottale/cms-mcp
 
+## 0.42.0
+
+### Patch Changes
+
+- 1cdc365: 어드민 도메인 변경 반영 — 문서·예시의 `mysite.roottale.com` 을 `admin.roottale.com` 으로 갱신 (키 발급·웹훅 등록 메뉴 경로 안내 포함). 기존 주소는 308 redirect 로 계속 동작.
+
 ## 0.41.1
 
 ### Patch Changes

package/README.md

@@ -30,7 +30,7 @@ RootTale CMS 연동 MCP 서버 — AI 코딩 에이전트(Claude Code, Cursor
 
 `ROOTTALE_API_KEY`는 선택입니다 — 문서·예시 코드 tool은 키 없이 동작하고,
 `listPublishedPosts` / `getPublishedPost` (연동 검증) tool만 키가 필요합니다.
-키 발급: 어드민(`mysite.roottale.com`) **설정 > 사이트 연결 키**.
+키 발급: 어드민(`admin.roottale.com`) **설정 > 사이트 연결 키**.
 
 Claude Code:
 

package/dist/index.js

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

@@ -52,7 +52,16 @@ export default function BlogPage() {
 > <RootTaleBlogList apiKey={apiKey} collection="blog" collections={COLLECTIONS} showCategoryFilter />
 > ```
 >
-> 자세한 내용은 `collections.md` 참고.
+> **`/blog` 가 선언 섹션이 아니라 "나머지 전부"인 사이트**(증상/질환/치료 같은
+> 아카이브 스트림만 선언)는 반대로 `collections`+**`excludeCollections`** 로 어느
+> 스트림에도 안 속한 글만 렌더하세요:
+>
+> ```tsx
+> <RootTaleBlogList apiKey={apiKey} collections={ARCHIVE_COLLECTIONS} excludeCollections showCategoryFilter />
+> ```
+>
+> 자세한 내용과 `excludeCollections` 오적용 주의(`blog` 자체가 선언 섹션인 사이트에
+> 쓰면 목록이 빈다)는 `collections.md` 참고.
 
 ### 상세 페이지
 
@@ -120,6 +129,40 @@ export default async function PostPage({
 경우 `@roottale/cms-core` 의 `extractFaqEntries(doc)` / `faqPageJsonLd(entries)`
 로 동일한 JSON-LD 를 생성할 수 있습니다.
 
+### 다국어 (ADR-0052 A안, W4-6 PR C1/C2)
+
+번역 사이트(어드민에서 "번역 추가"로 언어판을 만든 글)는 `RootTaleBlogList`/
+`RootTaleBlogPost`/`RootTalePage` 에 `locale` prop 을 넘기면 그 언어판만
+fetch 합니다(`fetchPosts`/`fetchPost` 의 `locale` 쿼리 그대로 전달). 미지정
+시 서버가 사이트 기본 locale 만 반환합니다(하위호환).
+
+```tsx
+// app/[locale]/blog/[slug]/page.tsx — starter 참조 구현 패턴
+const { locale, slug } = await params;
+<RootTaleBlogPost
+  apiKey={process.env.ROOTTALE_API_KEY!}
+  slugOrId={slug}
+  locale={locale}
+  showTableOfContents
+/>;
+```
+
+- **URL 전략**(권장, starter 참조 구현) — 기본 locale 은 prefix 없는 기존
+  경로(`/blog/{slug}`) 그대로 두고, 나머지 locale 만 `app/[locale]/...` 로
+  별도 트리를 둡니다(`app/[locale]/blog/`·`app/[locale]/blog/[slug]/`·
+  `app/[locale]/[slug]/`). 사이트 활성 locale 목록은 별도 API 없이
+  `fetchBlogSettings().sitemap.locales`(SSoT = `sites.settingsJson.locales`)
+  로 얻습니다 — 첫 원소가 기본 locale.
+- `<head>` hreflang · 사이트맵 hreflang 은 "SEO 연동" 문서(`seo.md`)의
+  "다국어 (hreflang)" 절 참고.
+- **UI 문자열**(cms-i18n, ADR-0034 §3) — `RootTaleBlogList.emptyMessage`/
+  `allCategoriesLabel`, `RootTaleBlogPost.relatedPostsTitle`/미발견 안내,
+  `RootTalePage` 미발견 안내, `RootTaleTableOfContents.title` 은 명시 prop
+  을 안 주면 `locale` prop 기준으로 자동 번역됩니다(`@roottale/cms-i18n`
+  ko/en 사전, `ja`/`zh-hans` 등 사전 없는 locale 은 ko 로 fallback). 글
+  본문·admin UI 는 이 자동 번역 대상이 아닙니다(사람이 직접 작성/ADR-0052
+  범위 밖).
+
 ### 고정 페이지 (회사소개 등)
 
 어드민의 고정 페이지(`type: "page"`)는 `RootTalePage`로 렌더링합니다 — 블로그
@@ -223,7 +266,7 @@ export async function generateMetadata({
 
 입력은 `{ title, description?, date?, image?, seo? }` 형태면 되고
 (`getPost` 의 `BlogPostMeta` 가 그대로 호환), 원본 post 를 쓸 땐
-`seo: (post.metaJson as { seo?: ... }).seo` 로 넘기세요.
+`seo`로 넘길 값은 `(post.metaJson as { seo?: ... }).seo`입니다.
 
 SEO 오버라이드 필드: `title`, `description`, `canonical`, `ogImage`,
 `noindex`, `nofollow`.

package/docs/collections.md

@@ -1,5 +1,5 @@
 ---
-title: 콘텐츠 유형 (Collections) — 공지·블로그 URL 분리
+title: 콘텐츠 유형 (Collections)
 description: 같은 글 풀을 공지 게시판(/notice)·블로그(/blog) 등 여러 섹션으로 나누는 법. 섹션=글의 collection_key, 카테고리=섹션 안의 주제. URL 구조, 어드민 설정, 연동 코드, slug·301·OG.
 ---
 
@@ -55,7 +55,7 @@ description: 같은 글 풀을 공지 게시판(/notice)·블로그(/blog) 등
 > 이전 버전은 *카테고리로 섹션을 추론*했지만, 지금은 섹션이 글에 **명시**됩니다.
 > 카테고리는 더 이상 어느 섹션에 속하는지를 결정하지 않습니다(주제 아카이브 전용).
 
-## 어드민에서 설정 (`mysite.roottale.com`)
+## 어드민에서 설정 (`admin.roottale.com`)
 
 **설정 > 콘텐츠 유형** 에서 섹션을 정의합니다. 빈 상태의 "공지 + 블로그 한 번에 만들기"
 버튼으로 표준 두 섹션을 한 번에 만들 수 있습니다. 각 섹션은:
@@ -198,6 +198,41 @@ export default function BlogPage() {
 `RootTaleBlogCategories` 도 같은 `collection`+`collections` 를 받아 그 섹션의 주제만
 집계합니다. 카테고리 칩/사이드바를 섹션별로 나눌 때 쓰세요.
 
+#### `/blog` 가 선언 섹션이 *아닌* 사이트 — `excludeCollections` (네거티브 스코프)
+
+증상/질환/치료처럼 **아카이브 전용 스트림만 선언하고, 나머지("미소속") 글을
+`/blog` 로 보여주는** 사이트도 있습니다. 이런 사이트는 `blog` 라는 섹션 자체가
+없으므로 `collection="blog"` 로 스코프할 수 없습니다 — 대신 `collections`+
+**`excludeCollections`** 로 "어느 스트림에도 안 속한 글만" 골라냅니다.
+
+```tsx
+// app/blog/page.tsx — 증상/질환/치료 스트림은 따로, 나머지는 블로그
+import { RootTaleBlogList } from "@roottale/cms-renderer-next/server";
+import { ARCHIVE_COLLECTIONS } from "@/lib/collections"; // symptoms/conditions/treatments
+
+export default function BlogPage() {
+  return (
+    <RootTaleBlogList
+      apiKey={process.env.ROOTTALE_API_KEY!}
+      collections={ARCHIVE_COLLECTIONS}
+      excludeCollections
+      showCategoryFilter
+    />
+  );
+}
+```
+
+⚠️ **`blog` 자체가 선언 섹션인 사이트에는 쓰지 마세요.** `collections` 목록에
+`{ key: "blog", ... }` 가 있고 글의 `collectionKey === "blog"` 라면, 그 글은
+"소속 글"로 판정되어 `excludeCollections` 가 오히려 **전부 제외**해 버립니다(빈
+목록). 그런 사이트는 위 "섹션 목록 페이지" 예시처럼 포지티브 `collection="blog"`
+가 정경로입니다.
+
+규칙:
+
+- `collection` 과 `excludeCollections` 동시 지정 = **throw**(포지티브/네거티브 배타).
+- `collections` 없이 `excludeCollections` 만 지정 = **throw**(조용한 no-op 금지).
+
 > 동적 basePath(어드민에서 자유 편집)나 catch-all 라우트를 쓰면 `collection` 값을
 > 요청 경로에서 판정해 넘기세요(아래 "동적 basePath" 참고).
 

package/docs/custom-redirects.md

@@ -5,7 +5,7 @@ description: 어드민 "설정 > 주소 이동"에서 정의한 임의 경로
 
 # 주소 이동 (커스텀 리다이렉트) 연동
 
-어드민(mysite.roottale.com)의 **설정 > 주소 이동**에서 운영자가 정의한 임의
+어드민(admin.roottale.com)의 **설정 > 주소 이동**에서 운영자가 정의한 임의
 경로 이동 규칙(`/old-event → /promo`)을 사이트 미들웨어로 적용합니다. 코드
 수정 없이 고객이 직접 규칙을 추가·수정·삭제할 수 있습니다.
 

package/docs/getting-started.md

@@ -7,7 +7,7 @@ description: API 키 발급, 환경변수 설정, 패키지 설치, 첫 콘텐
 
 ## 1. API 키 발급
 
-1. 어드민(`mysite.roottale.com`) 로그인
+1. 어드민(`admin.roottale.com`) 로그인
 2. **설정 > 사이트 연결 키** 메뉴로 이동
 3. 새 키 발급 — 권한 선택:
    - **read** (기본): 발행된 콘텐츠 조회만. 외부 사이트 연동은 이걸로 충분

package/docs/menus.md

@@ -5,7 +5,7 @@ description: 어드민 "디자인 > 메뉴"에서 관리하는 네비게이션
 
 # 메뉴 (네비게이션) 연동
 
-어드민(mysite.roottale.com)의 **디자인 > 메뉴**에서 저장한 네비게이션 트리를
+어드민(admin.roottale.com)의 **디자인 > 메뉴**에서 저장한 네비게이션 트리를
 사이트의 헤더·푸터에 렌더합니다. 고객이 직접 메뉴 항목(이름·주소·순서·하위
 항목)을 바꿀 수 있어 코드 수정 없이 네비가 갱신됩니다.
 

package/docs/overview.md

@@ -5,12 +5,12 @@ description: 연동 아키텍처, 단일 API 키 모델, 패키지 구성, 문
 
 # RootTale CMS 연동 개요
 
-RootTale CMS는 어드민(`mysite.roottale.com`)에서 콘텐츠를 작성·발행하고, 외부
+RootTale CMS는 어드민(`admin.roottale.com`)에서 콘텐츠를 작성·발행하고, 외부
 고객 사이트(자체 도메인의 Next.js/Astro 등)가 공개 API(`api.roottale.com`)로
 콘텐츠를 가져가는 헤드리스 구조입니다.
 
 ```
-어드민 (mysite.roottale.com)            고객 사이트 (예: example.com)
+어드민 (admin.roottale.com)            고객 사이트 (예: example.com)
   글 작성·발행 ──────────┐
                          ▼
               api.roottale.com  ◀── Bearer rtlk_cust_* ── 콘텐츠/설정 조회

package/docs/seo.md

@@ -105,19 +105,33 @@ export default async function AuthorArchive({
 - `RootTaleBlogList`에 `author={slug}` 를 주면 그 작가의 글만 가져옵니다
   (`GET /v1/cms/public/posts?author={slug}`).
 
-### 다국어 (hreflang)
-
-번역 페이지가 있는 사이트는 어드민 **설정 > 블로그 > 사이트맵**의 "다국어 로케일"에
-언어 코드를 입력하면(예: `ko, ja, en`), 사이트맵의 모든 항목에 `hreflang` 대체 언어
-링크(`<xhtml:link rel="alternate">`)가 붙습니다.
-
-- **첫 번째** 로케일이 기본 언어(현재 URL 그대로) + `x-default`.
-- 나머지는 **경로 접두사**로 매핑됩니다 — `ko`가 기본이면 `ja`는
-  `/ja/blog/{slug}`, `en`은 `/en/blog/{slug}`.
-- 같은 slug에 언어 접두사만 붙는 1:1 구조를 가정합니다. **실제 번역 페이지를
-  그 경로(`/ja/...`)에 서빙하는 것은 사이트 쪽 책임**입니다 — 사이트맵은 검색엔진에
-  대체 언어를 알릴 뿐입니다.
-- 비워두면 단일 언어로 동작합니다(기본).
+### 다국어 (hreflang) — ADR-0052 A안, 콘텐츠 다국어
+
+번역 글이 있는 사이트는 어드민 **설정 > 블로그 > 사이트맵**의 "다국어 로케일"에
+언어 코드를 입력합니다(예: `ko, ja, en`, 첫 번째 = 기본 locale). 사이트맵의
+`blog` 섹션(`GET /sitemap/blog.xml`)이 **글 단위 실제 번역 데이터**로 hreflang
+대체 언어 링크(`<xhtml:link rel="alternate">`)를 계산합니다:
+
+- 공개 API(`GET /v1/cms/public/posts`)가 글마다 `translations`(발행된 언어판
+  목록, 자기 자신 포함)를 내려줍니다. 언어판이 없는 글(자기 자신 1건뿐)은
+  hreflang alternates 자체가 생략됩니다 — 존재하지 않는 URL 을 검색엔진에
+  알리는 사고를 원천 차단합니다(옛 slug 1:1 path-prefix 가정 제거).
+- **기본 locale** = prefix 없는 경로 + `x-default`. 나머지는 **경로 접두사**
+  (`ko`가 기본이면 `ja` 언어판은 `/ja/blog/{그-언어판-실제-slug}`) — 언어판마다
+  **독립된 slug**를 가질 수 있습니다(동일 slug 강제 아님).
+- **실제 번역 라우트를 그 경로(`/ja/...`)에 서빙하는 것은 사이트 쪽 책임**
+  입니다 — starter 참조 구현은 `app/[locale]/blog/`·`app/[locale]/blog/[slug]/`·
+  `app/[locale]/[slug]/`(기본 locale 은 prefix 없는 기존 경로 그대로).
+- **`static`/`categories`/`authors` 섹션은 hreflang alternates 를 붙이지
+  않습니다** — v1 은 블로그 글 + CMS `[slug]` 페이지만 번역 대상이라(nav 정적
+  경로·카테고리 아카이브·작가 아카이브는 locale 라우트 자체가 없음), 옛 방식대로
+  path-prefix 를 씌우면 존재하지 않는 URL 의 hreflang 이 됩니다.
+- 로케일을 비워두면(또는 기본 locale 조차 발행 글 0건이면) 단일 언어로
+  동작합니다(alternates 미부착, fail-closed).
+
+글 상세 `<head>` hreflang 은 `buildPostMetadata`(아래 "글 메타데이터" 절 참고)의
+`locales`/`translations` 옵션으로 계산합니다 — 사이트맵과 같은 원본 데이터
+(`translations[]`)를 씁니다.
 
 ## 다중 스트림 (collections) — 공지·블로그 분리
 
@@ -244,6 +258,37 @@ export async function generateMetadata({ params }: Props): Promise<Metadata> {
 canonical 을 생략합니다(섹션 없는 글은 상세·sitemap에서 제외되는 규칙과 동일).
 단일 블로그 사이트는 기존처럼 `path: "/blog/" + post.slug` 만 주면 됩니다.
 
+### 다국어 hreflang (ADR-0052 A안, W4-6 PR C1)
+
+번역 사이트는 `translations`(글 응답의 `translations[]`)와 `locales` 옵션을
+넘기면 `<head>` 에 양방향 hreflang(+ `x-default`)이 자동으로 붙습니다:
+
+```tsx
+import { buildPostMetadata } from "@roottale/cms-renderer-next/routes";
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { locale, slug } = await params; // app/[locale]/blog/[slug]/page.tsx
+  const post = await getPost(slug, locale);
+  if (!post) return {};
+  return buildPostMetadata(
+    { ...post, translations: post.translations },
+    {
+      siteUrl: process.env.NEXT_PUBLIC_SITE_URL,
+      path: `/${locale}/blog/${post.slug}`,
+      locales: { defaultLocale: "ko" }, // 사이트 활성 locale 의 첫 원소
+    },
+  );
+}
+```
+
+- `pathFor` 를 안 주면 기본값 `기본locale → /blog/{slug}`, `그 외 → /{locale}/blog/{slug}`.
+  블로그가 아닌 라우트(CMS `[slug]` 페이지 등)는 `pathFor` override 필수 —
+  `buildHreflangLanguages(translations, siteUrl, { defaultLocale, pathFor })`
+  를 직접 호출하면 OG `type:"article"` 없이 plain `alternates` 만 조립할 수
+  있습니다.
+- `translations` 가 없거나(구 서버) 자기 자신 1건뿐(번역 없음)이면 `languages`
+  자체가 생략됩니다 — 단일 언어 사이트는 기존 canonical-only 동작 그대로.
+
 ## slug 변경 시 301 리다이렉트
 
 글 slug를 바꿔도 옛 URL이 깨지지 않습니다. API가 slug history로 글을 찾아
@@ -407,9 +452,10 @@ export default async function RootLayout({ children }) {
 - `sameAs`: 어드민에 입력한 네이버플레이스·구글 비즈니스 프로필·카카오 채널
   등의 URL — 검색엔진이 동일 사업장임을 연결합니다.
 
-네이버플레이스(new.smartplace.naver.com)와 구글 비즈니스 프로필
-(business.google.com) 등록 자체는 공개 API가 없어 사장님이 직접 해야 하며,
-어드민 화면에 등록 안내와 프로필 URL 입력란이 있습니다.
+네이버플레이스([new.smartplace.naver.com](https://new.smartplace.naver.com))와
+구글 비즈니스 프로필([business.google.com](https://business.google.com)) 등록
+자체는 공개 API가 없어 사장님이 직접 해야 하며, 어드민 화면에 등록 안내와
+프로필 URL 입력란이 있습니다.
 
 ## Fleet 프로브 (운영 가시성)
 

package/package.json

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