WhaTap MXQL命令行界面
使用MXQL（Metrics Query Language）查询Whatap监控数据的命令行界面。
功能
- 🔐 安全认证：存储AES-256-GCM加密会话
- 📊 项目管理：查看和筛选所有可访问的项目
- 🔍 MXQL查询：运行强大的MXQL查询（支持复杂的管道）
- 🎨 多种输出格式：表格、JSON、CSV
- 💬 交互式REPL：交互式查询执行环境
- ⏰ 时间范围支持：预设和自定义时间范围
- 🚀 MCP服务器：Claude Code集成完成！（工具提供）
- 🤖 Skill集成：与mxql-for-claude-code Skill一起使用（自然语言→MXQL）
🚀 快速入门
安装
# 저장소 클론
git clone
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💡 提示：在不登录的情况下运行任何命令时，将自动显示登录提示！
📋 命令
| 命令 | 说明 |
|---|---|
login [options] | 登录Whatap服务 |
logout | 注销和删除会话 |
projects [options] | 查看项目列表 |
| `query | |
| [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_安装.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
}
]🔧 发展
设置
npm install构建
npm run build测试
# 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棉绒和格式
npm run lint
npm run lint:fix
npm run format🧪 测试
单元测试
无外部依赖的所有模块的基于模拟的测试。
集成测试
对WhaTap服务的真实API调用（需要测试帐户）。
在中配置测试凭据 .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/ # 빌드 출력📊 测试现状
核心模块（52个单元测试）
- SSION Store:16/16通过测试
- AuthManager:16/16通过测试
- WhatapClient:13/13通过测试
- MxqlExecutor:7/7通过测试
命令行界面
- login:正常操作
- logout：正常动作
- projects:正常动作（查看12个项目）
- query:正常操作（实际数据查询成功）
- interactive:正常动作
- 输出格式：Table，JSON，CSV都正常
查询实际数据
- 执行复杂的MXQL管道查询
- 在27506项目中查看sessionCount数据
- 返回167行统计结果
- 涉及二进制数据的复杂结构处理
详细验证结果包括： 验证_报告.md请参阅。
📝 许可证
麻省理工学院
🔒 安全
会话数据使用AES-256-GCM加密。加密密钥以受限权限存储在本地（0600）。
永不承诺 .env.test 或任何包含版本控制凭据的文件。