gtm-autotag-mcp 2.0.0

package/README.md

@@ -0,0 +1,170 @@
+# GTM AutoTag MCP
+
+AI 에이전트(Claude Code, Cursor 등)에서 **Google Tag Manager 태그 설치/분석/검증을 자동화**하는 MCP 서버.
+
+사이트 분석부터 태그 생성, 검증까지 전 과정을 자연어로 수행할 수 있습니다.
+
+## Quick Start
+
+### 1. Claude Code
+
+```bash
+claude mcp add gtm-autotag -- npx gtm-autotag-mcp
+```
+
+### 2. Cursor / VS Code
+
+프로젝트 `.mcp.json` 추가:
+
+```json
+{
+  "mcpServers": {
+    "gtm-autotag": {
+      "command": "npx",
+      "args": ["gtm-autotag-mcp"]
+    }
+  }
+}
+```
+
+### 3. 첫 실행 - Google 로그인
+
+첫 실행 시 `list_accounts` 도구를 호출하면 브라우저가 열리며 Google 로그인을 요청합니다.
+로그인 후 토큰이 `~/.gtm-autotag/token.json`에 저장되어 이후 자동 갱신됩니다.
+
+> Playwright 브라우저가 필요합니다: `npx playwright install chromium`
+
+## 제공 도구 (17개)
+
+### 탐색
+
+| 도구 | 설명 |
+|------|------|
+| `list_accounts` | GTM 계정/컨테이너/워크스페이스 목록 |
+| `scan_container` | 컨테이너 태그/트리거/변수 압축 목록 |
+| `get_tag_detail` | 태그 상세 (Custom HTML 본문 포함) |
+| `scan_page` | 페이지 dataLayer + 인터랙티브 요소 분석 |
+
+### 사이트 분석
+
+| 도구 | 설명 |
+|------|------|
+| `classify_page` | 단일 페이지 유형 자동 분류 (상품상세/장바구니/결제 등) |
+| `analyze_site_taxonomy` | 사이트 크롤링 → 페이지 유형 맵 + 퍼널 + 갭 분석 |
+| `detect_datalayer_schema` | 여러 페이지 dataLayer 스키마 자동 추론 |
+
+### 사양 생성
+
+| 도구 | 설명 |
+|------|------|
+| `generate_tracking_spec` | 택소노미 → GA4/Meta/Kakao 추적 사양 자동 생성 |
+| `validate_ecommerce` | GA4 Enhanced Ecommerce 데이터 스키마 검증 |
+
+### 실행
+
+| 도구 | 설명 |
+|------|------|
+| `create_tracking` | 태그/트리거/변수 생성 (clone/new/update 3모드 + 자동 롤백) |
+| `publish_version` | 워크스페이스 → 버전 생성 + 게시 |
+| `compare_versions` | 두 버전 간 변경사항 비교 |
+
+### 검증
+
+| 도구 | 설명 |
+|------|------|
+| `verify_tags` | GTM 미리보기 + 액션 수행 + Tag Assistant 결과 확인 |
+| `bulk_verify` | 다중 페이지 x 다중 이벤트 검증 매트릭스 |
+| `start_preview` | GTM 미리보기 모드 시작 |
+| `check_results` | Tag Assistant 결과 확인 |
+
+### 유틸리티
+
+| 도구 | 설명 |
+|------|------|
+| `close_browser` | Playwright 브라우저 종료 |
+
+## 워크플로우 예시
+
+### "이 사이트 분석해줘"
+
+```
+analyze_site_taxonomy → 사이트 구조 + 페이지 유형 + 추적 갭 분석
+```
+
+### "태그 설치해줘"
+
+```
+1. list_accounts → 계정/컨테이너 확인
+2. analyze_site_taxonomy → 사이트 구조 분석
+3. detect_datalayer_schema → 기존 dataLayer 분석
+4. generate_tracking_spec → 추적 사양 자동 생성
+5. create_tracking → 태그/트리거/변수 생성
+6. bulk_verify → 다중 페이지 검증
+```
+
+### "기존 태그 검증해줘"
+
+```
+bulk_verify → 페이지별 이벤트 pass/fail 매트릭스
+validate_ecommerce → GA4 EEC 데이터 정확성 검증
+```
+
+## 인증 설정
+
+### 기본 (설정 불필요)
+
+내장 OAuth 클라이언트를 사용하여 별도 설정 없이 Google 로그인만으로 사용 가능합니다.
+
+### 자체 OAuth 앱 사용 (선택)
+
+Google Cloud Console에서 OAuth 클라이언트를 생성한 경우:
+
+**방법 A: 환경변수**
+
+```json
+{
+  "mcpServers": {
+    "gtm-autotag": {
+      "command": "npx",
+      "args": ["gtm-autotag-mcp"],
+      "env": {
+        "GTM_AUTOTAG_CLIENT_ID": "your-client-id",
+        "GTM_AUTOTAG_CLIENT_SECRET": "your-client-secret"
+      }
+    }
+  }
+}
+```
+
+**방법 B: credentials.json**
+
+```bash
+mkdir -p ~/.gtm-autotag
+cp your-credentials.json ~/.gtm-autotag/credentials.json
+```
+
+## 지원 태그 타입
+
+빌더 내장: `gaawe` (GA4 이벤트), `gaawc` (GA4 Config), `googtag` (Google Tag), `html` (Custom HTML), `awct` (Google Ads 전환), `awrmk` (Google Ads 리마케팅)
+
+그 외 타입은 `parametersJson`으로 GTM API 원본 파라미터 직접 전달 가능.
+
+## 요구 사항
+
+- Node.js >= 18
+- Chromium (`npx playwright install chromium`)
+- GTM 편집 권한이 있는 Google 계정
+
+## 개발
+
+```bash
+git clone https://github.com/madup-dct/FuncMVP.git
+cd FuncMVP/gtm/gtm-autotag-mcp
+npm install
+npm run build
+npm run dev    # TypeScript watch 모드
+```
+
+## License
+
+MIT

package/dist/data/ga4-events.d.ts

@@ -0,0 +1,24 @@
+/**
+ * GA4 권장 이벤트 레퍼런스
+ * https://developers.google.com/analytics/devguides/collection/ga4/reference/events
+ */
+export interface GA4EventSpec {
+    name: string;
+    category: "all" | "ecommerce" | "leadgen" | "engagement" | "search";
+    requiredParams: string[];
+    optionalParams: string[];
+    requiresItems: boolean;
+    requiredItemParams?: string[];
+    optionalItemParams?: string[];
+    applicableSiteTypes: string[];
+    funnelStage?: string;
+}
+export declare const GA4_RECOMMENDED_EVENTS: GA4EventSpec[];
+/**
+ * 이커머스 전환 퍼널 순서
+ */
+export declare const ECOMMERCE_FUNNEL_ORDER: string[];
+/**
+ * 페이지 유형 -> GA4 이벤트 매핑
+ */
+export declare const PAGE_TYPE_EVENT_MAP: Record<string, string[]>;

package/dist/data/ga4-events.js

@@ -0,0 +1,227 @@
+/**
+ * GA4 권장 이벤트 레퍼런스
+ * https://developers.google.com/analytics/devguides/collection/ga4/reference/events
+ */
+export const GA4_RECOMMENDED_EVENTS = [
+    // === 공통 이벤트 ===
+    {
+        name: "page_view",
+        category: "all",
+        requiredParams: [],
+        optionalParams: ["page_location", "page_referrer", "page_title"],
+        requiresItems: false,
+        applicableSiteTypes: ["ecommerce", "leadgen", "media", "saas", "content"],
+    },
+    {
+        name: "login",
+        category: "engagement",
+        requiredParams: [],
+        optionalParams: ["method"],
+        requiresItems: false,
+        applicableSiteTypes: ["ecommerce", "leadgen", "saas"],
+    },
+    {
+        name: "sign_up",
+        category: "engagement",
+        requiredParams: [],
+        optionalParams: ["method"],
+        requiresItems: false,
+        applicableSiteTypes: ["ecommerce", "leadgen", "saas"],
+    },
+    {
+        name: "search",
+        category: "search",
+        requiredParams: ["search_term"],
+        optionalParams: [],
+        requiresItems: false,
+        applicableSiteTypes: ["ecommerce", "leadgen", "media", "saas", "content"],
+    },
+    {
+        name: "share",
+        category: "engagement",
+        requiredParams: [],
+        optionalParams: ["method", "content_type", "item_id"],
+        requiresItems: false,
+        applicableSiteTypes: ["ecommerce", "media", "content"],
+    },
+    // === 이커머스 이벤트 ===
+    {
+        name: "view_item_list",
+        category: "ecommerce",
+        requiredParams: [],
+        optionalParams: ["item_list_id", "item_list_name"],
+        requiresItems: true,
+        requiredItemParams: ["item_id", "item_name"],
+        optionalItemParams: ["price", "quantity", "item_brand", "item_category", "item_variant", "index"],
+        applicableSiteTypes: ["ecommerce"],
+        funnelStage: "category",
+    },
+    {
+        name: "select_item",
+        category: "ecommerce",
+        requiredParams: [],
+        optionalParams: ["item_list_id", "item_list_name"],
+        requiresItems: true,
+        requiredItemParams: ["item_id", "item_name"],
+        optionalItemParams: ["price", "item_brand", "item_category"],
+        applicableSiteTypes: ["ecommerce"],
+        funnelStage: "category",
+    },
+    {
+        name: "view_item",
+        category: "ecommerce",
+        requiredParams: ["currency", "value"],
+        optionalParams: [],
+        requiresItems: true,
+        requiredItemParams: ["item_id", "item_name"],
+        optionalItemParams: ["price", "quantity", "item_brand", "item_category", "item_category2", "item_category3", "item_variant"],
+        applicableSiteTypes: ["ecommerce"],
+        funnelStage: "product_detail",
+    },
+    {
+        name: "add_to_cart",
+        category: "ecommerce",
+        requiredParams: ["currency", "value"],
+        optionalParams: [],
+        requiresItems: true,
+        requiredItemParams: ["item_id", "item_name"],
+        optionalItemParams: ["price", "quantity", "item_brand", "item_category"],
+        applicableSiteTypes: ["ecommerce"],
+        funnelStage: "cart",
+    },
+    {
+        name: "remove_from_cart",
+        category: "ecommerce",
+        requiredParams: ["currency", "value"],
+        optionalParams: [],
+        requiresItems: true,
+        requiredItemParams: ["item_id", "item_name"],
+        applicableSiteTypes: ["ecommerce"],
+        funnelStage: "cart",
+    },
+    {
+        name: "view_cart",
+        category: "ecommerce",
+        requiredParams: ["currency", "value"],
+        optionalParams: [],
+        requiresItems: true,
+        requiredItemParams: ["item_id", "item_name"],
+        optionalItemParams: ["price", "quantity"],
+        applicableSiteTypes: ["ecommerce"],
+        funnelStage: "cart",
+    },
+    {
+        name: "begin_checkout",
+        category: "ecommerce",
+        requiredParams: ["currency", "value"],
+        optionalParams: ["coupon"],
+        requiresItems: true,
+        requiredItemParams: ["item_id", "item_name"],
+        applicableSiteTypes: ["ecommerce"],
+        funnelStage: "checkout",
+    },
+    {
+        name: "add_shipping_info",
+        category: "ecommerce",
+        requiredParams: ["currency", "value"],
+        optionalParams: ["coupon", "shipping_tier"],
+        requiresItems: true,
+        requiredItemParams: ["item_id", "item_name"],
+        applicableSiteTypes: ["ecommerce"],
+        funnelStage: "checkout",
+    },
+    {
+        name: "add_payment_info",
+        category: "ecommerce",
+        requiredParams: ["currency", "value"],
+        optionalParams: ["coupon", "payment_type"],
+        requiresItems: true,
+        requiredItemParams: ["item_id", "item_name"],
+        applicableSiteTypes: ["ecommerce"],
+        funnelStage: "checkout",
+    },
+    {
+        name: "purchase",
+        category: "ecommerce",
+        requiredParams: ["transaction_id", "currency", "value"],
+        optionalParams: ["tax", "shipping", "coupon", "affiliation"],
+        requiresItems: true,
+        requiredItemParams: ["item_id", "item_name"],
+        optionalItemParams: ["price", "quantity", "item_brand", "item_category"],
+        applicableSiteTypes: ["ecommerce"],
+        funnelStage: "purchase_confirmation",
+    },
+    {
+        name: "refund",
+        category: "ecommerce",
+        requiredParams: ["transaction_id", "currency", "value"],
+        optionalParams: [],
+        requiresItems: false,
+        applicableSiteTypes: ["ecommerce"],
+    },
+    {
+        name: "view_promotion",
+        category: "ecommerce",
+        requiredParams: [],
+        optionalParams: ["creative_name", "creative_slot", "promotion_id", "promotion_name"],
+        requiresItems: true,
+        requiredItemParams: ["item_id", "item_name"],
+        applicableSiteTypes: ["ecommerce"],
+    },
+    {
+        name: "select_promotion",
+        category: "ecommerce",
+        requiredParams: [],
+        optionalParams: ["creative_name", "creative_slot", "promotion_id", "promotion_name"],
+        requiresItems: true,
+        requiredItemParams: ["item_id", "item_name"],
+        applicableSiteTypes: ["ecommerce"],
+    },
+    {
+        name: "add_to_wishlist",
+        category: "ecommerce",
+        requiredParams: ["currency", "value"],
+        optionalParams: [],
+        requiresItems: true,
+        requiredItemParams: ["item_id", "item_name"],
+        applicableSiteTypes: ["ecommerce"],
+    },
+    // === 리드 생성 ===
+    {
+        name: "generate_lead",
+        category: "leadgen",
+        requiredParams: [],
+        optionalParams: ["currency", "value"],
+        requiresItems: false,
+        applicableSiteTypes: ["leadgen", "saas"],
+    },
+];
+/**
+ * 이커머스 전환 퍼널 순서
+ */
+export const ECOMMERCE_FUNNEL_ORDER = [
+    "view_item_list",
+    "select_item",
+    "view_item",
+    "add_to_cart",
+    "view_cart",
+    "begin_checkout",
+    "add_shipping_info",
+    "add_payment_info",
+    "purchase",
+];
+/**
+ * 페이지 유형 -> GA4 이벤트 매핑
+ */
+export const PAGE_TYPE_EVENT_MAP = {
+    home: ["page_view"],
+    category: ["page_view", "view_item_list", "select_item"],
+    product_list: ["page_view", "view_item_list", "select_item"],
+    product_detail: ["page_view", "view_item", "add_to_cart", "add_to_wishlist"],
+    cart: ["page_view", "view_cart", "remove_from_cart"],
+    checkout: ["page_view", "begin_checkout", "add_shipping_info", "add_payment_info"],
+    purchase_confirmation: ["page_view", "purchase"],
+    login: ["page_view", "login"],
+    registration: ["page_view", "sign_up"],
+    search_results: ["page_view", "search", "view_item_list", "select_item"],
+};

package/dist/data/page-heuristics.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 페이지 분류 휴리스틱 규칙
+ * 다중 신호 스코어링 기반 페이지 유형 분류
+ */
+import { PageType } from "../types/taxonomy.js";
+export interface URLRule {
+    patterns: RegExp[];
+    pageType: PageType;
+    weight: number;
+}
+export declare const URL_RULES: URLRule[];
+export interface CTARule {
+    patterns: RegExp[];
+    functionType: string;
+    weight: number;
+}
+export declare const CTA_RULES: CTARule[];
+export interface FormFieldRule {
+    patterns: RegExp[];
+    semanticType: string;
+}
+export declare const FORM_FIELD_RULES: FormFieldRule[];
+export interface FormPurposeRule {
+    requiredFields: string[];
+    excludeFields?: string[];
+    purpose: string;
+    confidence: number;
+}
+export declare const FORM_PURPOSE_RULES: FormPurposeRule[];
+export declare const PRICE_PATTERNS: RegExp[];
+export declare const PRODUCT_SELECTORS: {
+    price: string[];
+    image: string[];
+    name: string[];
+    variant: string[];
+};
+export declare const CART_SELECTORS: {
+    quantity: string[];
+    total: string[];
+    remove: string[];
+};
+export declare const CHECKOUT_SELECTORS: {
+    payment: string[];
+    address: string[];
+    orderSummary: string[];
+};