# io.github.waterfallbridge/mcp (npm · @waterfallbridge/mcp) Explain why any KPI or rate metric changed: bridge/variance analysis by driver, from CSV/Excel. - Trust score: 51/100 (low) - Change this week: +51 - Registry status: active - Liveness: live - Owner verified: no - Last scored: 2026-08-08 ## Components - npm · `@waterfallbridge/mcp`: 51/100 (this document), [markdown](https://verifymcp.io/servers/waterfallbridge-mcp/waterfallbridge-mcp.md), [page](https://verifymcp.io/servers/waterfallbridge-mcp/waterfallbridge-mcp) ## Channel facts - Registry: `npm` - Package: `@waterfallbridge/mcp` - Version: `1.2.4` - Transport: `stdio` ## Trust breakdown How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog) Scored 2026-08-08. - **Supply Chain Security**: 87/100 - No malware found by supply-chain analysis. - CVE check failed: a known medium-severity CVE affects @hono/node-server 1.19.17, a direct dependency. A fixed version is available. - No install/post-install scripts declared. - 87 of 184 dependencies flagged as unhealthy (6 deprecated). - **Provenance & Transparency**: 19/100 - Repository check failed: the declared repository URL returned HTTP 404. - Provenance check failed: no build-provenance attestation is published. - Clear OSI-approved license (MIT). - Actively maintained (last published 61 days ago). - Security-disclosure policy not yet verified: we couldn't inspect the source repository. - **Schema Quality & AI Usability**: 30/100 - AI-judged instruction clarity (poor). - Context-footprint check failed: tool/resource definitions use about 9269 tokens (~181/item across 51 items; 51 tools + 0 resources), over budget; trim descriptions and params. - Usage-examples check failed: none of the tools include examples. - **Stability & Change Management**: 0/100 - Stability not yet verified: not enough scan history yet (needs a 30-day window). - **Tool Coverage**: 100/100 - 100% of tools have a non-trivial description (not blank, and not just the tool's name). - 100% of tool parameters carry a description. - **Capabilities**: 100/100 - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28. **Unverified: 1 category.** A category scored 0 because we could not verify it: a data source with nothing on this package, evidence we could not reach, or a check we could not run. We only credit what we can confirm. ## Install ### Claude ```bash claude mcp add waterfallbridge-mcp -- npx -y @waterfallbridge/mcp ``` ### Codex ```bash codex mcp add waterfallbridge-mcp -- npx -y @waterfallbridge/mcp ``` ### opencode ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "waterfallbridge-mcp": { "type": "local", "command": [ "npx", "-y", "@waterfallbridge/mcp" ], "enabled": true } } } ``` ### OpenClaw ```bash openclaw mcp add waterfallbridge-mcp --command npx --arg -y --arg @waterfallbridge/mcp ``` ### Hermes ```yaml mcp_servers: waterfallbridge-mcp: command: "npx" args: ["-y", "@waterfallbridge/mcp"] ``` ### Other ```json { "mcpServers": { "waterfallbridge-mcp": { "command": "npx", "args": [ "-y", "@waterfallbridge/mcp" ] } } } ``` ## Changelog Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims. ### 2026-08-07 (score 51, +3) - [functional] Dependency health: partial → 0.78 ### 2026-08-06 (score 48, +21) - [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window). - [functional improvement] MCP protocol: unverified → pass - [functional improvement] Tool coverage: unverified → 100 - [functional] First check of Schema quality: poor - [functional] First check of Tool coverage: 100 - [functional] First check of Schema quality: fail - [functional] First check of Schema quality: fail ### 2026-08-05 (score 27, 0) - [security improvement] CVE-2026-69207 no longer affects this package ### 2026-08-04 (score 27, 0) - [security regression] CVE-2026-69207 affects this package: medium ### 2026-08-02 (score 27, +27) - [security regression] GHSA-frvp-7c67-39w9 affects this package: medium - [security regression] CVE-2026-41907 affects this package: medium - [security regression] Provenance: unverified → fail - [security regression] Known CVEs: unverified → fail - [security improvement] Install scripts: unverified → pass - [security improvement] Malware scan: unverified → pass - [security] Stability: Stability not yet verified: our sandbox run of this package did not complete, so we have no schema to compare. - [functional improvement] License: unverified → pass - [functional improvement] Dependency health: unverified → partial - [functional improvement] Maintenance: unverified → pass - [functional] Tool coverage: Tool coverage not yet verified: our sandbox run of this package did not complete, so we have no tool definitions to assess. - [functional] Schema quality: Schema quality not yet verified: our sandbox run of this package did not complete, so we have no schema to assess. - [functional] Capabilities: Protocol version not yet verified: our sandbox run of this package did not complete, so we never saw its MCP handshake. - [functional] Licence: MIT ### 2026-07-31 (score 0, −18) - [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server ### 2026-07-30 (score 18, 0) - [functional] Tool coverage: Tool coverage not yet verified: our sandbox run of this package did not complete, so we have no tool definitions to assess. - [functional] Schema quality: Schema quality not yet verified: our sandbox run of this package did not complete, so we have no schema to assess. ### 2026-07-27 (score 18) First indexed and scored. ## MCP tools (51) ### `open_app` (~484 tokens) 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. Input parameters: - `email` (string): Optional. When provided alongside a previously saved session for the same URL+email, the saved session is restored instead of the most recently used one. Credentials are NOT required here. - `login_timeout_ms` (integer): How long (milliseconds) to wait for the user to finish signing in before timing out. Default 300000 (5 min). Max 1800000 (30 min). - `url` (string): WaterfallBridge app URL. Defaults to the configured WB_DEFAULT_URL (http://127.0.0.1:5173/app/ in dev, https://waterfallbridge.com/app/ in prod). - `wait_for_manual_login` (boolean): When no saved session exists and this is true (default), the tool opens a visible Chromium window on the sign-in page and waits for the user to authenticate themselves. The AI MUST tell the user to c… ### `login` (~93 tokens) 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. Input parameters: - `email` (string, required): Account email. - `password` (string, required): Account password. After successful login the session is encrypted (DPAPI on Windows) and the password itself is NOT stored. - `url` (string): Defaults to the configured WB_DEFAULT_URL. ### `close_app` (~31 tokens) Close the controlled browser and end the automation session. Persisted login state is retained for the next open_app call. ### `list_sessions` (~35 tokens) List all persisted login sessions known to the Agent (origin + email + last update). Useful when deciding which session open_app should use. ### `forget_session` (~62 tokens) Delete a persisted login session. The next open_app call for this (url, email) pair will return needsLogin: true. Input parameters: - `email` (string, required): Account email of the session to forget. - `url` (string, required): Origin URL of the session to forget. ### `upload_file` (~87 tokens) Upload an Excel (.xlsx) file to the WaterfallBridge app. The file must contain a Data worksheet with valid Data Type headers. Input parameters: - `auto_run` (boolean): If true (default), automatically click 'Build Bridge' or 'Run Analysis' after import if the app prompts. - `file_path` (string, required): Absolute path to a Bridge-formatted .xlsx file on the local filesystem. ### `export_xlsx` (~118 tokens) Export the current workbook or Bridge analysis result as an Excel file. Returns the absolute path the file was written to. Input parameters: - `target_path` (string): Optional absolute file path to save the exported XLSX to. When set, the file is moved to this path and `path` is returned. When omitted, the file lands in Playwright's temp download dir (returned in… - `type` (string): 'workbook' exports the full workbook; 'bridge' exports only the Bridge result sheet. Defaults to 'bridge'. ### `export_report` (~77 tokens) Open the AppHeader 'Report' dialog and download the Bridge analysis report as a PDF. Requires a successful Bridge run first. Input parameters: - `target_path` (string): Optional absolute file path to save the PDF report to (e.g. C:/Users/me/Documents/MyBridge.pdf). When omitted the file is kept in Playwright's temp download dir. ### `run_bridge` (~233 tokens) 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). Input parameters: - `wait_for_completion` (boolean): If true (default), block until the analysis finishes and return the result. If false, return immediately and poll with get_status. ### `refresh_bridge` (~176 tokens) 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). ### `new_bridge_template` (~102 tokens) 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. ### `reset_analysis` (~135 tokens) 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`). ### `get_status` (~32 tokens) Get the current status of the WaterfallBridge app: login state, subscription, bridge progress, errors, current file. ### `get_result` (~29 tokens) Get the result of the last Bridge analysis: success status, errors, and the full waterfall chart payload. ### `get_dimensions` (~29 tokens) Get available dimension fields and their current Baseline / Comparison filter selections. Useful before running a filtered analysis. ### `get_chart_data` (~31 tokens) Get the waterfall chart data from the most recent analysis: labels, values, total positions, and number format. ### `dismiss_dialog` (~52 tokens) Dismiss any currently visible dialog (error panel, progress complete, or confirmation prompt). Input parameters: - `action` (string): 'confirm' clicks the primary button; 'cancel' clicks the cancel button. Defaults to 'confirm'. ### `list_local_files` (~101 tokens) List files in a directory. Without a directory argument, returns the set of folders the AI is allowed to browse on this machine. Input parameters: - `directory` (string): Absolute directory path to list. If omitted, returns the set of allowed roots configured for the Agent (Downloads / Desktop / Documents by default). - `pattern` (string): Optional case-insensitive substring filter applied to file names (not paths). Use this to find 'sales*.xlsx' style matches. ### `inspect_local_file` (~169 tokens) 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). Input parameters: - `file_path` (string, required): Absolute path to the file to inspect. - `preview_rows` (integer): Number of preview rows to return (default 20, max 200). - `sheet` (string): Worksheet name (for .xlsx). Defaults to the first non-empty sheet. ### `select_source_sheet` (~278 tokens) 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. Input parameters: - `file_path` (string, required): Absolute path to the .xlsx/.xlsm file whose sheets to list. - `preview_columns` (integer): How many header columns to preview per sheet (default 12). ### `get_source_sheet_preview` (~178 tokens) 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. Input parameters: - `preview_rows` (integer): How many rows from the top to return (default 6, max 50). - `source_file` (string, required): Absolute path to the source CSV / XLSX / XLSM / TSV file. - `source_sheet` (string): Worksheet to read (xlsx/xlsm only). Defaults to the first non-empty sheet. On a multi-sheet workbook pass the sheet the user confirmed via select_source_sheet. ### `read_local_file` (~182 tokens) 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). Input parameters: - `as_text` (boolean): If true, return the file's raw UTF-8 text instead of parsing. Useful for JSON / TXT inspection. - `file_path` (string, required): Absolute path to the file to read. - `max_rows` (integer): Cap the number of data rows returned (defaults to WB_FS_MAX_ROWS). - `sheet` (string): Worksheet (xlsx only). ### `write_local_file` (~129 tokens) 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. Input parameters: - `content` (string, required): UTF-8 text content. For binary formats use prepare_bridge_xlsx. - `file_path` (string, required): Absolute path for the destination file. Parent directory must exist and be inside an allowed root. - `overwrite` (boolean): If false (default), fails when the file already exists. Set to true to allow overwriting; the AI should normally confirm with the user first. ### `delete_local_file` (~48 tokens) Delete a file (NOT a directory) inside an allowed root. The AI should confirm with the user before calling this. Input parameters: - `file_path` (string, required): Absolute path of the file to delete. ### `list_granted_paths` (~50 tokens) 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. ### `grant_path_access` (~190 tokens) 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). Input parameters: - `mode` (string): 'read' = list/inspect/read only. 'readwrite' = also allows write_local_file / delete_local_file. Default: 'read'. - `note` (string): Free-form reason recorded in the audit log. - `path` (string, required): Absolute directory (or file) path to authorize. The grant covers the path and all of its descendants. - `scope` (string): 'session' = forgotten on Agent exit. 'persistent' = saved to /granted-roots.json and reloaded on next start. Default: 'session'. ### `revoke_path_access` (~58 tokens) 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. Input parameters: - `path` (string, required): Absolute path of the grant to revoke (must match exactly). ### `prepare_bridge_xlsx` (~1936 tokens) 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:… Input parameters: - `column_map` (array, required): Ordered list of output columns. The first entry is written to sheet column B, the second to column C, etc. (Sheet column A is reserved for the Bridge label column — 'Data Type' in A1, 'Header' in A2,… - `confirm_data_prep` (boolean): Data-preparation gate override. Leave UNSET normally. If the source file still has BLOCKING data-prep issues this tool returns { blocked:true } instead of running — fix the file (or have the user fix… - `inline_rows` (array): Inline data as an array of objects keyed by source column name. Useful when the AI synthesizes a small dataset on the fly. - `output_path` (string): OPTIONAL absolute output path for the generated workbook (must be inside an allowed root and end with .xlsx). LEAVE IT UNSET in the normal flow: this workbook is just the Bridge-ready INPUT that gets… - `overwrite` (boolean): If false (default), fails when output_path already exists. The AI should normally confirm with the user before setting this to true. - `preview_only` (boolean): If true, validate the plan and return the first 10 transformed rows without writing the file. Useful for the AI to confirm with the user. - `source_file` (string): Absolute path to a CSV / XLSX / TSV source file. Either source_file or inline_rows is required. - `source_sheet` (string): Worksheet name to read from source_file (xlsx only). Defaults to the first non-empty sheet. ### `suggest_bridge_schema` (~488 tokens) 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). Input parameters: - `confirm_data_prep` (boolean): Data-preparation gate override. Leave UNSET normally. If the source file still has BLOCKING data-prep issues this tool returns { blocked:true } instead of profiling — fix the file (or have the user f… - `sample_rows` (integer): How many rows to sample for profiling. Default 200, max 2000. - `source_file` (string, required): Absolute path to a CSV/XLSX/TSV source file. - `source_sheet` (string): Worksheet name (xlsx only). Defaults to first non-empty sheet. - `user_intent` (string): Optional free-text description of what the user wants to analyse (e.g. 'YoY revenue bridge by product', 'GM% change between Q1 and Q2'). Used to bias Key / Result suggestions. ### `check_data_preparation` (~311 tokens) 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. Input parameters: - `source_file` (string, required): Absolute path to the user's source CSV / XLSX / XLSM / TSV file. - `source_sheet` (string): Worksheet to check (xlsx/xlsm only). Defaults to the first non-empty sheet. On a multi-sheet workbook pass the sheet the user confirmed via select_source_sheet. ### `set_baseline` (~185 tokens) 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. Input parameters: - `field` (string, required): Dimension field name (case-insensitive). Use `get_dimensions` to enumerate. - `values` (array, required): List of values to keep selected for this side. Pass [] to keep nothing (equivalent to 'Select None'). Unknown values are ignored and reported. ### `set_comparison` (~182 tokens) 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. Input parameters: - `field` (string, required): Dimension field name (case-insensitive). Use `get_dimensions` to enumerate. - `values` (array, required): List of values to keep selected for this side. Pass [] to keep nothing (equivalent to 'Select None'). Unknown values are ignored and reported. ### `reset_filters` (~29 tokens) Reset both Baseline and Comparison selections so every dimension is fully selected ('Select All' on both sides). ### `swap_filters` (~33 tokens) Swap the Baseline and Comparison selections (handy when the user phrases the comparison the other way around). Marks filters stale. ### `run_analysis` (~138 tokens) 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. Input parameters: - `wait_for_completion` (boolean): If true (default), block until analysis finishes and return the result. If false, dispatch and return immediately — poll get_status / get_result. ### `get_sheet_names` (~30 tokens) List all visible & hidden sheet names in the current workbook. Useful before reading or editing a particular sheet. ### `read_sheet` (~150 tokens) 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'. Input parameters: - `range` (string): Optional A1-style range, e.g. 'A1:E20'. Omit to read the sheet's used range. - `sheet` (string, required): Sheet name (case-sensitive). ### `get_data_sheet_preview` (~170 tokens) 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). Input parameters: - `sample_rows` (integer): How many leading data rows (after the Data Type / Field Name header rows) to include in `sample`. Defaults to 5. - `sheet` (string): Sheet name. Defaults to 'Data'. ### `get_contribution_table` (~98 tokens) 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. ### `write_sheet_cells` (~182 tokens) Write a batch of cells in the live workbook (values or formulas). After writing, marks filters stale and persists a workbook snapshot. WARNING about the 'Data' sheet layout: column A is the Bridge label column (A1='Data Type', A2='Header', A3='Data', A4+ empty) — do NOT overwrite A1/A2/A3 unless you specifically want to invalidate the Bridge data sheet. User data lives in columns B onwards: Row 1 = Data Type, Row 2 = Field Name, Row 3+ = values. For changing Data Types or Field Names prefer set_data_type / set_field_name (clearer intent + same-row validation). Input parameters: - `edits` (array, required): Batch of cell edits. Each entry needs either { a1 } or { row, col }. - `sheet` (string, required): Sheet name. ### `set_data_type` (~270 tokens) 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'. Input parameters: - `column` (string|number, required): Target column letter ('B','C',…) or 0-based index. Sheet column A (index 0) is the Bridge label column and is NOT a valid target — the first user column is always 'B' / 1. - `sheet` (string): Sheet name. Defaults to 'Data'. - `type` (string, required): WaterfallBridge data type for the column. ### `set_field_name` (~186 tokens) 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'. Input parameters: - `column` (string|number, required): Target column letter ('B','C',…) or 0-based index. Sheet column A (index 0) is the Bridge label column and is NOT a valid target — the first user column is always 'B' / 1. - `name` (string, required): Friendly field name (Row 2). - `sheet` (string): Sheet name. Defaults to 'Data'. ### `get_insights` (~82 tokens) 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). ### `set_ai_insight` (~474 tokens) 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. Input parameters: - `markdown` (string|null, required): AI-authored narrative analysis. Plain markdown — headings (# / ## / ###), **bold**, *italic*, `inline code`, bullets (- / *), numbered lists (1.), and tables (`| col | col |` with `|---|---|` separat… ### `get_active_dialog` (~66 tokens) 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_notifications` (~38 tokens) Get a snapshot of the user's notifications inbox: items (id, title, message, url, type, isRead), unreadCount, readCount. ### `get_subscription` (~47 tokens) Get the user's subscription state: status (active/trialing/expired/…), planType (free/online/complete), accessExpiresAt, isDemo. Use this before suggesting an upgrade. ### `save_workbook` (~332 tokens) 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 /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. Input parameters: - `export_path` (string): Optional absolute path for the exported .xlsx. Defaults to /Downloads/WaterfallBridge-AI-.xlsx. Ignored when export_to_disk=false. - `export_to_disk` (boolean): When true (default), also export an .xlsx copy of the workbook to the user's Downloads folder so the user can later import it from their regular browser. This is what makes the AI's work user-visible… - `to_browser` (boolean): When true (default), persist the workbook to the Agent-controlled Chromium's IndexedDB — equivalent to clicking Save / pressing Ctrl+S inside that window. NOTE: this storage is local to the Agent's C… ### `open_subscription_modal` (~37 tokens) 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_upgrade_modal` (~67 tokens) Open the Upgrade modal asking the user to pick a paid plan, optionally with a reason that explains why (row limits, premium features, etc.). Input parameters: - `reason` (string): Short human-readable reason shown to the user (e.g. 'Your dataset exceeds the Free Plan row limit.'). ### `open_notifications` (~31 tokens) Open the Notifications panel for the user (handy after `get_notifications` indicates unread items the user should see). ## Diagnostics Captured diagnostic sections: Provenance, Vulnerabilities, Dependencies. The full working is on the page: https://verifymcp.io/servers/waterfallbridge-mcp/waterfallbridge-mcp#diagnostics ## Score history - 2026-08-08: 51 - 2026-08-07: 51 - 2026-08-06: 48 - 2026-08-05: 27 - 2026-08-04: 27 - 2026-08-03: 27 - 2026-08-02: 27 - 2026-08-01: 0 - 2026-07-31: 0 - 2026-07-30: 18 - 2026-07-28: 18 - 2026-07-27: 18 ## Links - npm package: https://www.npmjs.com/package/@waterfallbridge/mcp - Socket report: https://socket.dev/npm/package/@waterfallbridge/mcp - Changelog RSS feed: https://verifymcp.io/servers/waterfallbridge-mcp/waterfallbridge-mcp.xml - Changelog JSON feed: https://verifymcp.io/servers/waterfallbridge-mcp/waterfallbridge-mcp.json - HTML version of this page: https://verifymcp.io/servers/waterfallbridge-mcp/waterfallbridge-mcp