careerly-data-mcp 2.1.0 → 2.2.0

package/README.md

@@ -1,6 +1,34 @@
-# Careerly GA4 MCP Server
+# Careerly Data MCP Server
 
-Claude Code에서 자연어로 GA4 데이터를 분석하는 MCP(Model Context Protocol) 서버입니다.
+Claude Code에서 **자연어로 GA4, BigQuery, Search Console 데이터를 분석**하는 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 +36,234 @@ 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
-  ─────────────────────────────────────
-
-✔ GA4 Property ID 517059569
-✔ 1개의 Service Account 키 파일 발견
-✔ 사용할 키 파일 선택 my-project-key.json (my-project-id)
-✔ 연결 성공!
-✔ Claude Code MCP 서버 등록 완료
+1. **Service Account 키 파일 자동 탐지** - 폴더에서 JSON 파일 스캔
+2. **GA4 + BigQuery 연결 테스트** - Property ID와 키 파일 검증
+3. **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. **Search Console API** 활성화
+5. **서비스 계정** 생성 후 JSON 키 다운로드
 
 ### 2. GA4 권한 설정
 
-1. [GA4 Admin](https://analytics.google.com/) > 속성 설정 > 속성 액세스 관리
-2. 서비스 계정 이메일 추가 (뷰어/읽기 전용 권한)
+- GA4 Admin > 속성 설정 > 속성 액세스 관리
+- 서비스 계정 이메일 추가 (뷰어 권한)
 
-> **Tip**: Service Account 이메일은 JSON 키 파일의 `client_email` 필드에서 확인할 수 있습니다.
+### 3. BigQuery 권한 설정
 
-## 기능
+- IAM & Admin > 서비스 계정에 **BigQuery 데이터 뷰어** 역할 추가
 
-| Tool | 설명 |
-|------|------|
-| `ga4_query` | GA4 데이터 조회 + 인사이트 생성 |
-| `ga4_metadata` | 지표/차원 목록 확인 |
-| `ga4_status` | 연결 상태 확인 |
+### 4. Search Console 권한 설정 (선택)
+
+- [Search Console](https://search.google.com/search-console) > 설정 > 사용자 및 권한
+- 서비스 계정 이메일 추가 (전체 권한 또는 제한된 권한)
+
+---
+
+## 제공 도구 (Tools)
+
+### GA4 Data API 도구
+
+| Tool | 설명 | 언제 쓰나요? |
+|------|------|------------|
+| `ga4_query` | GA4 데이터 조회 + 인사이트 | 세션, 사용자, 전환 등 기본 지표 |
+| `ga4_metadata` | 지표/차원 목록 | 어떤 데이터를 볼 수 있는지 확인 |
+| `ga4_status` | 연결 상태 확인 | 연결 문제 진단 |
+
+### BigQuery 기본 도구
+
+| 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` | 퍼널 분석 | 단계별 전환율 자동 계산 |
+
+### Google Search Console 도구 (v2.2.0 신규)
+
+| Tool | 설명 | 언제 쓰나요? |
+|------|------|------------|
+| `gsc_query` | 검색 분석 데이터 조회 | 검색어/페이지별 클릭, 노출, CTR, 순위 |
+| `gsc_status` | 연결 상태 확인 | 연결 문제 진단 |
+| `gsc_sites` | 등록된 사이트 목록 | 접근 가능한 사이트 확인 |
+
+---
 
 ## 사용 예시
 
-Claude Code에서 자연어로 질문:
+Claude Code에서 자연어로 질문하세요:
+
+### 기본 질의
 
 ```
 "지난 7일 세션수 보여줘"
 "채널별 전환수 알려줘"
 "어제 대비 오늘 트래픽 어때?"
 "랜딩 페이지별 이탈률 분석해줘"
-"캠페인별 성과 비교해줘"
 ```
 
+### 고급 질의 (v2.1.0)
+
+```
+"page_view 이벤트에서 page_location 파라미터 추출해줘"
+"사용자 ID 12345678의 행동 여정 보여줘"
+"page_view → post_detail_view → post_create_start 퍼널 분석해줘"
+"디바이스별 전환율 비교해줘"
+```
+
+### Search Console 질의 (v2.2.0)
+
+```
+"최근 28일 검색어별 클릭수 보여줘"
+"클릭률이 낮은 페이지 찾아줘"
+"모바일 vs 데스크톱 검색 성과 비교해줘"
+"순위가 높은데 CTR이 낮은 키워드 분석해줘"
+```
+
+### 실제 결과 예시 (퍼널 분석)
+
+```
+## 요약
+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.2.0 주요 업데이트 (최신)
+
+### Google Search Console 통합
+
+- **3개 새 도구 추가**: `gsc_query`, `gsc_status`, `gsc_sites`
+- 검색어/페이지별 클릭수, 노출수, CTR, 평균 순위 분석
+- 국가별, 디바이스별 필터링 지원
+- 16개월 이전 데이터까지 조회 가능
+
+### 새 환경변수
+
+| 변수 | 설명 |
+|------|------|
+| `GSC_SITE_URL` | 기본 사이트 URL (예: `https://example.com/` 또는 `sc-domain:example.com`) |
+
+### GSC 권한 설정
+
+1. Search Console > 설정 > 사용자 및 권한
+2. Service Account 이메일 추가 (전체 권한 또는 제한된 권한)
+
+---
+
+## 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
-  ─────────────────────────────────────
+## 문제 해결
 
-Status:      ✓ connected
-Property ID: 123456789
-Credentials: ~/project/service-account.json
-Tools:       3 tools
+### 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 데이터 뷰어" 역할 추가
+
+### 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 +271,54 @@ 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 GSC_SITE_URL=https://example.com/ \
+  -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",
+        "GSC_SITE_URL": "https://example.com/",
+        "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 스키마
+- `bq_raw_sql`은 **SELECT/WITH 문만 허용** (INSERT, DELETE 등 차단)
+- Service Account 키 파일은 **개인 로컬에서만 관리**
+- 민감 데이터 접근 시 권한 최소화 원칙 적용
 
-### 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
+npm install     # 의존성 설치
+npm run build   # 빌드
+npm run dev     # 개발 모드 (watch)
+npm run typecheck  # 타입 체크
 ```
 
+---
+
 ## 라이선스
 
 MIT

package/dist/cli/setup.d.ts

@@ -1,6 +1,6 @@
 /**
  * setup 명령어 - GUI 스타일
- * GA4 + BigQuery 설정 + Claude Code 자동 설정
+ * GA4 + BigQuery + Search Console 설정 + Claude Code 자동 설정
  */
 /**
  * GA4 설정
@@ -20,9 +20,17 @@ export declare function runBigQuerySetup(): Promise<{
     connected: boolean;
 }>;
 /**
- * 통합 설정 (GA4 + BigQuery)
+ * 통합 설정 (GA4 + BigQuery + GSC)
  */
 export declare function runSetup(): Promise<void>;
+/**
+ * Search Console 설정
+ */
+export declare function runGSCSetup(existingCredentialsPath?: string): Promise<{
+    siteUrl: string;
+    credentialsPath: string;
+    connected: boolean;
+}>;
 /**
  * 인터랙티브 메뉴
  */

package/dist/cli/setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/cli/setup.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAqSH;;GAEG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC,CAgED;AAED;;GAEG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC,CA4FD;AAED;;GAEG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAoJ9C;AAED;;GAEG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAmIxD"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/cli/setup.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAwTH;;GAEG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC,CAgED;AAED;;GAEG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC,CA4FD;AAED;;GAEG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAgL9C;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,uBAAuB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC,CA2ID;AAED;;GAEG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CA4JxD"}