careerly-data-mcp 2.1.0 → 2.1.1

package/README.md

@@ -1,6 +1,33 @@
-# Careerly GA4 MCP Server
+# Careerly Data MCP Server
 
-Claude Code에서 자연어로 GA4 데이터를 분석하는 MCP(Model Context Protocol) 서버입니다.
+Claude Code에서 **자연어로 GA4와 BigQuery 데이터를 분석**하는 MCP(Model Context Protocol) 서버입니다.
+
+## 왜 MCP를 쓰나요? (vs API 직접 호출)
+
+### 기존 방식의 문제점
+
+```
+GA4 데이터 보고 싶다 → GA4 API 문서 읽기 → 인증 설정 → 코드 작성 → 결과 해석
+BigQuery 분석하고 싶다 → SQL 작성 → UNNEST 문법 검색 → 쿼리 수정 → 결과 해석
+```
+
+### MCP 방식
+
+```
+"지난 7일 세션수 보여줘" → 끝!
+"page_view → post_detail_view 전환율 분석해줘" → 끝!
+```
+
+### 핵심 장점
+
+| 기존 API 직접 호출 | MCP 사용 |
+|------------------|---------|
+| API 문서 읽고 코드 작성 필요 | 자연어로 질문하면 끝 |
+| GA4 event_params 추출 = 복잡한 UNNEST SQL | `bq_event_params` 도구로 한 줄 |
+| 퍼널 분석 = 10줄 이상 SQL | `bq_funnel` 도구로 자동 계산 |
+| 결과는 숫자만 | **인사이트 + 다음 액션 제안**까지 |
+
+---
 
 ## 빠른 시작
 
@@ -8,110 +35,189 @@ Claude Code에서 자연어로 GA4 데이터를 분석하는 MCP(Model Context P
 # 1. Service Account JSON 키 파일이 있는 폴더에서 실행
 cd /path/to/your/project
 
-# 2. 설정 실행 (키 파일 자동 탐지 + Claude Code 자동 등록!)
-npx careerly-ga4-mcp setup
+# 2. 설정 실행 (키 파일 자동 탐지 + Claude Code 자동 등록)
+npx careerly-data-mcp setup
 
 # 3. Claude Code 재시작 후 /mcp 확인!
 ```
 
 ### 자동 설정 기능
 
-`setup` 명령어는 다음을 자동으로 처리합니다:
-
-1. **Service Account 키 파일 자동 탐지** - 현재 폴더에서 JSON 파일 스캔
-2. **GA4 연결 테스트** - Property ID와 키 파일 검증
-3. **Claude Code MCP 자동 등록** - `claude mcp add` 명령어로 자동 설정
+`setup` 명령어가 알아서 처리합니다:
 
-```
-  Careerly GA4 MCP Server
-  ─────────────────────────────────────
+1. **Service Account 키 파일 자동 탐지** - 폴더에서 JSON 파일 스캔
+2. **GA4 + BigQuery 연결 테스트** - Property ID와 키 파일 검증
+3. **Claude Code MCP 자동 등록** - 재시작만 하면 바로 사용 가능
 
-✔ 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 키 다운로드
+3. **BigQuery API** 활성화
+4. **서비스 계정** 생성 후 JSON 키 다운로드
 
 ### 2. GA4 권한 설정
 
-1. [GA4 Admin](https://analytics.google.com/) > 속성 설정 > 속성 액세스 관리
-2. 서비스 계정 이메일 추가 (뷰어/읽기 전용 권한)
+- GA4 Admin > 속성 설정 > 속성 액세스 관리
+- 서비스 계정 이메일 추가 (뷰어 권한)
+
+### 3. BigQuery 권한 설정
+
+- IAM & Admin > 서비스 계정에 **BigQuery 데이터 뷰어** 역할 추가
+
+---
+
+## 제공 도구 (Tools)
+
+### GA4 Data API 도구
 
-> **Tip**: Service Account 이메일은 JSON 키 파일의 `client_email` 필드에서 확인할 수 있습니다.
+| Tool | 설명 | 언제 쓰나요? |
+|------|------|------------|
+| `ga4_query` | GA4 데이터 조회 + 인사이트 | 세션, 사용자, 전환 등 기본 지표 |
+| `ga4_metadata` | 지표/차원 목록 | 어떤 데이터를 볼 수 있는지 확인 |
+| `ga4_status` | 연결 상태 확인 | 연결 문제 진단 |
 
-## 기능
+### BigQuery 기본 도구
 
-| Tool | 설명 |
-|------|------|
-| `ga4_query` | GA4 데이터 조회 + 인사이트 생성 |
-| `ga4_metadata` | 지표/차원 목록 확인 |
-| `ga4_status` | 연결 상태 확인 |
+| Tool | 설명 | 언제 쓰나요? |
+|------|------|------------|
+| `bq_query` | BigQuery 테이블 조회 | 일반 테이블 데이터 조회 |
+| `bq_metadata` | 스키마/테이블 목록 | 데이터 구조 파악 |
+| `bq_status` | 연결 상태 확인 | 연결 문제 진단 |
+| `bq_ga4_events` | GA4 Export 이벤트 조회 | event_params 자동 추출 |
+
+### BigQuery 고급 도구 (v2.1.0 신규)
+
+| Tool | 설명 | 언제 쓰나요? |
+|------|------|------------|
+| `bq_raw_sql` | SQL 직접 실행 | 복잡한 JOIN, 윈도우 함수 등 |
+| `bq_event_params` | 이벤트 파라미터 추출 | page_location, page_title 등 쉽게 추출 |
+| `bq_user_journey` | 사용자 여정 분석 | 특정 사용자가 어떤 행동을 했는지 |
+| `bq_funnel` | 퍼널 분석 | 단계별 전환율 자동 계산 |
+
+---
 
 ## 사용 예시
 
-Claude Code에서 자연어로 질문:
+Claude Code에서 자연어로 질문하세요:
+
+### 기본 질의
 
 ```
 "지난 7일 세션수 보여줘"
 "채널별 전환수 알려줘"
 "어제 대비 오늘 트래픽 어때?"
 "랜딩 페이지별 이탈률 분석해줘"
-"캠페인별 성과 비교해줘"
 ```
 
+### 고급 질의 (v2.1.0)
+
+```
+"page_view 이벤트에서 page_location 파라미터 추출해줘"
+"사용자 ID 12345678의 행동 여정 보여줘"
+"page_view → post_detail_view → post_create_start 퍼널 분석해줘"
+"디바이스별 전환율 비교해줘"
+```
+
+### 실제 결과 예시 (퍼널 분석)
+
+```
+## 요약
+page_view → post_create_start 전환율: 2.3% | 1,215 → 28명
+
+## 인사이트
+1. 전체 전환율: 2.3% (1,215명 중 28명 완료)
+2. 최대 이탈 구간: page_view → post_detail_view (89.8% 이탈)
+3. post_detail_view → post_create_start: 22.8% 전환 (개선 필요)
+
+## 퍼널 시각화
+1. page_view            ██████████████████████████████ 1,215명 (100%)
+2. post_detail_view     ███░░░░░░░░░░░░░░░░░░░░░░░░░░░ 123명 (10.1%)
+3. post_create_start    █░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 28명 (2.3%)
+```
+
+---
+
+## v2.1.0 주요 업데이트
+
+### 버그 수정
+
+- `bq_ga4_events` GROUP BY 오류 해결
+  - 이제 metrics 있을 때/없을 때 모두 정상 동작
+
+### 새 기능
+
+- **복합 필터 지원**: `filterLogic: "AND" | "OR"` 옵션 추가
+- **Raw SQL 실행**: 복잡한 쿼리도 직접 작성 가능 (SELECT만 허용)
+
+### 새 도구 4개 추가
+
+| 도구 | 하는 일 |
+|------|--------|
+| `bq_raw_sql` | SQL 직접 실행 (UNNEST, JOIN 등) |
+| `bq_event_params` | event_params 쉽게 추출 |
+| `bq_user_journey` | 사용자별 이벤트 시퀀스 분석 |
+| `bq_funnel` | 전환 퍼널 자동 계산 |
+
+---
+
 ## CLI 명령어
 
 ```bash
 # 인터랙티브 메뉴
-npx careerly-ga4-mcp
+npx careerly-data-mcp
 
-# 초기 설정 (자동 키 파일 탐지 + Claude Code 자동 등록)
-npx careerly-ga4-mcp setup
+# 초기 설정
+npx careerly-data-mcp setup
 
-# 서버 정보 확인
-npx careerly-ga4-mcp info
+# 연결 테스트
+npx careerly-data-mcp test-connection
 
-# GA4 연결 테스트
-npx careerly-ga4-mcp test-connection
+# 서버 정보
+npx careerly-data-mcp info
 
 # MCP 서버 시작 (수동)
-npx careerly-ga4-mcp serve
+npx careerly-data-mcp serve
 ```
 
-## 인터랙티브 메뉴
+> **별칭**: `careerly-ga4-mcp`, `careerly-ga4`도 동일하게 동작합니다.
 
-```bash
-npx careerly-ga4-mcp
-```
+---
 
-```
-  Careerly GA4 MCP Server
-  ─────────────────────────────────────
+## 문제 해결
+
+### MCP 서버가 `/mcp`에 안 보여요
+
+1. Claude Code 완전 종료 후 재시작
+2. `claude mcp list`로 등록 확인
+3. `npx careerly-data-mcp setup` 재실행
+
+### PERMISSION_DENIED 에러
+
+**GA4 권한 문제:**
+- GA4 Admin > 속성 액세스 관리 > Service Account 이메일 추가
+
+**BigQuery 권한 문제:**
+- IAM & Admin > Service Account에 "BigQuery 데이터 뷰어" 역할 추가
 
-Status:      ✓ connected
-Property ID: 123456789
-Credentials: ~/project/service-account.json
-Tools:       3 tools
+### MCP 제거
 
-? 선택하세요
-❯ View tools
-  Reconnect
-  Test connection
-  Disable
+```bash
+# CLI로 삭제
+claude mcp remove careerly-ga4 -s user
+
+# 또는 메뉴에서
+npx careerly-data-mcp
+# → Disable 선택
 ```
 
-## 수동 설정
+---
+
+## 수동 설정 (선택)
 
 ### Claude CLI로 추가
 
@@ -119,112 +225,52 @@ Tools:       3 tools
 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
+  -e BQ_PROJECT_ID=your-project-id \
+  -e GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json \
+  -- npx -y careerly-data-mcp serve
 ```
 
 ### 설정 파일 직접 수정
 
-`~/.claude/settings.local.json`에 직접 추가:
+`~/.claude/settings.local.json`:
 
 ```json
 {
   "mcpServers": {
     "careerly-ga4": {
       "command": "npx",
-      "args": ["-y", "careerly-ga4-mcp", "serve"],
+      "args": ["-y", "careerly-data-mcp", "serve"],
       "env": {
         "GA4_PROPERTY_ID": "123456789",
-        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
+        "BQ_PROJECT_ID": "your-project-id",
+        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/key.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)
+- `bq_raw_sql`은 **SELECT/WITH 문만 허용** (INSERT, DELETE 등 차단)
+- Service Account 키 파일은 **개인 로컬에서만 관리**
+- 민감 데이터 접근 시 권한 최소화 원칙 적용
 
-| 차원 | 설명 |
-|------|------|
-| `date` | 날짜 |
-| `sessionDefaultChannelGroup` | 채널 |
-| `sessionSourceMedium` | 소스/매체 |
-| `sessionCampaignName` | 캠페인 |
-| `landingPage` | 랜딩 페이지 |
-| `deviceCategory` | 디바이스 |
-| `country` | 국가 |
+---
 
 ## 개발
 
 ```bash
-# 의존성 설치
-npm install
-
-# 빌드
-npm run build
-
-# 개발 모드
-npm run dev
-
-# 타입 체크
-npm run typecheck
+npm install     # 의존성 설치
+npm run build   # 빌드
+npm run dev     # 개발 모드 (watch)
+npm run typecheck  # 타입 체크
 ```
 
+---
+
 ## 라이선스
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "careerly-data-mcp",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "GA4 + BigQuery 데이터 분석 MCP 서버 for Claude Code",
   "type": "module",
   "main": "dist/index.js",