Whatap Mxql Cli

🚀 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

💡 使用建議

若未登錄就執行任何命令，系統將自動彈出登錄提示。

📚 詳細文檔

📋 命令說明

詳細使用方法請參考 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 或任何包含憑證的文件提交到版本控制系統。