Whatap Mxql Cli

🚀 WhaTap MXQL CLI

WhaTapのモニタリングデータをMXQL（Metrics Query Language）で照会するコマンドラインインターフェースです。このツールを使用することで、ユーザーは安全に認証し、プロジェクトを管理し、強力な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

💡 使用ヒント

ログインせずにどのコマンドを実行しても、自動的にログインプロンプトが表示されます！

✨ 主な機能

• 🔐 安全な認証: AES-256-GCMで暗号化されたセッションを保存します。
• 📊 プロジェクト管理: アクセス可能なすべてのプロジェクトを照会およびフィルタリングします。
• 🔍 MXQLクエリ: 強力なMXQLクエリを実行します（複雑なパイプラインをサポート）。
• 🎨 様々な出力形式: テーブル、JSON、CSVなどの形式で出力します。
• 💬 対話型REPL: インタラクティブなクエリ実行環境を提供します。
• ⏰ 時間範囲のサポート: プリセットおよびカスタムの時間範囲を設定できます。
• 🚀 MCPサーバ: Claude Codeとの統合が完了しました！（ツールを提供）
• 🤖 Skill統合: mxql-for-claude-code Skillと一緒に使用できます（自然言語 → 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

高度な使用法

# 高度なMXQLクエリの実行例
./bin/whatap-mxql query 27506 "CATEGORY app_counter FILTER some_condition" -r 48h

📚 ドキュメント

コマンド一覧

詳細な使用方法については、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ツール) whatap.getProjects() - プロジェクトの一覧を確認します。
  4. (MCPツール) whatap.executeMxql(pcode, mxql) - クエリを実行します。
  5. 結果を分析し、応答します。

詳細なインストールガイドについては、MCP_INSTALLATION.mdを参照してください。

出力例

プロジェクト一覧

✓ 12個のプロジェクトが見つかりました

┌──────────────┬─────────────────────────┬─────────┬────────────┐
│ プロジェクトコード │ プロジェクト名            │ タイプ    │ ステータス     │
├──────────────┼─────────────────────────┼─────────┼────────────┤
│ 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

テスト

# すべてのテストを実行します
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 (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/                     # ビルド出力

テストの状況

Coreモジュール (52個の単体テスト)

• ✅ SessionStore: 16/16のテストに合格しました。
• ✅ AuthManager: 16/16のテストに合格しました。
• ✅ WhatapClient: 13/13のテストに合格しました。
• ✅ MxqlExecutor: 7/7のテストに合格しました。

CLI

• ✅ login: 正常に動作します。
• ✅ logout: 正常に動作します。
• ✅ projects: 正常に動作します (12個のプロジェクトを照会)。
• ✅ query: 正常に動作します (実際のデータを照会成功)。
• ✅ interactive: 正常に動作します。
• ✅ 出力形式: テーブル、JSON、CSVすべて正常に動作します。

実際のデータ照会

• ✅ 複雑なMXQLパイプラインクエリを実行します。
• ✅ プロジェクト27506からsessionCountデータを照会します。
• ✅ 167個の行の集計結果を返します。
• ✅ バイナリデータを含む複雑な構造を処理します。

詳細な検証結果については、VERIFICATION_REPORT.mdを参照してください。

📄 ライセンス

MIT

セキュリティ

セッションデータはAES-256-GCMを使用して暗号化されています。暗号化キーは、制限付きのパーミッション (0600) でローカルに保存されます。

.env.testや資格情報を含むファイルをバージョン管理にコミットしないでください。