feat(mcp): add JSON Schema for MCP/CLI configuration files

Auto-generate a JSON Schema (draft-07) from config.d.ts using the
TypeScript compiler API. The schema covers all Config fields including
recursively expanded LaunchOptions and BrowserContextOptions.

- Add utils/generate_mcp_config_schema.js generator script
- Output mcp-config.schema.json alongside config.d.ts
- Register in build.js onChanges and flint for CI staleness checks
- Add config-schema.spec.ts with structural assertion tests
- Fix config.d.ts / configIni.ts drift: add saveTrace, remove dead
  saveVideo, add timeouts.expect to longhandTypes
- Document $schema usage in getting-started-mcp.md and
  getting-started-cli.md

Author: lennondotw

docs/src/getting-started-cli.md

@@ -275,6 +275,14 @@ playwright-cli --config path/to/config.json open example.com
 
 The CLI also loads `.playwright/cli.config.json` automatically if present. The config file supports browser options, context options, network rules, timeouts, and more. Run `playwright-cli --help` for the full list of options.
 
+A JSON Schema is available for IDE autocompletion. Once registered with [SchemaStore](https://www.schemastore.org/), the `.playwright/cli.config.json` file will be automatically associated in supported editors. For other file names, add `$schema` manually:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/microsoft/playwright/main/packages/playwright-core/src/tools/mcp/mcp-config.schema.json"
+}
+```
+
 ### Browser extension
 
 Connect to your existing browser tabs instead of launching a new browser:

docs/src/getting-started-mcp.md

@@ -179,13 +179,30 @@ Playwright MCP supports three profile modes:
 
 ### Configuration file
 
-For advanced configuration, use a JSON config file:
+For advanced configuration, use a JSON or INI config file:
 
 ```bash
 npx @playwright/mcp@latest --config path/to/config.json
 ```
 
-The config file supports browser options, context options, network rules, timeouts, and more. See the [Playwright MCP repository](https://github.com/microsoft/playwright-mcp/blob/main/packages/playwright-mcp/config.d.ts) for the full schema.
+The config file supports browser options, context options, network rules, timeouts, and more. See the [Playwright MCP repository](https://github.com/microsoft/playwright-mcp/blob/main/packages/playwright-mcp/config.d.ts) for the full type definition.
+
+#### JSON Schema for IDE autocompletion
+
+A JSON Schema is available for configuration files. Add `$schema` to your config file for IDE autocompletion and validation:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/microsoft/playwright/main/packages/playwright-core/src/tools/mcp/mcp-config.schema.json",
+  "browser": {
+    "browserName": "chromium"
+  }
+}
+```
+
+If you are using `@playwright/cli`, the project-level config at `.playwright/cli.config.json` will be automatically associated with the schema once registered with [SchemaStore](https://www.schemastore.org/).
+
+**Note:** The JSON Schema only validates JSON config files. INI format config files use the same options but are not validated by this schema.
 
 ### Standalone server
 

package.json

@@ -35,7 +35,7 @@
     "lint": "npm run eslint && npm run tsc && npm run doc && npm run check-deps && node utils/generate_channels.js && node utils/generate_types/ && npm run lint-tests && npm run test-types && npm run lint-packages",
     "lint-packages": "node utils/workspace.js --ensure-consistent",
     "lint-tests": "node utils/lint_tests.js",
-    "flint": "concurrently \"npm run eslint\" \"npm run tsc\" \"npm run doc\" \"npm run check-deps\" \"node utils/generate_channels.js\" \"npm run lint-tests\" \"npm run test-types\" \"npm run lint-packages\" \"node utils/doclint/linting-code-snippets/cli.js --js-only\"",
+    "flint": "concurrently \"npm run eslint\" \"npm run tsc\" \"npm run doc\" \"npm run check-deps\" \"node utils/generate_channels.js\" \"node utils/generate_mcp_config_schema.js\" \"npm run lint-tests\" \"npm run test-types\" \"npm run lint-packages\" \"node utils/doclint/linting-code-snippets/cli.js --js-only\"",
     "clean": "node utils/build/clean.js",
     "build": "node utils/build/build.js",
     "watch": "node utils/build/build.js --watch --lint",

packages/playwright-core/src/tools/mcp/config.d.ts

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+// JSON Schema is auto-generated from this file by utils/generate_mcp_config_schema.js.
+
 import type * as playwright from '../../..';
 
 export type ToolCapability =
@@ -52,10 +54,9 @@ export type Config = {
     userDataDir?: string;
 
     /**
-     * Launch options passed to
+     * Launch options passed to browserType.launchPersistentContext().
+     * This is useful for setting options like `channel`, `headless`, `executablePath`, etc.
      * @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch-persistent-context
-     *
-     * This is useful for settings options like `channel`, `headless`, `executablePath`, etc.
      */
     launchOptions?: playwright.LaunchOptions;
 
@@ -137,6 +138,11 @@ export type Config = {
    */
   saveSession?: boolean;
 
+  /**
+   * Whether to save the Playwright trace into the output directory.
+   */
+  saveTrace?: boolean;
+
   /**
    * Reuse the same browser context between all connected HTTP clients.
    */
@@ -154,6 +160,11 @@ export type Config = {
    */
   outputDir?: string;
 
+  /**
+   * Whether to save snapshots, console messages, network logs and other session logs to a file or to the standard output. Defaults to "stdout".
+   */
+  outputMode?: 'file' | 'stdout';
+
   console?: {
     /**
      * The level of console messages to return. Each level includes the messages of more severe levels. Defaults to "info".
@@ -187,12 +198,12 @@ export type Config = {
   testIdAttribute?: string;
 
   timeouts?: {
-    /*
+    /**
      * Configures default action timeout: https://playwright.dev/docs/api/class-page#page-set-default-timeout. Defaults to 5000ms.
      */
     action?: number;
 
-    /*
+    /**
      * Configures default navigation timeout: https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout. Defaults to 60000ms.
      */
     navigation?: number;
@@ -204,7 +215,7 @@ export type Config = {
   };
 
   /**
-   * Whether to send image responses to the client. Can be "allow", "omit", or "auto". Defaults to "auto", which sends images if the client can display them.
+   * Whether to send image responses to the client. Defaults to "allow".
    */
   imageResponses?: 'allow' | 'omit';
 

packages/playwright-core/src/tools/mcp/configIni.ts

@@ -97,7 +97,7 @@ function setNestedValue(obj: Record<string, any>, dotPath: string, value: any) {
   current[parts[parts.length - 1]] = value;
 }
 
-// Regenerate this based on packages/playwright/src/tools/mcp/config.d.ts when config changes.
+// Keep in sync with config.d.ts. JSON Schema is auto-generated by utils/generate_mcp_config_schema.js.
 
 type LonghandType = 'string' | 'number' | 'boolean' | 'string[]' | 'size';
 
@@ -159,9 +159,9 @@ const longhandTypes: Record<string, LonghandType> = {
   'capabilities': 'string[]',
   'saveSession': 'boolean',
   'saveTrace': 'boolean',
-  'saveVideo': 'size',
   'sharedBrowserContext': 'boolean',
   'outputDir': 'string',
+  'outputMode': 'string',
   'imageResponses': 'string',
   'allowUnrestrictedFileAccess': 'boolean',
   'codegen': 'string',
@@ -182,6 +182,7 @@ const longhandTypes: Record<string, LonghandType> = {
   // timeouts
   'timeouts.action': 'number',
   'timeouts.navigation': 'number',
+  'timeouts.expect': 'number',
 
   // snapshot
   'snapshot.mode': 'string',