Register a local packet-capture file for subsequent analysis.

Call this before using tools that accept capture_id. The server stores the resolved path and file metadata in memory, but does not copy, modify, or keep the capture open. Loading an existing ID is idempotent and reports already_loaded.

Args: capture_id: Non-empty session-unique name chosen by the caller, such as office_wifi. Leading and trailing whitespace is removed. file_path: Local path to an existing .pcap or .pcapng file that is accessible to the MCP server process.

Returns: Load status, normalized capture ID, resolved path, file name, and size.

List every capture registered in the current MCP server session.

Use this to discover available capture IDs or confirm load/reload/unload operations. It reads only in-memory metadata and never rescans capture contents. Decryption-key values are never returned.

Returns: Capture count and metadata for each capture, including path, size, modification/load times, revision, and decryption-key configuration.

Remove a loaded capture from the current server session.

This forgets the capture metadata and any configured decryption keys. It never deletes or changes the source PCAP/PCAPNG file.

Args: capture_id: ID previously supplied to load_capture.

Returns: The removed capture ID and an unloaded confirmation flag.

Refresh a loaded capture after its source file changes.

The tool verifies the original file again, updates its path, size, modification time, and load time, and increments the capture revision. It does not scan packets during the reload.

Args: capture_id: ID of a currently loaded capture. clear_decryption_keys: When true, remove all keys stored for this capture. The default preserves them.

Returns: Refreshed metadata, new revision number, and a reloaded flag.

Configure Wi-Fi decryption keys for later packet analysis.

Keys exist only in server memory and are passed to TShark whenever the capture is read. Secret values are never included in tool responses or normal logs. Supported key types are wep, wpa-pwd, wpa-psk, tk, and msk.

Args: capture_id: ID of a currently loaded capture. keys: Key objects containing key_type and value. For example, [{"key_type": "wpa-pwd", "value": "password:SSID"}]. replace_existing: Replace existing keys when true; append when false. Passing an empty list with true clears all keys.

Returns: Capture ID, configured key count, and key types. Values are omitted.

Write packets matching a display filter to a new capture file.

The export uses a temporary file and replaces the destination only after TShark succeeds. It never allows the source capture to be overwritten. Configured decryption keys are applied while filtering.

Args: capture_id: ID of a currently loaded capture. filter_expression: Non-empty Wireshark display filter selecting packets. output_path: Destination ending in .pcap or .pcapng. Its parent directory must already exist and be writable by the server. overwrite: Allow replacement of an existing destination when true. Defaults to false.

Returns: Capture ID, normalized filter, resolved output path, name, and size.

Produce a quick packet-level overview of a loaded capture.

This iterates through the full capture and is useful as the first analysis call after loading. It reports packet count, observed protocol-layer names, first/last Unix timestamps, and duration.

Args: capture_id: ID of a currently loaded capture.

Returns: Packet count, sorted protocols, start/end timestamps, and duration.

Inspect PCAP/PCAPNG container and capture-interface metadata.

Use this for file format, encapsulation, snap length, timestamp precision, capture origin, comments, time range, and per-interface information. The result comes primarily from Capinfos and does not return packet dissections.

Args: capture_id: ID of a currently loaded capture.

Returns: File, timing, capture-host, and interface metadata when available.

Calculate aggregate traffic rates and packet-size statistics.

This combines Capinfos totals with a TShark pass over frame lengths. Use it to assess capture volume, duration, average traffic rate, and minimum, maximum, and average packet sizes.

Args: capture_id: ID of a currently loaded capture.

Returns: Packet/byte totals, file size, timing, rates, and packet-size metrics.

Validate capture readability and identify common packet-quality issues.

Checks malformed packets, captured-length truncation, missing core frame fields, severe decode failures, unsupported protocols, timestamps, and strict chronological order. Issue categories can overlap.

Args: capture_id: ID of a currently loaded capture. example_limit: Maximum frame numbers retained for each issue, from 0 through 100. Counts always include all matches.

Returns: Overall validity/readability, packet count, time-order status, and issue counts with example frame numbers.

List capture interfaces or radio adapters stored in the file.

This is a focused view of get_capture_metadata for multi-interface PCAPNG files. Interface fields depend on what the capture writer recorded.

Args: capture_id: ID of a currently loaded capture.

Returns: Interface count and available names, link types, snap lengths, timestamp precision, operating systems, and packet counts.

Divide the capture time range into packet and byte-count buckets.

Use this to locate bursts, quiet intervals, or the portion of a capture worth filtering in more detail. Every packet is assigned to one evenly sized time bucket.

Args: capture_id: ID of a currently loaded capture. bucket_count: Number of buckets to generate, from 1 through 100. Defaults to 20.

Returns: Overall time range plus timestamped packet/byte totals per bucket.

Find packets using a Wireshark/TShark display-filter expression.

Use standard display filters such as dns, tcp.port == 443, wlan.fc.retry == 1, or frame.number >= 10 && frame.number <= 20. This returns summaries rather than complete field trees; use dissect_packet on interesting frame numbers for full details.

Args: capture_id: ID of a currently loaded capture. filter_expression: Non-empty Wireshark display filter. This is not a BPF/libpcap capture filter. limit: Maximum results to return, from 1 through 1000. Defaults to 100.

Returns: Normalized filter, match count returned, and packet summaries containing frame number, Unix timestamp, protocols, and textual dissection.

Return the decoded protocol layers and fields for one frame.

Frame numbers are the one-based frame.number values shown by Wireshark. Use filter_packets or validation example frames to discover relevant numbers. A valid but absent frame is a successful result with found=false rather than an error.

Args: capture_id: ID of a currently loaded capture. packet_number: Positive, one-based Wireshark frame number.

Returns: Capture/frame identity, found flag, packet summary, and decoded fields grouped by protocol layer when the frame exists.

Retrieve and fully decode one packet by its Wireshark frame number.

This is a lookup-oriented alias of dissect_packet. Frame numbers are one-based values from frame.number; an absent frame returns found=false instead of raising an error.

Args: capture_id: ID of a currently loaded capture. packet_number: Positive frame.number value.

Returns: Capture/frame identity, found flag, packet summary, timestamp, protocol list, and decoded fields grouped by layer.

Retrieve packets whose Unix timestamps fall within an inclusive range.

Times use seconds since the Unix epoch, matching frame.time_epoch in Wireshark. Results are summaries; call dissect_packet when full decoded fields are required for an individual frame.

Args: capture_id: ID of a currently loaded capture. start_time: Inclusive Unix epoch start time. end_time: Inclusive Unix epoch end time. limit: Maximum number of packets, from 1 through 1000.

Returns: Requested range, normalized display filter, returned packet count, truncation flag, and packet summaries.

Retrieve packets in an inclusive Wireshark frame-number range.

Both range boundaries are included. Results contain compact packet summaries so a caller can select individual frames for detailed dissection without decoding every field in the requested range.

Args: capture_id: ID of a currently loaded capture. start_frame: Inclusive first frame number. end_frame: Inclusive last frame number. limit: Maximum number of packets, from 1 through 1000.

Returns: Requested frame range, generated display filter, returned count, truncation flag, and packet summaries.

Find packets related to a selected packet or connection event.

Correlation prefers exact TCP/UDP stream or DNS/DHCP transaction IDs, then falls back to Wi-Fi client/BSSID, IP, or Ethernet endpoints. Endpoint-based results are explicitly marked as heuristic and bounded by time.

Args: capture_id: ID of a currently loaded capture. packet_number: Positive, one-based source frame number. window_seconds: Seconds before and after the source packet to search; must be greater than zero and no more than 3600. limit: Maximum results to return, from 1 through 1000.

Returns: Source-frame status, correlation method and confidence, generated display filter, truncation flag, and related packet summaries.

Generate a chronological timeline of packet events.

The optional expression is a Wireshark display filter, not a capture filter. Events include deltas from the previous timestamp and elapsed time from the first returned event, making exchanges easier to inspect.

Args: capture_id: ID of a currently loaded capture. filter_expression: Optional Wireshark display filter. limit: Maximum number of timeline events.

Returns: Ordered events containing frame, timestamp, delta, elapsed time, protocols, textual summary, result count, and truncation status.

Retrieve packets belonging to a decoded transport or application flow.

Flow IDs are TShark stream identifiers, not port numbers. TLS and HTTP flows use their underlying tcp.stream and additionally require the selected application protocol to be present on the packet.

Args: capture_id: ID of a currently loaded capture. flow_type: One of tcp, udp, quic, tls, or http. flow_id: Non-negative TShark stream identifier. limit: Maximum results to return, from 1 through 1000.

Returns: Normalized flow type and ID, generated display filter, packet count, truncation flag, and matching packet summaries.

Retrieve IEEE 802.11 packets involving a Wi-Fi client MAC address.

The query uses wlan.addr so it matches the client in any applicable transmitter, receiver, source, or destination address role. Hyphenated and colon-separated MAC input is accepted and normalized.

Args: capture_id: ID of a currently loaded capture. client_mac: Client MAC address such as aa:bb:cc:dd:ee:ff. limit: Maximum results to return, from 1 through 1000.

Returns: Normalized client MAC, generated display filter, packet count, truncation flag, and matching packet summaries.

Retrieve IEEE 802.11 packets associated with an access-point BSSID.

The query uses the decoded wlan.bssid field and therefore requires an IEEE 802.11 capture containing that field. Hyphenated and colon-separated MAC input is accepted and normalized before filtering.

Args: capture_id: ID of a currently loaded capture. bssid: AP/BSSID MAC address such as aa:bb:cc:dd:ee:ff. limit: Maximum results to return, from 1 through 1000.

Returns: Normalized BSSID, generated display filter, packet count, truncation flag, and matching packet summaries.

Retrieve packets belonging to a DNS, DHCP, TCP, EAPOL, or ARP exchange.

DNS and DHCP keys may be decimal or 0x-prefixed transaction IDs; TCP uses a stream number. Because EAPOL and ARP lack a universal transaction number, their keys are a client MAC and IPv4 protocol address respectively.

Args: capture_id: ID of a currently loaded capture. transaction_type: One of dns, dhcp, tcp, eapol, or arp. transaction_key: Protocol-specific ID, stream, MAC, or IPv4 address. limit: Maximum results to return, from 1 through 1000.

Returns: Normalized transaction type and key, generated display filter, packet count, truncation flag, and matching packet summaries.