JinDaGe - whatap-mxql-cli MCP Details

article

README

🚀 WhaTap MXQL CLI

WhaTap MXQL CLI 是一个命令行界面工具，用于通过 MXQL（指标查询语言）查询 WhaTap 监控数据，为用户提供便捷、高效的数据查询体验。

✨ 主要特性

🔐 安全认证：采用 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 [options] | 登录 WhaTap 服务 | | logout | 登出并删除会话 | | projects [options] | 查询项目列表 | | query <pcode> [mxql] [options] | 执行 MXQL 查询 | | interactive [options] | 进入交互式 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 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。

🎨 输出示例

项目列表

✓ 找到 12 个项目

┌──────────────┬─────────────────────────┬─────────┬────────────┐
│ 项目代码 │ 项目名称            │ 类型    │ 状态     │
├──────────────┼─────────────────────────┼─────────┼────────────┤
│ 27506        │ Browser Monitoring Demo │ BROWSER │ 订阅中  │
│ 44482        │ mobile test project     │ MOBILE  │ 订阅中  │
└──────────────┴─────────────────────────┴─────────┴────────────┘

MXQL 查询结果

[
  {
    "_id_": "27506_",
    "pname": "Browser Monitoring Demo",
    "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

测试说明

单元测试

基于模拟的测试，适用于所有无外部依赖的模块。

集成测试

对 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/                     # 构建输出

测试现状

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。

📄 许可证

本项目采用 MIT 许可证。

🔒 安全说明

会话数据使用 AES - 256 - GCM 加密，加密密钥以受限权限（0600）存储在本地。

请勿将 .env.test 或任何包含凭证的文件提交到版本控制系统。

whatap-mxql-cli