mcpacket

Instructions

Implementation Reference

• src/mcpcap/modules/capinfos.py:20-39 (handler)

  The main handler function for the 'analyze_capinfos' MCP tool. It accepts a PCAP file path or URL and delegates to analyze_packets for metadata extraction.

  def analyze_capinfos(self, pcap_file: str) -> dict[str, Any]:
      """
      Return metadata from a PCAP file, similar to Wireshark's capinfos utility.
  
      IMPORTANT: This tool expects a FILE PATH or URL, not file content.
      - For local files: "/path/to/capture.pcap"
      - For remote files: "https://example.com/capture.pcap"
      - File uploads are NOT supported - save the file locally first
  
      Args:
          pcap_file: Path to local PCAP file or HTTP URL to remote PCAP file
                    (NOT file content - must be a path or URL)
  
      Returns:
          A structured dictionary containing PCAP metadata including:
          - File information (size, name, encapsulation type)
          - Packet statistics (count, data size, average sizes)
          - Temporal data (duration, timestamps, rates)
      """
      return self.analyze_packets(pcap_file)

• src/mcpcap/core/server.py:48-63 (registration)

  Registration of the analyze_capinfos tool from the CapInfosModule in the MCP server during tool registration loop.

  # Register tools for each loaded module
  for module_name, module in self.modules.items():
      if module_name == "dns":
          self.mcp.tool(module.analyze_dns_packets)
      elif module_name == "dhcp":
          self.mcp.tool(module.analyze_dhcp_packets)
      elif module_name == "icmp":
          self.mcp.tool(module.analyze_icmp_packets)
      elif module_name == "capinfos":
          self.mcp.tool(module.analyze_capinfos)
      elif module_name == "tcp":
          self.mcp.tool(module.analyze_tcp_connections)
          self.mcp.tool(module.analyze_tcp_anomalies)
          self.mcp.tool(module.analyze_tcp_retransmissions)
          self.mcp.tool(module.analyze_traffic_flow)

• src/mcpcap/modules/capinfos.py:41-61 (helper)

  Core analysis implementation (_analyze_protocol_file) that reads the PCAP, generates statistics, detects linktype, and returns metadata.

  def _analyze_protocol_file(self, pcap_file: str) -> dict[str, Any]:
      """Perform the actual information gathering on a local PCAP file."""
      try:
          packets = rdpcap(pcap_file)
  
          # Generate statistics
          stats = self._generate_statistics(packets)
  
          results = {
              "file_size_bytes": os.path.getsize(pcap_file),
              "filename": os.path.basename(pcap_file),
              "file_encapsulation": self._detect_linktype(pcap_file),
          }
  
          return results | stats
  
      except Exception as e:
          return {
              "error": f"Error reading PCAP file '{pcap_file}': {str(e)}",
              "file": pcap_file,
          }

• src/mcpcap/modules/base.py:43-105 (helper)

  Base class helper analyze_packets that handles local/remote PCAP files, validation, download if needed, and calls the module-specific _analyze_protocol_file.

  def analyze_packets(self, pcap_file: str) -> dict[str, Any]:
      """Analyze packets from a PCAP file (local or remote).
  
      Args:
          pcap_file: Path to local PCAP file or HTTP URL to remote PCAP file
  
      Returns:
          A structured dictionary containing packet analysis results
      """
      # Check if this is a remote URL or local file
      if pcap_file.startswith(("http://", "https://")):
          return self._handle_remote_analysis(pcap_file)
      else:
          return self._handle_local_analysis(pcap_file)
  
  def _handle_remote_analysis(self, pcap_url: str) -> dict[str, Any]:
      """Handle remote PCAP file analysis."""
      try:
          # Download remote file to temporary location
          with tempfile.NamedTemporaryFile(suffix=".pcap", delete=False) as tmp_file:
              temp_path = tmp_file.name
  
          local_path = self._download_pcap_file(pcap_url, temp_path)
          result = self._analyze_protocol_file(local_path)
  
          # Clean up temporary file
          try:
              os.unlink(local_path)
          except OSError:
              pass  # Ignore cleanup errors
  
          return result
  
      except Exception as e:
          return {
              "error": f"Failed to download PCAP file '{pcap_url}': {str(e)}",
              "pcap_url": pcap_url,
          }
  
  def _handle_local_analysis(self, pcap_file: str) -> dict[str, Any]:
      """Handle local PCAP file analysis."""
      # Validate file exists
      if not os.path.exists(pcap_file):
          return {
              "error": f"PCAP file not found: {pcap_file}",
              "pcap_file": pcap_file,
          }
  
      # Validate file extension
      if not pcap_file.lower().endswith((".pcap", ".pcapng", ".cap")):
          return {
              "error": f"File '{pcap_file}' is not a supported PCAP file (.pcap/.pcapng/.cap)",
              "pcap_file": pcap_file,
          }
  
      try:
          return self._analyze_protocol_file(pcap_file)
      except Exception as e:
          return {
              "error": f"Failed to analyze PCAP file '{pcap_file}': {str(e)}",
              "pcap_file": pcap_file,
          }

• src/mcpcap/modules/capinfos.py:63-92 (helper)

  Helper function to detect and map the PCAP linktype to a human-readable encapsulation type.

  def _detect_linktype(self, path: str) -> str:
      """Detect the linktype and try to map it to a human-readable encapsulation type.
  
      Args:
          path: Path to the packet capture
  
      Returns:
          Detected link-layer header (linktype)
  
      """
      # mapping based on pcap-linktype(7) and https://github.com/wireshark/wireshark/blob/master/wiretap/wtap.c#L656
      LINKTYPE_MAP = {
          1: "Ethernet",
          101: "Raw IP",
          105: "IEEE 802.11 Wireless LAN",
          113: "Linux cooked-mode capture v1",
          228: "Raw IPv4",
          229: "Raw IPv6",
          276: "Linux cooked-mode capture v2",
      }
      try:
          with PcapReader(path) as reader:
              linktype = getattr(reader, "linktype", None)
      except Exception:
          linktype = None
  
      return LINKTYPE_MAP.get(
          linktype, f"Unknown ({linktype})" if linktype else "Unknown"
      )