careerly-data-mcp 2.0.0

package/README.md

@@ -0,0 +1,230 @@
+# Careerly GA4 MCP Server
+
+Claude Code에서 자연어로 GA4 데이터를 분석하는 MCP(Model Context Protocol) 서버입니다.
+
+## 빠른 시작
+
+```bash
+# 1. Service Account JSON 키 파일이 있는 폴더에서 실행
+cd /path/to/your/project
+
+# 2. 설정 실행 (키 파일 자동 탐지 + Claude Code 자동 등록!)
+npx careerly-ga4-mcp setup
+
+# 3. Claude Code 재시작 후 /mcp 확인!
+```
+
+### 자동 설정 기능
+
+`setup` 명령어는 다음을 자동으로 처리합니다:
+
+1. **Service Account 키 파일 자동 탐지** - 현재 폴더에서 JSON 파일 스캔
+2. **GA4 연결 테스트** - Property ID와 키 파일 검증
+3. **Claude Code MCP 자동 등록** - `claude mcp add` 명령어로 자동 설정
+
+```
+  Careerly GA4 MCP Server
+  ─────────────────────────────────────
+
+✔ GA4 Property ID 517059569
+✔ 1개의 Service Account 키 파일 발견
+✔ 사용할 키 파일 선택 my-project-key.json (my-project-id)
+✔ 연결 성공!
+✔ Claude Code MCP 서버 등록 완료
+
+  ✓ 설정 완료!
+```
+
+## 사전 준비
+
+### 1. Google Cloud 설정
+
+1. [Google Cloud Console](https://console.cloud.google.com/)에서 프로젝트 생성
+2. **Google Analytics Data API** 활성화
+3. **서비스 계정** 생성 후 JSON 키 다운로드
+
+### 2. GA4 권한 설정
+
+1. [GA4 Admin](https://analytics.google.com/) > 속성 설정 > 속성 액세스 관리
+2. 서비스 계정 이메일 추가 (뷰어/읽기 전용 권한)
+
+> **Tip**: Service Account 이메일은 JSON 키 파일의 `client_email` 필드에서 확인할 수 있습니다.
+
+## 기능
+
+| Tool | 설명 |
+|------|------|
+| `ga4_query` | GA4 데이터 조회 + 인사이트 생성 |
+| `ga4_metadata` | 지표/차원 목록 확인 |
+| `ga4_status` | 연결 상태 확인 |
+
+## 사용 예시
+
+Claude Code에서 자연어로 질문:
+
+```
+"지난 7일 세션수 보여줘"
+"채널별 전환수 알려줘"
+"어제 대비 오늘 트래픽 어때?"
+"랜딩 페이지별 이탈률 분석해줘"
+"캠페인별 성과 비교해줘"
+```
+
+## CLI 명령어
+
+```bash
+# 인터랙티브 메뉴
+npx careerly-ga4-mcp
+
+# 초기 설정 (자동 키 파일 탐지 + Claude Code 자동 등록)
+npx careerly-ga4-mcp setup
+
+# 서버 정보 확인
+npx careerly-ga4-mcp info
+
+# GA4 연결 테스트
+npx careerly-ga4-mcp test-connection
+
+# MCP 서버 시작 (수동)
+npx careerly-ga4-mcp serve
+```
+
+## 인터랙티브 메뉴
+
+```bash
+npx careerly-ga4-mcp
+```
+
+```
+  Careerly GA4 MCP Server
+  ─────────────────────────────────────
+
+Status:      ✓ connected
+Property ID: 123456789
+Credentials: ~/project/service-account.json
+Tools:       3 tools
+
+? 선택하세요
+❯ View tools
+  Reconnect
+  Test connection
+  Disable
+```
+
+## 수동 설정
+
+### Claude CLI로 추가
+
+```bash
+claude mcp add careerly-ga4 \
+  -s user \
+  -e GA4_PROPERTY_ID=123456789 \
+  -e GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json \
+  -- npx -y careerly-ga4-mcp serve
+```
+
+### 설정 파일 직접 수정
+
+`~/.claude/settings.local.json`에 직접 추가:
+
+```json
+{
+  "mcpServers": {
+    "careerly-ga4": {
+      "command": "npx",
+      "args": ["-y", "careerly-ga4-mcp", "serve"],
+      "env": {
+        "GA4_PROPERTY_ID": "123456789",
+        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
+      }
+    }
+  }
+}
+```
+
+## 문제 해결
+
+### MCP 서버가 `/mcp`에 안 보여요
+
+1. Claude Code를 완전히 종료 후 재시작
+2. 설정 확인: `claude mcp list`
+3. 재설정: `npx careerly-ga4-mcp setup`
+
+### PERMISSION_DENIED 에러
+
+GA4에 Service Account 권한이 없습니다:
+
+1. GA4 Admin > 속성 설정 > 속성 액세스 관리
+2. Service Account 이메일 추가 (JSON의 `client_email`)
+3. 역할: 뷰어 (읽기 전용)
+
+### 설정 삭제
+
+```bash
+# Claude CLI로 삭제
+claude mcp remove careerly-ga4 -s user
+
+# 또는 인터랙티브 메뉴에서
+npx careerly-ga4-mcp
+# → Disable 선택
+```
+
+## Tool 스키마
+
+### ga4_query
+
+```typescript
+{
+  metrics: string[]      // 필수: ["sessions", "totalUsers", "conversions"]
+  dimensions?: string[]  // 선택: ["date", "sessionDefaultChannelGroup"]
+  startDate?: string     // 기본: "7daysAgo"
+  endDate?: string       // 기본: "today"
+  datePreset?: string    // "last_7_days", "last_30_days" 등
+  limit?: number         // 기본: 10
+}
+```
+
+### 지표 (Metrics)
+
+| 지표 | 설명 |
+|------|------|
+| `sessions` | 세션 수 |
+| `totalUsers` | 전체 사용자 |
+| `newUsers` | 신규 사용자 |
+| `activeUsers` | 활성 사용자 |
+| `bounceRate` | 이탈률 |
+| `conversions` | 전환 수 |
+| `screenPageViews` | 페이지뷰 |
+| `engagementRate` | 참여율 |
+
+### 차원 (Dimensions)
+
+| 차원 | 설명 |
+|------|------|
+| `date` | 날짜 |
+| `sessionDefaultChannelGroup` | 채널 |
+| `sessionSourceMedium` | 소스/매체 |
+| `sessionCampaignName` | 캠페인 |
+| `landingPage` | 랜딩 페이지 |
+| `deviceCategory` | 디바이스 |
+| `country` | 국가 |
+
+## 개발
+
+```bash
+# 의존성 설치
+npm install
+
+# 빌드
+npm run build
+
+# 개발 모드
+npm run dev
+
+# 타입 체크
+npm run typecheck
+```
+
+## 라이선스
+
+MIT

package/dist/bigquery/auth.d.ts

@@ -0,0 +1,18 @@
+/**
+ * BigQuery 인증 모듈
+ * GA4 auth.ts와 유사한 패턴
+ */
+import { BigQueryConfig } from "./types.js";
+/**
+ * 환경 변수에서 BigQuery 설정 로드
+ */
+export declare function loadBigQueryConfigFromEnv(): BigQueryConfig;
+/**
+ * 설정 검증 및 초기화
+ */
+export declare function initializeBigQueryAuth(config?: Partial<BigQueryConfig>): BigQueryConfig;
+/**
+ * Project ID 검증
+ */
+export declare function validateProjectId(projectId: string): boolean;
+//# sourceMappingURL=auth.d.ts.map

package/dist/bigquery/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/bigquery/auth.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAiB,MAAM,YAAY,CAAC;AAE3D;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,cAAc,CAe1D;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAC/B,cAAc,CAqBhB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAI5D"}

package/dist/bigquery/auth.js

@@ -0,0 +1,46 @@
+/**
+ * BigQuery 인증 모듈
+ * GA4 auth.ts와 유사한 패턴
+ */
+import { BigQueryError } from "./types.js";
+/**
+ * 환경 변수에서 BigQuery 설정 로드
+ */
+export function loadBigQueryConfigFromEnv() {
+    const projectId = process.env.BQ_PROJECT_ID || process.env.GOOGLE_CLOUD_PROJECT;
+    const credentialsPath = process.env.GOOGLE_APPLICATION_CREDENTIALS;
+    const location = process.env.BQ_LOCATION || "US";
+    if (!projectId) {
+        throw new BigQueryError("BQ_PROJECT_ID 또는 GOOGLE_CLOUD_PROJECT 환경 변수가 설정되지 않았습니다.\n" +
+            "설정 방법: export BQ_PROJECT_ID=your-project-id", "CONFIG_ERROR");
+    }
+    return { projectId, credentialsPath, location };
+}
+/**
+ * 설정 검증 및 초기화
+ */
+export function initializeBigQueryAuth(config) {
+    const envConfig = loadBigQueryConfigFromEnv();
+    const finalConfig = {
+        projectId: config?.projectId || envConfig.projectId,
+        credentialsPath: config?.credentialsPath || envConfig.credentialsPath,
+        location: config?.location || envConfig.location,
+    };
+    // 자격증명 파일 경로가 설정되어 있으면 로그 출력
+    if (finalConfig.credentialsPath) {
+        console.error(`[BigQuery] Service Account: ${finalConfig.credentialsPath}`);
+    }
+    else {
+        console.error("[BigQuery] Application Default Credentials(ADC) 사용 중");
+    }
+    return finalConfig;
+}
+/**
+ * Project ID 검증
+ */
+export function validateProjectId(projectId) {
+    // GCP 프로젝트 ID 규칙: 6-30자, 소문자/숫자/하이픈
+    const projectIdRegex = /^[a-z][a-z0-9-]{4,28}[a-z0-9]$/;
+    return projectIdRegex.test(projectId);
+}
+//# sourceMappingURL=auth.js.map

package/dist/bigquery/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/bigquery/auth.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAkB,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3D;;GAEG;AACH,MAAM,UAAU,yBAAyB;IACvC,MAAM,SAAS,GACb,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;IAChE,MAAM,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,8BAA8B,CAAC;IACnE,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,IAAI,CAAC;IAEjD,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,aAAa,CACrB,4DAA4D;YAC1D,6CAA6C,EAC/C,cAAc,CACf,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,QAAQ,EAAE,CAAC;AAClD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAgC;IAEhC,MAAM,SAAS,GAAG,yBAAyB,EAAE,CAAC;IAE9C,MAAM,WAAW,GAAmB;QAClC,SAAS,EAAE,MAAM,EAAE,SAAS,IAAI,SAAS,CAAC,SAAS;QACnD,eAAe,EAAE,MAAM,EAAE,eAAe,IAAI,SAAS,CAAC,eAAe;QACrE,QAAQ,EAAE,MAAM,EAAE,QAAQ,IAAI,SAAS,CAAC,QAAQ;KACjD,CAAC;IAEF,6BAA6B;IAC7B,IAAI,WAAW,CAAC,eAAe,EAAE,CAAC;QAChC,OAAO,CAAC,KAAK,CACX,+BAA+B,WAAW,CAAC,eAAe,EAAE,CAC7D,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CACX,sDAAsD,CACvD,CAAC;IACJ,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IACjD,oCAAoC;IACpC,MAAM,cAAc,GAAG,gCAAgC,CAAC;IACxD,OAAO,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AACxC,CAAC"}

package/dist/bigquery/client.d.ts

@@ -0,0 +1,77 @@
+/**
+ * BigQuery 클라이언트
+ * @google-cloud/bigquery 래퍼
+ */
+import type { BigQueryConfig, BigQueryRequest, BigQueryResponse, GA4EventsRequest, DatasetInfo, TableInfo } from "./types.js";
+export declare class BigQueryClient {
+    private client;
+    private projectId;
+    private location;
+    constructor(config?: Partial<BigQueryConfig>);
+    /**
+     * 연결 테스트
+     */
+    testConnection(): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * 파라미터 기반 쿼리 실행
+     */
+    runQuery(request: BigQueryRequest): Promise<BigQueryResponse>;
+    /**
+     * GA4 Export 이벤트 쿼리 실행
+     */
+    runGA4EventsQuery(request: GA4EventsRequest): Promise<BigQueryResponse>;
+    /**
+     * 데이터셋 목록 조회
+     */
+    listDatasets(): Promise<DatasetInfo[]>;
+    /**
+     * 테이블 목록 조회
+     */
+    listTables(datasetId: string): Promise<TableInfo[]>;
+    /**
+     * 테이블 스키마 조회
+     */
+    getTableSchema(datasetId: string, tableId: string): Promise<TableInfo>;
+    /**
+     * SELECT 쿼리 빌드 (SQL Injection 방지)
+     */
+    private buildSelectQuery;
+    /**
+     * GA4 Export 쿼리 빌드
+     */
+    private buildGA4EventsQuery;
+    /**
+     * WHERE 조건 빌드
+     */
+    private buildWhereCondition;
+    /**
+     * 집계 함수 빌드
+     */
+    private buildAggregation;
+    /**
+     * 식별자 이스케이프 (SQL Injection 방지)
+     */
+    private escapeIdentifier;
+    /**
+     * 스키마 변환
+     */
+    private transformSchema;
+    /**
+     * 에러 처리
+     */
+    private handleError;
+    /**
+     * Project ID 반환
+     */
+    getProjectId(): string;
+    /**
+     * Location 반환
+     */
+    getLocation(): string;
+}
+export declare function getBigQueryClient(config?: Partial<BigQueryConfig>): BigQueryClient;
+export declare function resetBigQueryClient(): void;
+//# sourceMappingURL=client.d.ts.map

package/dist/bigquery/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/bigquery/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,SAAS,EAIV,MAAM,YAAY,CAAC;AAIpB,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAS;gBAEb,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC;IAW5C;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAoBtE;;OAEG;IACG,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA+BnE;;OAEG;IACG,iBAAiB,CACrB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,gBAAgB,CAAC;IA+B5B;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAqB5C;;OAEG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAgCzD;;OAEG;IACG,cAAc,CAClB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,SAAS,CAAC;IAgCrB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA4ExB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAiH3B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAmE3B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAsBxB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAWxB;;OAEG;IACH,OAAO,CAAC,eAAe;IAevB;;OAEG;IACH,OAAO,CAAC,WAAW;IAuDnB;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,WAAW,IAAI,MAAM;CAGtB;AAKD,wBAAgB,iBAAiB,CAC/B,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAC/B,cAAc,CAKhB;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C"}