whatap-mxql-客户端
项目介绍
WhaTap MXQL CLI
WhaTap 监控数据的命令行接口，通过 MXQL（指标查询语言）进行查询。
✨ 功能
- 🔐 安全认证：使用 AES-256-GCM 加密的会话存储
- 📊 项目管理：查询并过滤所有可访问的项目
- 🔍 MXQL 查询：执行强大的 MXQL 查询（支持复杂的管道）
- 🎨 多种输出格式：Table、JSON、CSV
- 💬 交互式 REPL：交互式的查询执行环境
- ⏰ 时间范围支持：预设及自定义时间范围
- 🚀 MCP 服务器：与 Claude Code 完成集成！（提供工具）
- 🤖 技能集成：与 mxql-for-claude-code 技能一起使用（自然语言 → 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
💡 提示：如果没有登录就执行任何命令，会自动显示登录提示！
📋 命令
| 命令 | 描述 |
|---|---|
login [选项] | 登录 WhaTap 服务 |
logout | 注销并删除会话 |
projects [选项] | 查询项目列表 |
query <pcode> [mxql] [选项] | 执行 MXQL 查询 |
interactive [选项] | 交互式 REPL 模式 |
详细使用方法参见 CLI_GUIDE.md。
🤖 Claude Code 集成 (MCP)
MCP 服务器设置
# 构建（如果已经完成则跳过）
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 查询执行器"
}
}
}
EOF
⚠️ 重要：请将 /绝对/路径/ 替换为实际的项目路径！
技能安装 (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. (技能) 学习 PostgreSQL 类别及 MXQL 模式
2. (技能) 生成 MXQL: "CATEGORY db_postgresql_counter FILTER..."
3. (MCP 工具) whatap.getProjects() - 查看项目列表
4. (MCP 工具) whatap.executeMxql(pcode, mxql) - 执行查询
5. 分析结果并响应
详细安装指南：MCP_INSTALLATION.md
🎨 输出示例
项目列表
✓ 发现 12 个项目
┌──────────────┬─────────────────────────┬─────────┬────────────┐
│ 项目代码 │ 项目名称 │ 类型 │ 状态 │
├──────────────┼─────────────────────────┼─────────┼────────────┤
│ 27506 │ 浏览器监控演示 │ BROWSER │ 订阅 │
│ 44482 │ 移动测试项目 │ MOBILE │ 订阅 │
└──────────────┴─────────────────────────┴─────────┴────────────┘
MXQL 查询结果
[
{
"_id_": "27506_",
"pname": "浏览器监控演示",
"pcode": 27506,
"sessionCount": 108.04790419161677,
"_rows_": 167
}
]
🔧 开发
设置
npm install
构建
npm run build
测试
# 运行所有测试
npm test
# 仅运行单元测试
npm run test:unit
# 运行集成测试（需要 WhaTap 账户）
npm run test:integration
# 监视模式
npm run test:watch
# 覆盖率
npm run test:coverage
校验 & 格式化
npm run lint
npm run lint:fix
npm run format
🧪 测试
单元测试
基于 Mock 的无外部依赖模块测试。
集成测试
对 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（双认证）
│ │ └── 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 个单元测试）
- ✅ 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。
📝 许可证
MIT
🔒 安全
会话数据使用 AES-256-GCM 加密。加密密钥本地存储且具有受限权限（0600）。
切勿将 .env.test 或任何包含凭据的文件提交到版本控制。