/CONTRIBUTING.md

How to contribute

We'd love to accept your patches and contributions to this project.

Before you begin

Sign our Contributor License Agreement

Contributions to this project must be accompanied by a Contributor License Agreement (CLA). You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project.

If you or your current employer have already signed the Google CLA (even if it was for a different project), you probably don't need to do it again.

Visit https://cla.developers.google.com/ to see your current agreements or to sign a new one.

Review our community guidelines

This project follows Google's Open Source Community Guidelines.

Contribution process

Code reviews

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Conventional commits

Please follow conventional commits for PR and commit titles.

Installation

Check that you are using node version specified in .nvmrc, then run following commands:

git clone https://github.com/ChromeDevTools/chrome-devtools-mcp.git
cd chrome-devtools-mcp
npm ci
npm run build

Testing with @modelcontextprotocol/inspector

npx @modelcontextprotocol/inspector node build/src/index.js

Testing with an MCP client

Add the MCP server to your client's config.

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "node",
      "args": ["/path-to/build/src/index.js"]
    }
  }
}

Using with VS Code SSH

When running the @modelcontextprotocol/inspector it spawns 2 services - one on port 6274 and one on 6277. Usually VS Code automatically detects and forwards 6274 but fails to detect 6277 so you need to manually forward it.

Debugging

To write debug logs to log.txt in the working directory, run with the following commands:

npx @modelcontextprotocol/inspector node build/src/index.js --log-file=/your/desired/path/log.txt

You can use the DEBUG environment variable as usual to control categories that are logged.

Updating documentation

When adding a new tool or updating a tool name or description, make sure to run npm run docs to generate the tool reference documentation.

Contributing to Evals

We use Gemini to evaluate the MCP server tools in scripts/eval_scenarios. Each scenario is a TypeScript file that exports a scenario object implementing TestScenario.

• prompt: The prompt to send to the model.
• maxTurns: Maximum number of conversation turns.
• expectations: A function that verifies the tool calls made by the model.
• htmlRoute (Optional): Serve custom HTML content for the test at a specific path.

We look to test that the tools are used correctly without too rigid assertions. Avoid asserting exact argument values if they can vary (e.g., natural language reasoning), but ensure the core parameters (like URLs or selectors) were correct.

Example:

import {TestScenario} from '../eval_gemini.js';

export const scenario: TestScenario = {
  prompt: 'Navigate to example.com',
  maxTurns: 2,
  expectations: calls => {
    // Check that at least one call was 'browse_page'
    const navigation = calls.find(c => c.name === 'browse_page');
    if (!navigation) throw new Error('Model did not browse the page');
    // Verify essential args
    if (navigation.args.url !== 'http://example.com') {
      throw new Error(`Wrong URL: ${navigation.args.url}`);
    }
  },
};

Restrictions on JSON schema

• no .nullable(), no .object() types.
• represent complex object as a short formatted string.

TODO: implement eslint for schema https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1076