# TrafficKB

HTTP 抓包与流量知识库，记录真实发生过的请求和响应。

## 能做什么

- 抓取浏览器真实流量，让 AI 查询
- 按接口查路径、参数名、参数值和响应结构
- 把 HAR、dump 或在线抓包变成可查询的数据库
- 生成 OpenAPI 3.1 和站点地图，给接口写用途标注

## 安装

需要 **Python 3.11+**。进入项目目录后：

```bash
python -m pip install .
```

## 快速开始

```bash
cp config.example.toml config.toml
traffickb --config config.toml init
```

默认数据库文件是 `~/.traffickb/traffickb.db`。

开始抓流量：

```bash
traffickb --config config.toml proxy
```

把浏览器/curl 的代理指向 `127.0.0.1:8080`。HTTPS 需要信任：

```text
~/.traffickb/mitm-ca/mitmproxy-ca-cert.pem
```

Windows 对应 `C:\Users\<你>\.traffickb\mitm-ca\mitmproxy-ca-cert.pem`。

另开终端启动查询服务：

```bash
traffickb --config config.toml serve
```

```bash
curl "http://127.0.0.1:8081/api/routes"
curl "http://127.0.0.1:8081/api/map?format=md"
curl "http://127.0.0.1:8081/api/openapi.json?origin=https://example.com"
```

也可以直接用 CLI：

```bash
traffickb --config config.toml stats
traffickb --config config.toml query "SELECT id, path_template FROM routes LIMIT 10"
```

## 接入 Agent

MCP 客户端配置：

```json
{
  "mcpServers": {
    "traffickb": {
      "command": "traffickb",
      "args": ["--config", "C:\\path\\to\\config.toml", "mcp"]
    }
  }
}
```

MCP 工具：`list_hosts`、`get_map`、`list_endpoints`、`get_endpoint`、`get_params`、
`get_observation`、`get_openapi`、`sql_query`、`get_guide`、`add_assertion`、`resolve_review`。

MCP 初始化会带上 Agent 使用说明，每个工具描述也包含适用场景。Agent 不确定时调用
`get_guide(topic=...)`，可读取 `overview`、`tools`、`data`、`workflows`、
`sql`、`output` 或 `all`。完整说明见
[agent_guide.md](src/traffic_kb/agent_guide.md)。

## 常用命令

| 命令 | 用途 |
|---|---|
| `traffickb init` | 建表 |
| `traffickb import file.har` | 导入 HAR / JSONL / dump |
| `traffickb proxy` | 启动抓包代理 |
| `traffickb serve` | 启动 HTTP API |
| `traffickb mcp` | 启动 MCP 服务 |
| `traffickb query "SQL"` | 只读查询 |
| `traffickb stats` | 库统计 |
| `traffickb maintain merge/split/recompute` | 维护路由 |

## 配置

见 [config.example.toml](config.example.toml)。常会改动：

- `[database] path`：SQLite 文件路径
- `[proxy] listen` / `ca_path`：代理监听地址和 CA 目录
- `[scope]`：允许/拒绝抓取的 host 和 path
- `[api] listen`：HTTP API 监听地址
- `[mcp] transport`：`stdio` / `sse` / `streamable-http`

## License

[MIT](LICENSE)。