take_snapshot
Capture a textual page snapshot with stable element UIDs for reliable browser automation. Use the generated UIDs to interact with page elements consistently across navigation and DOM changes.
Instructions
Capture a textual page snapshot with stable UIDs for elements. Always take a fresh snapshot after navigation or major DOM changes. TIP: Use the UIDs with click_by_uid / fill_by_uid / hover_by_uid. The output may be truncated for readability.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| includeAttributes | No | Include detailed ARIA and computed attributes in output (default: false) | |
| includeText | No | Include text content in output (default: true) | |
| maxDepth | No | Maximum depth of tree to include (default: unlimited) | |
| maxLines | No | Maximum number of lines to return in output (default: 100) |
Implementation Reference
- src/tools/snapshot.ts:62-128 (handler)The main MCP tool handler for 'take_snapshot'. Parses input arguments, retrieves Firefox instance, calls underlying takeSnapshot method, formats the DOM tree snapshot, applies truncation limits, and constructs the response text.export async function handleTakeSnapshot(args: unknown): Promise<McpToolResponse> { try { const { maxLines: requestedMaxLines = DEFAULT_SNAPSHOT_LINES, includeAttributes = false, includeText = true, maxDepth, } = (args as { maxLines?: number; includeAttributes?: boolean; includeText?: boolean; maxDepth?: number; }) || {}; // Apply hard cap on maxLines to prevent token overflow const maxLines = Math.min(Math.max(1, requestedMaxLines), TOKEN_LIMITS.MAX_SNAPSHOT_LINES_CAP); const wasCapped = requestedMaxLines > TOKEN_LIMITS.MAX_SNAPSHOT_LINES_CAP; const { getFirefox } = await import('../index.js'); const firefox = await getFirefox(); const snapshot = await firefox.takeSnapshot(); // Import formatter to apply custom options const { formatSnapshotTree } = await import('../firefox/snapshot/formatter.js'); const options: any = { includeAttributes, includeText, }; if (maxDepth !== undefined) { options.maxDepth = maxDepth; } const formattedText = formatSnapshotTree(snapshot.json.root, 0, options); // Get snapshot text (truncated if needed) const lines = formattedText.split('\n'); const truncated = lines.length > maxLines; const displayLines = truncated ? lines.slice(0, maxLines) : lines; // Build compact output let output = `📸 Snapshot (id=${snapshot.json.snapshotId})`; if (wasCapped) { output += ` [maxLines capped: ${TOKEN_LIMITS.MAX_SNAPSHOT_LINES_CAP}]`; } if (snapshot.json.truncated) { output += ' [DOM truncated]'; } output += '\n\n'; // Add snapshot tree output += displayLines.join('\n'); if (truncated) { output += `\n\n[+${lines.length - maxLines} lines, use maxLines to see more]`; } return successResponse(output); } catch (error) { return errorResponse( new Error( `Failed to take snapshot: ${(error as Error).message}\n\n` + 'The page may not be fully loaded or accessible.' ) ); } }
- src/tools/snapshot.ts:11-35 (schema)Tool schema definition including name, description, and input schema for parameters like maxLines, includeAttributes, includeText, maxDepth.export const takeSnapshotTool = { name: 'take_snapshot', description: 'Capture DOM snapshot with stable UIDs. Retake after navigation.', inputSchema: { type: 'object', properties: { maxLines: { type: 'number', description: 'Max lines (default: 100)', }, includeAttributes: { type: 'boolean', description: 'Include ARIA attributes (default: false)', }, includeText: { type: 'boolean', description: 'Include text (default: true)', }, maxDepth: { type: 'number', description: 'Max tree depth', }, }, }, };
- src/index.ts:103-147 (registration)Registration of tool handlers in the Map, including entry for 'take_snapshot' mapped to tools.handleTakeSnapshot.const toolHandlers = new Map< string, (input: unknown) => Promise<{ content: Array<{ type: string; text: string }>; isError?: boolean }> >([ // Pages ['list_pages', tools.handleListPages], ['new_page', tools.handleNewPage], ['navigate_page', tools.handleNavigatePage], ['select_page', tools.handleSelectPage], ['close_page', tools.handleClosePage], // Script evaluation - DISABLED (see docs/future-features.md) // ['evaluate_script', tools.handleEvaluateScript], // Console ['list_console_messages', tools.handleListConsoleMessages], ['clear_console_messages', tools.handleClearConsoleMessages], // Network ['list_network_requests', tools.handleListNetworkRequests], ['get_network_request', tools.handleGetNetworkRequest], // Snapshot ['take_snapshot', tools.handleTakeSnapshot], ['resolve_uid_to_selector', tools.handleResolveUidToSelector], ['clear_snapshot', tools.handleClearSnapshot], // Input ['click_by_uid', tools.handleClickByUid], ['hover_by_uid', tools.handleHoverByUid], ['fill_by_uid', tools.handleFillByUid], ['drag_by_uid_to_uid', tools.handleDragByUidToUid], ['fill_form_by_uid', tools.handleFillFormByUid], ['upload_file_by_uid', tools.handleUploadFileByUid], // Screenshot ['screenshot_page', tools.handleScreenshotPage], ['screenshot_by_uid', tools.handleScreenshotByUid], // Utilities ['accept_dialog', tools.handleAcceptDialog], ['dismiss_dialog', tools.handleDismissDialog], ['navigate_history', tools.handleNavigateHistory], ['set_viewport_size', tools.handleSetViewportSize], ]);
- src/index.ts:150-191 (registration)Registration of tool definitions in the allTools array, including tools.takeSnapshotTool for listTools response.const allTools = [ // Pages tools.listPagesTool, tools.newPageTool, tools.navigatePageTool, tools.selectPageTool, tools.closePageTool, // Script evaluation - DISABLED (see docs/future-features.md) // tools.evaluateScriptTool, // Console tools.listConsoleMessagesTool, tools.clearConsoleMessagesTool, // Network tools.listNetworkRequestsTool, tools.getNetworkRequestTool, // Snapshot tools.takeSnapshotTool, tools.resolveUidToSelectorTool, tools.clearSnapshotTool, // Input tools.clickByUidTool, tools.hoverByUidTool, tools.fillByUidTool, tools.dragByUidToUidTool, tools.fillFormByUidTool, tools.uploadFileByUidTool, // Screenshot tools.screenshotPageTool, tools.screenshotByUidTool, // Utilities tools.acceptDialogTool, tools.dismissDialogTool, tools.navigateHistoryTool, tools.setViewportSizeTool, ];
- src/firefox/index.ts:318-323 (helper)FirefoxDevTools.takeSnapshot() method which delegates to SnapshotManager.takeSnapshot(). Called by the tool handler.async takeSnapshot(): Promise<Snapshot> { if (!this.snapshot) { throw new Error('Not connected'); } return await this.snapshot.takeSnapshot(); }