capture_packets

Instructions

Implementation Reference

• index.js:48-97 (registration)

  Registers the capture_packets tool with the MCP server, including name, description, input schema, and handler function.

  server.tool(
    'capture_packets',
    'Capture live traffic and provide raw packet data as JSON for LLM analysis',
    {
      interface: z.string().optional().default('en0').describe('Network interface to capture from (e.g., eth0, en0)'),
      duration: z.number().optional().default(5).describe('Capture duration in seconds'),
    },
    async (args) => {
      try {
        const tsharkPath = await findTshark();
        const { interface, duration } = args;
        const tempPcap = 'temp_capture.pcap';
        console.error(`Capturing packets on ${interface} for ${duration}s`);
  
        await execAsync(
          `${tsharkPath} -i ${interface} -w ${tempPcap} -a duration:${duration}`,
          { env: { ...process.env, PATH: `${process.env.PATH}:/usr/bin:/usr/local/bin:/opt/homebrew/bin` } }
        );
  
        const { stdout, stderr } = await execAsync(
          `${tsharkPath} -r "${tempPcap}" -T json -e frame.number -e ip.src -e ip.dst -e tcp.srcport -e tcp.dstport -e tcp.flags -e frame.time -e http.request.method -e http.response.code`,
          { env: { ...process.env, PATH: `${process.env.PATH}:/usr/bin:/usr/local/bin:/opt/homebrew/bin` } }
        );
        if (stderr) console.error(`tshark stderr: ${stderr}`);
        let packets = JSON.parse(stdout);
  
        const maxChars = 720000;
        let jsonString = JSON.stringify(packets);
        if (jsonString.length > maxChars) {
          const trimFactor = maxChars / jsonString.length;
          const trimCount = Math.floor(packets.length * trimFactor);
          packets = packets.slice(0, trimCount);
          jsonString = JSON.stringify(packets);
          console.error(`Trimmed packets from ${packets.length} to ${trimCount} to fit ${maxChars} chars`);
        }
  
        await fs.unlink(tempPcap).catch(err => console.error(`Failed to delete ${tempPcap}: ${err.message}`));
  
        return {
          content: [{
            type: 'text',
            text: `Captured packet data (JSON for LLM analysis):\n${jsonString}`,
          }],
        };
      } catch (error) {
        console.error(`Error in capture_packets: ${error.message}`);
        return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true };
      }
    }
  );

• index.js:55-96 (handler)

  The handler function for capture_packets: uses tshark to capture packets on the specified interface for the given duration, parses to JSON, trims if over size limit, deletes temp file, returns packet data as text.

  async (args) => {
    try {
      const tsharkPath = await findTshark();
      const { interface, duration } = args;
      const tempPcap = 'temp_capture.pcap';
      console.error(`Capturing packets on ${interface} for ${duration}s`);
  
      await execAsync(
        `${tsharkPath} -i ${interface} -w ${tempPcap} -a duration:${duration}`,
        { env: { ...process.env, PATH: `${process.env.PATH}:/usr/bin:/usr/local/bin:/opt/homebrew/bin` } }
      );
  
      const { stdout, stderr } = await execAsync(
        `${tsharkPath} -r "${tempPcap}" -T json -e frame.number -e ip.src -e ip.dst -e tcp.srcport -e tcp.dstport -e tcp.flags -e frame.time -e http.request.method -e http.response.code`,
        { env: { ...process.env, PATH: `${process.env.PATH}:/usr/bin:/usr/local/bin:/opt/homebrew/bin` } }
      );
      if (stderr) console.error(`tshark stderr: ${stderr}`);
      let packets = JSON.parse(stdout);
  
      const maxChars = 720000;
      let jsonString = JSON.stringify(packets);
      if (jsonString.length > maxChars) {
        const trimFactor = maxChars / jsonString.length;
        const trimCount = Math.floor(packets.length * trimFactor);
        packets = packets.slice(0, trimCount);
        jsonString = JSON.stringify(packets);
        console.error(`Trimmed packets from ${packets.length} to ${trimCount} to fit ${maxChars} chars`);
      }
  
      await fs.unlink(tempPcap).catch(err => console.error(`Failed to delete ${tempPcap}: ${err.message}`));
  
      return {
        content: [{
          type: 'text',
          text: `Captured packet data (JSON for LLM analysis):\n${jsonString}`,
        }],
      };
    } catch (error) {
      console.error(`Error in capture_packets: ${error.message}`);
      return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true };
    }
  }

• index.js:51-54 (schema)

  Input schema using Zod: interface (optional string, default 'en0'), duration (optional number, default 5).

  {
    interface: z.string().optional().default('en0').describe('Network interface to capture from (e.g., eth0, en0)'),
    duration: z.number().optional().default(5).describe('Capture duration in seconds'),
  },

• index.js:17-39 (helper)

  Helper function to dynamically locate the tshark executable, used by capture_packets handler.

  async function findTshark() {
    try {
      const tsharkPath = await which('tshark');
      console.error(`Found tshark at: ${tsharkPath}`);
      return tsharkPath;
    } catch (err) {
      console.error('which failed to find tshark:', err.message);
      const fallbacks = process.platform === 'win32'
        ? ['C:\\Program Files\\Wireshark\\tshark.exe', 'C:\\Program Files (x86)\\Wireshark\\tshark.exe']
        : ['/usr/bin/tshark', '/usr/local/bin/tshark', '/opt/homebrew/bin/tshark', '/Applications/Wireshark.app/Contents/MacOS/tshark'];
      
      for (const path of fallbacks) {
        try {
          await execAsync(`${path} -v`);
          console.error(`Found tshark at fallback: ${path}`);
          return path;
        } catch (e) {
          console.error(`Fallback ${path} failed: ${e.message}`);
        }
      }
      throw new Error('tshark not found. Please install Wireshark (https://www.wireshark.org/download.html) and ensure tshark is in your PATH.');
    }
  }