Skip to content

Chrome DevTools for coding agents

13.5 KB
Raw Blame
/**
 * @license
 * Copyright 2025 Google LLC
 * SPDX-License-Identifier: Apache-2.0
 */

import fs from 'node:fs';

import type {Options as YargsOptions} from 'yargs';

import {
  mcpOptions,
  type ParsedArguments,
} from '../out/Default/gen/src/config/mcp-options.js';
import {
  isCategoryOffByDefault,
  categoryToFlagName,
} from '../out/Default/gen/src/config/category-options.js';
import {zod} from '../out/Default/gen/src/third_party/index.js';
import {ToolCategory, labels} from '../out/Default/gen/src/tools/categories.js';
import {isSlimTool} from '../out/Default/gen/src/tools/ToolDefinition.js';
import type {AnyToolDefinition} from '../src/tools/ToolDefinition.js';
import {
  createTools,
  requiresHiddenFlag,
} from '../out/Default/gen/src/tools/tools.js';

const OUTPUT_PATH = './docs/tool-reference.md';
const SLIM_OUTPUT_PATH = './docs/slim-tool-reference.md';

interface TypeInfo {
  type?: string;
  enum?: string[];
  items?: TypeInfo;
  description?: string;
  default?: unknown;
}

interface ToolWithAnnotations {
  name: string;
  description: string;
  inputSchema: {
    type?: string;
    properties?: Record<string, TypeInfo>;
    required?: string[];
  };
  annotations?: {
    title?: string;
    category?: ToolCategory;
    conditions?: Array<keyof ParsedArguments>;
  };
}

function escapeHtmlTags(text: string): string {
  return text
    .replace(/&(?![a-zA-Z]+;)/g, '&amp;')
    .replace(/<([a-zA-Z][^>]*)>/g, '&lt;$1&gt;');
}

function addCrossLinks(text: string, tools: ToolWithAnnotations[]): string {
  let result = text;

  // Create a set of all tool names for efficient lookup
  const toolNames = new Set(tools.map(tool => tool.name));

  // Sort tool names by length (descending) to match longer names first
  const sortedToolNames = Array.from(toolNames).sort(
    (a, b) => b.length - a.length,
  );

  for (const toolName of sortedToolNames) {
    // Create regex to match tool name (case insensitive, word boundaries)
    const regex = new RegExp(`\\b${toolName}\\b`, 'gi');

    result = result.replace(regex, match => {
      // Only create link if the match isn't already inside a link
      if (result.indexOf(`[${match}]`) !== -1) {
        return match; // Already linked
      }
      const anchorLink = toolName.toLowerCase();
      return `[\`${match}\`](#${anchorLink})`;
    });
  }

  return result;
}

function hasOffByDefaultConditions(tool: ToolWithAnnotations): boolean {
  for (const condition of tool.annotations?.conditions || []) {
    if (condition === 'slim') {
      continue;
    }
    const option = mcpOptions[condition];
    if (!option || !('default' in option) || option.default !== true) {
      return true;
    }
  }
  return false;
}

function sortTools(a: ToolWithAnnotations, b: ToolWithAnnotations): number {
  const aHasConditions = hasOffByDefaultConditions(a);
  const bHasConditions = hasOffByDefaultConditions(b);

  if (aHasConditions && !bHasConditions) {
    return 1;
  }
  if (!aHasConditions && bHasConditions) {
    return -1;
  }

  return a.name.localeCompare(b.name);
}

function generateConfigOptionsMarkdown(): string {
  let markdown = '';

  for (const [optionName, optionConfig] of Object.entries(
    mcpOptions as Record<string, Partial<YargsOptions>>,
  )) {
    // Skip hidden options
    if (optionConfig.hidden) {
      continue;
    }

    const aliasText = optionConfig.alias
      ? `, \`${optionConfig.alias.length === 1 ? '-' : '--'}${optionConfig.alias}\``
      : '';
    const description = optionConfig.description || optionConfig.describe || '';

    // Convert camelCase to dash-case
    const dashCaseName = optionName
      .replace(/([a-z])([A-Z])/g, '$1-$2')
      .toLowerCase();
    const nameDisplay =
      dashCaseName !== optionName
        ? `\`--${optionName}\`/ \`--${dashCaseName}\``
        : `\`--${optionName}\``;

    // Start with option name and description
    markdown += `- **${nameDisplay}${aliasText}**\n`;
    markdown += `  ${description}\n`;

    // Add type information
    markdown += `  - **Type:** ${optionConfig.type}\n`;

    // Add choices if available
    if (optionConfig.choices) {
      markdown += `  - **Choices:** ${optionConfig.choices.map(c => `\`${c}\``).join(', ')}\n`;
    }

    const defaultValue =
      optionConfig.defaultDescription ?? optionConfig.default;
    if (defaultValue !== undefined) {
      markdown += `  - **Default:** \`${defaultValue}\`\n`;
    } else if (optionConfig.type === 'boolean') {
      markdown += `  - **Default:** \`false\`\n`;
    }

    markdown += '\n';
  }

  return markdown.trim();
}

function updateConfigurationWithOptionsMarkdown(optionsMarkdown: string): void {
  const configPath = './docs/configuration.md';
  const readmeContent = fs.readFileSync(configPath, 'utf8');

  const beginMarker = '<!-- BEGIN AUTO GENERATED OPTIONS -->';
  const endMarker = '<!-- END AUTO GENERATED OPTIONS -->';

  const beginIndex = readmeContent.indexOf(beginMarker);
  const endIndex = readmeContent.indexOf(endMarker);

  if (beginIndex === -1 || endIndex === -1) {
    console.warn(
      'Could not find auto-generated options markers in ./docs/configuration.md',
    );
    return;
  }

  const before = readmeContent.substring(0, beginIndex + beginMarker.length);
  const after = readmeContent.substring(endIndex);

  const updatedContent = before + '\n\n' + optionsMarkdown + '\n\n' + after;

  fs.writeFileSync(configPath, updatedContent);
  console.log('Updated configuration.md with options markdown');
}

async function generateReference(
  title: string,
  outputPath: string,
  toolsWithAnnotations: ToolWithAnnotations[],
  categories: Record<string, ToolWithAnnotations[]>,
  sortedCategories: string[],
) {
  console.log(`Found ${toolsWithAnnotations.length} tools`);

  // Generate markdown documentation
  let markdown = `<!-- AUTO GENERATED DO NOT EDIT - run 'npm run gen' to update-->

# ${title}

`;
  // Generate table of contents
  for (const category of sortedCategories) {
    const categoryTools = categories[category];
    const categoryName = labels[category];
    const anchorName = categoryName.toLowerCase().replace(/\s+/g, '-');
    markdown += `- **[${categoryName}](#${anchorName})** (${categoryTools.length} tools)\n`;

    // Sort tools within category for TOC
    categoryTools.sort(sortTools);
    for (const tool of categoryTools) {
      // Generate proper markdown anchor link: backticks are removed, keep underscores, lowercase
      const anchorLink = tool.name.toLowerCase();
      markdown += `  - [\`${tool.name}\`](#${anchorLink})\n`;
    }
  }
  markdown += '\n';

  for (const category of sortedCategories) {
    const categoryTools = categories[category];
    const categoryName = labels[category];

    markdown += `## ${categoryName}\n\n`;

    if (isCategoryOffByDefault(category)) {
      const flagName = `--${categoryToFlagName(category)}`;

      markdown += `> NOTE: The ${categoryName} category is not active by default. Use the '${flagName}' flag.\n\n`;
    }

    // Sort tools within category
    categoryTools.sort(sortTools);

    for (const tool of categoryTools) {
      markdown += `### \`${tool.name}\`\n\n`;

      if (tool.description) {
        // Escape HTML tags but preserve JS function syntax
        let escapedDescription = escapeHtmlTags(tool.description);

        const requiredFlags: string[] = [];

        const isOffByDefault = isCategoryOffByDefault(category);
        if (isOffByDefault) {
          const categoryFlag = categoryToFlagName(category);
          requiredFlags.push(`--${categoryFlag}=true`);
        }

        const conditions = tool.annotations?.conditions || [];
        for (const condition of conditions) {
          if (condition === 'slim') {
            continue;
          }
          const option = mcpOptions[condition];
          if (!option || !('default' in option) || option.default !== true) {
            requiredFlags.push(`--${condition}=true`);
          }
        }

        if (requiredFlags.length > 0) {
          escapedDescription += ` (requires flag: ${requiredFlags.join(', ')})`;
        }

        // Add cross-links to mentioned tools
        escapedDescription = addCrossLinks(
          escapedDescription,
          toolsWithAnnotations,
        );
        markdown += `**Description:** ${escapedDescription}\n\n`;
      }

      // Handle input schema
      if (
        tool.inputSchema &&
        tool.inputSchema.properties &&
        Object.keys(tool.inputSchema.properties).length > 0
      ) {
        const properties = tool.inputSchema.properties;
        const required = tool.inputSchema.required || [];

        markdown += '**Parameters:**\n\n';

        const propertyNames = Object.keys(properties).sort((a, b) => {
          const aRequired = required.includes(a);
          const bRequired = required.includes(b);
          if (aRequired && !bRequired) {
            return -1;
          }
          if (!aRequired && bRequired) {
            return 1;
          }
          return a.localeCompare(b);
        });
        for (const propName of propertyNames) {
          const prop = properties[propName] as TypeInfo;
          const isRequired = required.includes(propName);
          const requiredText = isRequired ? ' **(required)**' : ' _(optional)_';

          let typeInfo = prop.type || 'unknown';
          if (prop.enum) {
            typeInfo = `enum: ${prop.enum.map((v: string) => `"${v}"`).join(', ')}`;
          }

          markdown += `- **${propName}** (${typeInfo})${requiredText}`;
          if (prop.description) {
            let escapedParamDesc = escapeHtmlTags(prop.description);

            // Add cross-links to mentioned tools
            escapedParamDesc = addCrossLinks(
              escapedParamDesc,
              toolsWithAnnotations,
            );
            markdown += `: ${escapedParamDesc}`;
          }
          markdown += '\n';
        }
        markdown += '\n';
      } else {
        markdown += '**Parameters:** None\n\n';
      }

      markdown += '---\n\n';
    }
  }

  // Write the documentation to file
  fs.writeFileSync(outputPath, markdown.trim() + '\n');

  console.log(
    `Generated documentation for ${toolsWithAnnotations.length} tools in ${outputPath}`,
  );
}

function getToolsAndCategories(tools: AnyToolDefinition[]) {
  // Convert ToolDefinitions to ToolWithAnnotations
  const toolsWithAnnotations: ToolWithAnnotations[] = tools
    .filter(tool => {
      // Skipping in_page tools as they are not launched yet
      if (tool.annotations.category === ToolCategory.IN_PAGE) {
        return false;
      }

      // Skipping tools behind internal flags.
      if (requiresHiddenFlag(tool)) {
        return false;
      }

      // Skipping internal interop tools not meant for public documentation
      const skipTools = ['get_tab_id'];
      if (skipTools.includes(tool.name)) {
        return false;
      }

      return true;
    })
    .map(tool => {
      const inputSchema = zod.toJSONSchema(zod.object(tool.schema), {
        io: 'input',
      }) as ToolWithAnnotations['inputSchema'];

      return {
        name: tool.name,
        description: tool.description,
        inputSchema,
        annotations: tool.annotations,
      };
    });
  // Group tools by category (based on annotations)
  const categories: Record<string, ToolWithAnnotations[]> = {};
  toolsWithAnnotations.forEach((tool: ToolWithAnnotations) => {
    const category = tool.annotations?.category || 'Uncategorized';
    if (!categories[category]) {
      categories[category] = [];
    }
    categories[category].push(tool);
  });

  // Sort categories using the enum order
  const categoryOrder = Object.values(ToolCategory);
  const sortedCategories = Object.keys(categories).sort((a, b) => {
    const aOff = isCategoryOffByDefault(a);
    const bOff = isCategoryOffByDefault(b);

    if (aOff !== bOff) {
      return aOff ? 1 : -1;
    }

    const aIndex = categoryOrder.indexOf(a as ToolCategory);
    const bIndex = categoryOrder.indexOf(b as ToolCategory);

    // Put known categories first, unknown categories last
    if (aIndex === -1 && bIndex === -1) {
      return a.localeCompare(b);
    }
    if (aIndex === -1) {
      return 1;
    }
    if (bIndex === -1) {
      return -1;
    }
    return aIndex - bIndex;
  });
  return {toolsWithAnnotations, categories, sortedCategories};
}

async function generateToolDocumentation(): Promise<void> {
  try {
    console.log('Generating tool documentation from definitions...');
    // Returns both the regular and the slim tools.
    const tools = createTools({
      pageIdRouting: true,
      categoryExtensions: true,
      maxNavigationSaved: mcpOptions.maxNavigationSaved.default,
    } as ParsedArguments);

    {
      const {toolsWithAnnotations, categories, sortedCategories} =
        getToolsAndCategories(tools.filter(tool => !isSlimTool(tool)));
      await generateReference(
        'Chrome DevTools MCP Tool Reference',
        OUTPUT_PATH,
        toolsWithAnnotations,
        categories,
        sortedCategories,
      );
    }

    {
      const {toolsWithAnnotations, categories, sortedCategories} =
        getToolsAndCategories(tools.filter(tool => isSlimTool(tool)));
      await generateReference(
        'Chrome DevTools MCP Slim Tool Reference',
        SLIM_OUTPUT_PATH,
        toolsWithAnnotations,
        categories,
        sortedCategories,
      );
    }

    // Generate and update configuration options
    const optionsMarkdown = generateConfigOptionsMarkdown();
    updateConfigurationWithOptionsMarkdown(optionsMarkdown);
    process.exit(0);
  } catch (error) {
    console.error('Error generating documentation:', error);
    process.exit(1);
  }
}

// Run the documentation generator
generateToolDocumentation().catch(console.error);