@e4779/skills 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/chrome-devtools/README.md +76 -0
- package/chrome-devtools/SKILL.md +277 -0
- package/chrome-devtools/references/recipes.md +379 -0
- package/chrome-devtools/references/setup.md +138 -0
- package/drawio/SKILL.md +395 -0
- package/gh-cli/SKILL.md +83 -0
- package/grill/SKILL.md +72 -0
- package/layout-check/README.md +32 -0
- package/layout-check/SKILL.md +416 -0
- package/layout-check/scripts/layoutProbe.mjs +539 -0
- package/mcpls/SKILL.md +261 -0
- package/mcpls/references/configuration.md +131 -0
- package/mcpls/references/install.md +13 -0
- package/mcporter/SKILL.md +90 -0
- package/mindmap/SKILL.md +46 -0
- package/mindmap/references/drawio-recipe.md +60 -0
- package/mindmap/references/mindmap-design.md +63 -0
- package/opensource-contribution/SKILL.md +119 -0
- package/package.json +29 -5
- package/shell-taste/.shellcheckrc +16 -0
- package/shell-taste/SKILL.md +95 -0
- package/shell-taste/references/handbook/dialects.md +168 -0
- package/shell-taste/references/handbook/dom/01-output-logging.md +245 -0
- package/shell-taste/references/handbook/dom/02-errors-exit.md +48 -0
- package/shell-taste/references/handbook/dom/03-installation-setup.md +179 -0
- package/shell-taste/references/handbook/dom/04-network.md +384 -0
- package/shell-taste/references/handbook/dom/05-files-paths.md +74 -0
- package/shell-taste/references/handbook/dom/06-checks-validation.md +127 -0
- package/shell-taste/references/handbook/dom/07-system-administration.md +103 -0
- package/shell-taste/references/handbook/dom/08-privilege-users.md +58 -0
- package/shell-taste/references/handbook/dom/09-text-data.md +62 -0
- package/shell-taste/references/handbook/dom/10-terminal-ux.md +60 -0
- package/shell-taste/references/handbook/dom/11-process-control.md +28 -0
- package/shell-taste/references/handbook/dom/12-uncategorized.md +161 -0
- package/shell-taste/references/handbook/dom/13-containers.md +13 -0
- package/shell-taste/references/handbook/dom/14-agents-ai-tooling.md +13 -0
- package/shell-taste/references/handbook/family-index.md +230 -0
- package/shell-taste/references/handbook/index.md +41 -0
- package/skill-author/SKILL.md +86 -0
- package/sobesednik/SKILL.md +98 -0
- package/sobesednik/card-template.md +23 -0
- package/sobesednik/personas/advocate.md +27 -0
- package/sobesednik/personas/analyst.md +29 -0
- package/sobesednik/personas/chat.md +42 -0
- package/sobesednik/personas/ifs.md +32 -0
- package/sobesednik/personas/journal/README.md +6 -0
- package/sobesednik/personas/nasreddin.md +29 -0
- package/sobesednik/personas/premortem.md +29 -0
- package/sobesednik/personas/rogers.md +27 -0
- package/sobesednik/personas/socratic.md +29 -0
- package/sobesednik/personas/stoic.md +27 -0
- package/sobesednik/references/persona-design.md +41 -0
- package/zai-mcp/README.md +63 -0
- package/zai-mcp/SKILL.md +160 -0
- package/zai-mcp/references/recipes.md +273 -0
- package/zai-mcp/references/tools.md +266 -0
- package/README.md +0 -3
|
@@ -0,0 +1,379 @@
|
|
|
1
|
+
# Chrome DevTools — Recipes
|
|
2
|
+
|
|
3
|
+
> **Read on demand.** Worked scenarios using fabric natives
|
|
4
|
+
> (`mcp.chrome_devtools.*` inside `fabric_exec`). The core workflow is in
|
|
5
|
+
> `../SKILL.md`; live schemas via `tools.describe({ ref: "mcp.chrome_devtools.<tool>" })`.
|
|
6
|
+
|
|
7
|
+
**These recipes come from real sessions** (financial-data scraping: finam.ru,
|
|
8
|
+
MOEX, dohod.ru, ЦБ РФ, FRED). Usage frequency across ~1300 recorded calls:
|
|
9
|
+
|
|
10
|
+
| tool | calls | |
|
|
11
|
+
|---|---|---|
|
|
12
|
+
| `navigate_page` | 482 | most-used by far |
|
|
13
|
+
| `evaluate_script` | 290 | the swiss-army knife |
|
|
14
|
+
| `take_snapshot` | 241 | primary "eyes" |
|
|
15
|
+
| everything else | ~300 | |
|
|
16
|
+
|
|
17
|
+
`navigate` + `evaluate` + `snapshot` cover ~73% of real usage — that's why
|
|
18
|
+
`SKILL.md` teaches just those three first.
|
|
19
|
+
|
|
20
|
+
## Conventions
|
|
21
|
+
|
|
22
|
+
- **Every page tool requires `pageId`** — get it from `list_pages` / `new_page`.
|
|
23
|
+
Examples below assume `const pageId = …` is already bound.
|
|
24
|
+
- Every interaction starts from a fresh `take_snapshot` — **uids change when the
|
|
25
|
+
DOM changes**. Don't reuse a uid across navigation or dynamic updates.
|
|
26
|
+
- Arrays and objects are plain TS values now — no `--args` JSON quoting:
|
|
27
|
+
`list_console_messages({ pageId, types: ["error", "warn"] })`.
|
|
28
|
+
- `includeSnapshot: true` on click/fill/hover returns a fresh snapshot in the
|
|
29
|
+
same response — saves a round-trip.
|
|
30
|
+
- First call after idle may cold-start (`-32001` timeout) → wait ~8s, retry.
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## Recipe 1 — Scrape a data table out of a page
|
|
35
|
+
|
|
36
|
+
> *Pattern observed 5+ times parsing БПИФ / MOEX report tables.*
|
|
37
|
+
|
|
38
|
+
Most real pages don't give you clean JSON — the data is in a `<table>` you have
|
|
39
|
+
to walk. Three variants, cheapest first.
|
|
40
|
+
|
|
41
|
+
### Variant A — count + sanity-check before extracting
|
|
42
|
+
Don't dump a huge table blind. Probe structure first:
|
|
43
|
+
```ts
|
|
44
|
+
await mcp.chrome_devtools.evaluate_script({ pageId, function: `() => {
|
|
45
|
+
const tables = [...document.querySelectorAll("table")];
|
|
46
|
+
return {
|
|
47
|
+
tableCount: tables.length,
|
|
48
|
+
rowsPerTable: tables.map(t => t.rows.length),
|
|
49
|
+
h2: [...document.querySelectorAll("h2")].map(h => h.textContent.trim())
|
|
50
|
+
};
|
|
51
|
+
}` });
|
|
52
|
+
```
|
|
53
|
+
Tells you which table index holds your data (e.g. "the report table is `tables[1]`").
|
|
54
|
+
|
|
55
|
+
### Variant B — extract one table as a matrix
|
|
56
|
+
```ts
|
|
57
|
+
await mcp.chrome_devtools.evaluate_script({ pageId, function: `() => {
|
|
58
|
+
const tables = [...document.querySelectorAll("table")];
|
|
59
|
+
const report = tables[1]; // index from Variant A
|
|
60
|
+
if (!report) return { error: "no report table", tableCount: tables.length };
|
|
61
|
+
const rows = [...report.querySelectorAll("tr")].slice(1).map(tr =>
|
|
62
|
+
[...tr.querySelectorAll("td")].map(td => td.textContent.trim())
|
|
63
|
+
);
|
|
64
|
+
return { rows, rowCount: rows.length };
|
|
65
|
+
}` });
|
|
66
|
+
```
|
|
67
|
+
Returns `rows` as an array-of-arrays — ready to format as CSV/TOON.
|
|
68
|
+
|
|
69
|
+
### Variant C — table summary (when you only need shape + edges)
|
|
70
|
+
```ts
|
|
71
|
+
await mcp.chrome_devtools.evaluate_script({ pageId, function: `() => {
|
|
72
|
+
const t = document.querySelector(".tilt-table");
|
|
73
|
+
if (!t) return "no tilt-table";
|
|
74
|
+
return {
|
|
75
|
+
rows: t.rows.length,
|
|
76
|
+
cols: t.rows[0]?.cells.length ?? 0,
|
|
77
|
+
firstRow: [...t.rows[0].cells].map(c => c.textContent.trim()),
|
|
78
|
+
lastRow: [...t.rows.at(-1).cells].map(c => c.textContent.trim())
|
|
79
|
+
};
|
|
80
|
+
}` });
|
|
81
|
+
```
|
|
82
|
+
Cheaper than Variant B — read first/last row to confirm it's the right table,
|
|
83
|
+
then decide if you need the full dump.
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
## Recipe 2 — Extract a section between two headings
|
|
88
|
+
|
|
89
|
+
> *Real use: pull "Шаг 2: …" block out of a long regulatory document.*
|
|
90
|
+
|
|
91
|
+
When content lives between `<h2>`s, walk `nextElementSibling` until you hit the
|
|
92
|
+
next heading:
|
|
93
|
+
```ts
|
|
94
|
+
await mcp.chrome_devtools.evaluate_script({ pageId, function: `() => {
|
|
95
|
+
let el = document.querySelector("h2");
|
|
96
|
+
while (el && !el.textContent.includes("Шаг 2")) el = el.nextElementSibling;
|
|
97
|
+
if (!el) return "not found";
|
|
98
|
+
const section = el.parentElement;
|
|
99
|
+
const rows = [...section.querySelectorAll(".tilt-table tbody tr, table tr")]
|
|
100
|
+
.map(r => [...r.querySelectorAll("td,th")].map(c => c.textContent.trim()).join(" | "))
|
|
101
|
+
.filter(Boolean);
|
|
102
|
+
return rows.join("\n");
|
|
103
|
+
}` });
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## Recipe 3 — Trigger lazy-loaded content (scroll, click "load more")
|
|
109
|
+
|
|
110
|
+
> *Real use: infinite-scroll lists on dohod.ru / MOEX history.*
|
|
111
|
+
|
|
112
|
+
Many pages load rows as you scroll. Scroll with `press_key` (fires real scroll
|
|
113
|
+
events; JS `scrollTo` can be detected-and-blocked by some SPAs), wait, re-measure:
|
|
114
|
+
```ts
|
|
115
|
+
// 1. Scroll down — End jumps to bottom, PageDown steps. Use what fits the page.
|
|
116
|
+
await mcp.chrome_devtools.press_key({ pageId, key: "End" });
|
|
117
|
+
|
|
118
|
+
// 2. Wait for the fetch to land
|
|
119
|
+
await new Promise(r => setTimeout(r, 1000));
|
|
120
|
+
|
|
121
|
+
// 3. Re-count; repeat until the count stops growing (reading is a legit evaluate use)
|
|
122
|
+
await mcp.chrome_devtools.evaluate_script({ pageId,
|
|
123
|
+
function: "() => document.querySelectorAll('.item').length" });
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
For a **"Load more" button** — click the button by `uid` (not via JS), then wait:
|
|
127
|
+
```ts
|
|
128
|
+
await mcp.chrome_devtools.take_snapshot({ pageId }); // find the button uid
|
|
129
|
+
await mcp.chrome_devtools.click({ pageId, uid: "1_9" });
|
|
130
|
+
await mcp.chrome_devtools.wait_for({ pageId,
|
|
131
|
+
text: ["Loading", "More", "End of list"] });
|
|
132
|
+
```
|
|
133
|
+
For a batch of identical "load more" buttons, loop with `click` (each by uid) —
|
|
134
|
+
not a single `evaluate_script` that calls `.click()` in a loop. The dedicated
|
|
135
|
+
`click` fires real trusted events that SPAs listen for; synthetic clicks via
|
|
136
|
+
`evaluate_script` silently fail on frameworks that check `event.isTrusted`.
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## Recipe 4 — Investigate before interacting
|
|
141
|
+
|
|
142
|
+
> *The single most-repeated pattern. Always inspect page state first.*
|
|
143
|
+
|
|
144
|
+
Before filling a form, clicking, or scraping, probe the page cheaply:
|
|
145
|
+
```ts
|
|
146
|
+
await mcp.chrome_devtools.evaluate_script({ pageId, function: `() => ({
|
|
147
|
+
url: location.href,
|
|
148
|
+
title: document.title,
|
|
149
|
+
ready: document.readyState,
|
|
150
|
+
compatMode: document.compatMode, // "CSS1Compat" or "BackCompat" (quirks)
|
|
151
|
+
forms: document.forms.length,
|
|
152
|
+
buttons: document.querySelectorAll("button").length,
|
|
153
|
+
inputs: document.querySelectorAll("input").length,
|
|
154
|
+
h1: document.querySelector("h1")?.innerText,
|
|
155
|
+
subtitle: document.querySelector(".subtitle")?.textContent?.trim() || "none",
|
|
156
|
+
errors: [...document.querySelectorAll("[role=alert],.error,.invalid")]
|
|
157
|
+
.map(e => e.innerText).slice(0,5)
|
|
158
|
+
})` });
|
|
159
|
+
```
|
|
160
|
+
`compatMode: "BackCompat"` in particular explains a *lot* of "why does the
|
|
161
|
+
layout look wrong" bugs (page is in quirks mode).
|
|
162
|
+
|
|
163
|
+
---
|
|
164
|
+
|
|
165
|
+
## Recipe 5 — Read page text without dumping the whole DOM
|
|
166
|
+
|
|
167
|
+
> *Real use: quick "what's actually visible" check.*
|
|
168
|
+
|
|
169
|
+
`document.body.innerText` gives rendered text (no HTML noise). Always **slice**
|
|
170
|
+
it — full innerText of a long page blows up context:
|
|
171
|
+
```ts
|
|
172
|
+
// First 3000 chars — enough to identify the page
|
|
173
|
+
await mcp.chrome_devtools.evaluate_script({ pageId,
|
|
174
|
+
function: "() => document.body.innerText.slice(0, 3000)" });
|
|
175
|
+
|
|
176
|
+
// Too big? save to a file and pi.read it only if needed
|
|
177
|
+
await mcp.chrome_devtools.evaluate_script({ pageId,
|
|
178
|
+
function: "() => document.body.innerText", filePath: "/tmp/page.txt" });
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
---
|
|
182
|
+
|
|
183
|
+
## Recipe 6 — Find downloadable files (PDFs, videos, data)
|
|
184
|
+
|
|
185
|
+
> *Real use: locating PDF reports and video sources on a page.*
|
|
186
|
+
|
|
187
|
+
### PDF / link harvest
|
|
188
|
+
```ts
|
|
189
|
+
await mcp.chrome_devtools.evaluate_script({ pageId, function: `() => {
|
|
190
|
+
const links = document.querySelectorAll("a");
|
|
191
|
+
return [...links].filter(a => a.href.includes(".pdf")).map(a => a.href).slice(0, 10);
|
|
192
|
+
}` });
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
### Video / media (with fallback)
|
|
196
|
+
```ts
|
|
197
|
+
await mcp.chrome_devtools.evaluate_script({ pageId, function: `() => {
|
|
198
|
+
const results = [];
|
|
199
|
+
document.querySelectorAll("video").forEach(v => results.push({
|
|
200
|
+
src: v.src, currentSrc: v.currentSrc, poster: v.poster, readyState: v.readyState
|
|
201
|
+
}));
|
|
202
|
+
document.querySelectorAll("source").forEach(s => results.push({ src: s.src, type: s.type }));
|
|
203
|
+
if (results.length === 0) {
|
|
204
|
+
// fallback: any element whose src mentions media formats
|
|
205
|
+
document.querySelectorAll("*").forEach(el => {
|
|
206
|
+
const src = el.getAttribute("src");
|
|
207
|
+
if (src && (src.includes("mp4") || src.includes("m3u8") || src.includes("video")))
|
|
208
|
+
results.push({ tag: el.tagName, src });
|
|
209
|
+
});
|
|
210
|
+
}
|
|
211
|
+
return JSON.stringify(results.slice(0, 20));
|
|
212
|
+
}` });
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
---
|
|
216
|
+
|
|
217
|
+
## Recipe 7 — Login flow with validation
|
|
218
|
+
|
|
219
|
+
```ts
|
|
220
|
+
// 1. Navigate to the login page
|
|
221
|
+
await mcp.chrome_devtools.navigate_page({ pageId, type: "url",
|
|
222
|
+
url: "https://app.example.com/login" });
|
|
223
|
+
|
|
224
|
+
// 2. Snapshot to find the form fields
|
|
225
|
+
await mcp.chrome_devtools.take_snapshot({ pageId });
|
|
226
|
+
// → note uids: 1_3 = username, 1_4 = password, 1_5 = submit
|
|
227
|
+
|
|
228
|
+
// 3. Fill the whole form in ONE call (faster than two `fill`s)
|
|
229
|
+
await mcp.chrome_devtools.fill_form({ pageId, elements: [
|
|
230
|
+
{ uid: "1_3", value: "alice@example.com" },
|
|
231
|
+
{ uid: "1_4", value: "correct horse battery staple" },
|
|
232
|
+
] });
|
|
233
|
+
|
|
234
|
+
// 4. Click submit (return fresh snapshot in the same call)
|
|
235
|
+
await mcp.chrome_devtools.click({ pageId, uid: "1_5", includeSnapshot: true });
|
|
236
|
+
|
|
237
|
+
// 5. Wait for a success/failure indicator
|
|
238
|
+
await mcp.chrome_devtools.wait_for({ pageId,
|
|
239
|
+
text: ["Dashboard", "Welcome", "Invalid", "Log in"] });
|
|
240
|
+
```
|
|
241
|
+
**If it failed:** step 5 matches `"Invalid"` / `"Log in"`. Read cookies to debug
|
|
242
|
+
the session:
|
|
243
|
+
```ts
|
|
244
|
+
await mcp.chrome_devtools.evaluate_script({ pageId,
|
|
245
|
+
function: "() => document.cookie" });
|
|
246
|
+
```
|
|
247
|
+
**Skip re-login next time** — drive a real Chrome profile via `--browserUrl`
|
|
248
|
+
(Recipe 9) so cookies/2FA persist.
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
252
|
+
## Recipe 8 — Debug a SPA (console errors + failing API calls)
|
|
253
|
+
|
|
254
|
+
```ts
|
|
255
|
+
await mcp.chrome_devtools.navigate_page({ pageId, type: "url",
|
|
256
|
+
url: "https://app.example.com/dashboard" });
|
|
257
|
+
|
|
258
|
+
// SPA: snapshot is empty right after nav. Wait for real content.
|
|
259
|
+
await mcp.chrome_devtools.wait_for({ pageId,
|
|
260
|
+
text: ["Loading", "Dashboard", "Error", "No data"], timeout: 15000 });
|
|
261
|
+
|
|
262
|
+
// Console errors (only error/warn)
|
|
263
|
+
await mcp.chrome_devtools.list_console_messages({ pageId, types: ["error", "warn"] });
|
|
264
|
+
// → msgid=12 [error] Uncaught TypeError: Cannot read 'map' of undefined
|
|
265
|
+
await mcp.chrome_devtools.get_console_message({ pageId, msgid: 12 });
|
|
266
|
+
|
|
267
|
+
// The failing API call
|
|
268
|
+
await mcp.chrome_devtools.list_network_requests({ pageId,
|
|
269
|
+
resourceTypes: ["fetch", "xhr"] });
|
|
270
|
+
// → reqid=8 GET /api/items [500]
|
|
271
|
+
await mcp.chrome_devtools.get_network_request({ pageId, reqid: 8,
|
|
272
|
+
responseFilePath: "/tmp/err.json" });
|
|
273
|
+
// inspect /tmp/err.json offline — keeps the body out of context
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
---
|
|
277
|
+
|
|
278
|
+
## Recipe 9 — Use a real Chrome profile (persisted logins)
|
|
279
|
+
|
|
280
|
+
> *Solves the #1 pain: re-doing auth every session.*
|
|
281
|
+
|
|
282
|
+
Instead of a fresh headless profile, point the server at a Chrome that is
|
|
283
|
+
already logged in:
|
|
284
|
+
|
|
285
|
+
```bash
|
|
286
|
+
# 1. Start Chrome with remote debugging on :9222 (close other Chrome instances first)
|
|
287
|
+
google-chrome --remote-debugging-port=9222 & # or chromium / chrome.exe
|
|
288
|
+
|
|
289
|
+
# 2. Edit ~/.mcporter/mcporter.json → use --browserUrl:
|
|
290
|
+
# "args": ["-y","chrome-devtools-mcp@latest","--browserUrl","http://127.0.0.1:9222"]
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
```ts
|
|
294
|
+
// 3. Bounce fabric's MCP runtime so it picks up the new config
|
|
295
|
+
await tools.call({ ref: "mcp.$reload" });
|
|
296
|
+
|
|
297
|
+
// 4. Verify
|
|
298
|
+
await mcp.chrome_devtools.list_pages({}); // shows your real tabs
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
On this WSL box both servers already work this way (Windows Chrome instances on
|
|
302
|
+
9222 / 9223 — see `../SKILL.md`).
|
|
303
|
+
|
|
304
|
+
> **Frozen-tabs caveat:** chrome-devtools-mcp *forces every tab to load*. If your
|
|
305
|
+
> profile has hundreds of tabs, Chrome may OOM-crash. Close what you don't need,
|
|
306
|
+
> or use a dedicated `--userDataDir` profile for automation.
|
|
307
|
+
|
|
308
|
+
---
|
|
309
|
+
|
|
310
|
+
## Recipe 10 — Debug "why does the layout look wrong"
|
|
311
|
+
|
|
312
|
+
> *Real use: container inspection when a widget renders at the wrong height.*
|
|
313
|
+
|
|
314
|
+
Combine `getBoundingClientRect` + `getComputedStyle` + child structure:
|
|
315
|
+
```ts
|
|
316
|
+
await mcp.chrome_devtools.evaluate_script({ pageId, function: `() => {
|
|
317
|
+
const c = document.querySelector(".container");
|
|
318
|
+
if (!c) return "not found";
|
|
319
|
+
const r = c.getBoundingClientRect();
|
|
320
|
+
const cs = getComputedStyle(c);
|
|
321
|
+
return {
|
|
322
|
+
height: r.height,
|
|
323
|
+
minHeight: cs.minHeight,
|
|
324
|
+
children: c.children.length,
|
|
325
|
+
firstChild: c.children[0]?.tagName + (c.children[0]?.className ? "." + c.children[0].className : ""),
|
|
326
|
+
lastChild: c.children[c.children.length-1]?.tagName
|
|
327
|
+
};
|
|
328
|
+
}` });
|
|
329
|
+
```
|
|
330
|
+
For full pairwise layout verification (alignment, gaps, overlaps), pair this
|
|
331
|
+
with the **`layout-check`** skill instead of eyeballing screenshots.
|
|
332
|
+
|
|
333
|
+
---
|
|
334
|
+
|
|
335
|
+
## Recipe 11 — Performance trace
|
|
336
|
+
|
|
337
|
+
```ts
|
|
338
|
+
// 1. Land on the page first (trace reloads by default)
|
|
339
|
+
await mcp.chrome_devtools.navigate_page({ pageId, type: "url", url: "https://example.com" });
|
|
340
|
+
|
|
341
|
+
// 2. Record (auto-reloads + auto-stops after load)
|
|
342
|
+
await mcp.chrome_devtools.performance_start_trace({ pageId });
|
|
343
|
+
// For interactive tracing (clicks, animations):
|
|
344
|
+
await mcp.chrome_devtools.performance_start_trace({ pageId, reload: false, autoStop: false });
|
|
345
|
+
// … <interact> …
|
|
346
|
+
await mcp.chrome_devtools.performance_stop_trace({ pageId, filePath: "/tmp/trace.json.gz" });
|
|
347
|
+
|
|
348
|
+
// 3. Drill into an insight set (id from stop_trace output)
|
|
349
|
+
await mcp.chrome_devtools.performance_analyze_insight({ pageId,
|
|
350
|
+
insightSetId: "set_1", insightName: "LCPBreakdown" });
|
|
351
|
+
```
|
|
352
|
+
> **Lighthouse ≠ performance.** `lighthouse_audit` excludes perf. For Core Web
|
|
353
|
+
> Vitals always use the trace tools.
|
|
354
|
+
|
|
355
|
+
---
|
|
356
|
+
|
|
357
|
+
## When to stop reaching for Chrome
|
|
358
|
+
|
|
359
|
+
- **Static HTML / source** → `pi.read` the file. No browser needed.
|
|
360
|
+
- **Computed CSS / box model** → the `chrome-css` skill wraps the right calls.
|
|
361
|
+
- **Alignment verification** → `layout-check` skill (coordinates, not pixels).
|
|
362
|
+
- **Simple page→text** → try a reader tool (`zai-reader`) first; fall back to
|
|
363
|
+
Chrome only if the page needs JS to render.
|
|
364
|
+
|
|
365
|
+
---
|
|
366
|
+
|
|
367
|
+
## Real errors → fixes (from session logs)
|
|
368
|
+
|
|
369
|
+
| Error | Meaning | Fix |
|
|
370
|
+
|---|---|---|
|
|
371
|
+
| `chrome-devtools appears offline` | tab crashed / runtime lost Chrome | retry `list_pages`; persistent → `tools.call({ ref: "mcp.$reload" })` |
|
|
372
|
+
| `MCP error -32000: Connection closed` | Chrome process died | restart the Chrome instance; `$reload` |
|
|
373
|
+
| `MCP error -32001: Request timed out` | cold start or slow page | wait ~8s, retry once |
|
|
374
|
+
| `Navigation timeout of 10000 ms exceeded` | site too slow | retry `navigate_page` (often lands 2nd try); or raise `timeout` |
|
|
375
|
+
| `Element with uid … not found` | DOM changed since snapshot | `take_snapshot` again, use fresh uid |
|
|
376
|
+
| `must have required properties pageId` | schema drift — you skipped `pageId` | get it from `list_pages`; check `tools.describe` first |
|
|
377
|
+
|
|
378
|
+
Cold starts and stale uids cover the vast majority of real-world failures —
|
|
379
|
+
Chrome is the flaky part, not the MCP.
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
# Chrome DevTools — First-run Setup (WSL → Windows Chrome)
|
|
2
|
+
|
|
3
|
+
> **Load this only when a prerequisite is missing.** If
|
|
4
|
+
> `await mcp.chrome_devtools.list_pages({})` returns pages, skip this file.
|
|
5
|
+
>
|
|
6
|
+
> Every step is idempotent and safe to repeat. Ask the user before changing
|
|
7
|
+
> anything (Phase 3).
|
|
8
|
+
|
|
9
|
+
The chain has four links: **Windows Chrome instances** (debug ports),
|
|
10
|
+
**mirrored WSL networking** (127.0.0.1 shared), **config entries** in
|
|
11
|
+
`~/.mcporter/mcporter.json` (`--browserUrl`), and **fabric's MCP runtime**
|
|
12
|
+
(pooled connections, cold-start on first call).
|
|
13
|
+
|
|
14
|
+
| server | Chrome | port | use |
|
|
15
|
+
|---|---|---|---|
|
|
16
|
+
| `chrome-devtools` | `chrome-debug.ps1` | 9222 | direct — default |
|
|
17
|
+
| `chrome-devtools-proxy` | `chrome-debug-proxy.ps1` | 9223 | blocked foreign sites (bypass proxy `<proxy-host>:8888`) |
|
|
18
|
+
|
|
19
|
+
Scripts live in `C:\Users\e41q\.local\bin\`. Never open RU domains through
|
|
20
|
+
9223 (detection exposure) — see global `~/.pi/agent/AGENTS.md`.
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Phase 1 — Inventory (read-only)
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
# 1. Ports reachable? (mirrored networking + instance up)
|
|
28
|
+
curl -s -m 3 http://127.0.0.1:9222/json/version || echo "9222 DOWN"
|
|
29
|
+
curl -s -m 3 http://127.0.0.1:9223/json/version || echo "9223 DOWN"
|
|
30
|
+
|
|
31
|
+
# 2. Config entries present?
|
|
32
|
+
jq -r '.mcpServers | keys[]' ~/.mcporter/mcporter.json # expect both chrome-* entries
|
|
33
|
+
jq '.mcpServers["chrome-devtools"].args' ~/.mcporter/mcporter.json # expect --browserUrl ...:9222
|
|
34
|
+
|
|
35
|
+
# 3. Launcher scripts exist on the Windows side?
|
|
36
|
+
powershell.exe -NoProfile -Command "Get-ChildItem C:\Users\e41q\.local\bin\chrome-debug*.ps1 | Select -Expand Name"
|
|
37
|
+
|
|
38
|
+
# 4. Mirrored networking on?
|
|
39
|
+
wslinfo --networking-mode 2>/dev/null || grep -i networkingMode /mnt/c/Users/e41q/.wslconfig
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Inside fabric:
|
|
43
|
+
|
|
44
|
+
```ts
|
|
45
|
+
await tools.call({ ref: "mcp.$servers" }); // both chrome servers listed, tools: 29 each?
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Phase 2 — Report
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
port 9222 (direct): ✓ version json / ✗ down → Phase 3a
|
|
52
|
+
port 9223 (proxy): ✓ / ✗ down → Phase 3a
|
|
53
|
+
config entries: ✓ both map to --browserUrl / ✗ → Phase 3b
|
|
54
|
+
launcher scripts: ✓ chrome-debug*.ps1 / ✗ → recreate (user)
|
|
55
|
+
mirrored networking: ✓ mirrored / ✗ → Phase 3c (needs wsl --shutdown!)
|
|
56
|
+
fabric registration: ✓ in $servers / ✗ → Phase 3b + $reload
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Phase 3 — Repair (with user consent)
|
|
60
|
+
|
|
61
|
+
### 3a. Chrome instance down
|
|
62
|
+
|
|
63
|
+
Start it via Windows interop (or ask the user to run the script on Windows):
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
powershell.exe -NoProfile -Command "$p = Start-Process -WindowStyle Hidden powershell -ArgumentList '-NoProfile','-ExecutionPolicy','Bypass','-File','C:\Users\e41q\.local\bin\chrome-debug.ps1' -PassThru; $p.Id"
|
|
67
|
+
# note the PID for later cleanup:
|
|
68
|
+
# taskkill.exe /PID <pid> /T /F
|
|
69
|
+
sleep 3
|
|
70
|
+
curl -s -m 3 http://127.0.0.1:9222/json/version # verify
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Cold start of the mb-profile instance may restore many tabs and wedge early
|
|
74
|
+
MCP calls for a minute or two — wait for it to settle.
|
|
75
|
+
|
|
76
|
+
### 3b. Config entry missing / wrong
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
jq '.mcpServers["chrome-devtools"] = {
|
|
80
|
+
description: "Windows Chrome (direct) via CDP from WSL",
|
|
81
|
+
command: "npx",
|
|
82
|
+
args: ["-y","chrome-devtools-mcp@latest","--browserUrl","http://127.0.0.1:9222"],
|
|
83
|
+
env: { npm_config_loglevel: "error" }
|
|
84
|
+
}' ~/.mcporter/mcporter.json > /tmp/m.json && mv /tmp/m.json ~/.mcporter/mcporter.json
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
(same for `chrome-devtools-proxy` with port 9223), then inside fabric:
|
|
88
|
+
|
|
89
|
+
```ts
|
|
90
|
+
await tools.call({ ref: "mcp.$reload" });
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
### 3c. Mirrored networking off
|
|
94
|
+
|
|
95
|
+
`C:\Users\e41q\.wslconfig` needs `[wsl2]` → `networkingMode=mirrored`, then
|
|
96
|
+
`wsl --shutdown` from Windows — **this kills the current WSL session**; do it
|
|
97
|
+
only with the user, at a natural break.
|
|
98
|
+
|
|
99
|
+
## Phase 4 — Smoke test
|
|
100
|
+
|
|
101
|
+
```ts
|
|
102
|
+
await mcp.chrome_devtools.list_pages({}); // any page list = success
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
First call may cold-start (~10s; `-32001` timeout → wait 8s, retry once).
|
|
106
|
+
|
|
107
|
+
## Phase 5 — If the smoke test failed
|
|
108
|
+
|
|
109
|
+
| Symptom | Likely cause | Fix |
|
|
110
|
+
|---|---|---|
|
|
111
|
+
| `Could not connect to Chrome` | instance down (port check failed) | Phase 3a |
|
|
112
|
+
| `MCP error -32001: Request timed out` | cold start / mb-profile restoring tabs | wait ~8s, retry; if persistent restart instance |
|
|
113
|
+
| `appears offline` / `Connection closed` | tab/process crashed | retry `list_pages`; Phase 3a |
|
|
114
|
+
| server missing from `$servers` | config not loaded | Phase 3b + `mcp.$reload` |
|
|
115
|
+
| port up but calls hang | wedged instance | kill via `taskkill.exe` and Phase 3a |
|
|
116
|
+
| `Cannot find module ... chrome-devtools-mcp` | npx cache corrupt | `rm -rf ~/.npm/_npx && npm cache clean --force` |
|
|
117
|
+
|
|
118
|
+
## Tuning the tool surface (server flags)
|
|
119
|
+
|
|
120
|
+
Trim tools in `~/.mcporter/mcporter.json` args (then `mcp.$reload`):
|
|
121
|
+
|
|
122
|
+
- `--slim` — radical: 3 tools (navigate, evaluate, screenshot)
|
|
123
|
+
- `--no-category-network` / `--no-category-performance` / `--no-category-emulation`
|
|
124
|
+
- `--screenshotFormat jpeg --screenshotMaxWidth 1280` — smaller screenshots
|
|
125
|
+
- `--experimentalVision` — enables `click_at(x, y)`
|
|
126
|
+
|
|
127
|
+
Confirm what's live: `tools.list({ provider: "mcp" })` or
|
|
128
|
+
`tools.describe({ ref: "mcp.chrome_devtools.<tool>" })` — always current.
|
|
129
|
+
|
|
130
|
+
## Uninstall / disable
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
jq 'del(.mcpServers["chrome-devtools"], .mcpServers["chrome-devtools-proxy"])' \
|
|
134
|
+
~/.mcporter/mcporter.json > /tmp/m.json && mv /tmp/m.json ~/.mcporter/mcporter.json
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Then `tools.call({ ref: "mcp.$reload" })`. Chrome itself and the launcher
|
|
138
|
+
scripts stay (other things may depend on them).
|