whistle.agent-mcp

English

Permite que los asistentes de IA compatibles con MCP consulten directamente el tráfico HTTP, HTTPS y WebSocket capturado actualmente por Whistle.

No necesitas exportar sesiones, copiar contenidos de respuestas ni organizar manualmente la información de las solicitudes. Una vez conectado, puedes pedirle directamente a la IA que busque solicitudes, vea sesiones completas y analice tramas de WebSocket.

Para qué sirve

• Encontrar solicitudes recientes que fallaron, expiraron o coincidieron con una URL específica.

• Ver las cabeceras de solicitud, cabeceras de respuesta, cuerpo, tiempo de respuesta y reglas de coincidencia de una solicitud.

• Investigar el contenido y la dirección de los mensajes WebSocket.

• Permitir que la IA ayude a analizar problemas de red sin modificar la configuración de Whistle ni los datos capturados.

Related MCP server: Android Proxy MCP

Inicio rápido

Requisitos: Node.js 20+, Whistle>=2.10.7.

En el primer uso, copia y ejecuta todos los comandos siguientes:

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

Si Whistle ya está en ejecución, basta con instalar el plugin y reiniciarlo:

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

Confirma que el plugin está disponible:

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

Añade lo siguiente al archivo de configuración del cliente MCP:

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

Una vez completada la conexión, puedes hacer preguntas directamente así:

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

Herramientas proporcionadas

Los ID de sesión de los resultados de búsqueda se pueden pasar a las herramientas de consulta de detalles y de tramas.

Seguridad y limitaciones

• Todas las herramientas son de solo lectura; no modifican reglas, ajustes de proxy ni datos capturados, y no reproducen solicitudes.

• Las cabeceras de solicitud sensibles como authorization, cookie, API Key, Token, etc. se reemplazan automáticamente por [REDACTED].

• El cuerpo de texto se devuelve con un máximo de 200 000 caracteres; el contenido binario solo devuelve una vista previa base64 de longitud limitada.

• Los datos provienen de la caché en memoria de Whistle; las sesiones más antiguas pueden haber expirado.

• De forma predeterminada, solo se aceptan orígenes locales. No expongas el puerto de la interfaz de Whistle a redes no confiables sin autenticación.

Para añadir un Bearer Token al endpoint de MCP, configúralo al iniciar Whistle:

WHISTLE_MCP_TOKEN='your-token' w2 restart

Luego configura el mismo Bearer Token para ese servicio en el cliente MCP. También puedes añadir orígenes exactos adicionales mediante WHISTLE_MCP_ALLOWED_ORIGINS, separando varios valores con comas.

Desarrollo

Entra en el directorio del proyecto, instala las dependencias y compila:

npm install
npm run build

Al cargar un plugin local desde el código fuente, -A debe apuntar al directorio padre que contiene whistle.agent-mcp:

w2 start -A ..

Inicia el watcher de TypeScript, Whistle y la recarga del plugin local:

npm run dev

Verificación completa:

npm run check
npm test
npm run build
npm run smoke

npm run smoke:api se conecta adicionalmente a la API del Agente Local de Whistle instalada en la máquina y verifica la capacidad de consulta con los datos capturados actuales.

Estructura del proyecto

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