# whistle.agent-mcp

[English](./README.en.md)

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

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

## 适合用来做什么

- 找出最近失败、超时或命中特定 URL 的请求。
- 查看一次请求的请求头、响应头、正文、耗时和匹配规则。
- 排查 WebSocket 消息内容和收发方向。
- 在不修改 Whistle 配置和捕获数据的前提下，让 AI 辅助分析网络问题。

## 快速开始

要求：Node.js 20+、**Whistle>=2.10.7**。

首次使用时，复制并执行下面的全部命令：

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

如果 Whistle 已经在运行，只需安装插件并重启：

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

确认插件可用：

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

在 MCP 客户端的配置文件中添加：

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

连接完成后，可以直接这样提问：

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

## 提供的工具

| 工具 | 作用 |
| --- | --- |
| `whistle_search_sessions` | 按 URL、方法、状态码、类型或时间搜索捕获会话。 |
| `whistle_get_session` | 读取单个会话的请求、响应、耗时和匹配规则。 |
| `whistle_get_frames` | 读取 WebSocket 或 Socket 会话帧。 |

搜索结果中的会话 ID 可以继续传给详情和帧查询工具。

## 安全与限制

- 所有工具均为只读，不会修改规则、代理设置或捕获数据，也不会重放请求。
- `authorization`、`cookie`、API Key、Token 等敏感请求头会自动替换为 `[REDACTED]`。
- 文本正文最多返回 200,000 个字符；二进制内容只返回有限长度的 base64 预览。
- 数据来自 Whistle 内存缓存，较早的会话可能已经过期。
- 默认只接受本机 Origin。不要在没有认证的情况下把 Whistle UI 端口暴露到不可信网络。

如需为 MCP 端点增加 Bearer Token，在启动 Whistle 时设置：

```bash
WHISTLE_MCP_TOKEN='your-token' w2 restart
```

然后在 MCP 客户端中为该服务配置相同的 Bearer Token。也可以通过 `WHISTLE_MCP_ALLOWED_ORIGINS` 添加额外的精确 Origin，多个值用逗号分隔。

## 开发

进入项目目录后，安装依赖并构建：

```bash
npm install
npm run build
```

从源码加载本地插件时，`-A` 必须指向包含 `whistle.agent-mcp` 的父目录：

```bash
w2 start -A ..
```

启动 TypeScript watcher、Whistle 和本地插件重载：

```bash
npm run dev
```

完整验证：

```bash
npm run check
npm test
npm run build
npm run smoke
```

`npm run smoke:api` 会额外连接本机安装的 Whistle Local Agent API，并使用当前捕获数据验证查询能力。

## 项目结构

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