README.md•7.44 kB
# 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)
## 🚀 빠른 시작
### 설치
```bash
# 저장소 클론
git clone <repository-url>
cd whatap-mxql-cli
# 의존성 설치
npm install
# 빌드
npm run build
# bin 실행 권한 부여
chmod +x bin/whatap-mxql
```
### 기본 사용법
```bash
# 방법 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](./CLI_GUIDE.md)를 참조하세요.
## 🤖 Claude Code 통합 (MCP)
### MCP 서버 설정
```bash
# 빌드 (이미 완료된 경우 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)
```bash
# 저장소 클론
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](./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 쿼리 결과
```json
[
{
"_id_": "27506_",
"pname": "Browser Monitoring Demo",
"pcode": 27506,
"sessionCount": 108.04790419161677,
"_rows_": 167
}
]
```
## 🔧 Development
### Setup
```bash
npm install
```
### Build
```bash
npm run build
```
### Test
```bash
# 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
```bash
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`:
```bash
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 모두 정상
### 실제 데이터 조회
- ✅ 복잡한 MXQL 파이프라인 쿼리 실행
- ✅ 프로젝트 27506에서 sessionCount 데이터 조회
- ✅ 167개 행 집계 결과 반환
- ✅ 바이너리 데이터 포함한 복잡한 구조 처리
상세 검증 결과는 [VERIFICATION_REPORT.md](./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.