whistle.agent-mcp

English

让支持 MCP 的 AI 助手直接查询 Whistle 当前捕获的 HTTP、HTTPS 和 WebSocket 流量。

你不需要导出会话、复制响应内容或手动整理请求信息。连接后，可以直接让 AI 搜索请求、查看完整会话和分析 WebSocket 帧。

适合用来做什么

• 找出最近失败、超时或命中特定 URL 的请求。

• 查看一次请求的请求头、响应头、正文、耗时和匹配规则。

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