Whatap Mxql Cli

🚀 WhaTap MXQL CLI

A command-line interface for querying WhaTap monitoring data using MXQL (Metrics Query Language).

✨ Features

• 🔐 Secure Authentication: Stores sessions encrypted with AES-256-GCM.
• 📊 Project Management: Queries and filters all accessible projects.
• 🔍 MXQL Query: Executes powerful MXQL queries (supports complex pipelines).
• 🎨 Diverse Output Formats: Table, JSON, CSV.
• 💬 Interactive REPL: Provides an interactive query execution environment.
• ⏰ Time Range Support: Preset and custom time ranges.
• 🚀 MCP Server: Integrated with Claude Code! (Tools provided).
• 🤖 Skill Integration: Works with the mxql-for-claude-code Skill (Natural language → MXQL).

🚀 Quick Start

Installation

# Clone the repository
git clone <repository-url>
cd whatap-mxql-cli

# Install dependencies
npm install

# Build
npm run build

# Give execute permission to the bin file
chmod +x bin/whatap-mxql

Basic Usage

# Method 1: Run commands directly (triggers automatic login)
./bin/whatap-mxql projects
# → Displays the login prompt automatically if not logged in

# Method 2: Log in explicitly before use
./bin/whatap-mxql login
./bin/whatap-mxql projects

# 3. Execute an MXQL query
./bin/whatap-mxql query 27506 "CATEGORY app_counter" -r 24h

# 4. Interactive mode
./bin/whatap-mxql interactive

💡 Usage Tip

Running any command without logging in will automatically display the login prompt!

📋 Commands

Refer to CLI_GUIDE.md for detailed usage.

🤖 Claude Code Integration (MCP)

MCP Server Setup

# Build (skip if already completed)
npm run build

# Create the MCP configuration file
mkdir -p ~/.claude/mcp
cat > ~/.claude/mcp/whatap-mxql.json << 'EOF'
{
  "mcpServers": {
    "whatap-mxql": {
      "command": "node",
      "args": ["/absolute/path/whatap-mxql-cli/dist/mcp/index.js"],
      "description": "WhaTap MXQL Query Executor"
    }
  }
}
EOF

⚠️ Important Note

Replace /absolute/path/ with the actual project path!

Skill Installation (mxql-for-claude-code)

# Clone the repository
git clone https://github.com/kyupid/mxql-for-claude-code.git
cd mxql-for-claude-code

# Install
./install.sh

Usage Example

User: "Find instances with CPU over 80% in PostgreSQL."

Claude Code:
  1. (Skill) Learn the PostgreSQL category and MXQL patterns.
  2. (Skill) Generate MXQL: "CATEGORY db_postgresql_counter FILTER..."
  3. (MCP Tool) whatap.getProjects() - Check the project list.
  4. (MCP Tool) whatap.executeMxql(pcode, mxql) - Execute the query.
  5. Analyze the results and respond.

Refer to MCP_INSTALLATION.md for detailed installation instructions.

🎨 Output Examples

Project List

✓ Found 12 project(s)

┌──────────────┬─────────────────────────┬─────────┬────────────┐
│ Project Code │ Project Name            │ Type    │ Status     │
├──────────────┼─────────────────────────┼─────────┼────────────┤
│ 27506        │ Browser Monitoring Demo │ BROWSER │ subscribe  │
│ 44482        │ mobile test project     │ MOBILE  │ subscribe  │
└──────────────┴─────────────────────────┴─────────┴────────────┘

MXQL Query Result

[
  {
    "_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 a 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

Makes real API calls to the WhaTap service (requires a 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

📁 Project Structure

whatap-mxql-cli/
├── src/
│   ├── core/                 # Core modules (shared by CLI & MCP)
│   │   ├── types/           # TypeScript type definitions
│   │   ├── auth/            # Authentication module
│   │   │   ├── SessionStore.ts      # Session storage (AES-256-GCM)
│   │   │   └── AuthManager.ts       # Authentication management (Cookie Jar)
│   │   ├── client/          # API client
│   │   │   └── WhatapClient.ts      # WhaTap API (Dual Auth)
│   │   └── executor/        # MXQL executor
│   │       └── MxqlExecutor.ts      # Query execution and utility methods
│   └── cli/                  # CLI interface
│       ├── commands/        # Command implementations
│       │   ├── login.ts
│       │   ├── logout.ts
│       │   ├── projects.ts
│       │   ├── query.ts
│       │   └── interactive.ts
│       ├── utils/           # Utilities
│       │   ├── formatters.ts        # Output formatting
│       │   └── session.ts           # Session management
│       └── index.ts         # CLI entry point
├── test/                     # Tests
├── bin/                      # Executable files
│   └── whatap-mxql
└── dist/                     # Build output

📊 Test Status

Core Modules (52 unit tests)

• ✅ SessionStore: Passed 16/16 tests.
• ✅ AuthManager: Passed 16/16 tests.
• ✅ WhatapClient: Passed 13/13 tests.
• ✅ MxqlExecutor: Passed 7/7 tests.

CLI

• ✅ login: Functions correctly.
• ✅ logout: Functions correctly.
• ✅ projects: Functions correctly (queries 12 projects).
• ✅ query: Functions correctly (successfully queries real data).
• ✅ interactive: Functions correctly.
• ✅ Output formats: Table, JSON, and CSV all work correctly.

Real Data Query

• ✅ Executes complex MXQL pipeline queries.
• ✅ Queries sessionCount data from project 27506.
• ✅ Returns aggregated results of 167 rows.
• ✅ Handles complex structures including binary data.

Refer to VERIFICATION_REPORT.md for detailed verification results.

📝 License

MIT

🔒 Security

Session data is encrypted using AES-256-GCM. Encryption keys are stored locally with restricted permissions (0600).

Never commit .env.test or any files containing credentials to version control.