chore: auto update tools in README (#219)

Motivation: Keeping the readme up to date is a manual effort - this
keeps it automatically up to date and prevents things like
https://github.com/microsoft/playwright-mcp/pull/214 and other
consistency errors in the future.

utils/update-readme.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+// @ts-check
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const commonTools = require('../lib/tools/common').default;
+const consoleTools = require('../lib/tools/console').default;
+const dialogsTools = require('../lib/tools/dialogs').default;
+const filesTools = require('../lib/tools/files').default;
+const installTools = require('../lib/tools/install').default;
+const keyboardTools = require('../lib/tools/keyboard').default;
+const navigateTools = require('../lib/tools/navigate').default;
+const pdfTools = require('../lib/tools/pdf').default;
+const snapshotTools = require('../lib/tools/snapshot').default;
+const tabsTools = require('../lib/tools/tabs').default;
+const screenTools = require('../lib/tools/screen').default;
+
+// Category definitions for tools
+const categories = {
+  'Snapshot-based Interactions': [
+    ...snapshotTools,
+  ],
+  'Vision-based Interactions': [
+    ...screenTools
+  ],
+  'Tab Management': [
+    ...tabsTools(true),
+  ],
+  'Navigation': [
+    ...navigateTools(true),
+  ],
+  'Keyboard': [
+    ...keyboardTools(true)
+  ],
+  'Console': [
+    ...consoleTools
+  ],
+  'Files and Media': [
+    ...filesTools(true),
+    ...pdfTools
+  ],
+  'Utilities': [
+    ...commonTools(true),
+    ...installTools,
+    ...dialogsTools(true),
+  ],
+};
+
+const kStartMarker = `<!--- Generated by ${path.basename(__filename)} -->`;
+const kEndMarker = `<!--- End of generated section -->`;
+
+/**
+ * @param {ParsedToolSchema} tool 
+ * @returns {string}
+ */
+function formatToolForReadme(tool) {
+  const lines = /** @type {string[]} */ ([]);
+  lines.push(`<!-- NOTE: This has been generated via ${path.basename(__filename)} -->\n\n`);
+  lines.push(`- **${tool.name}**\n`);
+  lines.push(`  - Description: ${tool.description}\n`);
+
+  if (tool.parameters && tool.parameters.length > 0) {
+    lines.push(`  - Parameters:\n`);
+    tool.parameters.forEach(param => {
+      const meta = /** @type {string[]} */ ([]);
+      if (param.type)
+        meta.push(param.type);
+      if (param.optional)
+        meta.push('optional');
+      lines.push(`    - \`${param.name}\` ${meta.length ? `(${meta.join(', ')})` : ''}: ${param.description}\n`);
+    });
+  } else {
+    lines.push(`  - Parameters: None\n`);
+  }
+
+  lines.push('\n');
+  return lines.join('');
+}
+
+/**
+ * @typedef {{
+ *   name: any;
+ *  description: any;
+ *   parameters: {
+ *       name: string;
+ *     description: string;
+ *     optional: boolean;
+ *     type: string;
+ *   }[];
+ *}} ParsedToolSchema
+ */
+
+/**
+ * @param {import('../src/tools/tool').ToolSchema} schema 
+ * @returns {ParsedToolSchema}
+ */
+function processToolSchema(schema) {
+  const inputSchema =  /** @type {import('zod-to-json-schema').JsonSchema7ObjectType} */ (schema.inputSchema || {});
+  if (inputSchema.type !== 'object')
+    throw new Error(`Tool ${schema.name} input schema is not an object`);
+
+  // In JSON Schema, properties are considered optional unless listed in the required array
+  const requiredParams = inputSchema?.required || [];
+
+  const parameters = Object.entries(inputSchema.properties).map(([name, prop]) => {
+    return {
+      name,
+      description: prop.description || '',
+      optional: !requiredParams.includes(name),
+      type: /** @type {any} */ (prop).type,
+    };
+  });
+
+  return {
+    name: schema.name,
+    description: schema.description,
+    parameters
+  };
+}
+
+async function updateReadme() {
+  console.log('Loading tool information from compiled modules...');
+
+  // Count the tools processed
+  const totalTools = Object.values(categories).flat().length;
+  console.log(`Found ${totalTools} tools`);
+
+  const generatedLines = /** @type {string[]} */ ([]);
+
+  for (const [category, categoryTools] of Object.entries(categories)) {
+    generatedLines.push(`### ${category}\n\n`);
+    for (const tool of categoryTools) {
+      const scheme = processToolSchema(tool.schema);
+      generatedLines.push(formatToolForReadme(scheme));
+    }
+  }
+
+  const readmePath = path.join(__dirname, '..', 'README.md');
+  const readmeContent = await fs.promises.readFile(readmePath, 'utf-8');
+  const startMarker = readmeContent.indexOf(kStartMarker);
+  const endMarker = readmeContent.indexOf(kEndMarker);
+  if (startMarker === -1 || endMarker === -1)
+    throw new Error('Markers for generated section not found in README');
+
+  const newReadmeContent = [
+    readmeContent.slice(0, startMarker),
+    kStartMarker + '\n\n',
+    generatedLines.join(''),
+    kEndMarker,
+    readmeContent.slice(endMarker + kEndMarker.length),
+  ].join('');
+
+  // Write updated README
+  await fs.promises.writeFile(readmePath, newReadmeContent, 'utf-8');
+  console.log('README updated successfully');
+}
+
+// Run the update
+updateReadme().catch(err => {
+  console.error('Error updating README:', err);
+  process.exit(1);
+});