take_snapshot

Instructions

Implementation Reference

• src/tools/snapshot.ts:62-128 (handler)

  Main handler for take_snapshot tool: validates args, calls FirefoxDevTools.takeSnapshot(), formats and truncates the DOM snapshot tree, constructs output with metadata.

  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 defining name, description, and input parameters for take_snapshot.

  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 all tool handlers in the toolHandlers Map, including take_snapshot mapped to 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 all tools in allTools array for ListToolsRequest, including takeSnapshotTool.

  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-322 (helper)

  FirefoxDevTools method called by the handler to capture the raw snapshot, delegates to this.snapshot.takeSnapshot().

  async takeSnapshot(): Promise<Snapshot> {
    if (!this.snapshot) {
      throw new Error('Not connected');
    }
    return await this.snapshot.takeSnapshot();