whistle.agent-mcp

English

MCP をサポートする AI アシスタントから、Whistle が現在キャプチャしている HTTP、HTTPS、WebSocket トラフィックを直接クエリできます。

セッションのエクスポート、レスポンス内容のコピー、リクエスト情報の手動整理は不要です。接続後は、AI にリクエストの検索、完全なセッションの表示、WebSocket フレームの分析を直接依頼できます。

用途

• 最近失敗した、タイムアウトした、または特定の URL に一致したリクエストを探す。

• 1 つのリクエストについて、リクエストヘッダー、レスポンスヘッダー、ボディ、所要時間、マッチしたルールを確認する。

• WebSocket メッセージの内容と送受信の方向を調査する。

• Whistle の設定やキャプチャデータを変更せずに、AI でネットワーク問題の分析を支援する。

Related MCP server: Android Proxy MCP

クイックスタート

要件: Node.js 20+、Whistle>=2.10.7。

初回使用時は、以下のコマンドをすべてコピーして実行してください:

npm install -g whistle@latest
w2 install @wilson_janet/whistle.agent-mcp
w2 start

Whistle がすでに実行中の場合は、プラグインをインストールして再起動するだけです:

w2 install @wilson_janet/whistle.agent-mcp
w2 restart

プラグインが利用可能かを確認:

curl http://127.0.0.1:8899/whistle.agent-mcp/health

MCP クライアントの設定ファイルに追加:

{
  "mcpServers": {
    "whistle": {
      "url": "http://127.0.0.1:8899/whistle.agent-mcp/mcp"
    }
  }
}

接続完了後は、次のように直接質問できます:

查找最近 20 个状态码为 500 的请求。
查看 URL 包含 /api/orders 的最新请求，分析它为什么失败。
读取会话 1750000000000-001 的请求、响应和耗时。
查看指定 WebSocket 会话最近由服务端发送的消息。

提供されるツール

検索結果のセッション ID は、詳細やフレームのクエリツールに引き継いで渡せます。

セキュリティと制限

• すべてのツールは読み取り専用です。ルール、プロキシ設定、キャプチャデータを変更したり、リクエストを再送信したりしません。

• authorization、cookie、API Key、Token などの機密リクエストヘッダーは、自動的に [REDACTED] に置き換えられます。

• テキスト本文は最大 200,000 文字まで返されます。バイナリコンテンツは、長さが制限された base64 プレビューのみ返されます。

• データは Whistle のメモリキャッシュから取得されるため、古いセッションは期限切れになっている可能性があります。

• デフォルトではローカルホストの Origin のみを受け付けます。認証なしで Whistle UI ポートを信頼できないネットワークに公開しないでください。

MCP エンドポイントに Bearer Token を追加するには、Whistle の起動時に設定します:

WHISTLE_MCP_TOKEN='your-token' w2 restart

次に、MCP クライアントでそのサービスに同じ Bearer Token を設定します。また、WHISTLE_MCP_ALLOWED_ORIGINS を使用して追加の完全一致 Origin を追加でき、複数の値はカンマ区切りです。

開発

プロジェクトディレクトリに移動し、依存関係をインストールしてビルドします:

npm install
npm run build

ソースコードからローカルプラグインを読み込む場合、-A は whistle.agent-mcp を含む親ディレクトリを指す必要があります:

w2 start -A ..

TypeScript watcher、Whistle、ローカルプラグインのリロードを開始:

npm run dev

完全な検証:

npm run check
npm test
npm run build
npm run smoke

npm run smoke:api は、ローカルにインストールされた Whistle Local Agent API に追加で接続し、現在のキャプチャデータを使ってクエリ機能を検証します。

プロジェクト構成

index.cjs              Whistle 插件入口
src/
  plugin/handler.ts    HTTP 路由与访问控制
  mcp/server.ts        MCP 工具定义
  whistle/             API 适配、查询、脱敏、错误与类型
  testing/smoke.ts     构建后的端到端 smoke test
test/
  whistle/             Whistle 相关单元测试
scripts/dev.sh         本地开发脚本