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" )