Skip to content

Commit c723efb

Browse files
jitterboxjitterbox
committed
feat(styles): computed CSS, box model, visibility, batch diffs, named snapshots
Adds computed CSS inspection, box model rects, visibility checks, batch multi-element queries, CSS diff/snapshot tools, and named snapshot support. Updates docs, tests, and test harness accordingly.
1 parent 569e306 commit c723efb

41 files changed

Lines changed: 2132 additions & 456 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CONTRIBUTING.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,8 @@ You can use the `DEBUG` environment variable as usual to control categories that
118118

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

121+
If the change affects when or why to use a tool, update `docs/mcp-tools-user-guide.md` as well.
122+
121123
### Contributing to Evals
122124

123125
We use Gemini to evaluate the MCP server tools in `scripts/eval_scenarios`.

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ control and inspect a live Chrome browser. It acts as a Model-Context-Protocol
77
(MCP) server, giving your AI coding assistant access to the full power of
88
Chrome DevTools for reliable automation, in-depth debugging, and performance analysis.
99

10-
## [Tool reference](./docs/tool-reference.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md) | [Troubleshooting](./docs/troubleshooting.md) | [Design Principles](./docs/design-principles.md)
10+
## [Tool reference](./docs/tool-reference.md) | [MCP tools guide](./docs/mcp-tools-user-guide.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md) | [Troubleshooting](./docs/troubleshooting.md) | [Design Principles](./docs/design-principles.md)
1111

1212
## Key features
1313

@@ -474,6 +474,8 @@ Your MCP client should open the browser and record a performance trace.
474474

475475
If you run into any issues, checkout our [troubleshooting guide](./docs/troubleshooting.md).
476476

477+
For scenario-based guidance on each tool, see the [MCP tools guide](./docs/mcp-tools-user-guide.md).
478+
477479
<!-- BEGIN AUTO GENERATED TOOLS -->
478480

479481
- **Input automation** (9 tools)

‎docs/mcp-tools-user-guide.md‎

Lines changed: 282 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,282 @@
1+
# Chrome DevTools MCP — tools user guide
2+
3+
This guide explains **when and how** to use each MCP tool. For parameter details, see [tool-reference.md](./tool-reference.md).
4+
5+
## Core workflow (recommended)
6+
7+
1. **`list_pages`** — See open tabs; note `pageId` for the tab you care about.
8+
2. **`select_page`** — Target that tab for subsequent tools (unless you only
9+
have one page).
10+
3. **`take_snapshot`** — Get the accessibility tree with **`uid`** values
11+
for elements. **Prefer this over screenshots** for structure and automation.
12+
4. Act (navigate, click, fill, etc.), then **`take_snapshot`** again when the
13+
DOM may have changed.
14+
15+
**uids expire** when the page updates. Always use the **latest** snapshot.
16+
17+
---
18+
19+
## Navigation automation
20+
21+
### `list_pages`
22+
23+
- **Use when:** You need to know which tabs exist, their URLs, or which `pageId` to pass to `select_page` / `close_page`.
24+
- **Typical scenario:** Multi-tab debugging; picking the tab that shows the bug.
25+
26+
### `select_page`
27+
28+
- **Use when:** More than one tab is open, or you need to switch context.
29+
- **Pairs with:** Every page-scoped tool after switching tabs.
30+
31+
### `new_page`
32+
33+
- **Use when:** You need a fresh tab, a specific URL in isolation, or an
34+
**`isolatedContext`** (separate cookies/storage from the default profile).
35+
- **Typical scenario:** Testing logged-out vs logged-in side by side.
36+
37+
### `navigate_page`
38+
39+
- **Use when:** Loading a URL, going **back/forward**, **reload** (optionally
40+
**ignore cache**), or injecting an **init script** before the next document.
41+
- **Prefer over** asking the user to open links manually.
42+
43+
### `close_page`
44+
45+
- **Use when:** Cleaning up extra tabs. **Cannot** close the last remaining page.
46+
47+
### `wait_for`
48+
49+
- **Use when:** The UI updates asynchronously; wait until **any** of the given
50+
strings appears before continuing.
51+
- **Pairs with:** `take_snapshot` after the wait.
52+
53+
### `get_tab_id` _(experimental)_
54+
55+
- **Use when:** Integrating with external tooling that needs the Chrome **tab
56+
ID** for the selected page.
57+
58+
---
59+
60+
## Input automation
61+
62+
All of these need **`uid`** values from **`take_snapshot`** (except
63+
`type_text`, which uses the focused element).
64+
65+
### `click`
66+
67+
- **Use when:** Activating buttons, links, controls, or opening menus.
68+
- **Tip:** Use **`dblClick`** when a double-click is required.
69+
70+
### `click_at` _(experimental vision)_
71+
72+
- **Use when:** You must hit **pixel coordinates** (e.g. canvas, non-a11y
73+
overlay) and **`uid`-based `click`** is not enough.
74+
75+
### `hover`
76+
77+
- **Use when:** Revealing tooltips, mega-menus, or hover-only controls before
78+
another action.
79+
80+
### `fill`
81+
82+
- **Use when:** Setting **inputs**, **text areas**, **`<select>`**, or
83+
combobox-like controls with option children.
84+
- **Prefer over** `type_text` when you have a clear field `uid`.
85+
86+
### `fill_form`
87+
88+
- **Use when:** Many fields should be set in one pass (forms, wizards).
89+
90+
### `type_text`
91+
92+
- **Use when:** Simulating **keystrokes** after focus (e.g. contenteditable,
93+
IME-heavy fields). Optional **`submitKey`** (e.g. Enter).
94+
95+
### `press_key`
96+
97+
- **Use when:** Shortcuts (**Ctrl+R**), Escape, Tab navigation, or keys that
98+
**`fill`** does not model.
99+
100+
### `drag`
101+
102+
- **Use when:** Drag-and-drop between two elements identified by **`from_uid`**
103+
and **`to_uid`**.
104+
105+
### `upload_file`
106+
107+
- **Use when:** Attaching a file; pass a real **`filePath`** on the MCP host.
108+
109+
### `handle_dialog`
110+
111+
- **Use when:** **`alert` / `confirm` / `prompt`** blocks automation; accept
112+
or dismiss, with optional **`promptText`**.
113+
114+
---
115+
116+
## Emulation
117+
118+
### `emulate`
119+
120+
- **Use when:** Reproducing **mobile**, **slow network**, **CPU throttling**,
121+
**geolocation**, **user agent**, **dark/light**, or **viewport** conditions.
122+
- **Typical scenario:** “Why does this break on slow 3G?” or “Does dark mode
123+
break contrast?”
124+
125+
### `resize_page`
126+
127+
- **Use when:** You need an exact **content** width/height (layout breakpoints,
128+
responsive bugs).
129+
130+
---
131+
132+
## Debugging (DOM, visuals, scripts)
133+
134+
### `take_snapshot`
135+
136+
- **Use when:** You need **structure, roles, names, and uids** for automation or
137+
reasoning about the page.
138+
- **Prefer over** `take_screenshot` for “what can I click?” questions.
139+
140+
### `take_screenshot`
141+
142+
- **Use when:** You need **pixels** (visual regression, layout proof, sharing
143+
with a human). Optional **element `uid`**, **`fullPage`**, or **`filePath`**.
144+
145+
### `evaluate_script`
146+
147+
- **Use when:** Reading **`window` state**, calling page APIs, or extracting
148+
data **as JSON**. Pass element **`uid`s** as **`args`** when the script
149+
should receive DOM nodes.
150+
- **Not for:** Long arbitrary scripts without a return value—keep functions
151+
**JSON-serializable**.
152+
153+
### `list_console_messages` / `get_console_message`
154+
155+
- **Use when:** Investigating **errors, warnings, logs**, or **DevTools issues**
156+
after navigation or interaction.
157+
- **Flow:** List to get **`msgid`**, then fetch full detail for one message.
158+
159+
### `lighthouse_audit`
160+
161+
- **Use when:** You want **a11y, SEO, best-practices** scores and reports
162+
(HTML/JSON). **Does not** replace performance tracing for load timelines.
163+
- **Performance:** Use **`performance_start_trace`** / **`performance_stop_trace`**.
164+
165+
### Style, layout, and comparison tools
166+
167+
| Tool | Use when |
168+
| ----------------------------------- | --------------------------------------------------------------------------------- |
169+
| **`get_computed_styles`** | Inspect **resolved CSS** for one node; optional **rule origins**. |
170+
| **`get_computed_styles_batch`** | Same for **many uids** (design-system parity checks). |
171+
| **`get_box_model`** | **Padding/margin/content** quads and geometry debugging. |
172+
| **`get_visibility`** | “Why is this invisible?” (**display**, **opacity**, off-screen, etc.). |
173+
| **`diff_computed_styles`** | **Side-by-side** two elements (A vs B) on the **same** page. |
174+
| **`save_computed_styles_snapshot`** | **Baseline** captured styles + meta for later comparison. |
175+
| **`diff_computed_styles_snapshot`** | Compare **live** node to a **saved** baseline; use **`domPath`** if uids drifted. |
176+
| **`highlight_elements_for_styles`** | Draw **DevTools overlays** and return **border quads** for external diagrams. |
177+
178+
**Typical comparison flow:** `take_snapshot` → `save_computed_styles_snapshot`
179+
→ change URL or code → `take_snapshot` → `diff_computed_styles_snapshot`.
180+
181+
### `screencast_start` / `screencast_stop` _(experimental)_
182+
183+
- **Use when:** You need a **video** repro (MP4). Requires **ffmpeg** on PATH.
184+
185+
---
186+
187+
## Network
188+
189+
### `list_network_requests`
190+
191+
- **Use when:** Seeing **what loaded**, **failed**, or **order/timing** of
192+
requests since navigation. Filter by **resource type** or paginate.
193+
194+
### `get_network_request`
195+
196+
- **Use when:** Inspecting **headers, bodies, status** for one request.
197+
Omit **`reqid`** to use the row **selected in the DevTools Network panel**.
198+
- **Tip:** Save large bodies with **`requestFilePath`** / **`responseFilePath`**.
199+
200+
---
201+
202+
## Performance and memory
203+
204+
### `performance_start_trace` / `performance_stop_trace`
205+
206+
- **Use when:** Diagnosing **load performance**, **main-thread jank**,
207+
**LCP/INP/CLS**, or sharing a **trace** file.
208+
- **Note:** Default flow reloads the page; navigate first if **`reload`** is
209+
used as intended.
210+
211+
### `performance_analyze_insight`
212+
213+
- **Use when:** A trace is done and you need **deeper detail** on one
214+
**insight** (ids/names come from the trace summary).
215+
216+
### `take_memory_snapshot`
217+
218+
- **Use when:** **Heap leaks** or retaining paths; produces a **`.heapsnapshot`**
219+
for Chrome DevTools Memory panel.
220+
221+
---
222+
223+
## Extensions _(experimental)_
224+
225+
### `install_extension` / `uninstall_extension` / `list_extensions` / `reload_extension`
226+
227+
- **Use when:** Testing **unpacked** extensions or automating extension
228+
lifecycle during E2E.
229+
230+
### `trigger_extension_action`
231+
232+
- **Use when:** Clicking the extension **toolbar action** programmatically.
233+
234+
---
235+
236+
## In-page tools _(experimental)_
237+
238+
Pages can expose **`window.__dtmcp`** tools (schemas defined by the app).
239+
240+
### `list_in_page_tools`
241+
242+
- **Use when:** The app under test registers **custom diagnostics** (feature
243+
flags, store state, etc.).
244+
245+
### `execute_in_page_tool`
246+
247+
- **Use when:** Calling those tools with **JSON `params`**; **`{ "uid": "…" }`**
248+
in params is resolved to a real element.
249+
250+
---
251+
252+
## Slim mode (`--slim`)
253+
254+
For minimal deployments, the server exposes only:
255+
256+
| Tool | Role |
257+
| ---------------- | ----------------------------------- |
258+
| **`screenshot`** | Viewport PNG to a temp path |
259+
| **`navigate`** | `goto` a URL |
260+
| **`evaluate`** | Run a script string; result as text |
261+
262+
Use full mode for **network, console, performance, styles, and snapshot-based
263+
automation**.
264+
265+
---
266+
267+
## Choosing tools vs generic web search
268+
269+
- **Prefer this MCP** when the task needs **ground truth** from a real browser:
270+
computed styles, traces, network waterfalls, console stacks, or reproducible
271+
clicks tied to the a11y tree.
272+
- **Prefer crawling/search** for **documentation or third-party content** you
273+
are not loading in the instrumented Chrome instance.
274+
275+
---
276+
277+
## See also
278+
279+
- [Tool reference](./tool-reference.md) — full schemas
280+
- [Slim tool reference](./slim-tool-reference.md)
281+
- [Troubleshooting](./troubleshooting.md)
282+
- [CLI options](../README.md) — flags that enable experimental categories

‎docs/slim-tool-reference.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<!-- AUTO GENERATED DO NOT EDIT - run 'npm run gen' to update-->
22

3-
# Chrome DevTools MCP Slim Tool Reference (~359 cl100k_base tokens)
3+
# Chrome DevTools MCP Slim Tool Reference (~391 cl100k_base tokens)
44

55
- **[Navigation automation](#navigation-automation)** (1 tools)
66
- [`navigate`](#navigate)
@@ -12,7 +12,7 @@
1212

1313
### `navigate`
1414

15-
**Description:** Loads a URL
15+
**Description:** [`Navigate`](#navigate) the selected tab to url (--slim; accepts beforeunload).
1616

1717
**Parameters:**
1818

@@ -24,7 +24,7 @@
2424

2525
### `evaluate`
2626

27-
**Description:** Evaluates a JavaScript script
27+
**Description:** [`Evaluate`](#evaluate) a script string in page context; returns text/JSON (--slim).
2828

2929
**Parameters:**
3030

@@ -34,7 +34,7 @@
3434

3535
### `screenshot`
3636

37-
**Description:** Takes a [`screenshot`](#screenshot)
37+
**Description:** Viewport PNG saved to a temp path (--slim mode; minimal footprint).
3838

3939
**Parameters:** None
4040

0 commit comments

Comments
 (0)