# fiddler-mcp

一个 MCP (Model Context Protocol) 服务，用于**分析 Telerik Fiddler 抓包产生的 SAZ 会话存档**。

把 Fiddler 导出的 `.saz` 文件交给这个服务，即可让 AI 助手完成：

- **会话总览**：方法 / 状态码 / 域名 / Content-Type 分布、流量体积、耗时分位数、4xx/5xx 错误样本
- **会话详情**：任意会话的完整请求与响应（请求行/状态行、全部 headers、自动解压并解码的 body）
- **过滤与搜索**：按 Host、方法、状态码、URL 关键词/正则、请求/响应正文关键词、大小、耗时组合过滤
- **性能分析**：最慢请求 Top N、耗时分布（DNS / TCP 连接 / TLS / 总耗时）
- **安全审计**：明文 HTTP 传输凭证、URL/正文中的密钥与 Token、Cookie 缺少 Secure/HttpOnly、敏感文件泄露、响应中的 PII（邮箱/手机号）等

## 工作原理

SAZ 是 ZIP 容器，内部结构（Fiddler Classic 5.x 及兼容版本）：

```
sample.saz
├── raw/
│   ├── 1_c.txt     客户端请求（请求行 + headers + body）
│   ├── 1_s.txt     服务端响应（状态行 + headers + body）
│   ├── 1_m.xml     会话元数据（SessionTimers 计时 / SessionFlags 进程名）
│   └── 1_w.txt     可选：WebSocket 消息
└── _index.htm      可选：会话索引（用于提取 Comments）
```

body 按 wire 原始字节存储，可能带 `Content-Encoding: gzip/deflate/br`，服务在展示与搜索时自动解压。

## 安装

```bash
cd E:\McpService\fiddler-mcp
python -m venv .venv
.venv\Scripts\pip install -e ".[dev]"
```

> 国内网络可加清华镜像：`.venv\Scripts\pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -e ".[dev]"`

> 依赖 `mcp`（官方 Python SDK），当前锁定 `mcp>=1.2,<2.0`（2.0 重构了 FastMCP API，暂不兼容）。

## 在 Fiddler 中导出 SAZ

1. 打开 Fiddler Classic，抓包完成后选中需要的会话
2. `File → Export Sessions → All Sessions`
3. 保存类型选择 **SAZ Archives**（文件名以 `.saz` 结尾）

## 接入 MCP 客户端

### Claude Desktop（`claude_desktop_config.json`）

```json
{
  "mcpServers": {
    "fiddler-mcp": {
      "command": "E:\\MCP\\Fiddler\\.venv\\Scripts\\python.exe",
      "args": ["-m", "fiddler_mcp"],
      "cwd": "E:\\MCP\\Fiddler"
    }
  }
}
```

### Cursor / 其他支持 stdio MCP 的工具

在 `.mcp.json`（项目级）或全局配置中加入：

```json
{
  "mcpServers": {
    "fiddler-mcp": {
      "command": "E:\\MCP\\Fiddler\\.venv\\Scripts\\python.exe",
      "args": ["-m", "fiddler_mcp"]
    }
  }
}
```

### 命令行冒烟测试

```bash
.venv\Scripts\python -c "import fiddler_mcp.server as s; print(s.mcp.list_tools())"
```

## 提供的工具

| 工具 | 说明 |
| --- | --- |
| `open_archive(saz_path)` | 解析并缓存 SAZ，返回概览（支持 `reload` 强制重读） |
| `list_sessions(saz_path, limit, offset)` | 分页列出会话摘要 |
| `get_session(saz_path, index, include_body, max_body_chars)` | 单个会话完整详情 |
| `filter_sessions(...)` | 组合条件过滤/搜索（Host、方法、状态码、URL 关键词/正则、正文关键词、大小、耗时） |
| `session_stats(saz_path)` | 聚合统计 |
| `slow_requests(saz_path, top_n, min_ms)` | 最慢请求排名 |
| `security_scan(saz_path, max_findings)` | 安全审计，按 high/medium/low 分级输出 |

## 开发与测试

```bash
.venv\Scripts\python -m pytest
```

测试通过合成 SAZ 夹具（覆盖 gzip body、UTF-8 BOM、中文 URL、空响应、WebSocket 标记、`_index.htm` 注释）验证解析与各分析功能。

## 已知限制

- 解析器面向 Fiddler Classic 现代版本（`raw/<N>_c.txt` / `_s.txt` / `_m.xml` 结构）；极老版本的 `cXXXXcYYYY` 命名格式不支持
- `_index.htm` 仅作 Comments 提取（尽力而为，失败不影响核心解析）
- 会话计时来自 `_m.xml` 的 `SessionTimers`；SAZ 中不包含绝对时间戳（无法还原真实抓包时刻）
- 安全扫描为启发式正则，可能存在误报/漏报，结论需人工复核
- 出于安全考虑，`list_sessions` / `filter_sessions` / `session_stats` / `slow_requests` / `security_scan` 的输出会对 URL 中敏感查询参数（token、password、secret、api_key 等）及 fragment 自动脱敏；`get_session` 是唯一返回完整 URL 与 body 的工具（用于深入检查单条会话）
- 防御性上限：单个 zip 条目 > 512MB 跳过、元数据条目 > 16MB 跳过、body 解压预览上限 64MB、`url_regex` 最长 200 字符