pcap-mcp

基于 tshark/Wireshark dissector 的 PCAP 分析 MCP Server。

它把 Wireshark 常用的工作流（Display Filter 检索、字段抽取/时间线、按帧下钻、会话跟踪、导出 Packet List）封装为一组结构化 MCP tools，方便智能体/脚本按“像 Wireshark 一样”的方式自动化排障。

适用场景

• 5G 核心网/无线侧信令排障：NGAP/NAS-5GS/PFCP/GTPv2/GTP
• IMS/SIP 呼叫问题排查：SIP + Rx(Diameter) + SBI(HTTP2)
• QoS/策略问题：Rx AAR/AAA、PCF /npcf*、SMF 下发 packet filter 与 UE reject 的因果链

依赖

• Python: >=3.10
• 系统工具：tshark（必须）、capinfos（建议，通常随 wireshark 安装）

安装

pip install -r requirements.txt

如需以本地源码方式使用：

pip install -e .

启动

python3 -m pcap_mcp

或使用脚本入口：

pcap-mcp

配置

默认会尝试读取仓库根目录的 pcap_mcp_config.json。也可以通过环境变量指定：

• PCAP_MCP_CONFIG_JSON=/abs/path/to/pcap_mcp_config.json

常用配置项（见 pcap_mcp_config.json）：

• allowed_pcap_dirs: 允许分析的 PCAP 目录白名单
• allow_any_pcap_path: 是否允许任意绝对路径 PCAP（默认 false，建议保持关闭）
• global_decode_as: 全局 tshark -d 规则（例如把某端口按 http2 解码）
• profiles: 常用 display filter / decode-as 组合
• packet_list_columns: Packet List 导出列模板（用于 Diameter/HTTP2/SIP 跟踪字段）

MCP Tools（已实现）

• pcap_config_get
  • 获取当前加载的配置快照（profiles、packet_list_columns 等）
• pcap_config_reload
  • 重新加载配置文件（无需重启 server）
• pcap_list_fields
  • 字段发现：等价 tshark -G fields 的可搜索封装
• pcap_info
  • 抓包摘要：包数/时间范围/sha256/tshark 版本/是否包含常见协议等
• pcap_frames_by_filter
  • 输入 display filter，返回匹配的 frame.number 列表（分页）
• pcap_timeline
  • 输入 display filter + fields，返回“时间线表格”（分页）
• pcap_frame_detail
  • 指定帧下钻：
    • restrict_layers=true + layers=[...]：只输出指定协议树（更像“只看关心层”）
    • restrict_layers=false：输出完整协议树（等价 Wireshark 全量下钻）
    • verbosity=full：额外输出十六进制（tshark -x）
    • max_bytes：截断保护
• pcap_text_search
  • 在过滤后的帧集合里做文本搜索（内部会抓 detail 形成 snippet）
• pcap_follow
  • 会话跟踪：从指定帧提取并生成 follow filter（例如 HTTP2 streamid / Diameter Session-Id / SIP Call-ID）
• pcap_packet_list
  • 导出类似 Wireshark Packet List 的 TSV 文件，并返回预览行

推荐工作流（Wireshark-like）

1. pcap_info：确认抓包概况、协议是否齐全
2. pcap_packet_list：先导出一个“全局 Packet List”，观察主要协议与时间窗
3. pcap_frames_by_filter：对关键协议/错误码做一次定位（例如 sip.Status-Code==580、diameter.cmd.code==265、http2.headers.path contains "npcf"）
4. pcap_frame_detail：对关键帧下钻（必要时 restrict_layers=false + verbosity=full）
5. pcap_follow：用 SIP Call-ID / Diameter Session-Id / HTTP2 streamid 串起完整会话
6. pcap_timeline：抽关键字段形成“可读的时间线”并对齐多协议因果关系

示例（以工具调用参数为主）

1）按 SIP 580 定位并下钻

• pcap_frames_by_filter

{
  "pcap_path": "/home/ailink/code/mcp/test_iphone_call_jx-1230.pcap",
  "display_filter": "sip && sip.Status-Code==580",
  "limit": 50,
  "offset": 0
}

• pcap_frame_detail（全量下钻）

{
  "pcap_path": "/home/ailink/code/mcp/test_iphone_call_jx-1230.pcap",
  "frame_numbers": [3470],
  "restrict_layers": false,
  "verbosity": "full",
  "max_bytes": 400000
}

2）查看 Rx AAR（cmd.code==265）里下发的 Flow-Description

{
  "pcap_path": "/home/ailink/code/mcp/test_iphone_call_jx-1230.pcap",
  "display_filter": "diameter && diameter.cmd.code==265",
  "columns_profile": "rx_compact",
  "preview_rows": 50
}

3）查询 PCF Npcf 信令

{
  "pcap_path": "/home/ailink/code/mcp/test_iphone_call_jx-1230.pcap",
  "display_filter": "http2 && http2.headers.path contains \"npcf\"",
  "limit": 200,
  "offset": 0
}

输出文件

• Packet List 导出默认写到：pcap_mcp_config.json 的 output_dir
• 文件名形如：<pcap_stem>.packet_list.<UTC_TIMESTAMP>.tsv