WhaTap MXQL

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

npm install

Build

npm run 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:

[email protected]
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 모두 정상

실제 데이터 조회

• ✅ 복잡한 MXQL 파이프라인 쿼리 실행
• ✅ 프로젝트 27506에서 sessionCount 데이터 조회
• ✅ 167개 행 집계 결과 반환
• ✅ 바이너리 데이터 포함한 복잡한 구조 처리

상세 검증 결과는 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.