@roottale/cms-mcp 0.41.1 → 0.44.0

package/docs/overview.md

@@ -5,12 +5,21 @@ description: 연동 아키텍처, 단일 API 키 모델, 패키지 구성, 문
 
 # RootTale CMS 연동 개요
 
-RootTale CMS는 어드민(`mysite.roottale.com`)에서 콘텐츠를 작성·발행하고, 외부
+RootTale CMS는 어드민(`admin.roottale.com`)에서 콘텐츠를 작성·발행하고, 외부
 고객 사이트(자체 도메인의 Next.js/Astro 등)가 공개 API(`api.roottale.com`)로
 콘텐츠를 가져가는 헤드리스 구조입니다.
 
+## 권장 연동 순서
+
+1. `getting-started.md` — 키 발급 + 환경 설정
+2. `blog.md` — `/blog` 목록·상세 페이지
+3. `revalidation-webhooks.md` — 웹훅 등록 (발행 → 즉시 반영)
+4. `seo.md` — RSS·사이트맵·동적 OG 이미지
+5. `inquiries.md` — 상담문의 폼 (선택)
+6. `menus.md` — 어드민 관리 네비게이션 (선택)
+
 ```
-어드민 (mysite.roottale.com)            고객 사이트 (예: example.com)
+어드민 (admin.roottale.com)            고객 사이트 (예: example.com)
   글 작성·발행 ──────────┐
                          ▼
               api.roottale.com  ◀── Bearer rtlk_cust_* ── 콘텐츠/설정 조회
@@ -53,12 +62,3 @@ RootTale CMS는 어드민(`mysite.roottale.com`)에서 콘텐츠를 작성·발
 | `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` — 어드민 관리 네비게이션 (선택)

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/examples/nextjs/app/blog/[slug]/page.tsx

@@ -41,10 +41,12 @@ export default async function PostPage({ params }: Props) {
 
   return (
     <main>
+      <h1>{post.title}</h1>
       <RootTaleBlogPost
         apiKey={process.env.ROOTTALE_API_KEY!}
         baseUrl={process.env.ROOTTALE_API_BASE}
         slugOrId={post.id}
+        showTitle={false}
       />
     </main>
   );

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@roottale/cms-mcp",
-  "version": "0.41.1",
+  "version": "0.44.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",
+  "description": "RootTale CMS MCP server and CLI for post publishing, media uploads, integration docs, and public API access.",
   "bin": {
     "roottale-cms-mcp": "dist/index.js"
   },
@@ -16,6 +16,8 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "commander": "^13.0.0",
+    "ky": "^1.14.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {