SharkMCP

Instructions

Implementation Reference

• src/tools/start-capture-session.ts:22-168 (handler)

  The main handler function that starts a background tshark packet capture process, manages sessions, handles configurations, and sets up timeouts and limits.
  export async function startCaptureSessionHandler(args: any, activeSessions: Map<string, CaptureSession>) { try { const tsharkPath = await findTshark(); let { interface: networkInterface, captureFilter, timeout, maxPackets, sessionName, configName } = args; // If configName is provided, load and use that configuration if (configName) { const savedConfig = await loadFilterConfig(configName); if (!savedConfig) { return { content: [{ type: 'text' as const, text: `Error: Configuration '${configName}' not found. Use manage_config with action 'list' to see available configurations.`, }], isError: true }; } // Override parameters with saved config (saved config takes precedence) if (savedConfig.interface) networkInterface = savedConfig.interface; if (savedConfig.captureFilter) captureFilter = savedConfig.captureFilter; if (savedConfig.timeout) timeout = savedConfig.timeout; if (savedConfig.maxPackets) maxPackets = savedConfig.maxPackets; console.error(`Using saved configuration '${configName}': ${JSON.stringify(savedConfig)}`); } // Generate unique session ID const sessionId = sessionName || `capture_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`; // Check if session already exists if (activeSessions.has(sessionId)) { return { content: [{ type: 'text' as const, text: `Error: Session '${sessionId}' already exists. Use a different session name or stop the existing session.`, }], isError: true }; } const tempFile = `/tmp/shark_${sessionId}.pcap`; console.error(`Starting capture session: ${sessionId} on ${networkInterface}`); // Build comprehensive tshark command for background capture // Use timeout as primary stopping mechanism, with maxPackets as safety limit const args_array = [ '-i', networkInterface, '-a', `duration:${timeout}`, // Auto-stop after timeout seconds '-c', maxPackets.toString(), // Safety limit to prevent excessive capture '-w', tempFile ]; // Add capture filter if provided (as a single argument to -f) if (captureFilter) { args_array.push('-f', captureFilter); } // Set up basic environment const captureEnv: Record<string, string> = { ...process.env, PATH: `${process.env.PATH}:/usr/bin:/usr/local/bin:/opt/homebrew/bin` }; // Log the command with proper quoting for copy-paste debugging const quotedArgs = args_array.map(arg => { // Quote arguments that contain spaces or special characters if (arg.includes(' ') || arg.includes('|') || arg.includes('&') || arg.includes('(') || arg.includes(')')) { return `"${arg}"`; } return arg; }); console.error(`Running background command: ${tsharkPath} ${quotedArgs.join(' ')}`); // Start background capture process with stderr logging const captureProcess = spawn(tsharkPath, args_array, { env: captureEnv, stdio: ['ignore', 'ignore', 'pipe'], // Capture stderr for error logging detached: true // Fully detach the process }); // Log any errors from tshark if (captureProcess.stderr) { captureProcess.stderr.on('data', (data) => { console.error(`tshark stderr [${sessionId}]: ${data.toString().trim()}`); }); } // Unref the process so the parent can exit independently captureProcess.unref(); // Store session info const session: CaptureSession = { id: sessionId, process: captureProcess, interface: networkInterface, captureFilter, timeout, maxPackets, startTime: new Date(), tempFile, status: 'running' }; activeSessions.set(sessionId, session); // Handle process completion - KEEP SESSION ALIVE for result retrieval captureProcess.on('exit', (code) => { console.error(`Capture session ${sessionId} exited with code: ${code}`); if (activeSessions.has(sessionId)) { const session = activeSessions.get(sessionId)!; session.process = null; session.status = code === 0 ? 'completed' : 'error'; session.endTime = new Date(); if (code !== null) { session.exitCode = code; } console.error(`Session ${sessionId} marked as ${session.status}, file: ${session.tempFile}`); } }); captureProcess.on('error', (error) => { console.error(`Capture session ${sessionId} error: ${error.message}`); if (activeSessions.has(sessionId)) { const session = activeSessions.get(sessionId)!; session.process = null; session.status = 'error'; session.endTime = new Date(); } }); const configInfo = configName ? `\nUsing saved config: ${configName}` : ''; return { content: [{ type: 'text' as const, text: `Capture session started successfully!${configInfo}\nSession ID: ${sessionId}\nInterface: ${networkInterface}\nCapture Filter: ${captureFilter || 'none'}\nTimeout: ${timeout}s (auto-stop)\nMax Packets: ${maxPackets} (safety limit)\n\nCapture will auto-stop after ${timeout} seconds or use 'stop_capture_session' with session ID '${sessionId}' to stop manually and retrieve results.`, }], }; } catch (error: any) { console.error(`Error starting capture session: ${error.message}`); return { content: [{ type: 'text' as const, text: `Error: ${error.message}` }], isError: true }; } }
• src/tools/start-capture-session.ts:9-16 (schema)

  Zod schema defining the input parameters for the start_capture_session tool, including interface, filters, timeouts, and config options.
  export const startCaptureSessionSchema = { interface: z.string().optional().default('lo0').describe('Network interface to capture from (e.g., eth0, en0, lo0)'), captureFilter: z.string().optional().describe('Optional BPF capture filter to apply while capturing (e.g., "port 443")'), timeout: z.number().optional().default(60).describe('Timeout in seconds before auto-stopping capture (default: 60s to prevent orphaned sessions)'), maxPackets: z.number().optional().default(100000).describe('Maximum number of packets to capture (safety limit, default: 100,000)'), sessionName: z.string().optional().describe('Optional session name for easier identification'), configName: z.string().optional().describe('Name of saved configuration to use (will override other parameters)') };
• src/index.ts:24-29 (registration)

  Registration of the start_capture_session tool with the MCP server, including name, description, schema, and handler reference.
  server.tool( 'start_capture_session', 'Start a background packet capture session. LLMs control all capture parameters including filters, interfaces, and packet limits. Can use saved configurations.', startCaptureSessionSchema, async (args) => startCaptureSessionHandler(args, activeSessions) );