WhaTap MXQL CLI

# Claude CLI로 WhaTap MXQL 쿼리 실행하기 ## 🎯 개요 Claude CLI를 사용해서 WhaTap 모니터링 데이터를 자연어로 조회할 수 있습니다. ## 📋 필수 조건 1. **MCP 서버 빌드 완료** ```bash cd /Users/devload/whatap/mxqlMCPWork/whatap-mxql-cli npm run build ``` 2. **인증 방법 (둘 중 하나)** ### 방법 1: 환경변수 설정 (권장) MCP 설정 파일 (`~/.claude/mcp/whatap-mxql.json`)에 credentials를 추가: ```json { "mcpServers": { "whatap-mxql": { "command": "node", "args": ["/절대/경로/whatap-mxql-cli/dist/mcp/index.js"], "env": { "WHATAP_EMAIL": "your-email@whatap.io", "WHATAP_PASSWORD": "your-password", "WHATAP_SERVICE_URL": "https://service.whatap.io" } } } } ``` ### 방법 2: CLI로 한 번 로그인 ```bash ./bin/whatap-mxql login ``` 세션이 `~/.whatap-mxql/session.enc`에 암호화되어 저장됩니다. ## 🚀 실행 방법 ### 기본 실행 (인터랙티브) ```bash claude --mcp-config ~/.claude/mcp/whatap-mxql.json "프로젝트 27506에서 지난 일주일간 브라우저 사용자 세션이 얼마나 있었는지 알려줘." ``` ### 빠른 실행 (permission skip) ```bash claude --mcp-config ~/.claude/mcp/whatap-mxql.json --dangerously-skip-permissions "프로젝트 27506에서 지난 일주일간 브라우저 사용자 세션이 얼마나 있었는지 알려줘." ``` ### 파일에서 프롬프트 읽기 ```bash claude --mcp-config ~/.claude/mcp/whatap-mxql.json --dangerously-skip-permissions "$(cat prompts/session-analysis.txt)" ``` ### 출력만 받기 (스크립트용) ```bash claude --mcp-config ~/.claude/mcp/whatap-mxql.json --print --dangerously-skip-permissions "프로젝트 27506에서 최근 24시간 세션 수 알려줘." ``` ## 📝 준비된 프롬프트 파일 ### 1. 세션 분석 ```bash claude --mcp-config ~/.claude/mcp/whatap-mxql.json --dangerously-skip-permissions "$(cat prompts/session-analysis.txt)" ``` ### 2. 페이지 성능 ```bash claude --mcp-config ~/.claude/mcp/whatap-mxql.json --dangerously-skip-permissions "$(cat prompts/page-performance.txt)" ``` ### 3. AJAX 모니터링 ```bash claude --mcp-config ~/.claude/mcp/whatap-mxql.json --dangerously-skip-permissions "$(cat prompts/ajax-monitoring.txt)" ``` ### 4. 에러 추적 ```bash claude --mcp-config ~/.claude/mcp/whatap-mxql.json --dangerously-skip-permissions "$(cat prompts/error-tracking.txt)" ``` ### 5. 종합 대시보드 ```bash claude --mcp-config ~/.claude/mcp/whatap-mxql.json --dangerously-skip-permissions "$(cat prompts/comprehensive-dashboard.txt)" ``` ## 🔧 편의 스크립트 만들기 ### Alias 설정 ```bash # ~/.zshrc 또는 ~/.bashrc에 추가 alias whatap-query='claude --mcp-config ~/.claude/mcp/whatap-mxql.json --dangerously-skip-permissions' # 사용 예시 whatap-query "프로젝트 27506에서 최근 1시간 세션 수 알려줘" ``` ### 스크립트 파일 생성 ```bash cat > ~/bin/whatap-query << 'EOF' #!/bin/bash claude --mcp-config ~/.claude/mcp/whatap-mxql.json --dangerously-skip-permissions "$@" EOF chmod +x ~/bin/whatap-query # 사용 예시 whatap-query "프로젝트 27506 세션 조회" ``` ## ⚙️ 옵션 설명 | 옵션 | 설명 | |------|------| | `--mcp-config <file>` | MCP 서버 설정 파일 지정 (필수) | | `--dangerously-skip-permissions` | 권한 확인 건너뛰기 (빠른 실행) | | `--print` / `-p` | 결과만 출력하고 종료 (스크립트용) | | `--output-format json` | JSON 형식으로 출력 | | `--model opus` | 모델 변경 (opus, sonnet 등) | ## 📊 예시 프롬프트 ### 자연어 프롬프트 (추천) ```bash # 좋은 예시 ✅ whatap-query "프로젝트 27506에서 지난 일주일간 브라우저 사용자 세션이 얼마나 있었는지 알려줘" whatap-query "최근 24시간 동안 페이지 로드 시간이 3초 이상인 페이지들 찾아줘" whatap-query "AJAX 요청 중 에러가 발생한 것들을 분석해줘" ``` ### ❌ 피해야 할 프롬프트 ```bash # 카테고리를 직접 지정하면 Skill의 목적을 상실합니다 whatap-query "rum_session_count 카테고리를 조회해줘" # ❌ # 자연어로 요청하세요 whatap-query "세션 데이터를 조회해줘" # ✅ ``` ## 🔍 동작 방식 1. **자연어 입력**: 사용자가 자연어로 쿼리 요청 2. **MXQL 생성**: Claude가 적절한 MXQL 쿼리 생성 3. **MCP Tool 실행**: `whatap.executeMxql` Tool이 실제 API 호출 4. **결과 분석**: Claude가 결과를 분석해서 자연어로 응답 ``` 사용자 프롬프트 ↓ Claude (MXQL 생성) ↓ MCP Tool (whatap.executeMxql) ↓ WhaTap API ↓ 결과 반환 및 분석 ``` ## 🚨 주의사항 ### 1. Skill은 CLI에서 작동하지 않음 - `mxql-for-claude-code` Skill은 Claude Desktop/Code IDE에서만 작동 - CLI에서는 MCP Tools만 사용 가능 - Claude가 직접 MXQL을 생성해야 함 ### 2. 권한 확인 - `--dangerously-skip-permissions`는 신뢰하는 디렉토리에서만 사용 - 프로덕션 환경에서는 권한 확인을 거치는 것을 추천 ### 3. 세션 만료 - 로그인 세션이 만료되면 다시 로그인 필요: ```bash ./bin/whatap-mxql login ``` ## 💡 팁 ### 1. JSON 출력으로 스크립트 연동 ```bash claude --mcp-config ~/.claude/mcp/whatap-mxql.json \ --print \ --output-format json \ --dangerously-skip-permissions \ "프로젝트 27506 세션 수" | jq '.data' ``` ### 2. 여러 프로젝트 조회 ```bash whatap-query "사용 가능한 프로젝트 목록을 보여줘" ``` ### 3. 복잡한 분석 ```bash whatap-query "프로젝트 27506에서 최근 7일과 그 이전 7일의 세션 수를 비교해줘" ``` ## 📖 더 보기 - [CLI 가이드](./CLI_GUIDE.md) - [MCP 설치 가이드](./MCP_INSTALLATION.md) - [완벽 가이드](./COMPLETE_GUIDE.md)