io.github.waterfallbridge/mcp

Validate that a source file is in the FLAT, one-dimensional 'tidy data' layout WaterfallBridge requires (see https://www.waterfallbridge.com/data-preparation). Detects merged cells, crosstab/pivot layouts, cross-row or cross-sheet / non-arithmetic formulas, title rows above the table, mixed-type columns and stray summary rows. CALL THIS FIRST — right after the worksheet is chosen and BEFORE inspect_local_file / suggest_bridge_schema / prepare_bridge_xlsx or any Data-Type work. When it returns blocking issues (uiHint.requiresConfirmation=true) the data is NOT ready: the structural problems require the USER to reshape the data (you must NOT guess an unpivot or delete rows yourself). How to surface the issues depends on your environment: the WaterfallBridge Web AI Panel shows a fix-it card (the user's confirmation arrives as the next user message); in any other MCP host (Cursor / Codex / Claude Desktop) there is NO panel — list each issue's howToFix to the user in chat, then call this tool again after they edit & re-save the file. Either way write a one-sentence summary and STOP this turn.

Close the controlled browser and end the automation session. Persisted login state is retained for the next open_app call.

Delete a file (NOT a directory) inside an allowed root. The AI should confirm with the user before calling this.

Dismiss any currently visible dialog (error panel, progress complete, or confirmation prompt).

Open the AppHeader 'Report' dialog and download the Bridge analysis report as a PDF. Requires a successful Bridge run first.

Export the current workbook or Bridge analysis result as an Excel file. Returns the absolute path the file was written to.

Delete a persisted login session. The next open_app call for this (url, email) pair will return needsLogin: true.

Inspect the currently open dialog / overlay (error, progress, confirm, subscription, upgrade, expiry, welcome, trial-ended, notifications, export-report). Returns { kind: 'none' } when nothing is open. Useful BEFORE calling dismiss_dialog to know what the user is being asked.

Get the waterfall chart data from the most recent analysis: labels, values, total positions, and number format.

Read the Contribution Analysis table from the Bridge sheet (column E and right). Returns headers, product names, and a 2-D values matrix. Returns null if Bridge has not been built yet. Use this (with get_chart_data + get_insights) to write a DETAILED final analysis: call out the biggest positive/negative contributors BY NAME with their values, plus Added/Removed Data rows — don't just restate the headline.

Get a compact JSON snapshot of a Bridge Data sheet. Sheet layout: column A is the Bridge label column (A1='Data Type', A2='Header', A3='Data', A4+ empty); user data lives in columns B onwards (Row 1 Data Types, Row 2 Field Names, Row 3+ values). Use this before deciding what to edit. Column letters/indices returned by this tool are SHEET coordinates: the first user column is 'B' (index 1), never 'A' (index 0).

Get available dimension fields and their current Baseline / Comparison filter selections. Useful before running a filtered analysis.

Get the auto-generated Key Findings (level 0/1/2 insights) for the most recent Bridge run. Each insight has tone (positive/negative/neutral) and inline emphasis hints. Use this — together with get_chart_data and get_contribution_table — as raw material for a thorough, number-cited final analysis (not just a one-line summary).

Get a snapshot of the user's notifications inbox: items (id, title, message, url, type, isRead), unreadCount, readCount.

Get the result of the last Bridge analysis: success status, errors, and the full waterfall chart payload.

List all visible & hidden sheet names in the current workbook. Useful before reading or editing a particular sheet.

Preview the first rows of a worksheet straight from the SOURCE FILE on disk (NOT the loaded workbook — use get_data_sheet_preview for that). Use it to compare on-disk source data against what is currently loaded in the app (e.g. to verify a user's manual edit was saved, or to see the raw layout before preparing it). Returns rows verbatim as text arrays plus a content signature.

Get the current status of the WaterfallBridge app: login state, subscription, bridge progress, errors, current file.

Get the user's subscription state: status (active/trialing/expired/…), planType (free/online/complete), accessExpiresAt, isDemo. Use this before suggesting an upgrade.

Authorize the Agent to access an additional directory. This is the user's explicit consent — call only after the user has agreed in chat to allow access to the path (or when the user has typed the command directly). Cannot grant access to system directories (Windows / Program Files / other apps' AppData).

Peek at the structure of a local data file: detect format, list sheet names (for .xlsx), extract headers, infer column types, and return the first few rows. Use this before deciding how to map data into WaterfallBridge format. GATE: on a multi-sheet workbook called WITHOUT a `sheet`, this returns { success:false, blocked:true, sheets:[…] } — ask the user which worksheet to use, then re-call with that `sheet` name (do NOT guess the tab).

List every directory the AI can currently read/write, including the static WB_FS_ALLOWED_ROOTS white-list, any user-granted paths from previous sessions (persistent), and any granted just for this session.

List files in a directory. Without a directory argument, returns the set of folders the AI is allowed to browse on this machine.

List all persisted login sessions known to the Agent (origin + email + last update). Useful when deciding which session open_app should use.

Perform a one-time interactive login and persist the resulting session so future open_app calls do not need credentials. The password is used exactly once and never written to disk.

Clear the current workbook and create a fresh Bridge template with a blank Data sheet. Layout: column A = label column (A1='Data Type', A2='Header', A3='Data', A4+ empty); columns B onwards are the user data area (Row 1 = Data Type dropdown, Row 2 = Field Name, Row 3+ = values). Equivalent to clicking 'New Template' in the Analysis Panel. Disabled in Demo Mode.

Open the WaterfallBridge web app in a controlled Chromium instance. Restores a persisted login session when available; otherwise opens a visible sign-in window and blocks until the user signs in by hand. The password never leaves the browser — neither the AI nor the Agent process ever sees it. After a successful manual sign-in, the resulting session is persisted so subsequent open_app calls skip authentication. RESULT SHAPES — the AI MUST inspect these BEFORE calling any other tool: • { success: true, mode: 'restored'|'already-logged-in'|'manual-login' } → Logged in, OK to proceed. • { success: false, actionRequired: 'user-must-sign-in', ... } → STOP. Show `userMessage` to the user verbatim. If the user has no account yet, point them to the 'Register' link on the same sign-in page (new accounts get a free Complete trial). Do NOT call upload_file / run_bridge / etc. until the user reports back that sign-in (or registration) succeeded, then re-call open_app to verify. If `wait_for_manual_login` is false (or the process is running headless), only the second shape is returned — no blocking.

Open the Notifications panel for the user (handy after `get_notifications` indicates unread items the user should see).

Open the Subscription / billing modal in the UI so the user can change their plan or manage payment. The AI never handles credit-card data.

Open the Upgrade modal asking the user to pick a paid plan, optionally with a reason that explains why (row limits, premium features, etc.).

Convert a user's local data file into a WaterfallBridge-ready Excel workbook. ═══ What is preserved from the source xlsx ═══ • Source-cell FORMULAS on SumY / SumN columns are re-emitted in the target file (column letters + row numbers automatically remapped). Bridge's remoteFormulaBreakdown service depends on these formulas to decompose the Result into per-input drivers, so this is not just cosmetic — dropping a formula degrades the analysis quality. • Source row-2 NUMBER FORMATS (e.g. '#,##0', '0.00%', '$#,##0') are copied onto target row 3 cells. Bridge's engine reads the first data row's numFmt to pick chart and contribution-table display formats. numFmt priority per output column: (1) `num_fmt` explicitly set on the column_map entry (use this for Result columns where you want '0.00%' even though there is no source cell to inherit from); (2) inherited from the source column's row-2 numFmt — works for any column that declared `source`, INCLUDING Result columns that point at a source column purely to inherit its format (the Result row data still comes from `formula`, not from the source cells). • Formulas referencing columns NOT in column_map fall back to the cached scalar value (the file still opens cleanly). Return values `preservedFormulaCells` / `droppedFormulaCells` / `appliedNumFmtCells` report what happened. ═══ Sheet layout (FIXED — required by Bridge) ═══ Column A — Bridge label column. Only A1/A2/A3 are populated with the literal strings 'Data Type', 'Header', 'Data'. Rows A4+ stay empty. This column is auto-emitted by prepare_bridge_xlsx; do NOT include it in column_map. Column B onwards — your data columns. Row 1 = Data Type (Dimension/Key/SumY/SumN/Result), Row 2 = Field Name, Row 3+ = values. column_map[0] → sheet column B, column_map[1] → C, etc. Result formulas reference sheet letters (e.g. '=E3-F3'). IMPORTANT:…

Read a local CSV / XLSX / TSV / TXT file. Returns parsed rows as an array of objects when possible. Bound by WB_FS_MAX_BYTES and WB_FS_MAX_ROWS. GATE: on a multi-sheet workbook called WITHOUT a `sheet` (and not as_text), this returns { success:false, blocked:true, sheets:[…] } — ask the user which worksheet to use, then re-call with that `sheet` name (do NOT guess the tab).

Read a rectangular range of the workbook as a 2-D array of values. Returns null if the sheet does not exist. For the 'Data' sheet, remember that column A is the Bridge label column (A1='Data Type', A2='Header', A3='Data', A4+ empty) and user data lives in B onwards. To inspect just the user portion read e.g. 'B1:Z100'; to verify the labels read 'A1:A3'.

RE-RUN the Bridge analysis using the CURRENT Baseline_Filters / Comparison_Filters selections. Equivalent to clicking 'Run Analysis' in the Analysis Panel. PRESERVES filter selections (this is the key difference vs run_bridge). STANDARD WORKFLOW for filter-driven analysis: 1. `upload_file` + `run_bridge` (first build, all filters selected) 2. `set_baseline { field, values }` 3. `set_comparison { field, values }` 4. `refresh_bridge` ← THIS TOOL (re-runs with the new selections) 5. `get_result` / `get_contribution_table` Requires `run_bridge` to have been called at least once on the currently loaded data (otherwise the 'Run Analysis' button is disabled).

Clear the residual analysis state — the last Bridge result, errors, AI insight, dimension fields and Baseline/Comparison filter selections — WITHOUT unloading the workbook or signing the user out. WHY: the app is stateful and shared across conversations. Leftover result/filters from a PREVIOUS request must not be mistaken for the current request's answer. Call this at the START of a fresh analysis (before `upload_file` / `run_bridge`) so you build from a clean slate. It does NOT rebuild anything — follow it with the normal pipeline (`upload_file` → `run_bridge` → set filters → `refresh_bridge`).

Reset both Baseline and Comparison selections so every dimension is fully selected ('Select All' on both sides).

Remove a previously granted directory access. Static white-list entries (from WB_FS_ALLOWED_ROOTS) cannot be revoked at runtime — edit the environment variable instead.

Re-run the Bridge analysis with the CURRENT Baseline / Comparison selections. Equivalent to clicking 'Run Analysis' in the panel. Functionally identical to `refresh_bridge` — both PRESERVE filter selections (unlike `run_bridge`, which is the 'Build Bridge' button and would reset filters). This tool dispatches a refresh event via the JS API; `refresh_bridge` clicks the UI button. Prefer `refresh_bridge` unless you have a reason not to.

BUILD a fresh Bridge analysis from the currently loaded Data sheet. Equivalent to clicking 'Build Bridge' (or 'New Bridge') in the app UI. ⚠ SIDE EFFECT: this rebuilds every internal sheet (BaselinePT, ComparisonPT, Bridge Data, Process, Bridge, …) AND RESETS the Baseline_Filters / Comparison_Filters sheets to the default 'select all' state. Any prior `set_baseline` / `set_comparison` choices are LOST when you call this. WHEN TO USE: • First time after `upload_file` (no Bridge structure exists yet). • After re-uploading or significantly editing the Data sheet. • When you explicitly want to reset filters back to 'all selected'. DO NOT USE after `set_baseline` / `set_comparison` — those changes will be overwritten. Use `refresh_bridge` instead (it preserves the filter selections and just re-runs the calculation).

Persist the current workbook so the user can keep it. WaterfallBridge stores no user data on the server, and the Agent-controlled Chromium has its own IndexedDB profile that is isolated from the user's daily browser. By default this tool therefore does BOTH of the following: 1. Save the Univer snapshot to the Agent Chromium's IndexedDB (equivalent to Ctrl+S inside that window). 2. Export an .xlsx copy to <UserHome>/Downloads so the user can import it from their regular browser (or open it in Excel). Disable either side via `to_browser=false` / `export_to_disk=false`. Returns the exported file path so the AI can tell the user where their result was saved.

List every worksheet in an .xlsx/.xlsm workbook with its row/column counts, a header preview, and whether it already looks like a Bridge 'Data' sheet. CALL THIS BEFORE inspect_local_file / suggest_bridge_schema / prepare_bridge_xlsx WHENEVER a workbook has more than one worksheet — do NOT guess which tab the user means. When the workbook has 2+ non-empty sheets the result carries uiHint.requiresConfirmation=true. How to surface the choice depends on your environment: the WaterfallBridge Web AI Panel renders a sheet-picker card (the user's choice arrives as the next user message); in any other MCP host (Cursor / Codex / Claude Desktop) there is NO panel — ASK THE USER in chat which sheet to use, then call the data tool again passing their choice as the sheet argument. Either way STOP and wait after calling this; do not call other tools in the same turn. A `recommendedSheet` is provided (a Bridge-formatted or 'Data'-named sheet when present, else the first non-empty sheet) and is pre-selected in the card, but the user must still confirm it.

Write the AI's narrative interpretation of the current Bridge analysis into the 'AI Insights' panel below Key Findings. ═══ When to call ═══ Call this AFTER `run_bridge` / `refresh_bridge` and AFTER you have inspected the result via `get_chart_data` / `get_contribution_table` / `get_insights`. The panel auto-clears on every new bridge run so you only need to call it once per analysis. ═══ Why this exists ═══ Key Findings (the existing panel above) is deterministic template output — guaranteed accurate, audit-safe, every number traceable to the chart. Useful for compliance/finance scenarios. AI Insights is the additive layer where YOU can: • interpret the result in plain business language • identify root causes (e.g. 'SkyView X1 is the portfolio's margin diluter — high volume, low GM') • recommend actions (e.g. 'Review pricing on category X') • compare across analyses ('Q1 mix shift is the opposite of Q4') ═══ Visibility ═══ The AI Insights panel is ONLY rendered when the page is running inside the Agent-controlled Chromium (the MCP-mode flag). Human-launched browsers never see this panel — they only see Key Findings. So this tool is a no-op for human users; it is purely a channel for AI clients. ═══ Format guidance ═══ Keep it concise — 5-15 lines is typical. A useful structure is: ## Summary (1-2 sentences of the headline finding) ## Root causes (bullet list of factor → contribution) ## Recommended actions (bullet list of next steps) Do not duplicate Key Findings — focus on interpretation and business judgement that the template cannot infer.

Set the Baseline filter selection for a dimension. The change is persisted to the Baseline_Filters sheet and marks filters as stale. ⚠ CRITICAL: After calling set_baseline / set_comparison you MUST use `refresh_bridge` (NOT `run_bridge`) to apply the change. `run_bridge` is the 'Build Bridge' button — it would RESET your filter selections back to 'select all' before running, undoing this call. Requires `run_bridge` to have been called at least once on the currently loaded data so the Baseline_Filters sheet exists.

Set the Comparison filter selection for a dimension. The change is persisted to the Comparison_Filters sheet and marks filters as stale. ⚠ CRITICAL: After calling set_baseline / set_comparison you MUST use `refresh_bridge` (NOT `run_bridge`) to apply the change. `run_bridge` is the 'Build Bridge' button — it would RESET your filter selections back to 'select all' before running, undoing this call. Requires `run_bridge` to have been called at least once on the currently loaded data so the Comparison_Filters sheet exists.

Set the Data Type (Row 1) of a column on a Data sheet — one of Dimension / Key / SumY / SumN / Result. Bridge requires exactly one Key, exactly one Result, and at least one SumY column. USE THIS to fix the data-type row of a workbook that is ALREADY loaded in Bridge (e.g. a Dimension column was misclassified as a Key, or you forgot to mark Year as a Dimension). After updating types, call run_bridge to re-run the analysis with the new layout — DO NOT regenerate the file with prepare_bridge_xlsx and re-upload; it is slower and loses any in-app edits. Note: Sheet column A is the Bridge label column ('Data Type'/'Header'/'Data'); user columns start at B. Pass 'B' / 'C' / 'D' etc., not 'A'.

Set the Field Name (Row 2) for a column on a Data sheet. Field names must be non-empty and unique across the sheet. After renaming, call run_bridge to refresh the analysis — no need to re-import the file. Note: Sheet column A is the Bridge label column ('Data Type'/'Header'/'Data'); user columns start at B. Pass 'B' / 'C' / 'D' etc., not 'A'.

Profile a source CSV/XLSX file and recommend a Bridge column_map (Dimension / Key / SumY / SumN / Result) for each column based on content type, cardinality, additivity heuristics, and any existing cell formulas. Call this BEFORE prepare_bridge_xlsx when the user hasn't given an explicit mapping, then present the suggestion to the user for confirmation (the Web AI Panel renders a confirm card; in other MCP hosts like Cursor / Codex / Claude there is NO panel — show the proposed types + Result formula in chat, DEFINE each Data Type using the returned `dataTypeGlossary`, give the user the `helpUrl` link, and ask them to confirm, then call prepare_bridge_xlsx with the agreed column_map). Returns a `dataReadinessIssues` array when the source cannot be bridged so the AI can ask for better data. GATE: if the source file still has BLOCKING data-preparation issues (merged cells, crosstab layout, bad formulas, title rows) this returns { success:false, blocked:true, issues:[…] } WITHOUT profiling — call check_data_preparation / show the user the issues, let them fix the file, then retry (or pass confirm_data_prep:true to override a false positive).

Swap the Baseline and Comparison selections (handy when the user phrases the comparison the other way around). Marks filters stale.

Upload an Excel (.xlsx) file to the WaterfallBridge app. The file must contain a Data worksheet with valid Data Type headers.

Write UTF-8 text content (CSV / JSON / TXT) to a file inside an allowed root. Refuses to overwrite by default; the user should be informed before set overwrite=true.