@roottale/cms-mcp 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @roottale/cms-mcp
 
+## 0.24.0
+
+### Minor Changes
+
+- 299c9b2: 문의 유입 어트리뷰션 (ADR-0048 §2). `submitInquiry` 에 `attribution` 필드 추가 — 비콘이 기억한 first-touch(처음 도착한 페이지·단축링크/QR 토큰·utm·외부 referrer 호스트명)를 문의와 함께 보내면 어드민 CRM 에 유입 경로가 표시된다. 신규: `@roottale/cms-client/attribution` 서브패스의 `readAttribution()`(브라우저 전용), 서버 엔트리의 `parseAttributionJson()`, intake API `attr_*` 폼 필드. cms-mcp docs(inquiries/api-reference) 및 예제(AttributionField) 동반 갱신.
+
+### Patch Changes
+
+- edba5a1: README 에 사람용 문서 경로 추가 — 공식 문서 사이트(roottale.com/docs) + unpkg 원문 열람
+
 ## 0.23.0
 
 ### Minor Changes

package/README.md

@@ -49,10 +49,14 @@ claude mcp add roottale-cms -- npx -y @roottale/cms-mcp
 | `listPublishedPosts` | 공개 API로 발행 글 목록 조회 (키 필요) |
 | `getPublishedPost` | 공개 API로 발행 글 1개 조회 (키 필요) |
 
-## 사람용 문서
+## 사람용 문서 (브라우저 열람)
 
-문서 원문은 패키지의 [`docs/`](./docs/overview.md) 폴더에서 직접 읽을 수
-있습니다. 진입점: `docs/overview.md`.
+- **공식 문서 사이트**: <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
 

package/dist/index.js

@@ -256,7 +256,7 @@ function registerTools(server2) {
 }
 
 // src/server.ts
-var VERSION = true ? "0.23.0" : "dev";
+var VERSION = true ? "0.24.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/api-reference.md

@@ -88,6 +88,7 @@ JS/TS 스택은 raw 호출 대신 `@roottale/cms-client`를 사용하세요 —
 | `message`, `consultation_field`, `current_site_url` | | |
 | `lead_kind` | | `patient`(기본) \| `sales` |
 | `_redirect_url` | | 완료 후 redirect base (allowlist 검증) |
+| `attr_landing_path`, `attr_rt_src`, `attr_utm_source`, `attr_utm_medium`, `attr_utm_campaign`, `attr_referrer`, `attr_first_touch_at` | | 유입 어트리뷰션 — CRM에 유입 경로 표시 (`inquiries.md` 참고). 그 외 `attr_*` 키는 무시 |
 | 기타 임의 필드 | | 최대 50개, 암호화 보관, CRM 상세 노출 |
 
 응답: `302` redirect — 성공 `?ok=1`, 실패 `?err=<code>`

package/docs/inquiries.md

@@ -81,9 +81,62 @@ export async function submitContact(
 | `overseasTransferConsent` | medical 시 ✅ | 국외이전 동의 |
 | `leadKind` | | `patient`(기본) \| `sales` |
 | `extras` | | 임의 추가 항목 (최대 50개, 암호화 보관, CRM 상세에 노출) |
+| `attribution` | | 유입 first-touch — 아래 [유입 어트리뷰션](#유입-어트리뷰션-attribution) 참고 |
 
 `extras`에 개인정보가 담길 수 있으므로 폼의 동의 고지에 수집 항목을 반영하세요.
 
+## 유입 어트리뷰션 (`attribution`)
+
+문의가 **어느 글·검색·단축링크/QR에서 왔는지**를 CRM에 표시하려면 두 줄만
+추가하면 됩니다. RootTale 비콘이 방문자의 first-touch(처음 도착한
+경로·`rt_src` 토큰·utm·외부 referrer 호스트명)를 30일간 기억하며,
+`readAttribution()`(브라우저 전용, `@roottale/cms-client/attribution`)으로
+읽습니다. 식별자가 아니므로 개인정보가 아닙니다.
+
+1. 폼 안에 hidden input 추가 (클라이언트 컴포넌트):
+
+```tsx
+"use client";
+import { useEffect, useState } from "react";
+import { readAttribution } from "@roottale/cms-client/attribution";
+
+export function AttributionField() {
+  const [value, setValue] = useState("");
+  useEffect(() => {
+    const attribution = readAttribution();
+    if (attribution) setValue(JSON.stringify(attribution));
+  }, []);
+  return <input type="hidden" name="attribution" value={value} />;
+}
+// 사용: <form action={...}> ... <AttributionField /> ... </form>
+```
+
+2. Server Action에서 파싱해 전달:
+
+```ts
+import { parseAttributionJson, submitInquiry } from "@roottale/cms-client/server";
+
+const attribution = parseAttributionJson(formData.get("attribution")); // 깨진 값은 null
+const result = await submitInquiry({
+  apiKey: process.env.ROOTTALE_API_KEY!,
+  fields: { /* ...표준 필드 */ attribution },
+});
+```
+
+`InquiryAttribution` 형태 (모든 필드 선택):
+
+| 필드 | 설명 |
+|---|---|
+| `landing_path` | 첫 방문 landing pathname |
+| `rt_src` | 단축링크/QR 토큰 (`roottale.link` 경유 시) |
+| `utm_source` / `utm_medium` / `utm_campaign` | UTM 파라미터 |
+| `referrer` | 외부 referrer **호스트명** (raw URL 아님) |
+| `first_touch_at` | first-touch 시각 (ISO 8601) |
+
+직접 HTTP 연동 시에는 같은 값을 `attr_landing_path`, `attr_rt_src`,
+`attr_utm_source`, `attr_utm_medium`, `attr_utm_campaign`, `attr_referrer`,
+`attr_first_touch_at` 폼 필드로 보내면 됩니다.
+
 ## 에러 처리
 
 `submitInquiry`는 throw 하지 않고 구조화된 결과를 반환합니다:

package/examples/nextjs/components/attribution-field.tsx

@@ -0,0 +1,19 @@
+// 유입 어트리뷰션 hidden input — 문의 폼 <form> 안에 넣기만 하면 된다.
+// RootTale 비콘이 localStorage 에 기억해 둔 first-touch(처음 도착한 페이지 ·
+// 단축링크/QR 토큰 · utm · 외부 referrer 호스트명)를 JSON 으로 실어 보내고,
+// 서버 액션이 parseAttributionJson(formData.get("attribution")) 으로 받는다.
+// 값이 없으면 빈 문자열 → 서버에서 null 처리되므로 항상 안전하다.
+"use client";
+
+import { useEffect, useState } from "react";
+
+import { readAttribution } from "@roottale/cms-client/attribution";
+
+export function AttributionField() {
+  const [value, setValue] = useState("");
+  useEffect(() => {
+    const attribution = readAttribution();
+    if (attribution) setValue(JSON.stringify(attribution));
+  }, []);
+  return <input type="hidden" name="attribution" value={value} />;
+}

package/examples/nextjs/lib/actions/submit-contact.ts

@@ -2,7 +2,7 @@
 // 클라이언트 폼에서 useActionState(submitContact, { status: "idle" })로 연결.
 "use server";
 
-import { submitInquiry } from "@roottale/cms-client/server";
+import { parseAttributionJson, submitInquiry } from "@roottale/cms-client/server";
 
 export interface ContactState {
   status: "idle" | "success" | "error";
@@ -19,6 +19,9 @@ export async function submitContact(
   const field = (formData.get("field") as string | null)?.trim() ?? "";
   const message = (formData.get("message") as string | null)?.trim() ?? "";
   const privacyConsent = formData.get("privacyConsent") !== null;
+  // 유입 어트리뷰션 (선택) — 클라이언트 폼이 readAttribution() 값을 hidden
+  // input(name="attribution")에 JSON 으로 실어 보내면 CRM 에 유입 경로가 표시된다.
+  const attribution = parseAttributionJson(formData.get("attribution"));
 
   const errors: ContactState["errors"] = {};
   if (!name) errors.name = "이름을 입력해주세요.";
@@ -40,6 +43,7 @@ export async function submitContact(
       consultationField: field || undefined,
       message: message || undefined,
       privacyConsent: true, // 사용자가 명시 동의한 경우에만
+      attribution,
     },
   });
 

package/package.json

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