WhaTap MXQL CLI
WhaTap 모니터링 데이터를 MXQL(Metrics Query Language)로 조회하는 명령줄 인터페이스입니다.
✨ 기능
🔐 안전한 인증: AES-256-GCM 암호화된 세션 저장
📊 프로젝트 관리: 접근 가능한 모든 프로젝트 조회 및 필터링
🔍 MXQL 쿼리: 강력한 MXQL 쿼리 실행 (복잡한 파이프라인 지원)
🎨 다양한 출력 형식: Table, JSON, CSV
💬 대화형 REPL: 인터랙티브한 쿼리 실행 환경
⏰ 시간 범위 지원: 프리셋 및 커스텀 시간 범위
🚀 MCP 서버: Claude Code 통합 완료! (Tools 제공)
🤖 Skill 통합: mxql-for-claude-code Skill과 함께 사용 (자연어 → MXQL)
🚀 빠른 시작
설치
# 저장소 클론
git clone <repository-url>
cd whatap-mxql-cli
# 의존성 설치
npm install
# 빌드
npm run build
# bin 실행 권한 부여
chmod +x bin/whatap-mxql
기본 사용법
# 방법 1: 명령어 바로 실행 (자동 로그인 유도)
./bin/whatap-mxql projects
# → 로그인 안 되어 있으면 자동으로 로그인 프롬프트 표시
# 방법 2: 명시적 로그인 후 사용
./bin/whatap-mxql login
./bin/whatap-mxql projects
# 3. MXQL 쿼리 실행
./bin/whatap-mxql query 27506 "CATEGORY app_counter" -r 24h
# 4. 대화형 모드
./bin/whatap-mxql interactive
💡 TIP: 로그인 없이 어떤 명령어든 실행하면 자동으로 로그인 프롬프트가 표시됩니다!
📋 명령어
명령어 | 설명 |
login [options]
| WhaTap 서비스 로그인 |
logout
| 로그아웃 및 세션 삭제 |
projects [options]
| 프로젝트 목록 조회 |
query <pcode> [mxql] [options]
| MXQL 쿼리 실행 |
interactive [options]
| 대화형 REPL 모드 |
상세 사용법은 CLI_GUIDE.md를 참조하세요.
🤖 Claude Code 통합 (MCP)
MCP 서버 설정
# 빌드 (이미 완료된 경우 skip)
npm run build
# MCP 설정 파일 생성
mkdir -p ~/.claude/mcp
cat > ~/.claude/mcp/whatap-mxql.json << 'EOF'
{
"mcpServers": {
"whatap-mxql": {
"command": "node",
"args": ["/절대/경로/whatap-mxql-cli/dist/mcp/index.js"],
"description": "WhaTap MXQL Query Executor"
}
}
}
EOF
⚠️ 중요: /절대/경로/를 실제 프로젝트 경로로 변경하세요!
Skill 설치 (mxql-for-claude-code)
# 저장소 클론
git clone https://github.com/kyupid/mxql-for-claude-code.git
cd mxql-for-claude-code
# 설치
./install.sh
사용 예시
사용자: "PostgreSQL에서 CPU 80% 이상인 인스턴스 찾아줘"
Claude Code:
1. (Skill) PostgreSQL 카테고리 및 MXQL 패턴 학습
2. (Skill) MXQL 생성: "CATEGORY db_postgresql_counter FILTER..."
3. (MCP Tool) whatap.getProjects() - 프로젝트 목록 확인
4. (MCP Tool) whatap.executeMxql(pcode, mxql) - 쿼리 실행
5. 결과 분석 및 응답
상세 설치 가이드: MCP_INSTALLATION.md
🎨 출력 예시
프로젝트 목록
✓ Found 12 project(s)
┌──────────────┬─────────────────────────┬─────────┬────────────┐
│ Project Code │ Project Name │ Type │ Status │
├──────────────┼─────────────────────────┼─────────┼────────────┤
│ 27506 │ Browser Monitoring Demo │ BROWSER │ subscribe │
│ 44482 │ mobile test project │ MOBILE │ subscribe │
└──────────────┴─────────────────────────┴─────────┴────────────┘
MXQL 쿼리 결과
[
{
"_id_": "27506_",
"pname": "Browser Monitoring Demo",
"pcode": 27506,
"sessionCount": 108.04790419161677,
"_rows_": 167
}
]
🔧 Development
Setup
Build
Test
# Run all tests
npm test
# Run unit tests only
npm run test:unit
# Run integration tests (requires WhaTap account)
npm run test:integration
# Watch mode
npm run test:watch
# Coverage
npm run test:coverage
Lint & Format
npm run lint
npm run lint:fix
npm run format
🧪 Testing
Unit Tests
Mock-based tests for all modules without external dependencies.
Integration Tests
Real API calls to WhaTap service (requires test account).
Configure test credentials in .env.test:
WHATAP_TEST_EMAIL=your-email@whatap.io
WHATAP_TEST_PASSWORD=your-password
WHATAP_SERVICE_URL=https://service.whatap.io
RUN_INTEGRATION_TESTS=true
📁 프로젝트 구조
whatap-mxql-cli/
├── src/
│ ├── core/ # 핵심 모듈 (CLI & MCP 공유)
│ │ ├── types/ # TypeScript 타입 정의
│ │ ├── auth/ # 인증 모듈
│ │ │ ├── SessionStore.ts # 세션 저장 (AES-256-GCM)
│ │ │ └── AuthManager.ts # 인증 관리 (Cookie Jar)
│ │ ├── client/ # API 클라이언트
│ │ │ └── WhatapClient.ts # WhaTap API (Dual Auth)
│ │ └── executor/ # MXQL 실행기
│ │ └── MxqlExecutor.ts # 쿼리 실행 및 편의 메서드
│ └── cli/ # CLI 인터페이스
│ ├── commands/ # 명령어 구현
│ │ ├── login.ts
│ │ ├── logout.ts
│ │ ├── projects.ts
│ │ ├── query.ts
│ │ └── interactive.ts
│ ├── utils/ # 유틸리티
│ │ ├── formatters.ts # 출력 포맷팅
│ │ └── session.ts # 세션 관리
│ └── index.ts # CLI 진입점
├── test/ # 테스트
├── bin/ # 실행 파일
│ └── whatap-mxql
└── dist/ # 빌드 출력
📊 테스트 현황
Core 모듈 (52개 유닛 테스트)
✅ SessionStore: 16/16 테스트 통과
✅ AuthManager: 16/16 테스트 통과
✅ WhatapClient: 13/13 테스트 통과
✅ MxqlExecutor: 7/7 테스트 통과
CLI
✅ login: 정상 동작
✅ logout: 정상 동작
✅ projects: 정상 동작 (12개 프로젝트 조회)
✅ query: 정상 동작 (실제 데이터 조회 성공)
✅ interactive: 정상 동작
✅ 출력 형식: Table, JSON, CSV 모두 정상
실제 데이터 조회
상세 검증 결과는 VERIFICATION_REPORT.md를 참조하세요.
📝 License
MIT
🔒 Security
Session data is encrypted using AES-256-GCM. Encryption keys are stored locally with restricted permissions (0600).
Never commit .env.test or any files containing credentials to version control.