@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.
Files changed (57) hide show
  1. package/chrome-devtools/README.md +76 -0
  2. package/chrome-devtools/SKILL.md +277 -0
  3. package/chrome-devtools/references/recipes.md +379 -0
  4. package/chrome-devtools/references/setup.md +138 -0
  5. package/drawio/SKILL.md +395 -0
  6. package/gh-cli/SKILL.md +83 -0
  7. package/grill/SKILL.md +72 -0
  8. package/layout-check/README.md +32 -0
  9. package/layout-check/SKILL.md +416 -0
  10. package/layout-check/scripts/layoutProbe.mjs +539 -0
  11. package/mcpls/SKILL.md +261 -0
  12. package/mcpls/references/configuration.md +131 -0
  13. package/mcpls/references/install.md +13 -0
  14. package/mcporter/SKILL.md +90 -0
  15. package/mindmap/SKILL.md +46 -0
  16. package/mindmap/references/drawio-recipe.md +60 -0
  17. package/mindmap/references/mindmap-design.md +63 -0
  18. package/opensource-contribution/SKILL.md +119 -0
  19. package/package.json +29 -5
  20. package/shell-taste/.shellcheckrc +16 -0
  21. package/shell-taste/SKILL.md +95 -0
  22. package/shell-taste/references/handbook/dialects.md +168 -0
  23. package/shell-taste/references/handbook/dom/01-output-logging.md +245 -0
  24. package/shell-taste/references/handbook/dom/02-errors-exit.md +48 -0
  25. package/shell-taste/references/handbook/dom/03-installation-setup.md +179 -0
  26. package/shell-taste/references/handbook/dom/04-network.md +384 -0
  27. package/shell-taste/references/handbook/dom/05-files-paths.md +74 -0
  28. package/shell-taste/references/handbook/dom/06-checks-validation.md +127 -0
  29. package/shell-taste/references/handbook/dom/07-system-administration.md +103 -0
  30. package/shell-taste/references/handbook/dom/08-privilege-users.md +58 -0
  31. package/shell-taste/references/handbook/dom/09-text-data.md +62 -0
  32. package/shell-taste/references/handbook/dom/10-terminal-ux.md +60 -0
  33. package/shell-taste/references/handbook/dom/11-process-control.md +28 -0
  34. package/shell-taste/references/handbook/dom/12-uncategorized.md +161 -0
  35. package/shell-taste/references/handbook/dom/13-containers.md +13 -0
  36. package/shell-taste/references/handbook/dom/14-agents-ai-tooling.md +13 -0
  37. package/shell-taste/references/handbook/family-index.md +230 -0
  38. package/shell-taste/references/handbook/index.md +41 -0
  39. package/skill-author/SKILL.md +86 -0
  40. package/sobesednik/SKILL.md +98 -0
  41. package/sobesednik/card-template.md +23 -0
  42. package/sobesednik/personas/advocate.md +27 -0
  43. package/sobesednik/personas/analyst.md +29 -0
  44. package/sobesednik/personas/chat.md +42 -0
  45. package/sobesednik/personas/ifs.md +32 -0
  46. package/sobesednik/personas/journal/README.md +6 -0
  47. package/sobesednik/personas/nasreddin.md +29 -0
  48. package/sobesednik/personas/premortem.md +29 -0
  49. package/sobesednik/personas/rogers.md +27 -0
  50. package/sobesednik/personas/socratic.md +29 -0
  51. package/sobesednik/personas/stoic.md +27 -0
  52. package/sobesednik/references/persona-design.md +41 -0
  53. package/zai-mcp/README.md +63 -0
  54. package/zai-mcp/SKILL.md +160 -0
  55. package/zai-mcp/references/recipes.md +273 -0
  56. package/zai-mcp/references/tools.md +266 -0
  57. 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).