atengk-mcp-server-traffic-inspector

专为 AI Agent / LLM 打造的网络流量抓包、会话检索、底层链路诊断、请求重放与规则 Mock 全功能 MCP Server

📖 项目简介

atengk-mcp-server-traffic-inspector 是一款工业级全栈网络流量巡检与抓包 Model Context Protocol (MCP) Server。采用 主控与受控子进程解耦架构，基于共享 SQLite WAL 数据总线连接应用层（L7 mitmproxy）与传输层（L3/L4 tshark），为 AI Agent 赋予完整的网络流量观测与排障闭环：

flowchart LR
    A["AI Agent<br/>(Claude / Cursor / Antigravity)"] <-->|"MCP 协议 (stdio / sse)"| B["FastMCP 主控进程<br/>(18 Tools 注册)"]
    B <-->|"数据查询 / 状态同步"| C[("共享 SQLite WAL<br/>数据总线")]
    B -->|"受控子进程启停"| D["mitmdump (L7 HTTP/HTTPS)"]
    B -->|"受控 CLI 执行"| E["tshark (L3/L4 PCAP)"]
    D -->|"流式入库 / 分流落盘"| C
    D <-->|"热读取 Mock 规则"| C
    E -->|"离线解析 / 实时抓包"| B

✨ 核心特性

• 🌐 应用层 (L7) 流量拦截与操控：基于受控 mitmdump 子进程捕获 HTTP/HTTPS 流量；支持多条件分页检索、基于 httpx 的参数变异重放（Replay & Diff）及 SQLite 规则热同步非阻塞 Mock/改写。
• 📡 网络层 (L3/L4) 原始网卡抓包与深度分析：集成 Wireshark tshark 引擎，支持网卡枚举、双重安全熔断（默认 2000 包 / 60 秒）的实时抓包及离线 PCAP 深度解析（TCP 重传率、RTT 时延、DNS 耗时）。
• 🩺 全栈 SessionDiagnosis 智能根因诊断：自动聚合慢请求 Top 5、互斥状态码分布及精确占比、高频端点与底层链路指标，输出结构化健康度（0~100）与可操作排障建议。
• 🛡️ LLM 上下文防爆保护：列表检索严禁携带 Body；详情接口默认截断至 2048 字符预览；超大载荷（>256KB）自动分流至临时文件，支持一键落盘原始无损文件。
• 📦 标准 HAR 1.2 归档导出：一键将捕获会话及完整载荷导出为标准 .har 归档文件，完全兼容浏览器开发者工具导入。
• 🔌 跨平台系统代理托管与安全退出还原：Windows 下通过注册表一键托管全局代理并在主控退出时自动还原初始状态（防断网）；非 Windows 平台优雅降级为环境变量配置指引。

💡 AI Agent 常用交互提示词 (Prompt Examples)

配置完成后，您可以直接在 AI Agent 对话框（如 Cursor、Claude Desktop、Antigravity 等）中发送以下提示词，Agent 将自主调用本 MCP Server 的工具链：

场景一：HTTP 会话抓包与慢接口排查

用户提示词：
“请帮我启动 HTTP 代理抓包，监听端口 8080，过滤域名 api.mycompany.com。随后我会发起业务调用，请帮我列出返回 4xx/5xx 或响应时间超过 1 秒的请求，并诊断其异常原因。”

场景二：接口故障注入与非阻塞 Mock 模拟

用户提示词：
“请添加一条 Mock 拦截规则，将所有匹配 */v1/order/checkout* 的请求拦截并直接返回 HTTP 500 状态码，响应正文为 {"error": "ORDER_TIMEOUT", "message": "支付网关超时"}，方便我测试客户端的降级容灾逻辑。”

场景三：历史请求参数变异重放与差异对比 (Replay & Diff)

用户提示词：
“请查询最近一次会话中请求 /v1/users/profile 失败的流量 ID，将请求头中的 Authorization 替换为测试 Token Bearer mock-token-123 并重放该请求，对比新响应与旧响应在状态码和返回数据上的差异。”

场景四：原始网卡抓包与底层协议链路诊断

用户提示词：
“请查看当前主机的抓包网卡列表，并在第一张网卡上启动 30 秒的 PCAP 抓包（过滤条件为 tcp port 443）。抓包完成后调用诊断工具，分析当前网络是否存在高 TCP 重传率或 RTT 延迟突增的情况。”

场景五：网络会话完整导出为标准 HAR 文件

用户提示词：
“请将当前抓包会话的所有 HTTP 流量以及完整请求/响应 Body 导出为本地文件 session_backup.har，我要导入到 Charles 和 Chrome DevTools 中进行留存归档。”

🛠️ 快速开始

方式 1：使用 uvx 免安装开箱即用（推荐）

无需手动克隆代码库，支持在各主流 MCP 客户端中一键接入：

桌面 MCP 客户端配置

在客户端配置文件（如 claude_desktop_config.json 或各编辑器的 MCP 设置）中添加：

{
  "mcpServers": {
    "traffic-inspector": {
      "command": "uvx",
      "args": [
        "atengk-mcp-server-traffic-inspector"
      ]
    }
  }
}

配置文件路径参考

• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• Cursor: Settings -> Cursor Settings -> Features -> MCP
• Windsurf: ~/.codeium/windsurf/mcp_config.json

方式 2：使用 Docker 容器化运行（内置 tshark）

Docker 镜像已内置 tshark、uv 及完整 Python 运行环境，开箱即具备全栈三/四层与七层抓包能力：

# 启动 SSE 模式容器 (8000 为 MCP 端口，8080 为 HTTP 代理端口)
docker run -d --name traffic-inspector \
  -p 8000:8000 \
  -p 8080:8080 \
  ghcr.io/atengk/mcp-server-traffic-inspector:latest

# 执行容器内运行环境自检
docker exec -it traffic-inspector mcp-server-traffic-inspector --check

方式 3：本地源码调试与开发

# 1. 克隆代码库并配置 Git 规范提交钩子
git clone https://github.com/atengk/mcp-server-traffic-inspector.git
cd mcp-server-traffic-inspector
git config core.hooksPath .githooks

# 2. 同步安装依赖
uv sync --all-extras --dev

# 3. 执行环境自检探针 (检查 Python、mitmdump、tshark 与 CA 状态)
uv run mcp-server-traffic-inspector --check

# 4. 启动本地 stdio 模式服务
uv run mcp-server-traffic-inspector

依赖要求 (Prerequisites)

抓包引擎快速安装命令

• Windows: winget install WiresharkFoundation.Wireshark（自动包含 tshark 与 Npcap）
• Ubuntu/Debian: sudo apt-get install -y tshark
• macOS: brew install wireshark

🧰 MCP Tools 能力矩阵 (18 Tools)

本服务完整实现了 18 个 MCP Tools，覆盖网络流量观测与排障的全生命周期：

⚙️ CLI 命令行参数与环境变量

命令执行参数优先级严格遵循：CLI 命令行参数 > MCP_TRAFFIC_INSPECTOR_* 环境变量 > 内置默认值。

🩺 常见问题与排障 (FAQ)

1. 抓取 HTTPS 请求提示证书不信任或 TLS 握手失败？

• 调用 MCP 工具 get_ca_certificate 获取本地 CA 证书路径。
• Windows：以管理员身份运行 certutil -addstore -user Root "<ca_cert_path>"，或双击 .cer 文件导入至“受信任的根证书颁发机构”。
• Linux：sudo cp "<ca_cert_path>" /usr/local/share/ca-certificates/mitmproxy.crt && sudo update-ca-certificates。

2. Windows 下开启系统代理后，服务退出会导致断网吗？

• 绝不会。mcp-server-traffic-inspector 内置完善的 LifecycleManager，主控进程在正常退出或接收到中断信号（SIGINT/SIGTERM）时，会自动将系统注册表还原至变更前的原始状态。

3. 在 Linux 或 Docker 容器中如何使客户端流量经过代理？

• 在 Linux/macOS/Docker 环境下，请通过标准环境变量配置客户端代理：

  export http_proxy=http://127.0.0.1:8080
  export https_proxy=http://127.0.0.1:8080
  

4. 提示 tshark 未找到？

• Windows：请安装 Wireshark 并确保勾选安装命令行工具，或在启动服务时指定 --tshark-path "C:/Program Files/Wireshark/tshark.exe"。
• Linux (Ubuntu/Debian)：sudo apt-get update && sudo apt-get install -y tshark。
• Docker：直接使用官方镜像 ghcr.io/atengk/mcp-server-traffic-inspector，镜像内已预装并配置好 tshark。

🤝 参与贡献

欢迎任何形式的贡献、建议与 Issue 反馈！请在提交代码前仔细阅读我们的 贡献指南 (CONTRIBUTING.md)。

📄 开源许可证

本项目基于 Apache License 2.0 协议开源。