@cci-labs/mode-mcp 1.0.1

package/README.md

@@ -0,0 +1,925 @@
+# Mode Analytics MCP Server
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/AwesomeCICD/mode-mcp/blob/main/LICENSE)
+[![CircleCI](https://dl.circleci.com/status-badge/img/gh/AwesomeCICD/mode-mcp/tree/main.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/AwesomeCICD/mode-mcp/tree/main)
+[![npm](https://img.shields.io/npm/v/%40cci-labs%2Fmode-mcp?logo=npm)](https://www.npmjs.com/package/@cci-labs/mode-mcp)
+[![Docker](https://img.shields.io/badge/docker-ccilabs%2Fmode--mcp-blue?logo=docker)](https://hub.docker.com/r/ccilabs/mode-mcp)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22-brightgreen?logo=node.js)](https://nodejs.org)
+[![MCP](https://img.shields.io/badge/MCP-compatible-purple)](https://modelcontextprotocol.io)
+
+Model Context Protocol (MCP) is a [standardized protocol](https://modelcontextprotocol.io/introduction) for managing context between large language models (LLMs) and external systems. In this repository, we provide an MCP Server for [Mode Analytics](https://mode.com).
+
+Use Cursor, Windsurf, Copilot, Claude, or any MCP-compatible client to interact with Mode Analytics using natural language — without leaving your IDE.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| [`mode_list_reports`](#mode_list_reports) | List reports in the workspace, optionally filtered by space |
+| [`mode_get_report`](#mode_get_report) | Get report details including queries, data sources, and last run status |
+| [`mode_list_queries`](#mode_list_queries) | List all queries in a report with their SQL content |
+| [`mode_run_report`](#mode_run_report) | Trigger a new report run (non-destructive) |
+| [`mode_get_run_status`](#mode_get_run_status) | Check whether a report run has completed, is running, or failed |
+| [`mode_get_query_results`](#mode_get_query_results) | Download query results as a markdown table, optionally save as CSV |
+| [`mode_execute_and_fetch`](#mode_execute_and_fetch) | Run a report, wait for completion, and return results — all in one call |
+| [`mode_list_report_runs`](#mode_list_report_runs) | List past runs for a report |
+| [`mode_get_query_run`](#mode_get_query_run) | Get details on a specific query run (state, errors, timing) |
+| [`mode_search_reports`](#mode_search_reports) | Search reports by name across the workspace |
+| [`mode_get_report_parameters`](#mode_get_report_parameters) | Discover what parameters a report accepts before running it |
+| [`mode_list_report_filters`](#mode_list_report_filters) | List interactive filters on a report |
+| [`mode_list_report_charts`](#mode_list_report_charts) | List charts/visualizations in a query |
+| [`mode_list_spaces`](#mode_list_spaces) | List all spaces (collections) in the workspace |
+| [`mode_list_data_sources`](#mode_list_data_sources) | List all connected data sources (databases) |
+| [`mode_get_data_source`](#mode_get_data_source) | Get detailed connection info for a data source |
+| [`mode_list_definitions`](#mode_list_definitions) | List saved SQL definitions (reusable snippets) |
+| [`mode_list_report_schedules`](#mode_list_report_schedules) | List automated schedules for a report |
+| [`mode_list_report_subscriptions`](#mode_list_report_subscriptions) | List email subscriptions for a report |
+| [`mode_get_audit_logs`](#mode_get_audit_logs) | Retrieve workspace audit logs |
+| [`mode_list_datasets`](#mode_list_datasets) | List datasets in a space |
+| [`mode_get_dataset`](#mode_get_dataset) | Get dataset details with fields and descriptions |
+| [`mode_list_dataset_reports`](#mode_list_dataset_reports) | Find reports that use a dataset |
+| [`mode_export_report`](#mode_export_report) | Export a report as PDF or CSV |
+
+## Installation
+
+<details>
+<summary><strong>Claude Code</strong></summary>
+
+**Prerequisites:**
+- [Mode API token and secret](https://app.mode.com) — generate at `app.mode.com/{workspace}/settings/api_tokens`
+- Docker: [Docker](https://docs.docker.com/get-docker/)
+- NPX: [Node.js >= v22](https://nodejs.org/)
+
+#### Using Docker in a local MCP Server
+
+```bash
+claude mcp add mode-analytics \
+  -e MODE_WORKSPACE=your-workspace \
+  -e MODE_API_TOKEN=your-token \
+  -e MODE_API_SECRET=your-secret \
+  -- docker run --rm -i \
+    -e MODE_WORKSPACE -e MODE_API_TOKEN -e MODE_API_SECRET \
+    -v "$HOME/Downloads:/output" \
+    ccilabs/mode-mcp
+```
+
+> The `-v "$HOME/Downloads:/output"` mount lets tools save CSV and PDF exports to your `~/Downloads` folder. Use `/output` as the `output_dir` parameter when downloading files.
+
+#### Using Node.js in a local MCP Server
+
+```bash
+claude mcp add mode-analytics \
+  -e MODE_WORKSPACE=your-workspace \
+  -e MODE_API_TOKEN=your-token \
+  -e MODE_API_SECRET=your-secret \
+  -- node /path/to/mode-mcp/dist/index.js
+```
+
+> With the Node.js setup, tools can save files directly to any path on your machine.
+
+#### Using npx (no install)
+
+```bash
+claude mcp add mode-analytics \
+  -e MODE_WORKSPACE=your-workspace \
+  -e MODE_API_TOKEN=your-token \
+  -e MODE_API_SECRET=your-secret \
+  -- npx -y @cci-labs/mode-mcp
+```
+
+For more information: https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp
+
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
+
+**Prerequisites:**
+- [Mode API token and secret](https://app.mode.com) — generate at `app.mode.com/{workspace}/settings/api_tokens`
+- Docker: [Docker](https://docs.docker.com/get-docker/)
+- NPX: [Node.js >= v22](https://nodejs.org/)
+
+#### Using Docker in a local MCP Server
+
+Add the following to your Cursor MCP config:
+
+```json
+{
+  "mcpServers": {
+    "mode-analytics": {
+      "command": "docker",
+      "args": [
+        "run", "--rm", "-i",
+        "-e", "MODE_WORKSPACE",
+        "-e", "MODE_API_TOKEN",
+        "-e", "MODE_API_SECRET",
+        "-v", "${HOME}/Downloads:/output",
+        "ccilabs/mode-mcp"
+      ],
+      "env": {
+        "MODE_WORKSPACE": "your-workspace",
+        "MODE_API_TOKEN": "your-token",
+        "MODE_API_SECRET": "your-secret"
+      }
+    }
+  }
+}
+```
+
+#### Using Node.js in a local MCP Server
+
+```json
+{
+  "mcpServers": {
+    "mode-analytics": {
+      "command": "node",
+      "args": ["/path/to/mode-mcp/dist/index.js"],
+      "env": {
+        "MODE_WORKSPACE": "your-workspace",
+        "MODE_API_TOKEN": "your-token",
+        "MODE_API_SECRET": "your-secret"
+      }
+    }
+  }
+}
+```
+
+#### Using npx (no install)
+
+```json
+{
+  "mcpServers": {
+    "mode-analytics": {
+      "command": "npx",
+      "args": ["-y", "@cci-labs/mode-mcp"],
+      "env": {
+        "MODE_WORKSPACE": "your-workspace",
+        "MODE_API_TOKEN": "your-token",
+        "MODE_API_SECRET": "your-secret"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>VS Code</strong></summary>
+
+**Prerequisites:**
+- [Mode API token and secret](https://app.mode.com) — generate at `app.mode.com/{workspace}/settings/api_tokens`
+- Docker: [Docker](https://docs.docker.com/get-docker/)
+- NPX: [Node.js >= v22](https://nodejs.org/)
+
+#### Using Docker in a local MCP Server
+
+Add the following to `.vscode/mcp.json` in your project:
+
+```json
+{
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "mode-workspace",
+      "description": "Mode workspace name"
+    },
+    {
+      "type": "promptString",
+      "id": "mode-token",
+      "description": "Mode API Token",
+      "password": true
+    },
+    {
+      "type": "promptString",
+      "id": "mode-secret",
+      "description": "Mode API Secret",
+      "password": true
+    }
+  ],
+  "servers": {
+    "mode-analytics": {
+      "type": "stdio",
+      "command": "docker",
+      "args": [
+        "run", "--rm", "-i",
+        "-e", "MODE_WORKSPACE",
+        "-e", "MODE_API_TOKEN",
+        "-e", "MODE_API_SECRET",
+        "-v", "${HOME}/Downloads:/output",
+        "ccilabs/mode-mcp"
+      ],
+      "env": {
+        "MODE_WORKSPACE": "${input:mode-workspace}",
+        "MODE_API_TOKEN": "${input:mode-token}",
+        "MODE_API_SECRET": "${input:mode-secret}"
+      }
+    }
+  }
+}
+```
+
+> Inputs are prompted on first server start, then stored securely by VS Code.
+
+#### Using Node.js in a local MCP Server
+
+```json
+{
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "mode-workspace",
+      "description": "Mode workspace name"
+    },
+    {
+      "type": "promptString",
+      "id": "mode-token",
+      "description": "Mode API Token",
+      "password": true
+    },
+    {
+      "type": "promptString",
+      "id": "mode-secret",
+      "description": "Mode API Secret",
+      "password": true
+    }
+  ],
+  "servers": {
+    "mode-analytics": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/path/to/mode-mcp/dist/index.js"],
+      "env": {
+        "MODE_WORKSPACE": "${input:mode-workspace}",
+        "MODE_API_TOKEN": "${input:mode-token}",
+        "MODE_API_SECRET": "${input:mode-secret}"
+      }
+    }
+  }
+}
+```
+
+#### Using npx (no install)
+
+```json
+{
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "mode-workspace",
+      "description": "Mode workspace name"
+    },
+    {
+      "type": "promptString",
+      "id": "mode-token",
+      "description": "Mode API Token",
+      "password": true
+    },
+    {
+      "type": "promptString",
+      "id": "mode-secret",
+      "description": "Mode API Secret",
+      "password": true
+    }
+  ],
+  "servers": {
+    "mode-analytics": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@cci-labs/mode-mcp"],
+      "env": {
+        "MODE_WORKSPACE": "${input:mode-workspace}",
+        "MODE_API_TOKEN": "${input:mode-token}",
+        "MODE_API_SECRET": "${input:mode-secret}"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Claude Desktop</strong></summary>
+
+**Prerequisites:**
+- [Mode API token and secret](https://app.mode.com) — generate at `app.mode.com/{workspace}/settings/api_tokens`
+- Docker: [Docker](https://docs.docker.com/get-docker/)
+- NPX: [Node.js >= v22](https://nodejs.org/)
+
+#### Using Docker in a local MCP Server
+
+Add the following to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mode-analytics": {
+      "command": "docker",
+      "args": [
+        "run", "--rm", "-i",
+        "-e", "MODE_WORKSPACE",
+        "-e", "MODE_API_TOKEN",
+        "-e", "MODE_API_SECRET",
+        "-v", "${HOME}/Downloads:/output",
+        "ccilabs/mode-mcp"
+      ],
+      "env": {
+        "MODE_WORKSPACE": "your-workspace",
+        "MODE_API_TOKEN": "your-token",
+        "MODE_API_SECRET": "your-secret"
+      }
+    }
+  }
+}
+```
+
+#### Using Node.js in a local MCP Server
+
+```json
+{
+  "mcpServers": {
+    "mode-analytics": {
+      "command": "node",
+      "args": ["/path/to/mode-mcp/dist/index.js"],
+      "env": {
+        "MODE_WORKSPACE": "your-workspace",
+        "MODE_API_TOKEN": "your-token",
+        "MODE_API_SECRET": "your-secret"
+      }
+    }
+  }
+}
+```
+
+#### Using npx (no install)
+
+```json
+{
+  "mcpServers": {
+    "mode-analytics": {
+      "command": "npx",
+      "args": ["-y", "@cci-labs/mode-mcp"],
+      "env": {
+        "MODE_WORKSPACE": "your-workspace",
+        "MODE_API_TOKEN": "your-token",
+        "MODE_API_SECRET": "your-secret"
+      }
+    }
+  }
+}
+```
+
+To find or create your config file, open Claude Desktop settings, click **Developer** in the left sidebar, then click **Edit Config**. The config file is located at:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+For more information: https://modelcontextprotocol.io/quickstart/user
+
+</details>
+
+<details>
+<summary><strong>Windsurf</strong></summary>
+
+**Prerequisites:**
+- [Mode API token and secret](https://app.mode.com) — generate at `app.mode.com/{workspace}/settings/api_tokens`
+- Docker: [Docker](https://docs.docker.com/get-docker/)
+- NPX: [Node.js >= v22](https://nodejs.org/)
+
+#### Using Docker in a local MCP Server
+
+Add the following to your Windsurf `mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mode-analytics": {
+      "command": "docker",
+      "args": [
+        "run", "--rm", "-i",
+        "-e", "MODE_WORKSPACE",
+        "-e", "MODE_API_TOKEN",
+        "-e", "MODE_API_SECRET",
+        "-v", "${HOME}/Downloads:/output",
+        "ccilabs/mode-mcp"
+      ],
+      "env": {
+        "MODE_WORKSPACE": "your-workspace",
+        "MODE_API_TOKEN": "your-token",
+        "MODE_API_SECRET": "your-secret"
+      }
+    }
+  }
+}
+```
+
+#### Using Node.js in a local MCP Server
+
+```json
+{
+  "mcpServers": {
+    "mode-analytics": {
+      "command": "node",
+      "args": ["/path/to/mode-mcp/dist/index.js"],
+      "env": {
+        "MODE_WORKSPACE": "your-workspace",
+        "MODE_API_TOKEN": "your-token",
+        "MODE_API_SECRET": "your-secret"
+      }
+    }
+  }
+}
+```
+
+#### Using npx (no install)
+
+```json
+{
+  "mcpServers": {
+    "mode-analytics": {
+      "command": "npx",
+      "args": ["-y", "@cci-labs/mode-mcp"],
+      "env": {
+        "MODE_WORKSPACE": "your-workspace",
+        "MODE_API_TOKEN": "your-token",
+        "MODE_API_SECRET": "your-secret"
+      }
+    }
+  }
+}
+```
+
+For more information: https://docs.windsurf.com/windsurf/mcp
+
+</details>
+
+## Tool Details
+
+<details>
+<summary id="mode_list_reports"><strong><code>mode_list_reports</code></strong></summary>
+
+Lists reports in the Mode workspace. When no space is specified, fetches reports across all spaces.
+
+**Parameters:**
+- `space_token` (optional) — filter reports by space/collection token
+- `filter` (optional) — filter string (e.g. timestamp-based)
+- `order` (optional) — `asc` or `desc`
+- `order_by` (optional) — `created_at` or `updated_at`
+
+**Returns:** Numbered list of reports with names, tokens, spaces, query counts, and last run timestamps.
+
+**Example prompts:**
+- "What reports are in our Mode workspace?"
+- "List all reports in the Data Science space"
+
+</details>
+
+<details>
+<summary id="mode_get_report"><strong><code>mode_get_report</code></strong></summary>
+
+Gets detailed information about a specific report.
+
+**Parameters:**
+- `report_token` (required) — the report token (found in Mode URLs or from `mode_list_reports`)
+
+**Returns:** Report name, description, query count, last run timestamp and token, space, and web URL.
+
+**Example prompts:**
+- "Show me details for report 578c18655469"
+- "What queries are in the Runner Dashboard report?"
+
+</details>
+
+<details>
+<summary id="mode_list_queries"><strong><code>mode_list_queries</code></strong></summary>
+
+Lists all queries within a report, including their full SQL content.
+
+**Parameters:**
+- `report_token` (required) — the report token
+
+**Returns:** Query names, tokens, raw SQL previews, data source IDs, and timestamps.
+
+**Example prompts:**
+- "Show me the SQL for all queries in report 578c18655469"
+- "What queries does the Runner Dashboard use?"
+
+</details>
+
+<details>
+<summary id="mode_run_report"><strong><code>mode_run_report</code></strong></summary>
+
+Triggers a new run of a Mode report. This is non-destructive — it executes the report's queries but does not modify the report itself.
+
+**Parameters:**
+- `report_token` (required) — the report token
+- `parameters` (optional) — key/value parameters to pass to the report run
+
+**Returns:** Run token and state. Use `mode_get_run_status` to poll for completion.
+
+**Example prompts:**
+- "Run report 578c18655469"
+- "Trigger the weekly metrics report"
+
+</details>
+
+<details>
+<summary id="mode_get_run_status"><strong><code>mode_get_run_status</code></strong></summary>
+
+Checks the status of a report run — whether it has completed, is still running, or failed.
+
+**Parameters:**
+- `report_token` (required) — the report token
+- `run_token` (required) — the run token returned by `mode_run_report`
+
+**Returns:** Run state, creation time, and completion time.
+
+</details>
+
+<details>
+<summary id="mode_get_query_results"><strong><code>mode_get_query_results</code></strong></summary>
+
+Downloads the results of a completed query run. Returns data as a markdown table and optionally saves a CSV file.
+
+**Parameters:**
+- `report_token` (required) — the report token
+- `run_token` (required) — the run token
+- `query_run_token` (required) — the query run token
+- `max_rows` (optional) — maximum rows to return (default: 100)
+- `output_dir` (optional) — directory to save results as CSV. If omitted, results are returned inline only.
+- `filename` (optional) — CSV filename (default: `query-results.csv`)
+
+**Returns:** Markdown table with row data. If `output_dir` is provided and writable, also saves the full CSV to disk.
+
+**Example prompts:**
+- "Get the results from the latest run of report 578c18655469"
+- "Download the query results as a CSV to /output"
+
+</details>
+
+<details>
+<summary id="mode_execute_and_fetch"><strong><code>mode_execute_and_fetch</code></strong></summary>
+
+The highest-value tool — runs a report, waits for completion (with progressive backoff polling), and returns the query results, all in a single call. Optionally saves results as CSV.
+
+**Parameters:**
+- `report_token` (required) — the report token
+- `query_index` (optional) — which query's results to return, 0-based (default: 0)
+- `parameters` (optional) — report parameters
+- `max_rows` (optional) — maximum rows to return (default: 100)
+- `timeout_seconds` (optional) — max seconds to wait (default: 300). Increase for reports with heavy queries.
+- `output_dir` (optional) — directory to save results as CSV. If omitted, results are returned inline only.
+- `filename` (optional) — CSV filename. Defaults to the report name (e.g. `runner-dashboard.csv`).
+
+**Returns:** Report and query name, markdown table of results, total row count, and run metadata. If `output_dir` is provided and writable, also saves the full CSV to disk.
+
+**Example prompts:**
+- "Run report 578c18655469 and show me the results"
+- "Execute the Runner Dashboard and save the results as CSV"
+
+</details>
+
+<details>
+<summary id="mode_list_report_runs"><strong><code>mode_list_report_runs</code></strong></summary>
+
+Lists past runs for a report with their status and timestamps. Useful for finding run tokens without triggering a new run.
+
+**Parameters:**
+- `report_token` (required) — the report token
+
+**Returns:** Numbered list of runs with tokens, states (succeeded/failed), and timestamps.
+
+**Example prompts:**
+- "Show me the past runs for report 578c18655469"
+- "Has the Runner Dashboard been run recently?"
+
+</details>
+
+<details>
+<summary id="mode_get_query_run"><strong><code>mode_get_query_run</code></strong></summary>
+
+Gets details on a specific query run, including state, timing, SQL, and error details if the query failed.
+
+**Parameters:**
+- `report_token` (required) — the report token
+- `run_token` (required) — the run token
+- `query_run_token` (required) — the query run token
+
+**Returns:** Query run state, query name, data source, timestamps, SQL preview, and error message if failed.
+
+**Example prompts:**
+- "Why did this query fail?"
+- "Show me the details of query run abc123"
+
+</details>
+
+<details>
+<summary id="mode_search_reports"><strong><code>mode_search_reports</code></strong></summary>
+
+Searches reports by name with case-insensitive substring matching. Searches across all spaces by default.
+
+**Parameters:**
+- `query` (required) — search string to match against report names
+- `space_token` (optional) — limit search to a specific space
+
+**Returns:** Numbered list of matching reports with tokens, spaces, and last run timestamps.
+
+**Example prompts:**
+- "Find reports about flaky tests"
+- "Search for 'runner' in our Mode reports"
+
+</details>
+
+<details>
+<summary id="mode_get_report_parameters"><strong><code>mode_get_report_parameters</code></strong></summary>
+
+Discovers what parameters a report accepts before running it. Inspects the last successful run's form fields for parameter names, types, defaults, last-used values, and available dropdown options. If no prior runs exist, falls back to scanning query SQL for `{{ template_variable }}` patterns.
+
+**Parameters:**
+- `report_token` (required) — the report token
+
+**Returns:** Parameter names, types (text, dropdown, etc.), default values, last-used values, and available options.
+
+**Example prompts:**
+- "What parameters does this report need?"
+- "Check the inputs for the Cost Optimization report before running it"
+- "Does report 3d3b95474b93 require any parameters?"
+
+> **Note:** Always call this before `mode_execute_and_fetch`, `mode_run_report`, or `mode_export_report` — reports run with default parameters rarely produce the desired results.
+
+</details>
+
+<details>
+<summary id="mode_list_spaces"><strong><code>mode_list_spaces</code></strong></summary>
+
+Lists all spaces (collections) in the workspace. Spaces organize reports into groups.
+
+**Parameters:**
+- `filter` (optional) — `all` (default) or `custom` (non-personal spaces only)
+
+**Returns:** Numbered list of spaces with tokens, types, and restricted status.
+
+**Example prompts:**
+- "What spaces are in our Mode workspace?"
+- "List all collections"
+
+</details>
+
+<details>
+<summary id="mode_list_data_sources"><strong><code>mode_list_data_sources</code></strong></summary>
+
+Lists all connected data sources (databases) in the workspace.
+
+**Parameters:** None.
+
+**Returns:** Numbered list of data sources with adapter types (e.g. Snowflake, Postgres), hosts, and databases.
+
+**Example prompts:**
+- "What databases are connected to Mode?"
+- "Show me our data sources"
+
+</details>
+
+<details>
+<summary id="mode_list_definitions"><strong><code>mode_list_definitions</code></strong></summary>
+
+Lists saved SQL definitions (reusable snippets/macros) available in the workspace.
+
+**Parameters:** None.
+
+**Returns:** Numbered list of definitions with SQL previews and associated data sources.
+
+**Example prompts:**
+- "What SQL definitions do we have?"
+- "Show me our saved SQL snippets"
+
+> **Note:** This endpoint may not be available on all Mode plan tiers.
+
+</details>
+
+<details>
+<summary id="mode_export_report"><strong><code>mode_export_report</code></strong></summary>
+
+Exports a report as PDF or CSV. For PDF, triggers generation with progressive backoff polling. For CSV, fetches raw query results. If `output_dir` is provided and writable, saves the file to disk.
+
+**Parameters:**
+- `report_token` (required) — the report token
+- `format` (required) — `pdf` for a rendered report with charts, `csv` for raw query data
+- `run_token` (optional) — the run token. If omitted, uses the last successful run.
+- `query_index` (optional) — for CSV: which query to export, 0-based (default: 0). Ignored for PDF.
+- `filename` (optional) — output filename (default: report name with `.pdf` or `.csv` extension)
+- `output_dir` (optional) — directory to save the file. If omitted or not writable, returns a download URL (PDF) or inline preview (CSV).
+
+**Returns:** Saved file path/size if written to disk, download URL for PDF, or inline CSV preview for small datasets.
+
+> **Note:** Always call `mode_get_report_parameters` first to check if the report requires parameters. If it does, run it with `mode_run_report` (passing the right parameters) and use the resulting `run_token` here.
+
+**Example prompts:**
+- "Export the Runner Dashboard as PDF"
+- "Download the Cost Optimization report as CSV for org infusionsoft"
+- "Get a PDF of report 3d3b95474b93 for billing org common-room"
+
+</details>
+
+## Configuration
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `MODE_WORKSPACE` | Yes | Your Mode workspace name (the slug in Mode URLs) |
+| `MODE_API_TOKEN` | Yes | API token from Mode |
+| `MODE_API_SECRET` | Yes | API secret from Mode |
+| `MODE_MAX_ROWS` | No | Max rows returned per query (default: `100`) |
+| `MODE_POLL_INTERVAL_MS` | No | Initial polling interval in ms (default: `2000`). Increases with progressive backoff. |
+| `MODE_POLL_TIMEOUT_MS` | No | Max time to wait for a run/export in ms (default: `300000` / 5 minutes) |
+| `MODE_BASE_URL` | No | Mode API base URL (default: `https://app.mode.com`) |
+| `MODE_MAX_OUTPUT_LENGTH` | No | Max characters in tool output before truncation (default: `50000`) |
+
+## CI/CD
+
+This project uses [CircleCI](https://circleci.com) for continuous integration and deployment.
+
+**Every push:**
+- **Lint** — TypeScript type checking + ESLint
+- **Test** — full test suite with coverage reporting (JUnit for Test Insights)
+- **Audit Dependencies** — npm audit + Trivy filesystem scan (vulns, secrets, misconfig, licenses) + SBOM generation
+- **Build Docker Image** — multi-arch (amd64 + arm64), pushed with SHA tags
+- **Test Docker Image** — dgoss container structure tests per architecture
+- **Scan Docker Image** — Trivy vulnerability + license scan per architecture
+
+**On `v*` tags (releases):**
+- **Publish Docker Image** — retags SHA images, creates multi-arch manifest with version + latest tags
+- **Publish npm Package** — publishes `@cci-labs/mode-mcp` to npm
+
+## Safety
+
+This server is **read-only by design**. It cannot create, modify, or delete any resources in Mode. The only "write" operations are:
+- **Triggering report runs** — executes existing queries but does not change the report
+- **Triggering PDF exports** — generates a PDF from an existing run
+
+## Troubleshooting
+
+<details>
+<summary><strong>Authentication Issues</strong></summary>
+
+- **401 Unauthorized:** Verify your `MODE_API_TOKEN` and `MODE_API_SECRET` at `app.mode.com/{workspace}/settings/api_tokens`
+- **403 Forbidden:** Your token may lack permission. Workspace admin tokens are required for some endpoints.
+- **"account not found":** Double-check `MODE_WORKSPACE` — it should be the slug from your Mode URL (e.g. `my-company`, not the display name).
+
+</details>
+
+<details>
+<summary><strong>Rate Limiting</strong></summary>
+
+Mode's API allows 40 requests per 10-second window (~4 req/sec). The server automatically:
+- Throttles to stay under the limit (35 req/10s with headroom)
+- Reads `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers from every response
+- Proactively slows down when remaining requests < 5
+- Retries on 429 responses using the server-provided reset time
+- Retries transient 5xx errors up to 3 times with exponential backoff
+
+</details>
+
+<details>
+<summary><strong>Timeouts and Long-Running Reports</strong></summary>
+
+The server uses **progressive backoff** when polling for report runs and PDF exports:
+- Starts polling every 2 seconds
+- Increases interval by 1.5x each poll (2s → 3s → 4.5s → 6.75s → 10s → 15s)
+- Caps at 15-second intervals
+- Default maximum wait: 5 minutes (`MODE_POLL_TIMEOUT_MS=300000`)
+
+For reports with heavy queries (e.g. large Snowflake warehouses), you can:
+- Pass a higher `timeout_seconds` to `mode_execute_and_fetch` (e.g. `600` for 10 minutes)
+- Increase the global default with `MODE_POLL_TIMEOUT_MS`
+- Use `mode_run_report` + `mode_get_run_status` to poll manually
+
+</details>
+
+<details>
+<summary><strong>Docker Issues</strong></summary>
+
+- **Environment variables not reaching container:** Ensure you have both the `-e VAR_NAME` in `args` AND the value in `env`. The MCP client sets the env var, and `-e` forwards it into the container.
+- **Image not found:** Build with `docker build -t ccilabs/mode-mcp .` from the project root.
+- **Network errors inside container:** Docker Desktop must be running. On macOS, ensure Docker has network access.
+- **File downloads not working:** When running in Docker, the `output_dir` parameter writes inside the container. To save files to your host machine, add a volume mount to your Docker args:
+  ```json
+  "args": [
+    "run", "--rm", "-i",
+    "-e", "MODE_WORKSPACE",
+    "-e", "MODE_API_TOKEN",
+    "-e", "MODE_API_SECRET",
+    "-v", "/Users/you/Downloads:/output",
+    "ccilabs/mode-mcp"
+  ]
+  ```
+  Then use `/output` as the `output_dir`. Without a mount, the tools still return download URLs as a fallback.
+
+</details>
+
+<details>
+<summary><strong>Common Errors</strong></summary>
+
+- **"Report not found" (404):** The report token may be wrong. Use `mode_list_reports` or `mode_search_reports` to find valid tokens. Report tokens are the alphanumeric strings in Mode URLs (e.g. `578c18655469`).
+- **Empty results:** The report may not have been run recently. Use `mode_execute_and_fetch` to trigger a fresh run.
+- **Polling timeout:** Increase `timeout_seconds` for long-running reports, or increase `MODE_POLL_TIMEOUT_MS`.
+- **"PDF export is not available":** The export may have expired. Run the report again with `mode_run_report`, then export the new run.
+
+</details>
+
+# Development
+
+## Getting Started
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/AwesomeCICD/mode-mcp.git
+   cd mode-mcp
+   ```
+
+2. Install dependencies:
+
+   ```bash
+   npm install
+   ```
+
+3. Build the project:
+
+   ```bash
+   npm run build
+   ```
+
+4. Create a `.env` file:
+
+   ```
+   MODE_WORKSPACE=your-workspace
+   MODE_API_TOKEN=your-token
+   MODE_API_SECRET=your-secret
+   ```
+
+5. Run linting and tests:
+
+   ```bash
+   npm run lint    # TypeScript type check + ESLint
+   npm test        # Run all tests
+   ```
+
+## Building Docker Container
+
+```bash
+docker build -t ccilabs/mode-mcp .
+```
+
+To test the container:
+
+```bash
+export MODE_WORKSPACE=your-workspace
+export MODE_API_TOKEN=your-token
+export MODE_API_SECRET=your-secret
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' \
+  | docker run --rm -i -e MODE_WORKSPACE -e MODE_API_TOKEN -e MODE_API_SECRET ccilabs/mode-mcp
+```
+
+## Project Structure
+
+```
+src/
+├── index.ts              # MCP server entry point (stdio transport)
+├── config.ts             # Environment variable loading and validation
+├── mode-client.ts        # Mode API HTTP client (auth, rate limiting, retries, HAL+JSON)
+├── file-utils.ts         # File saving utilities (slugify, trySaveFile)
+├── truncate.ts           # Output truncation for LLM context limits
+├── utils.ts              # Shared formatters (dates, errors, markdown tables, CSV parsing)
+├── __tests__/            # Unit tests (vitest, all mocked — no live API needed)
+└── tools/
+    ├── analytics.ts      # Report, query, run, search, filter, and chart tools
+    ├── management.ts     # Spaces, data sources, definitions, schedules, subscriptions, audit logs
+    ├── datasets.ts       # Dataset discovery and field inspection tools
+    └── distribution.ts   # PDF and CSV export tools
+docs/
+├── MCP_TEST_PLAYBOOK.md  # Manual integration test prompts (34 tests across 9 categories)
+```
+
+## Testing
+
+```bash
+npm test                    # Run all tests
+npm run test:watch          # Watch mode
+npx vitest run --coverage   # Run with coverage report
+```
+
+129+ tests covering all 24 tools, CSV parsing, Mode client (auth, rate limiting, retries, polling), config loading, file utilities, and output formatting. All tests use mocked API responses — no live credentials required.
+
+### Integration Testing
+
+For manual integration testing with a live MCP connection, see the [MCP Test Playbook](docs/MCP_TEST_PLAYBOOK.md) — 34 structured prompts across 9 categories that validate tool calls, chaining, error handling, and read-only safety.
+
+### Docker Testing
+
+Container structure tests use [dgoss](https://github.com/goss-org/goss/tree/master/extras/dgoss):
+
+```bash
+# Requires goss/dgoss installed and a Linux goss binary for container exec
+dgoss run --entrypoint /bin/sh ccilabs/mode-mcp:test -c "sleep 30"
+```