MCP 服务器

WhaTap MXQL CLI

Enables querying WhaTap monitoring data using MXQL (Metrics Query Language) through Claude Code, providing project management, secure authentication, and natural language to MXQL query translation capabilities.

README

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

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:

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/                     # 빌드 출력