Cursor Directory

excel-webview2-mcp

0

MCP server for automating and debugging Excel add-ins running in WebView2 via the Chrome DevTools Protocol

Source

7 skills

debug-optimize-lcp

Guides debugging and optimizing Largest Contentful Paint (LCP) using Excel WebView2 MCP tools. Use this skill whenever the user asks about LCP performance, slow page loads, Core Web Vitals optimization, or wants to understand why their page's main content takes too long to appear. Also use when the user mentions "largest contentful paint", "page load speed", "CWV", or wants to improve how fast their hero image or main content renders.

## What is LCP and why it matters Largest Contentful Paint (LCP) measures how quickly a page's main content becomes visible. It's the time from navigation start until the largest image or text block renders in the viewport. - **Good**: 2.5 seconds or less - **Needs improvement**: 2.5–4.0 seconds - **Poor**: greater than 4.0 seconds LCP is a Core Web Vital that directly affects user experience and search ranking. On 73% of mobile pages, the LCP element is an image. ## LCP Subparts Breakdown Every page's LCP breaks down into four sequential subparts with no gaps or overlaps. Understanding which subpart is the bottleneck is the key to effective optimization. | Subpart | Ideal % of LCP | What it measures | | ----------------------------- | -------------- | ---------------------------------------------- | | **Time to First Byte (TTFB)** | ~40% | Navigation start → first byte of HTML received | | **Resource load delay** | <10% | TTFB → browser starts loading the LCP resource | | **Resource load duration** | ~40% | Time to download the LCP resource | | **Element render delay** | <10% | LCP resource downloaded → LCP element rendered | The "delay" subparts should be as close to zero as possible. If either delay subpart is large relative to the total LCP, that's the first place to optimize. **Common Pitfall**: Optimizing one subpart (like compressing an image to reduce load duration) without checking others. If render delay is the real bottleneck, a smaller image won't help — the saved time just shifts to render delay. ## Debugging Workflow Follow these steps in order. Each step builds on the previous one. ### Step 1: Record a Performance Trace Navigate to the page, then record a trace with reload to capture the full page load including LCP: 1. `navigate_page` to the target URL. 2. `performance_start_trace` with `reload: true` and `autoStop: true`. The trace results will include LCP timing and available insight sets. Note the insight set IDs from the output — you'll need them in the next step. ### Step 2: Analyze LCP Insights Use `performance_analyze_insight` to drill into LCP-specific insights. Look for these insight names in the trace results: - **LCPBreakdown** — Shows the four LCP subparts with timing for each. - **DocumentLatency** — Server response time issues affecting TTFB. - **RenderBlocking** — Resources blocking the LCP element from rendering. - **LCPDiscovery** — Whether the LCP resource was discoverable early. Call `performance_analyze_insight` with the insight set ID and the insight name from the trace results. ### Step 3: Identify the LCP Element Use `evaluate_script` with the **"Identify LCP Element" snippet** found in [references/lcp-snippets.md](references/lcp-snippets.md) to reveal the LCP element's tag, resource URL, and raw timing data. The `url` field tells you what resource to look for in the network waterfall. If `url` is empty, the LCP element is text-based (no resource to load). ### Step 4: Check the Network Waterfall Use `list_network_requests` to see when the LCP resource loaded relative to other resources: - Call `list_network_requests` filtered by `resourceTypes: ["Image", "Font"]` (adjust based on Step 3). - Then use `get_network_request` with the LCP resource's request ID for full details. **Key Checks:** - **Start Time**: Compare against the HTML document and the first resource. If the LCP resource starts much later than the first resource, there's resource load delay to eliminate. - **Duration**: A large resource load duration suggests the file is too big or the server is slow. ### Step 5: Inspect HTML for Common Issues Use `evaluate_script` with the **"Audit Common Issues" snippet** found in [references/lcp-snippets.md](references/lcp-snippets.md) to check for lazy-loaded images in the viewport, missing fetchpriority, and render-blocking scripts. ## Optimization Strategies After identifying the bottleneck subpart, apply these prioritized fixes. ### 1. Eliminate Resource Load Delay (target: <10%) The most common bottleneck. The LCP resource should start loading immediately. - **Root Cause**: LCP image loaded via JS/CSS, `data-src` usage, or `loading="lazy"`. - **Fix**: Use standard `<img>` with `src`. **Never** lazy-load the LCP image. - **Fix**: Add `<link rel="preload" fetchpriority="high">` if the image isn't discoverable in HTML. - **Fix**: Add `fetchpriority="high"` to the LCP `<img>` tag. ### 2. Eliminate Element Render Delay (target: <10%) The element should render immediately after loading. - **Root Cause**: Large stylesheets, synchronous scripts in `<head>`, or main thread blocking. - **Fix**: Inline critical CSS, defer non-critical CSS/JS. - **Fix**: Break up long tasks blocking the main thread. - **Fix**: Use Server-Side Rendering (SSR) so the element exists in initial HTML. ### 3. Reduce Resource Load Duration (target: ~40%) Make the resource smaller or faster to deliver. - **Fix**: Use modern formats (WebP, AVIF) and responsive images (`srcset`). - **Fix**: Serve from a CDN. - **Fix**: Set `Cache-Control` headers. - **Fix**: Use `font-display: swap` if LCP is text blocked by a web font. ### 4. Reduce TTFB (target: ~40%) The HTML document itself takes too long to arrive. - **Fix**: Minimize redirects and optimize server response time. - **Fix**: Cache HTML at the edge (CDN). - **Fix**: Ensure pages are eligible for back/forward cache (bfcache). ## Verifying Fixes & Emulation - **Verification**: Re-run the trace (`performance_start_trace` with `reload: true`) and compare the new subpart breakdown. The bottleneck should shrink. - **Emulation**: Lab measurements differ from real-world experience. Use `emulate` to test under constraints: - `emulate` with `networkConditions: "Fast 3G"` and `cpuThrottlingRate: 4`. - This surfaces issues visible only on slower connections/devices.

excel-addin-debugging

Debug and automate Excel add-ins running in WebView2 with Office.js awareness — active range inspection, Office context detection, dialog API handling, and requirement-set probing. Use when the user mentions Office.js, Excel.run, taskpane, ribbon command, named ranges, or an add-in dialog.

## When to use Trigger this skill when any of the following apply: - The user mentions **Office.js**, `Office.context`, `Excel.run`, or requirement sets (`ExcelApi`, `DialogApi`, etc.). - The user is debugging a **taskpane**, **ribbon command**, or **add-in dialog** running inside Excel's WebView2. - The user asks about **the currently selected range**, **named ranges**, or **active worksheet state**. - The target at `http://localhost:9222` is an Excel add-in rather than a generic web page. For generic DOM/CDP interaction against the WebView2 target (snapshot, click, screenshot), defer to the `excel-webview2` skill. ## Readiness check (always run first) Call [`excel_context_info`](../../src/tools/excel.ts) **before** any Office.js-aware tool. If it returns `hasOfficeGlobal: false`, stop and report the target is not an Excel add-in — subsequent Office.js tools will fail. The tool returns: - `hasOfficeGlobal`, `hasExcelGlobal` — presence of the runtime globals. - `hostInfo` — `{ host, platform, version }` from `Office.context.diagnostics`. - `contentLanguage`, `displayLanguage` — locale info. - `requirementSets` — which `ExcelApi` / `DialogApi` / `SharedRuntime` / `ExcelApiOnline` / `RibbonApi` / `IdentityAPI` versions the host supports. Branch behavior on `requirementSets`. For example, only call `getItemOrNullObject` patterns if `ExcelApi 1.4` is reported. ## Common workflows ### Inspect the current selection 1. `excel_context_info` — confirm `hasExcelGlobal: true`. 2. `excel_active_range` — returns `{ address, values, rowCount, columnCount, formulas?, numberFormat? }`. 3. For ranges over 1000 cells, the tool truncates `values` and notes the truncation in the response. Narrow the selection or read a named sub-range instead. ### Read a named range Use `evaluate_script` with the pattern from [references/office-js-cheatsheet.md](references/office-js-cheatsheet.md) §3. Always guard with `typeof Excel === 'undefined'` and wrap in `Excel.run`. ### Capture taskpane state after a ribbon click 1. Ask the user to invoke the ribbon command. 2. `list_pages` — a new CDP target may have appeared (shared-runtime commands reuse the taskpane target; UI-less commands may not expose one). 3. `take_snapshot` on the taskpane target to see post-command DOM. 4. `list_console_messages` to surface any Office.js errors from the command handler. ### Dialog API flow `Office.context.ui.displayDialogAsync` opens a **new debuggable CDP target**. After the add-in invokes it: 1. `list_pages` again — the dialog appears as a separate target. 2. `select_page` to switch into the dialog. 3. Interact via `take_snapshot` / `click` / `evaluate_script` as usual. 4. The dialog posts messages back via `Office.context.ui.messageParent` (see cheatsheet §7); the parent handles them through `Office.EventType.DialogMessageReceived`. The dialog's `startAddress` must be HTTPS and same-origin with the taskpane. On Excel Online the dialog is an iframe modal — it is not a separate CDP target there, but this skill targets Excel desktop WebView2. ### Requirement-set branching ```js // Inside evaluate_script if (Office.context.requirements.isSetSupported('ExcelApi', '1.12')) { // Use Excel API 1.12 features } else { // Fall back or report unsupported } ``` Prefer probing over version-string comparison against `diagnostics.version`. ## Anti-patterns - **Never invent Office.js APIs.** Only call members listed in [references/office-js-cheatsheet.md](references/office-js-cheatsheet.md). That file is sourced from [docs/plans/office-js-api-reference.md](../../docs/plans/office-js-api-reference.md) — if you need something not in the cheatsheet, add it there first (with a source URL) rather than guessing. - **Never `load('*')`.** Excel throws `PropertyNotLoaded`. Enumerate property names explicitly. - **Never read loaded properties without `await ctx.sync()`** inside `Excel.run`. - **Never assume `Office` or `Excel` globals exist** — always guard with `typeof`. - **Do not duplicate generic CDP debugging advice** already in the `excel-webview2` skill. Cross-link instead. ## Troubleshooting **`hasOfficeGlobal: false`** — the attached target is not an add-in page. It may be the taskpane's sign-in iframe, a dialog, or the wrong tab. Run `list_pages` and `select_page` to switch. **`Excel.run` throws `PropertyNotLoaded`** — a property was read without first being loaded. Add it to the `range.load([...])` call and re-sync. **Dialog never appears in `list_pages`** — the add-in may be running on Excel Online (where dialogs are iframes, not CDP targets), or the dialog's HTTPS/same-origin check failed. Check `list_console_messages` for the Office.js error. **Requirement set reports `false` unexpectedly** — confirm Excel version via `excel_context_info.hostInfo.version`. `ExcelApi` versions are tied to specific Microsoft 365 builds.

excel-webview2-cli

Use this skill to write shell scripts or run shell commands to automate tasks in the browser or otherwise use Excel WebView2 via CLI.

The `excel-webview2-mcp` CLI lets you interact with the browser from your terminal. ## Setup _Note: If this is your very first time using the CLI, see [references/installation.md](references/installation.md) for setup. Installation is a one-time prerequisite and is **not** part of the regular AI workflow._ ## AI Workflow 1. **Execute**: Run tools directly (e.g., `excel-webview2 list_pages`). The background server starts implicitly; **do not** run `start`/`status`/`stop` before each use. 2. **Inspect**: Use `take_snapshot` to get an element `<uid>`. 3. **Act**: Use `click`, `fill`, etc. State persists across commands. Snapshot example: ``` uid=1_0 RootWebArea "Example Domain" url="https://example.com/" uid=1_1 heading "Example Domain" level="1" ``` ## Command Usage ```sh excel-webview2 <tool> [arguments] [flags] ``` Use `--help` on any command. Output defaults to Markdown, use `--output-format=json` for JSON. ## Input Automation (<uid> from snapshot) ```bash excel-webview2 take_snapshot --help # Help message for commands, works for any command. excel-webview2 take_snapshot # Take a text snapshot of the page to get UIDs for elements excel-webview2 click "id" # Clicks on the provided element excel-webview2 click "id" --dblClick true --includeSnapshot true # Double clicks and returns a snapshot excel-webview2 drag "src" "dst" # Drag an element onto another element excel-webview2 drag "src" "dst" --includeSnapshot true # Drag an element and return a snapshot excel-webview2 fill "id" "text" # Type text into an input or select an option excel-webview2 fill "id" "text" --includeSnapshot true # Fill an element and return a snapshot excel-webview2 handle_dialog accept # Handle a browser dialog excel-webview2 handle_dialog dismiss --promptText "hi" # Dismiss a dialog with prompt text excel-webview2 hover "id" # Hover over the provided element excel-webview2 hover "id" --includeSnapshot true # Hover over an element and return a snapshot excel-webview2 press_key "Enter" # Press a key or key combination excel-webview2 press_key "Control+A" --includeSnapshot true # Press a key and return a snapshot excel-webview2 type_text "hello" # Type text using keyboard into a focused input excel-webview2 type_text "hello" --submitKey "Enter" # Type text and press a submit key excel-webview2 upload_file "id" "file.txt" # Upload a file through a provided element excel-webview2 upload_file "id" "file.txt" --includeSnapshot true # Upload a file and return a snapshot ``` ## Navigation ```bash excel-webview2 close_page 1 # Closes the page by its index excel-webview2 list_pages # Get a list of pages open in the browser excel-webview2 navigate_page --url "https://example.com" # Navigates the currently selected page to a URL excel-webview2 navigate_page --type "reload" --ignoreCache true # Reload page ignoring cache excel-webview2 navigate_page --url "https://example.com" --timeout 5000 # Navigate with a timeout excel-webview2 navigate_page --handleBeforeUnload "accept" # Handle before unload dialog excel-webview2 navigate_page --type "back" --initScript "foo()" # Navigate back and run an init script excel-webview2 new_page "https://example.com" # Creates a new page excel-webview2 new_page "https://example.com" --background true --timeout 5000 # Create new page in background excel-webview2 new_page "https://example.com" --isolatedContext "ctx" # Create new page with isolated context excel-webview2 select_page 1 # Select a page as a context for future tool calls excel-webview2 select_page 1 --bringToFront true # Select a page and bring it to front ``` ## Emulation ```bash excel-webview2 emulate --networkConditions "Offline" # Emulate network conditions excel-webview2 emulate --cpuThrottlingRate 4 --geolocation "0x0" # Emulate CPU throttling and geolocation excel-webview2 emulate --colorScheme "dark" --viewport "1920x1080" # Emulate color scheme and viewport excel-webview2 emulate --userAgent "Mozilla/5.0..." # Emulate user agent excel-webview2 resize_page 1920 1080 # Resizes the selected page's window ``` ## Performance ```bash excel-webview2 performance_analyze_insight "1" "LCPBreakdown" # Get more details on a specific Performance Insight excel-webview2 performance_start_trace true false # Starts a performance trace recording excel-webview2 performance_start_trace true true --filePath t.gz # Start trace and save to a file excel-webview2 performance_stop_trace # Stops the active performance trace excel-webview2 performance_stop_trace --filePath "t.json" # Stop trace and save to a file excel-webview2 take_memory_snapshot "./snap.heapsnapshot" # Capture a memory heapsnapshot ``` ## Network ```bash excel-webview2 get_network_request # Get the currently selected network request excel-webview2 get_network_request --reqid 1 --requestFilePath req.md # Get request by id and save to file excel-webview2 get_network_request --responseFilePath res.md # Save response body to file excel-webview2 list_network_requests # List all network requests excel-webview2 list_network_requests --pageSize 50 --pageIdx 0 # List network requests with pagination excel-webview2 list_network_requests --resourceTypes Fetch # Filter requests by resource type excel-webview2 list_network_requests --includePreservedRequests true # Include preserved requests ``` ## Debugging & Inspection ```bash excel-webview2 evaluate_script "() => document.title" # Evaluate a JavaScript function on the page excel-webview2 evaluate_script "(a) => a.innerText" --args 1_4 # Evaluate JS with UID arguments excel-webview2 get_console_message 1 # Gets a console message by its ID excel-webview2 lighthouse_audit --mode "navigation" # Run Lighthouse audit for navigation excel-webview2 lighthouse_audit --mode "snapshot" --device "mobile" # Run Lighthouse audit for a snapshot on mobile excel-webview2 lighthouse_audit --outputDirPath ./out # Run Lighthouse audit and save reports excel-webview2 list_console_messages # List all console messages excel-webview2 list_console_messages --pageSize 20 --pageIdx 1 # List console messages with pagination excel-webview2 list_console_messages --types error --types info # Filter console messages by type excel-webview2 list_console_messages --includePreservedMessages true # Include preserved messages excel-webview2 take_screenshot # Take a screenshot of the page viewport excel-webview2 take_screenshot --fullPage true --format "jpeg" --quality 80 # Take a full page screenshot as JPEG with quality excel-webview2 take_screenshot --uid "id" --filePath "s.png" # Take a screenshot of an element excel-webview2 take_snapshot # Take a text snapshot of the page from the a11y tree excel-webview2 take_snapshot --verbose true --filePath "s.txt" # Take a verbose snapshot and save to file ``` ## Service Management ```bash excel-webview2 start # Start or restart excel-webview2-mcp excel-webview2 status # Checks if excel-webview2-mcp is running excel-webview2 stop # Stop excel-webview2-mcp if any ```

excel-webview2

Uses Excel WebView2 via MCP to debug, inspect, and automate an Excel add-in's embedded WebView2 browser. Use when inspecting or interacting with a running Excel add-in's task pane or web content. Requires the add-in to already be running with remote debugging enabled on port 9222.

## Prerequisites This skill connects to an **already-running** Excel add-in WebView2 instance. The MCP server does **not** launch Chrome or create a browser — it attaches to the existing WebView2 remote debugging endpoint at `http://localhost:9222`. Before using any tools, the user must have their add-in running locally with the WebView2 debug port enabled. Setup instructions live in one place: [README.md#launching-excel-with-the-debug-port](../../README.md#launching-excel-with-the-debug-port) If tools fail to connect, verify the debuggable target is available: `curl http://localhost:9222/json/version` ## Launching Excel from the agent When the user is working inside an Excel add-in repository, this server can launch Excel directly instead of asking them to run an `npm run start:cdp`-style script in another terminal. Three lifecycle tools cover the flow: - `excel_detect_addin` — inspects `cwd` (or a passed-in path) and reports whether it looks like an add-in repo. Detection signals: a `manifest.xml` (classic) or `manifest.json` (unified) at/above the working directory, plus signals from `package.json` (`office-addin-debugging` devDep, `--remote-debugging-port` in any script). Returns the detected `manifestPath`, `manifestKind`, `packageManager`, and any existing CDP-enabled script. - `excel_launch_addin` — spawns `office-addin-debugging start <manifest>` with `WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=<port>` injected into the child process env. Polls the CDP endpoint until ready, then (by default, `autoConnect: true`) calls the connect path so subsequent tools work without an extra step. **Idempotent per manifest** — a second call returns the existing tracked launch instead of spawning a duplicate. - `excel_stop_addin` — runs `office-addin-debugging stop <manifest>` against the tracked launch (or all tracked launches when no `manifestPath` is given). Falls back to killing the child if stop does not exit cleanly. ### Env-var contract The launcher only sets `WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS` in the spawned child's environment — it does not mutate the user's shell. If that variable is **already** set in `process.env` and contains `--remote-debugging-port`, the launch refuses with `port-already-configured` rather than silently overwriting. Tell the user to unset it (or just run the tool without the manual env var). ### When to suggest the launch tools Suggest `excel_launch_addin` when: - Connection tools fail because no CDP endpoint is up, AND - `excel_detect_addin` confirms the working directory is an Excel add-in repo. Do NOT suggest the launch tools on macOS/Linux — WebView2 is Windows-only and the launcher refuses with a platform error. The user's existing `start:cdp` npm script remains a valid manual alternative; the launch tools simply move that step into the agent loop. If the user prefers running the script themselves, just connect to the resulting endpoint. ### Auto-launch at server startup The `--auto-launch` CLI flag runs `excel_launch_addin` once during MCP server startup if the working directory is detected as an add-in repo. `--launch-port` (default 9222) and `--launch-timeout` (default 60000ms) control the launch. ## Core Concepts **Connection**: The MCP server attaches to the WebView2 instance via the Chrome DevTools Protocol (CDP) at `http://localhost:9222`. No browser is launched. **Page selection**: WebView2 may expose multiple debuggable targets (task pane, dialog, etc.). Use `list_pages` to see available targets, then `select_page` to switch context. **Element interaction**: Use `take_snapshot` to get page structure with element `uid`s. Each element has a unique `uid` for interaction. If an element isn't found, take a fresh snapshot — the element may have been removed or the page changed. ## Workflow Patterns ### Starting a session 1. `list_pages` — confirm the WebView2 target is visible and select the right one 2. `take_snapshot` — understand the current page structure before interacting ### Before interacting with a page 1. Snapshot: `take_snapshot` to understand page structure 2. Interact: Use element `uid`s from snapshot for `click`, `fill`, etc. 3. Wait: `wait_for` if an action triggers async UI updates **Note**: The MCP server exposes no navigation or tab-creation tools — the add-in host owns its URL and window. Attach to an already-running add-in and interact with the pages it exposes. **For Office.js-aware debugging** (inspecting the selected range, reading `Office.context`, handling dialogs, probing requirement sets), see the [`excel-addin-debugging`](../excel-addin-debugging/SKILL.md) skill. ### Verifying workbook state after add-in code changes The `excel_*` read tools run inside the add-in page via `Excel.run` and return structured JSON. They are all read-only (no mutation) and cap grid payloads at 1000 cells (`truncated: true` when exceeded). Use them to confirm that a code change produced the expected workbook state rather than only relying on UI screenshots. - **Workbook surface**: `excel_context_info`, `excel_workbook_info`, `excel_list_worksheets`, `excel_worksheet_info`, `excel_calculation_state`, `excel_list_named_items`, `excel_custom_xml_parts`, `excel_settings_get`. - **Ranges**: `excel_active_range` (current selection), `excel_read_range` (by A1 address or `Sheet!A1:C10`), `excel_used_range`, `excel_range_formulas` (A1 + R1C1 side-by-side with values), `excel_range_properties` (valueTypes, hidden flags, optional font/fill/alignment), `excel_range_special_cells` (constants/formulas/blanks/visible), `excel_find_in_range`. - **Tables**: `excel_list_tables`, `excel_table_info`, `excel_table_rows`, `excel_table_filters`. - **PivotTables**: `excel_list_pivot_tables`, `excel_pivot_table_info`, `excel_pivot_table_values`. - **Charts & shapes**: `excel_list_charts`, `excel_chart_info`, `excel_chart_image` (base64 PNG), `excel_list_shapes`. - **Validation & formatting rules**: `excel_list_conditional_formats`, `excel_list_data_validations`, `excel_list_comments`. Range-targeting tools accept either `{sheet, address}` or a fully qualified `'Sheet1!A1:C10'` address; omit the address to operate on the active selection. When a tool returns `{error: "Excel API not available on this target"}`, the selected page is not an Excel add-in context — re-run `list_pages` / `select_page`. ### Efficient data retrieval - Use `filePath` parameter for large outputs (screenshots, snapshots, traces) - Use pagination (`pageIdx`, `pageSize`) and filtering (`types`) to minimize data - Set `includeSnapshot: false` on input actions unless you need updated page state ### Tool selection - **Automation/interaction**: `take_snapshot` (text-based, faster, better for automation) - **Visual inspection**: `take_screenshot` (when user needs to see visual state) - **Additional details**: `evaluate_script` for data not in accessibility tree ### Parallel execution You can send multiple tool calls in parallel, but maintain correct order: snapshot → interact → wait (if needed) → snapshot again. ## Troubleshooting **Cannot connect / no pages listed**: The add-in is not running, or remote debugging is not enabled on port 9222. Ask the user to verify their add-in is started and the debug port is configured. **Element not found**: Take a fresh snapshot — the add-in may have re-rendered the page. **Unexpected navigation**: The add-in controls routing internally. If the taskpane changes URL on its own, re-run `list_pages` and `select_page` to re-attach to the new target. For DevTools protocol reference: https://developer.chrome.com/docs/devtools

memory-leak-debugging

Diagnoses and resolves memory leaks in JavaScript/Node.js applications. Use when a user reports high memory usage, OOM errors, or wants to analyze heapsnapshots or run memory leak detection tools like memlab.

# Memory Leak Debugging This skill provides expert guidance and workflows for finding, diagnosing, and fixing memory leaks in JavaScript and Node.js applications. ## Core Principles - **Prefer `memlab`:** Do NOT attempt to read raw `.heapsnapshot` files directly, as they are extremely large and will consume too many tokens. Always recommend and use `memlab` to process snapshots and identify leak traces. - **Isolate the Leak:** Determine if the leak is in the browser (client-side) or Node.js (server-side). - **Common Culprits:** Look for detached DOM nodes, unhandled closures, global variables, event listeners not being removed, and caches growing unbounded. _Note: Detached DOM nodes are sometimes intentional caches; always ask the user before nulling them._ ## Workflows ### 1. Capturing Snapshots When investigating a frontend web application memory leak, utilize the `excel-webview2-mcp` tools to interact with the application and take snapshots. - Use tools like `click`, `navigate_page`, `fill`, etc., to manipulate the page into the desired state. - Revert the page back to the original state after interactions to see if memory is released. - Repeat the same user interactions 10 times to amplify the leak. - Use `take_memory_snapshot` to save `.heapsnapshot` files to disk at baseline, target (after actions), and final (after reverting actions) states. ### 2. Using Memlab to Find Leaks (Recommended) Once you have generated `.heapsnapshot` files using `take_memory_snapshot`, use `memlab` to automatically find memory leaks. - Read [references/memlab.md](references/memlab.md) for how to use `memlab` to analyze the generated heapsnapshots. - Do **not** read raw `.heapsnapshot` files using `read_file` or `cat`. ### 3. Identifying Common Leaks When you have found a leak trace (e.g., via `memlab` output), you must identify the root cause in the code. - Read [references/common-leaks.md](references/common-leaks.md) for examples of common memory leaks and how to fix them. ### 4. Fallback: Comparing Snapshots Manually If `memlab` is not available, you MUST use the fallback script in the references directory to compare two `.heapsnapshot` files and identify the top growing objects and common leak types. Run the script using Node.js: ```bash node skills/memory-leak-debugging/references/compare_snapshots.js <baseline.heapsnapshot> <target.heapsnapshot> ``` The script will analyze and output the top growing objects by size and highlight the 3 most common types of memory leaks (e.g., Detached DOM nodes, closures, Contexts) if they are present.

troubleshooting

Uses Excel WebView2 MCP and documentation to troubleshoot connection and target issues. Trigger this skill when list_pages, new_page, or navigate_page fail, or when the server initialization fails.

## Troubleshooting Wizard You are acting as a troubleshooting wizard to help the user configure and fix their Excel WebView2 MCP server setup. When this skill is triggered (e.g., because `list_pages`, `new_page`, or `navigate_page` failed, or the server wouldn't start), follow this step-by-step diagnostic process: ### Step 1: Find and Read Configuration Your first action should be to locate and read the MCP configuration file. Search for the following files in the user's workspace: `.mcp.json`, `gemini-extension.json`, `.claude/settings.json`, `.vscode/launch.json`, or `.gemini/settings.json`. If you find a configuration file, read and interpret it to identify potential issues such as: - Incorrect arguments or flags. - Missing environment variables. - Usage of `--autoConnect` in incompatible environments. If you cannot find any of these files, only then should you ask the user to provide their configuration file content. ### Step 2: Triage Common Connection Errors Before reading documentation or suggesting configuration changes, check if the error message matches one of the following common patterns. #### Error: `Could not find DevToolsActivePort` This error is highly specific to the `--autoConnect` feature. It means the MCP server cannot find the file created by a running, debuggable Chrome instance. This is not a generic connection failure. Your primary goal is to guide the user to ensure Chrome is running and properly configured. Do not immediately suggest switching to `--browserUrl`. Follow this exact sequence: 1. **Ask the user to confirm that the correct Chrome version** (e.g., "Chrome Canary" if the error mentions it) is currently running. 2. **If the user confirms it is running, instruct them to enable remote debugging.** Be very specific about the URL and the action: "Please open a new tab in Chrome, navigate to `chrome://inspect/#remote-debugging`, and make sure the 'Enable remote debugging' checkbox is checked." 3. **Once the user confirms both steps, your only next action should be to call the `list_pages` tool.** This is the simplest and safest way to verify if the connection is now successful. Do not retry the original, more complex command yet. 4. **If `list_pages` succeeds, the problem is resolved.** If it still fails with the same error, then you can proceed to the more advanced steps like suggesting `--browserUrl` or checking for sandboxing issues. #### Symptom: Server starts but creates a new empty profile If the server starts successfully but `list_pages` returns an empty list or creates a new profile instead of connecting to the existing Chrome instance, check for typos in the arguments. - **Check for flag typos:** For example, `--autoBronnect` instead of `--autoConnect`. - **Verify the configuration:** Ensure the arguments match the expected flags exactly. #### Symptom: Missing Tools / Only 9 tools available If the server starts successfully but only a limited subset of tools (like `list_pages`, `get_console_message`, `lighthouse_audit`, `take_memory_snapshot`) are available, this is likely because the MCP client is enforcing a **read-only mode**. All tools in `excel-webview2-mcp` are annotated with `readOnlyHint: true` (for safe, non-modifying tools) or `readOnlyHint: false` (for tools that modify browser state, like `emulate`, `click`, `navigate_page`). To access the full suite of tools, the user must disable read-only mode in their MCP client (e.g., by exiting "Plan Mode" in Gemini CLI or adjusting their client's tool safety settings). #### Other Common Errors Identify other error messages from the failed tool call or the MCP initialization logs: - `Target closed` - "Tool not found" (check if they are using `--slim` which only enables navigation and screenshot tools). - `ProtocolError: Network.enable timed out` or `The socket connection was closed unexpectedly` - `Error [ERR_MODULE_NOT_FOUND]: Cannot find module` - Any sandboxing or host validation errors. ### Step 3: Read Known Issues Read the contents of https://github.com/dsbissett/excel-webview2-mcp/blob/main/docs/troubleshooting.md to map the error to a known issue. Pay close attention to: - Sandboxing restrictions (macOS Seatbelt, Linux containers). - WSL requirements. - `--autoConnect` handshakes, timeouts, and requirements (requires **running** Chrome 144+). ### Step 4: Formulate a Configuration Based on the exact error and the user's environment (OS, MCP client), formulate the correct MCP configuration snippet. Check if they need to: - Pass `--browser-url=http://127.0.0.1:9222` instead of `--autoConnect` (e.g. if they are in a sandboxed environment like Claude Desktop). - Enable remote debugging in Chrome (`chrome://inspect/#remote-debugging`) and accept the connection prompt. **Ask the user to verify this is enabled if using `--autoConnect`.** - Add `--logFile <absolute_path_to_log_file>` to capture debug logs for analysis. - Increase `startup_timeout_ms` (e.g. to 20000) if using Codex on Windows. _If you are unsure of the user's configuration, ask the user to provide their current MCP server JSON configuration._ ### Step 5: Run Diagnostic Commands If the issue is still unclear, run diagnostic commands to test the server directly: - Run `npx @dsbissett/excel-webview2-mcp@latest --help` to verify the installation and Node.js environment. - If you need more information, run `DEBUG=* npx @dsbissett/excel-webview2-mcp@latest --logFile=/tmp/cdm-test.log` to capture verbose logs. Analyze the output for errors. ### Step 6: Check GitHub for Existing Issues If https://github.com/dsbissett/excel-webview2-mcp/blob/main/docs/troubleshooting.md does not cover the specific error, check if the `gh` (GitHub CLI) tool is available in the environment. If so, search the GitHub repository for similar issues: `gh issue list --repo dsbissett/excel-webview2-mcp --search "<error snippet>" --state all` Alternatively, you can recommend that the user checks https://github.com/dsbissett/excel-webview2-mcp/issues and https://github.com/dsbissett/excel-webview2-mcp/discussions for help.

a11y-debugging

Uses Excel WebView2 MCP for accessibility (a11y) debugging and auditing based on web.dev guidelines. Use when testing semantic HTML, ARIA labels, focus states, keyboard navigation, tap targets, and color contrast.

## Core Concepts **Accessibility Tree vs DOM**: Visually hiding an element (e.g., `CSS opacity: 0`) behaves differently for screen readers than `display: none` or `aria-hidden="true"`. The `take_snapshot` tool returns the accessibility tree of the page, which represents what assistive technologies "see", making it the most reliable source of truth for semantic structure. **Reading web.dev documentation**: If you need to research specific accessibility guidelines (like `https://web.dev/articles/accessible-tap-targets`), you can append `.md.txt` to the URL (e.g., `https://web.dev/articles/accessible-tap-targets.md.txt`) to fetch the clean, raw markdown version. This is much easier to read! ## Workflow Patterns ### 1. Automated Audit (Lighthouse) Start by running a Lighthouse accessibility audit to get a comprehensive baseline. This tool provides a high-level score and lists specific failing elements with remediation advice. 1. Run the audit: - Set `mode` to `"navigation"` to refresh the page and capture load issues. - Set `outputDirPath` (e.g., `/tmp/lh-report`) to save the full JSON report. 2. **Analyze the Summary**: - Check `scores` (0-1 scale). A score < 1 indicates violations. - Review `audits.failed` count. 3. **Review the Report (CRITICAL)**: - **Parsing**: Do not read the entire file line-by-line. Use a CLI tool like `jq` or a Node.js one-liner to filter for failures: ```bash # Extract failing audits with their details node -e "const r=require('./report.json'); Object.values(r.audits).filter(a=>a.score!==null && a.score<1).forEach(a=>console.log(JSON.stringify({id:a.id, title:a.title, items:a.details?.items})))" ``` - This efficiently extracts the `selector` and `snippet` of failing elements without loading the full report into context. ### 2. Browser Issues & Audits Chrome automatically checks for common accessibility problems. Use `list_console_messages` to check for these native audits: - `types`: `["issue"]` - `includePreservedMessages`: `true` (to catch issues that occurred during page load) This often reveals missing labels, invalid ARIA attributes, and other critical errors without manual investigation. ### 3. Semantics & Structure The accessibility tree exposes the heading hierarchy and semantic landmarks. 1. Navigate to the page. 2. Use `take_snapshot` to capture the accessibility tree. 3. **Check Heading Levels**: Ensure heading levels (`h1`, `h2`, `h3`, etc.) are logical and do not skip levels. The snapshot will include heading roles. 4. **Content Reordering**: Verify that the DOM order (which drives the accessibility tree) matches the visual reading order. Use `take_screenshot` to inspect the visual layout and compare it against the snapshot structure to catch CSS floats or absolute positioning that jumbles the logical flow. ### 4. Labels, Forms & Text Alternatives 1. Locate buttons, inputs, and images in the `take_snapshot` output. 2. Ensure interactive elements have an accessible name (e.g., a button should not just say `""` if it only contains an icon). 3. **Orphaned Inputs**: Verify that all form inputs have associated labels. Use `evaluate_script` with the **"Find Orphaned Form Inputs" snippet** found in [references/a11y-snippets.md](references/a11y-snippets.md). 4. Check images for `alt` text. ### 5. Focus & Keyboard Navigation Testing "keyboard traps" and proper focus management without visual feedback relies on tracking the focused element. 1. Use the `press_key` tool with `"Tab"` or `"Shift+Tab"` to move focus. 2. Use `take_snapshot` to capture the updated accessibility tree. 3. Locate the element marked as focused in the snapshot to verify focus moved to the expected interactive element. 4. If a modal opens, focus must move into the modal and "trap" within it until closed. ### 6. Tap Targets and Visuals According to web.dev, tap targets should be at least 48x48 pixels with sufficient spacing. Since the accessibility tree doesn't show sizes, use `evaluate_script` with the **"Measure Tap Target Size" snippet** found in [references/a11y-snippets.md](references/a11y-snippets.md). _Pass the element's `uid` from the snapshot as an argument to `evaluate_script`._ ### 7. Color Contrast To verify color contrast ratios, start by checking for native accessibility issues: 1. Call `list_console_messages` with `types: ["issue"]`. 2. Look for "Low Contrast" issues in the output. If native audits do not report issues (which may happen in some headless environments) or if you need to check a specific element manually, use `evaluate_script` with the **"Check Color Contrast" snippet** found in [references/a11y-snippets.md](references/a11y-snippets.md). ### 8. Global Page Checks Verify document-level accessibility settings often missed in component testing using the **"Global Page Checks" snippet** found in [references/a11y-snippets.md](references/a11y-snippets.md). ## Troubleshooting If standard a11y queries fail or the `evaluate_script` snippets return unexpected results: - **Visual Inspection**: If automated scripts cannot determine contrast (e.g., text over gradient images or complex backgrounds), use `take_screenshot` to capture the element. While models cannot measure exact contrast ratios from images, they can visually assess legibility and identify obvious issues.