@roottale/cms-mcp 0.22.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# @roottale/cms-mcp
+
+> cms-* linked 그룹과 버전을 함께 올린다. 변경 시 `pnpm changeset` 으로
+> 업데이트 로그를 남기면 Version Packages PR 이 본 파일에 자동 반영한다.
+
+## 0.22.0
+
+- 최초 릴리스 — RootTale CMS 연동 MCP 서버 (stdio). cms-* 라인(renderer-next
+  0.22.0)에 버전 정렬.
+  - `blog.md`에 고정 페이지 렌더러 `RootTalePage` (renderer-next 0.22.0) 반영
+  - 통합 문서 번들 (`docs/`): 개요, 시작하기, 블로그, 발행 웹훅, 상담문의,
+    SEO, 테마/설정, HTTP API 레퍼런스
+  - Next.js 연동 예시 코드 번들 (`examples/nextjs/`)
+  - Tools: `listRootTaleDocs`, `readRootTaleDoc`, `searchRootTaleDocs`,
+    `readRootTaleNextjsExampleCode`, `listPublishedPosts`, `getPublishedPost`

package/README.md

@@ -0,0 +1,59 @@
+# @roottale/cms-mcp
+
+RootTale CMS 연동 MCP 서버 — AI 코딩 에이전트(Claude Code, Cursor 등)가
+통합 문서를 하나하나 복사해 붙여넣지 않고도 RootTale CMS를 외부 사이트에
+연동할 수 있게 합니다.
+
+번들 내용:
+
+- **통합 문서** (`docs/`) — 시작하기, 블로그, 발행 웹훅, 상담문의, SEO,
+  테마/설정, HTTP API 레퍼런스
+- **Next.js 예시 코드** (`examples/nextjs/`) — 블로그 목록/상세, revalidate
+  라우트, RSS/사이트맵, 상담문의 서버 액션 등 완전한 연동 1세트
+- **공개 API 조회 tool** — 연동 검증용 발행 글 목록/상세 조회
+
+## 설정
+
+```json
+{
+  "mcpServers": {
+    "roottale-cms": {
+      "command": "npx",
+      "args": ["-y", "@roottale/cms-mcp"],
+      "env": {
+        "ROOTTALE_API_KEY": "rtlk_cust_..."
+      }
+    }
+  }
+}
+```
+
+`ROOTTALE_API_KEY`는 선택입니다 — 문서·예시 코드 tool은 키 없이 동작하고,
+`listPublishedPosts` / `getPublishedPost` (연동 검증) tool만 키가 필요합니다.
+키 발급: 어드민(`mysite.roottale.com`) **설정 > 사이트 연결 키**.
+
+Claude Code:
+
+```bash
+claude mcp add roottale-cms -- npx -y @roottale/cms-mcp
+```
+
+## Tools
+
+| Tool | 설명 |
+|---|---|
+| `listRootTaleDocs` | 통합 문서 목록 (경로·제목·설명) |
+| `readRootTaleDoc` | 문서 1개 읽기 |
+| `searchRootTaleDocs` | 문서 전체 정규식 검색 |
+| `readRootTaleNextjsExampleCode` | Next.js 연동 예시 코드 전체 |
+| `listPublishedPosts` | 공개 API로 발행 글 목록 조회 (키 필요) |
+| `getPublishedPost` | 공개 API로 발행 글 1개 조회 (키 필요) |
+
+## 사람용 문서
+
+문서 원문은 패키지의 [`docs/`](./docs/overview.md) 폴더에서 직접 읽을 수
+있습니다. 진입점: `docs/overview.md`.
+
+## License
+
+Proprietary (UNLICENSED). RootTale 고객 계약 하에 제공됩니다.

package/dist/index.js

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+
+// src/tools.ts
+import {
+  CallToolRequestSchema,
+  ErrorCode,
+  ListToolsRequestSchema,
+  McpError
+} from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+
+// src/docs.ts
+import { readdir, readFile } from "fs/promises";
+import path from "path";
+import { fileURLToPath } from "url";
+var PKG_ROOT = fileURLToPath(new URL("..", import.meta.url));
+var DOCS_ROOT = path.join(PKG_ROOT, "docs");
+var EXAMPLES_ROOT = path.join(PKG_ROOT, "examples");
+function parseFrontmatter(markdown) {
+  const result = { title: "", description: "" };
+  const match = markdown.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return result;
+  for (const line of match[1].split("\n")) {
+    const idx = line.indexOf(":");
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    const value = line.slice(idx + 1).trim();
+    if (key === "title") result.title = value;
+    if (key === "description") result.description = value;
+  }
+  return result;
+}
+async function walkFiles(root, dir = root) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await walkFiles(root, full));
+    } else {
+      files.push(path.relative(root, full));
+    }
+  }
+  return files.sort();
+}
+async function listDocs() {
+  const files = (await walkFiles(DOCS_ROOT)).filter((f) => f.endsWith(".md"));
+  return Promise.all(
+    files.map(async (rel) => {
+      const content = await readFile(path.join(DOCS_ROOT, rel), "utf8");
+      const fm = parseFrontmatter(content);
+      return { path: rel, title: fm.title || rel, description: fm.description };
+    })
+  );
+}
+async function readDoc(relPath) {
+  const resolved = path.resolve(DOCS_ROOT, relPath);
+  if (!resolved.startsWith(DOCS_ROOT + path.sep)) return null;
+  try {
+    return await readFile(resolved, "utf8");
+  } catch {
+    return null;
+  }
+}
+async function searchDocs(query) {
+  const regex = new RegExp(query, "i");
+  const matches = [];
+  for (const doc of await listDocs()) {
+    const content = await readDoc(doc.path);
+    if (!content) continue;
+    content.split("\n").forEach((text, idx) => {
+      if (regex.test(text)) {
+        matches.push({ path: doc.path, line: idx + 1, text: text.trim() });
+      }
+    });
+  }
+  return matches;
+}
+async function readNextjsExampleCode() {
+  const root = path.join(EXAMPLES_ROOT, "nextjs");
+  const files = await walkFiles(root);
+  const sections = await Promise.all(
+    files.map(async (rel) => {
+      const content = await readFile(path.join(root, rel), "utf8");
+      return `--- FILE: ${rel} ---
+${content}`;
+    })
+  );
+  return sections.join("\n\n");
+}
+
+// src/tools.ts
+var DEFAULT_API_BASE = "https://api.roottale.com";
+var ReadDocInput = z.object({ path: z.string().min(1) }).strict();
+var SearchDocsInput = z.object({ query: z.string().min(1) }).strict();
+var ListPostsInput = z.object({
+  limit: z.number().int().min(1).max(100).optional(),
+  type: z.enum(["post", "page"]).optional(),
+  cursor: z.string().optional()
+}).strict();
+var GetPostInput = z.object({ slugOrId: z.string().min(1) }).strict();
+var TOOL_DEFINITIONS = [
+  {
+    name: "listRootTaleDocs",
+    description: "RootTale CMS \uD1B5\uD569 \uBB38\uC11C \uC804\uCCB4 \uBAA9\uB85D(\uACBD\uB85C\xB7\uC81C\uBAA9\xB7\uC124\uBA85)\uC744 \uBC18\uD658\uD569\uB2C8\uB2E4. RootTale \uC5F0\uB3D9 \uC791\uC5C5\uC744 \uC2DC\uC791\uD558\uAE30 \uC804 \uAC00\uC7A5 \uBA3C\uC800 \uD638\uCD9C\uD558\uC138\uC694.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false }
+  },
+  {
+    name: "readRootTaleDoc",
+    description: "RootTale CMS \uD1B5\uD569 \uBB38\uC11C 1\uAC1C\uB97C \uACBD\uB85C\uB85C \uC77D\uC2B5\uB2C8\uB2E4. \uACBD\uB85C\uB294 listRootTaleDocs \uAC00 \uBC18\uD658\uD55C path \uAC12\uC744 \uC0AC\uC6A9\uD558\uC138\uC694.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "\uBB38\uC11C \uACBD\uB85C (\uC608: blog.md)" }
+      },
+      required: ["path"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "searchRootTaleDocs",
+    description: "RootTale CMS \uD1B5\uD569 \uBB38\uC11C \uC804\uCCB4\uC5D0\uC11C \uC815\uADDC\uC2DD\uC73C\uB85C \uAC80\uC0C9\uD569\uB2C8\uB2E4 (\uB300\uC18C\uBB38\uC790 \uBB34\uC2DC). \uB9E4\uCE58\uB41C \uD30C\uC77C \uACBD\uB85C\xB7\uB77C\uC778 \uBC88\uD638\xB7\uB77C\uC778 \uB0B4\uC6A9\uC744 \uBC18\uD658\uD569\uB2C8\uB2E4.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "\uC815\uADDC\uC2DD \uD328\uD134 (\uC608: revalidate|webhook)" }
+      },
+      required: ["query"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "readRootTaleNextjsExampleCode",
+    description: "RootTale CMS\uB97C \uC678\uBD80 Next.js(App Router) \uC0AC\uC774\uD2B8\uC5D0 \uC5F0\uB3D9\uD558\uB294 \uC644\uC804\uD55C \uC608\uC2DC \uCF54\uB4DC \uC138\uD2B8\uB97C \uBC18\uD658\uD569\uB2C8\uB2E4 (\uBE14\uB85C\uADF8 \uBAA9\uB85D/\uC0C1\uC138, \uC6F9\uD6C5 revalidate \uB77C\uC6B0\uD2B8, RSS/\uC0AC\uC774\uD2B8\uB9F5, \uC0C1\uB2F4\uBB38\uC758 \uC11C\uBC84 \uC561\uC158 \uB4F1). \uC5F0\uB3D9 \uCF54\uB4DC\uB97C \uC791\uC131\uD558\uAE30 \uC804 \uBC18\uB4DC\uC2DC \uD638\uCD9C\uD574 \uD328\uD134\uC744 \uB530\uB77C \uC791\uC131\uD558\uC138\uC694.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false }
+  },
+  {
+    name: "listPublishedPosts",
+    description: "\uC5F0\uB3D9 \uAC80\uC99D\uC6A9 \u2014 RootTale \uACF5\uAC1C CMS API(GET /v1/cms/public/posts)\uB85C \uBC1C\uD589\uB41C \uAE00 \uBAA9\uB85D\uC744 \uC870\uD68C\uD569\uB2C8\uB2E4. \uD658\uACBD\uBCC0\uC218 ROOTTALE_API_KEY(rtlk_cust_*)\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "number", description: "1-100, \uAE30\uBCF8 20" },
+        type: { type: "string", enum: ["post", "page"] },
+        cursor: { type: "string", description: "\uC774\uC804 \uC751\uB2F5\uC758 next_cursor" }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: "getPublishedPost",
+    description: "\uC5F0\uB3D9 \uAC80\uC99D\uC6A9 \u2014 RootTale \uACF5\uAC1C CMS API(GET /v1/cms/public/posts/:identifier)\uB85C \uBC1C\uD589\uB41C \uAE00 1\uAC1C\uB97C slug \uB610\uB294 UUID\uB85C \uC870\uD68C\uD569\uB2C8\uB2E4. \uD658\uACBD\uBCC0\uC218 ROOTTALE_API_KEY(rtlk_cust_*)\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        slugOrId: { type: "string", description: "\uAE00 slug \uB610\uB294 UUID" }
+      },
+      required: ["slugOrId"],
+      additionalProperties: false
+    }
+  }
+];
+function requireApiKey() {
+  const apiKey = process.env.ROOTTALE_API_KEY;
+  if (!apiKey) {
+    throw new McpError(
+      ErrorCode.InvalidRequest,
+      "ROOTTALE_API_KEY \uD658\uACBD\uBCC0\uC218\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4. MCP \uC11C\uBC84 \uC124\uC815\uC758 env\uC5D0 rtlk_cust_* \uD0A4\uB97C \uCD94\uAC00\uD558\uC138\uC694 (\uBC1C\uAE09: \uC5B4\uB4DC\uBBFC \uC124\uC815 > \uC0AC\uC774\uD2B8 \uC5F0\uACB0 \uD0A4)."
+    );
+  }
+  const baseUrl = (process.env.ROOTTALE_API_BASE ?? DEFAULT_API_BASE).replace(/\/+$/, "");
+  return { apiKey, baseUrl };
+}
+async function fetchPublicApi(pathname, params) {
+  const { apiKey, baseUrl } = requireApiKey();
+  const url = new URL(`${baseUrl}${pathname}`);
+  for (const [key, value] of Object.entries(params ?? {})) {
+    url.searchParams.set(key, value);
+  }
+  const response = await fetch(url, {
+    headers: { authorization: `Bearer ${apiKey}` }
+  });
+  const body = await response.text();
+  if (!response.ok) {
+    throw new Error(`RootTale API ${response.status}: ${body.slice(0, 500)}`);
+  }
+  return JSON.parse(body);
+}
+function textResponse(text) {
+  return { content: [{ type: "text", text }] };
+}
+function jsonResponse(value) {
+  return textResponse(JSON.stringify(value, null, 2));
+}
+function registerTools(server2) {
+  server2.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOL_DEFINITIONS.map((t) => ({ ...t }))
+  }));
+  server2.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const args = request.params.arguments ?? {};
+    try {
+      switch (request.params.name) {
+        case "listRootTaleDocs":
+          return jsonResponse(await listDocs());
+        case "readRootTaleDoc": {
+          const input = ReadDocInput.parse(args);
+          const content = await readDoc(input.path);
+          if (content === null) {
+            throw new McpError(
+              ErrorCode.InvalidParams,
+              `\uBB38\uC11C\uB97C \uCC3E\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4: ${input.path} \u2014 listRootTaleDocs\uB85C \uACBD\uB85C\uB97C \uD655\uC778\uD558\uC138\uC694.`
+            );
+          }
+          return textResponse(content);
+        }
+        case "searchRootTaleDocs": {
+          const input = SearchDocsInput.parse(args);
+          return jsonResponse(await searchDocs(input.query));
+        }
+        case "readRootTaleNextjsExampleCode":
+          return textResponse(await readNextjsExampleCode());
+        case "listPublishedPosts": {
+          const input = ListPostsInput.parse(args);
+          const params = {};
+          if (input.limit) params.limit = String(input.limit);
+          if (input.type) params.type = input.type;
+          if (input.cursor) params.cursor = input.cursor;
+          return jsonResponse(await fetchPublicApi("/v1/cms/public/posts", params));
+        }
+        case "getPublishedPost": {
+          const input = GetPostInput.parse(args);
+          return jsonResponse(
+            await fetchPublicApi(
+              `/v1/cms/public/posts/${encodeURIComponent(input.slugOrId)}`
+            )
+          );
+        }
+        default:
+          throw new McpError(
+            ErrorCode.InvalidParams,
+            `Unknown RootTale tool: ${request.params.name}`
+          );
+      }
+    } catch (error) {
+      if (error instanceof McpError) throw error;
+      const message = error instanceof Error ? error.message : String(error);
+      return { isError: true, content: [{ type: "text", text: message }] };
+    }
+  });
+}
+
+// src/server.ts
+var VERSION = true ? "0.22.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.
+
+\uC9C0\uCF1C\uC57C \uD560 \uADDC\uCE59:
+- RootTale \uC5F0\uB3D9 \uAD00\uB828 \uC791\uC5C5\uC740 \uAC00\uC7A5 \uBA3C\uC800 listRootTaleDocs\uB97C \uD638\uCD9C\uD574 \uBB38\uC11C \uBAA9\uB85D\uC744 \uD30C\uC545\uD558\uC138\uC694.
+- \uC5F0\uB3D9 \uCF54\uB4DC\uB97C \uC791\uC131\uD558\uAE30 \uC804 \uBC18\uB4DC\uC2DC readRootTaleNextjsExampleCode\uB97C \uD638\uCD9C\uD574 \uC608\uC2DC \uCF54\uB4DC\uB97C
+  \uCC38\uACE0\uD55C \uD6C4 \uADF8 \uD328\uD134\uC744 \uB530\uB77C \uC791\uC131\uD558\uC138\uC694.
+- API \uD0A4(rtlk_cust_*)\uB294 \uC11C\uBC84 \uC804\uC6A9\uC785\uB2C8\uB2E4. NEXT_PUBLIC_* \uB4F1 \uBE0C\uB77C\uC6B0\uC800\uB85C \uB178\uCD9C\uB418\uB294
+  \uD658\uACBD\uBCC0\uC218\uC5D0 \uC808\uB300 \uB123\uC9C0 \uB9C8\uC138\uC694.
+- \uC774\uBBF8 \uD559\uC2B5\uB41C \uB0B4\uC6A9\uC774\uB354\uB77C\uB3C4 \uBCF8 \uC11C\uBC84\uC758 \uBB38\uC11C\uB85C \uB354\uBE14\uCCB4\uD06C \uD6C4 \uC791\uC5C5\uD558\uC138\uC694.
+`.trim();
+function createServer() {
+  const server2 = new Server(
+    { name: "roottale-cms", version: VERSION },
+    { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS }
+  );
+  registerTools(server2);
+  return server2;
+}
+
+// src/index.ts
+var server = createServer();
+var transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/server.ts","../src/tools.ts","../src/docs.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\n\nimport { createServer } from \"./server.js\";\n\nconst server = createServer();\nconst transport = new StdioServerTransport();\nawait server.connect(transport);\n","import { Server } from \"@modelcontextprotocol/sdk/server/index.js\";\n\nimport { registerTools } from \"./tools.js\";\n\n// tsup define 으로 빌드타임 주입 — 비번들 실행(vitest 등)에서는 \"dev\".\ndeclare const __CMS_MCP_VERSION__: string | undefined;\nconst VERSION =\n  typeof __CMS_MCP_VERSION__ === \"string\" ? __CMS_MCP_VERSION__ : \"dev\";\n\nexport const SERVER_INSTRUCTIONS = `\nroottale-cms-mcp는 RootTale CMS를 외부 사이트(주로 Next.js)에 연동하기 위한\n통합 문서·예시 코드·공개 API 조회 tool을 제공합니다.\n\n지켜야 할 규칙:\n- RootTale 연동 관련 작업은 가장 먼저 listRootTaleDocs를 호출해 문서 목록을 파악하세요.\n- 연동 코드를 작성하기 전 반드시 readRootTaleNextjsExampleCode를 호출해 예시 코드를\n  참고한 후 그 패턴을 따라 작성하세요.\n- API 키(rtlk_cust_*)는 서버 전용입니다. NEXT_PUBLIC_* 등 브라우저로 노출되는\n  환경변수에 절대 넣지 마세요.\n- 이미 학습된 내용이더라도 본 서버의 문서로 더블체크 후 작업하세요.\n`.trim();\n\nexport function createServer(): Server {\n  const server = new Server(\n    { name: \"roottale-cms\", version: VERSION },\n    { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS },\n  );\n  registerTools(server);\n  return server;\n}\n","import type { Server } from \"@modelcontextprotocol/sdk/server/index.js\";\nimport {\n  CallToolRequestSchema,\n  ErrorCode,\n  ListToolsRequestSchema,\n  McpError,\n} from \"@modelcontextprotocol/sdk/types.js\";\nimport { z } from \"zod\";\n\nimport { listDocs, readDoc, readNextjsExampleCode, searchDocs } from \"./docs.js\";\n\nconst DEFAULT_API_BASE = \"https://api.roottale.com\";\n\nconst ReadDocInput = z.object({ path: z.string().min(1) }).strict();\nconst SearchDocsInput = z.object({ query: z.string().min(1) }).strict();\nconst ListPostsInput = z\n  .object({\n    limit: z.number().int().min(1).max(100).optional(),\n    type: z.enum([\"post\", \"page\"]).optional(),\n    cursor: z.string().optional(),\n  })\n  .strict();\nconst GetPostInput = z.object({ slugOrId: z.string().min(1) }).strict();\n\nexport const TOOL_DEFINITIONS = [\n  {\n    name: \"listRootTaleDocs\",\n    description:\n      \"RootTale CMS 통합 문서 전체 목록(경로·제목·설명)을 반환합니다. \" +\n      \"RootTale 연동 작업을 시작하기 전 가장 먼저 호출하세요.\",\n    inputSchema: { type: \"object\", properties: {}, additionalProperties: false },\n  },\n  {\n    name: \"readRootTaleDoc\",\n    description:\n      \"RootTale CMS 통합 문서 1개를 경로로 읽습니다. \" +\n      \"경로는 listRootTaleDocs 가 반환한 path 값을 사용하세요.\",\n    inputSchema: {\n      type: \"object\",\n      properties: {\n        path: { type: \"string\", description: \"문서 경로 (예: blog.md)\" },\n      },\n      required: [\"path\"],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: \"searchRootTaleDocs\",\n    description:\n      \"RootTale CMS 통합 문서 전체에서 정규식으로 검색합니다 (대소문자 무시). \" +\n      \"매치된 파일 경로·라인 번호·라인 내용을 반환합니다.\",\n    inputSchema: {\n      type: \"object\",\n      properties: {\n        query: { type: \"string\", description: \"정규식 패턴 (예: revalidate|webhook)\" },\n      },\n      required: [\"query\"],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: \"readRootTaleNextjsExampleCode\",\n    description:\n      \"RootTale CMS를 외부 Next.js(App Router) 사이트에 연동하는 완전한 예시 코드 세트를 반환합니다 \" +\n      \"(블로그 목록/상세, 웹훅 revalidate 라우트, RSS/사이트맵, 상담문의 서버 액션 등). \" +\n      \"연동 코드를 작성하기 전 반드시 호출해 패턴을 따라 작성하세요.\",\n    inputSchema: { type: \"object\", properties: {}, additionalProperties: false },\n  },\n  {\n    name: \"listPublishedPosts\",\n    description:\n      \"연동 검증용 — RootTale 공개 CMS API(GET /v1/cms/public/posts)로 발행된 글 목록을 조회합니다. \" +\n      \"환경변수 ROOTTALE_API_KEY(rtlk_cust_*)가 필요합니다.\",\n    inputSchema: {\n      type: \"object\",\n      properties: {\n        limit: { type: \"number\", description: \"1-100, 기본 20\" },\n        type: { type: \"string\", enum: [\"post\", \"page\"] },\n        cursor: { type: \"string\", description: \"이전 응답의 next_cursor\" },\n      },\n      additionalProperties: false,\n    },\n  },\n  {\n    name: \"getPublishedPost\",\n    description:\n      \"연동 검증용 — RootTale 공개 CMS API(GET /v1/cms/public/posts/:identifier)로 발행된 글 1개를 \" +\n      \"slug 또는 UUID로 조회합니다. 환경변수 ROOTTALE_API_KEY(rtlk_cust_*)가 필요합니다.\",\n    inputSchema: {\n      type: \"object\",\n      properties: {\n        slugOrId: { type: \"string\", description: \"글 slug 또는 UUID\" },\n      },\n      required: [\"slugOrId\"],\n      additionalProperties: false,\n    },\n  },\n] as const;\n\nfunction requireApiKey(): { apiKey: string; baseUrl: string } {\n  const apiKey = process.env.ROOTTALE_API_KEY;\n  if (!apiKey) {\n    throw new McpError(\n      ErrorCode.InvalidRequest,\n      \"ROOTTALE_API_KEY 환경변수가 없습니다. MCP 서버 설정의 env에 \" +\n        \"rtlk_cust_* 키를 추가하세요 (발급: 어드민 설정 > 사이트 연결 키).\",\n    );\n  }\n  const baseUrl = (process.env.ROOTTALE_API_BASE ?? DEFAULT_API_BASE).replace(/\\/+$/, \"\");\n  return { apiKey, baseUrl };\n}\n\nasync function fetchPublicApi(pathname: string, params?: Record<string, string>): Promise<unknown> {\n  const { apiKey, baseUrl } = requireApiKey();\n  const url = new URL(`${baseUrl}${pathname}`);\n  for (const [key, value] of Object.entries(params ?? {})) {\n    url.searchParams.set(key, value);\n  }\n  const response = await fetch(url, {\n    headers: { authorization: `Bearer ${apiKey}` },\n  });\n  const body = await response.text();\n  if (!response.ok) {\n    throw new Error(`RootTale API ${response.status}: ${body.slice(0, 500)}`);\n  }\n  return JSON.parse(body);\n}\n\nfunction textResponse(text: string) {\n  return { content: [{ type: \"text\" as const, text }] };\n}\n\nfunction jsonResponse(value: unknown) {\n  return textResponse(JSON.stringify(value, null, 2));\n}\n\nexport function registerTools(server: Server): void {\n  server.setRequestHandler(ListToolsRequestSchema, async () => ({\n    tools: TOOL_DEFINITIONS.map((t) => ({ ...t })),\n  }));\n\n  server.setRequestHandler(CallToolRequestSchema, async (request) => {\n    const args = (request.params.arguments ?? {}) as Record<string, unknown>;\n    try {\n      switch (request.params.name) {\n        case \"listRootTaleDocs\":\n          return jsonResponse(await listDocs());\n        case \"readRootTaleDoc\": {\n          const input = ReadDocInput.parse(args);\n          const content = await readDoc(input.path);\n          if (content === null) {\n            throw new McpError(\n              ErrorCode.InvalidParams,\n              `문서를 찾을 수 없습니다: ${input.path} — listRootTaleDocs로 경로를 확인하세요.`,\n            );\n          }\n          return textResponse(content);\n        }\n        case \"searchRootTaleDocs\": {\n          const input = SearchDocsInput.parse(args);\n          return jsonResponse(await searchDocs(input.query));\n        }\n        case \"readRootTaleNextjsExampleCode\":\n          return textResponse(await readNextjsExampleCode());\n        case \"listPublishedPosts\": {\n          const input = ListPostsInput.parse(args);\n          const params: Record<string, string> = {};\n          if (input.limit) params.limit = String(input.limit);\n          if (input.type) params.type = input.type;\n          if (input.cursor) params.cursor = input.cursor;\n          return jsonResponse(await fetchPublicApi(\"/v1/cms/public/posts\", params));\n        }\n        case \"getPublishedPost\": {\n          const input = GetPostInput.parse(args);\n          return jsonResponse(\n            await fetchPublicApi(\n              `/v1/cms/public/posts/${encodeURIComponent(input.slugOrId)}`,\n            ),\n          );\n        }\n        default:\n          throw new McpError(\n            ErrorCode.InvalidParams,\n            `Unknown RootTale tool: ${request.params.name}`,\n          );\n      }\n    } catch (error) {\n      if (error instanceof McpError) throw error;\n      const message = error instanceof Error ? error.message : String(error);\n      return { isError: true, content: [{ type: \"text\" as const, text: message }] };\n    }\n  });\n}\n","/**\n * 패키지에 번들된 통합 문서(`docs/`)·예시 코드(`examples/`) 로더.\n *\n * dist/index.js 와 src/docs.ts 모두 패키지 루트에서 한 단계 아래이므로\n * `..` 상대 경로 해석이 빌드 전후 동일하다. npm publish 시 `files` 에\n * docs/, examples/ 가 포함되어 npx 환경에서도 같은 구조로 설치된다.\n */\nimport { readdir, readFile } from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\nconst PKG_ROOT = fileURLToPath(new URL(\"..\", import.meta.url));\nconst DOCS_ROOT = path.join(PKG_ROOT, \"docs\");\nconst EXAMPLES_ROOT = path.join(PKG_ROOT, \"examples\");\n\nexport interface DocEntry {\n  /** docs/ 기준 상대 경로 (예: \"blog.md\"). */\n  path: string;\n  title: string;\n  description: string;\n}\n\ninterface Frontmatter {\n  title: string;\n  description: string;\n}\n\n/** `---\\ntitle: ...\\ndescription: ...\\n---` 형태의 단순 frontmatter 파서. */\nexport function parseFrontmatter(markdown: string): Frontmatter {\n  const result: Frontmatter = { title: \"\", description: \"\" };\n  const match = markdown.match(/^---\\n([\\s\\S]*?)\\n---/);\n  if (!match) return result;\n  for (const line of match[1].split(\"\\n\")) {\n    const idx = line.indexOf(\":\");\n    if (idx === -1) continue;\n    const key = line.slice(0, idx).trim();\n    const value = line.slice(idx + 1).trim();\n    if (key === \"title\") result.title = value;\n    if (key === \"description\") result.description = value;\n  }\n  return result;\n}\n\nasync function walkFiles(root: string, dir = root): Promise<string[]> {\n  const entries = await readdir(dir, { withFileTypes: true });\n  const files: string[] = [];\n  for (const entry of entries) {\n    const full = path.join(dir, entry.name);\n    if (entry.isDirectory()) {\n      files.push(...(await walkFiles(root, full)));\n    } else {\n      files.push(path.relative(root, full));\n    }\n  }\n  return files.sort();\n}\n\nexport async function listDocs(): Promise<DocEntry[]> {\n  const files = (await walkFiles(DOCS_ROOT)).filter((f) => f.endsWith(\".md\"));\n  return Promise.all(\n    files.map(async (rel) => {\n      const content = await readFile(path.join(DOCS_ROOT, rel), \"utf8\");\n      const fm = parseFrontmatter(content);\n      return { path: rel, title: fm.title || rel, description: fm.description };\n    }),\n  );\n}\n\n/** 경로 탈출(../) 방지 후 단일 문서 읽기. 없으면 null. */\nexport async function readDoc(relPath: string): Promise<string | null> {\n  const resolved = path.resolve(DOCS_ROOT, relPath);\n  if (!resolved.startsWith(DOCS_ROOT + path.sep)) return null;\n  try {\n    return await readFile(resolved, \"utf8\");\n  } catch {\n    return null;\n  }\n}\n\nexport interface SearchMatch {\n  path: string;\n  line: number;\n  text: string;\n}\n\n/** 모든 문서에 대해 정규식 검색 (대소문자 무시). 매치 라인을 반환. */\nexport async function searchDocs(query: string): Promise<SearchMatch[]> {\n  const regex = new RegExp(query, \"i\");\n  const matches: SearchMatch[] = [];\n  for (const doc of await listDocs()) {\n    const content = await readDoc(doc.path);\n    if (!content) continue;\n    content.split(\"\\n\").forEach((text, idx) => {\n      if (regex.test(text)) {\n        matches.push({ path: doc.path, line: idx + 1, text: text.trim() });\n      }\n    });\n  }\n  return matches;\n}\n\n/**\n * Next.js 통합 예시 코드 전체를 `--- FILE: <path> ---` 헤더로 이어붙여 반환.\n * 파일 수가 적어(통합 1세트) 한 번에 주는 쪽이 에이전트 왕복을 줄인다.\n */\nexport async function readNextjsExampleCode(): Promise<string> {\n  const root = path.join(EXAMPLES_ROOT, \"nextjs\");\n  const files = await walkFiles(root);\n  const sections = await Promise.all(\n    files.map(async (rel) => {\n      const content = await readFile(path.join(root, rel), \"utf8\");\n      return `--- FILE: ${rel} ---\\n${content}`;\n    }),\n  );\n  return sections.join(\"\\n\\n\");\n}\n"],"mappings":"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","names":["server","server"]}

package/docs/api-reference.md

@@ -0,0 +1,117 @@
+---
+title: HTTP API 레퍼런스
+description: 공개 API raw 엔드포인트 — JS 외 스택이나 저수준 연동용
+---
+
+# HTTP API 레퍼런스
+
+베이스 URL: `https://api.roottale.com`
+인증: 모든 요청에 `Authorization: Bearer rtlk_cust_...` 헤더.
+
+JS/TS 스택은 raw 호출 대신 `@roottale/cms-client`를 사용하세요 — 에러 처리,
+브라우저 노출 방지, 전화번호 포맷 등이 포함되어 있습니다.
+
+## GET /v1/cms/public/posts
+
+발행된 글 목록 (커서 페이지네이션).
+
+| 쿼리 | 설명 |
+|---|---|
+| `limit` | 페이지 크기 (서버에서 상한 clamp) |
+| `cursor` | 이전 응답의 `next_cursor` |
+| `type` | `post` \| `page` |
+| `site_id` | 멀티 사이트 키일 때만 — site-scoped 키면 생략 |
+
+```json
+{
+  "items": [ { "id": "…", "slug": "…", "title": "…", "body_json": {…},
+               "terms": [{ "taxonomy": "category", "name": "…", "slug": "…" }],
+               "published_at": "…" } ],
+  "has_more": false,
+  "next_cursor": null
+}
+```
+
+## GET /v1/cms/public/posts/{identifier}
+
+글 1개 — `identifier`는 slug 또는 UUID. 미발행/없는 글은 `404`.
+
+## GET /v1/cms/public/theme
+
+어드민에서 설정한 디자인 토큰. 설정된 그룹만 포함됩니다.
+
+```json
+{ "tenant_id": "…", "site_id": "…",
+  "colors": {…}, "fonts": {…}, "radius": {…}, "updated_at": "…" }
+```
+
+## GET /v1/cms/public/blog-settings
+
+블로그 표시 설정 (TOC·작성자·발행일·작성자 카드, 저자 프로필).
+
+```json
+{ "show_table_of_contents": false, "show_author": true, "show_date": true,
+  "show_author_card": true, "toc_title": null,
+  "author_profile_name": null, "author_profile_bio": null,
+  "author_profile_image_url": null, "author_profile_image_radius": "circle",
+  "updated_at": null }
+```
+
+## GET /v1/cms/public/analytics
+
+분석 태그 설정.
+
+```json
+{ "tags": [ { "provider": "ga4", "id": "G-XXXXXXX", "enabled": true } ] }
+```
+
+`provider`: `ga4` | `clarity` | `meta_pixel` | `naver`.
+
+## GET /v1/cms/public/jwks
+
+웹훅 서명 검증용 site-scoped JWKS 공개키. **site-scoped 키 필수** — 테넌트
+전체 키로 호출하면 `400 site_scope_required`.
+
+## POST /v1/public/inquiries
+
+상담문의(리드) 접수. `multipart/form-data`.
+
+| 필드 | 필수 | 비고 |
+|---|---|---|
+| `vertical` | ✅ | `consulting` \| `medical` \| `tax` \| `legal` |
+| `contact_name` | ✅ | |
+| `business_name` | ✅ | |
+| `email` | ✅ | `.+@.+\..+` |
+| `phone` | ✅ | |
+| `privacy_consent` | ✅ | 체크박스 (`on`) |
+| `overseas_transfer_consent` | medical 시 ✅ | |
+| `message`, `consultation_field`, `current_site_url` | | |
+| `lead_kind` | | `patient`(기본) \| `sales` |
+| `_redirect_url` | | 완료 후 redirect base (allowlist 검증) |
+| 기타 임의 필드 | | 최대 50개, 암호화 보관, CRM 상세 노출 |
+
+응답: `302` redirect — 성공 `?ok=1`, 실패 `?err=<code>`
+(`consent_privacy`, `consent_overseas`, `invalid_vertical`, `missing_fields`,
+`invalid_email`, `internal`). 잘못된 키는 `401`.
+
+서버-서버 호출 시 redirect를 따라가지 말고(`redirect: "manual"`) `Location`
+헤더를 파싱하세요 — `@roottale/cms-client`의 `submitInquiry`가 이를 대신합니다.
+
+## POST /v1/cms/revalidate
+
+수동 캐시 갱신 트리거 (등록된 웹훅으로 재발송).
+
+```json
+{ "event": "post.updated", "paths": ["/blog", "/blog/my-post"], "slug": "my-post" }
+```
+
+## 에러 형식
+
+비 2xx 응답은 JSON 에러 바디(`code`, `message`)를 가집니다. 주요 코드:
+`invalid_key`(401), `insufficient_scope`(403), `rate_limited`(429),
+`not_found`(404).
+
+## 캐시 헤더
+
+공개 콘텐츠 응답은 private 캐시 헤더로 내려갑니다 — CDN 공유 캐시에 의존하지
+말고 사이트 측 ISR + 발행 웹훅 조합을 사용하세요.