whistle.agent-mcp

English

Позволяет AI-ассистентам с поддержкой MCP напрямую запрашивать трафик HTTP, HTTPS и WebSocket, который в данный момент захвачен Whistle.

Вам не нужно экспортировать сессии, копировать содержимое ответов или вручную собирать информацию о запросах. После подключения можно прямо попросить AI искать запросы, просматривать полные сессии и анализировать фреймы WebSocket.

Для чего это подходит

• Находить последние запросы, завершившиеся ошибкой, таймаутом или совпавшие с конкретным URL.

• Просматривать заголовки запроса и ответа, тело, время выполнения и совпавшие правила для одного запроса.

• Разбирать содержимое сообщений WebSocket и направление отправки/получения.

• Помогать AI анализировать сетевые проблемы без изменения конфигурации Whistle и захваченных данных.

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 会话最近由服务端发送的消息。

Предоставляемые инструменты

Идентификаторы сессий из результатов поиска можно передавать в инструменты деталей и фреймов.

Безопасность и ограничения

• Все инструменты доступны только для чтения: они не изменяют правила, настройки прокси или захваченные данные и не воспроизводят запросы.

• Чувствительные заголовки запроса, такие как authorization, cookie, API Key, Token и т.п., автоматически заменяются на [REDACTED].

• Текстовое тело возвращается максимум 200 000 символов; для бинарного содержимого возвращается только base64-превью ограниченной длины.

• Данные берутся из кэша Whistle в памяти, поэтому более старые сессии могли уже истечь.

• По умолчанию принимается только локальный Origin. Не открывайте порт UI Whistle в ненадёжную сеть без аутентификации.

Чтобы добавить Bearer Token для MCP-эндпоинта, задайте его при запуске Whistle:

WHISTLE_MCP_TOKEN='your-token' w2 restart

Затем настройте тот же Bearer Token для этого сервиса в MCP-клиенте. Также можно добавить дополнительные точные Origins через WHISTLE_MCP_ALLOWED_ORIGINS; несколько значений разделяются запятыми.

Разработка

Перейдите в каталог проекта, установите зависимости и соберите проект:

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         本地开发脚本