@cci-labs/mode-mcp 1.0.1

package/dist/tools/analytics.js

@@ -0,0 +1,707 @@
+import { z } from "zod";
+import { trySaveFile, slugify } from "../file-utils.js";
+import { truncateOutput } from "../truncate.js";
+import { formatError, formatDate, formatBytes, markdownTable, parseCSVLine } from "../utils.js";
+export function registerAnalyticsTools(server, client, config) {
+    // --- mode_list_reports ---
+    server.tool("mode_list_reports", "List reports in the Mode workspace. Can filter by space. Returns report names, tokens, and last run timestamps.", {
+        space_token: z.string().optional().describe("Filter reports by space/collection token"),
+        filter: z.string().optional().describe("Filter string (e.g. timestamp-based)"),
+        order: z.enum(["asc", "desc"]).optional().describe("Sort order"),
+        order_by: z.enum(["created_at", "updated_at"]).optional().describe("Sort field"),
+    }, async ({ space_token, filter, order, order_by }) => {
+        try {
+            const params = {};
+            if (filter)
+                params.filter = filter;
+            if (order)
+                params.order = order;
+            if (order_by)
+                params.order_by = order_by;
+            const path = space_token
+                ? `/spaces/${space_token}/reports`
+                : `/reports`;
+            let allReports = [];
+            if (!space_token) {
+                const spaceParams = { ...params, filter: params.filter ?? "all" };
+                const spacesResp = await client.get("/spaces", { params: spaceParams });
+                const spaces = client.getEmbedded(spacesResp, "spaces");
+                // Batch spaces 5 at a time for parallelism
+                for (let i = 0; i < spaces.length; i += 5) {
+                    const batch = spaces.slice(i, i + 5);
+                    const results = await Promise.allSettled(batch.map(async (space) => {
+                        const spaceToken = space.token;
+                        const spaceName = space.name;
+                        const reportsResp = await client.get(`/spaces/${spaceToken}/reports`, { params });
+                        const reports = client.getEmbedded(reportsResp, "reports");
+                        return reports.map((r) => ({
+                            token: r.token,
+                            name: r.name,
+                            description: r.description,
+                            space: spaceName,
+                            space_token: spaceToken,
+                            created_at: r.created_at,
+                            updated_at: r.updated_at,
+                            last_successfully_run_at: r.last_successfully_run_at,
+                            query_count: r.query_count,
+                            is_archived: r.archived,
+                        }));
+                    }));
+                    for (const result of results) {
+                        if (result.status === "fulfilled") {
+                            allReports.push(...result.value);
+                        }
+                    }
+                }
+            }
+            else {
+                const resp = await client.get(path, { params });
+                allReports = client.getEmbedded(resp, "reports").map((r) => ({
+                    token: r.token,
+                    name: r.name,
+                    description: r.description,
+                    space: space_token,
+                    created_at: r.created_at,
+                    updated_at: r.updated_at,
+                    last_successfully_run_at: r.last_successfully_run_at,
+                    query_count: r.query_count,
+                    is_archived: r.archived,
+                }));
+            }
+            if (allReports.length === 0) {
+                const msg = space_token
+                    ? `No reports found in space ${space_token}.`
+                    : "No reports found across any accessible spaces in this workspace.";
+                return { content: [{ type: "text", text: msg }] };
+            }
+            const text = truncateOutput(formatReportList(allReports) + "\n\nNext steps: Use mode_get_report with a report token for details, or mode_search_reports to filter by name.");
+            return { content: [{ type: "text", text }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: formatError(e) }], isError: true };
+        }
+    });
+    // --- mode_get_report ---
+    server.tool("mode_get_report", "Get details of a specific Mode report including its queries, data sources, and last run status.", {
+        report_token: z.string().describe("The report token (e.g. '578c18655469')"),
+    }, async ({ report_token }) => {
+        try {
+            const report = await client.get(`/reports/${report_token}`);
+            const webUrl = client.getLink(report, "web") ?? "";
+            const lines = [
+                `Report: ${report.name ?? "Untitled"}`,
+                `Token: ${report.token}`,
+                `Space: ${report.space_token ?? "N/A"}`,
+                `Queries: ${report.query_count ?? 0}`,
+                `Created: ${formatDate(report.created_at)}`,
+                `Last run: ${formatDate(report.last_successfully_run_at)}`,
+                `Last run token: ${report.last_successful_run_token ?? "N/A"}`,
+                `Archived: ${report.archived ? "yes" : "no"}`,
+            ];
+            if (report.description) {
+                lines.push(`Description: ${report.description}`);
+            }
+            if (webUrl) {
+                lines.push(`URL: ${webUrl}`);
+            }
+            return { content: [{ type: "text", text: truncateOutput(lines.join("\n")) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: formatError(e) }], isError: true };
+        }
+    });
+    // --- mode_list_queries ---
+    server.tool("mode_list_queries", "List all queries within a Mode report, including their SQL content and data sources.", {
+        report_token: z.string().describe("The report token"),
+    }, async ({ report_token }) => {
+        try {
+            const resp = await client.get(`/reports/${report_token}/queries`);
+            const queries = client.getEmbedded(resp, "queries");
+            if (queries.length === 0) {
+                return { content: [{ type: "text", text: `No queries found in report ${report_token}. The report may be empty or still being set up.` }] };
+            }
+            const lines = [`Found ${queries.length} ${queries.length === 1 ? "query" : "queries"}:`, ""];
+            queries.forEach((q, i) => {
+                lines.push(`${i + 1}. ${q.name ?? "Untitled"} (token: ${q.token})`);
+                lines.push(`   Data source ID: ${q.data_source_id ?? "N/A"}`);
+                lines.push(`   Updated: ${formatDate(q.updated_at)}`);
+                const sql = q.raw_query;
+                if (sql) {
+                    const preview = sql.length > 200 ? sql.slice(0, 200) + "..." : sql;
+                    lines.push(`   SQL: ${preview}`);
+                }
+                lines.push("");
+            });
+            return { content: [{ type: "text", text: truncateOutput(lines.join("\n").trimEnd()) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: formatError(e) }], isError: true };
+        }
+    });
+    // --- mode_run_report ---
+    server.tool("mode_run_report", "Trigger a new run of a Mode report. Returns a run token for polling status. This is non-destructive — it does not modify the report. IMPORTANT: Call mode_get_report_parameters first to check if the report requires parameters — running with defaults rarely produces the desired results.", {
+        report_token: z.string().describe("The report token"),
+        parameters: z.record(z.string(), z.unknown()).optional().describe("Optional report parameters to pass to the run"),
+    }, async ({ report_token, parameters }) => {
+        try {
+            const body = {};
+            if (parameters) {
+                body.parameters = parameters;
+            }
+            const run = await client.post(`/reports/${report_token}/runs`, Object.keys(body).length > 0 ? body : undefined);
+            const lines = [
+                `Report run triggered.`,
+                ``,
+                `Run token: ${run.token}`,
+                `State: ${run.state}`,
+                `Created: ${formatDate(run.created_at)}`,
+                ``,
+                `Use mode_get_run_status to poll for completion, or mode_execute_and_fetch to wait for results automatically.`,
+            ];
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: formatError(e) }], isError: true };
+        }
+    });
+    // --- mode_get_run_status ---
+    server.tool("mode_get_run_status", "Check whether a Mode report run has completed, is still running, or failed.", {
+        report_token: z.string().describe("The report token"),
+        run_token: z.string().describe("The run token returned by mode_run_report"),
+    }, async ({ report_token, run_token }) => {
+        try {
+            const run = await client.get(`/reports/${report_token}/runs/${run_token}`);
+            const lines = [
+                `Run: ${run.token}`,
+                `State: ${run.state}`,
+                `Created: ${formatDate(run.created_at)}`,
+                `Completed: ${formatDate(run.completed_at)}`,
+            ];
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: formatError(e) }], isError: true };
+        }
+    });
+    // --- mode_get_query_results ---
+    server.tool("mode_get_query_results", "Download the results of a completed query run. Returns data as a markdown table and optionally saves a CSV file if output_dir is provided.", {
+        report_token: z.string().describe("The report token"),
+        run_token: z.string().describe("The run token"),
+        query_run_token: z.string().describe("The query run token"),
+        max_rows: z.number().optional().describe(`Maximum rows to return (default: ${100})`),
+        output_dir: z.string().optional().describe("Directory to save results as CSV. If omitted, results are returned inline only."),
+        filename: z.string().optional().describe("CSV filename (e.g. 'results.csv'). Defaults to 'query-results.csv'."),
+    }, async ({ report_token, run_token, query_run_token, max_rows, output_dir, filename }) => {
+        try {
+            const limit = max_rows ?? config.maxRowsDefault;
+            const csv = await client.get(`/reports/${report_token}/runs/${run_token}/query_runs/${query_run_token}/results/content.csv`, { accept: "text/csv" });
+            const cleanCsv = csv.replace(/\r\n/g, "\n").trim();
+            if (!cleanCsv) {
+                return { content: [{ type: "text", text: "Query returned no data. The response was empty." }] };
+            }
+            const csvLines = cleanCsv.split("\n");
+            if (csvLines.length <= 1) {
+                return { content: [{ type: "text", text: "Query returned no rows. The query completed successfully but produced an empty result set." }] };
+            }
+            const headers = parseCSVLine(csvLines[0]);
+            if (headers.every((h) => h.trim() === "")) {
+                return { content: [{ type: "text", text: "Query returned malformed CSV data (no valid column headers)." }], isError: true };
+            }
+            const totalRows = csvLines.length - 1;
+            const dataLines = csvLines.slice(1, limit + 1);
+            const rows = dataLines.map((line) => {
+                const values = parseCSVLine(line);
+                const row = {};
+                headers.forEach((h, i) => {
+                    row[h] = values[i] ?? "";
+                });
+                return row;
+            });
+            const showing = rows.length < totalRows ? ` (showing ${rows.length})` : "";
+            const output = [
+                `Query run: ${query_run_token}`,
+                `Rows: ${totalRows} total${showing}`,
+                ``,
+                markdownTable(headers, rows),
+            ];
+            // Try saving CSV if output_dir provided
+            const outputFilename = filename ?? "query-results.csv";
+            const saveResult = await trySaveFile(cleanCsv, outputFilename, output_dir);
+            if (saveResult.saved) {
+                output.push("");
+                output.push(`Saved to: ${saveResult.path} (${formatBytes(saveResult.size_bytes)})`);
+            }
+            else if (output_dir) {
+                output.push("");
+                output.push(`Save failed: Could not write to ${output_dir}`);
+            }
+            return { content: [{ type: "text", text: truncateOutput(output.join("\n")) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: formatError(e) }], isError: true };
+        }
+    });
+    // --- mode_execute_and_fetch ---
+    server.tool("mode_execute_and_fetch", "Run a Mode report, wait for completion, and return the query results — all in one call. This is the highest-value tool for getting data from Mode. Optionally saves results as CSV. IMPORTANT: Call mode_get_report_parameters first to check if the report requires parameters — running with defaults rarely produces the desired results.", {
+        report_token: z.string().describe("The report token"),
+        query_index: z.number().optional().describe("Which query's results to return (0-based, default: 0 for the first query)"),
+        parameters: z.record(z.string(), z.unknown()).optional().describe("Optional report parameters"),
+        max_rows: z.number().optional().describe("Maximum rows to return (default: 100)"),
+        timeout_seconds: z.number().optional().describe("Max seconds to wait for completion (default: 300). Increase for reports with heavy queries."),
+        output_dir: z.string().optional().describe("Directory to save results as CSV. If omitted, results are returned inline only."),
+        filename: z.string().optional().describe("CSV filename. Defaults to the report name slugified (e.g. 'runner-dashboard.csv')."),
+    }, async ({ report_token, query_index, parameters, max_rows, timeout_seconds, output_dir, filename }) => {
+        try {
+            const limit = max_rows ?? config.maxRowsDefault;
+            const timeoutMs = (timeout_seconds ?? 300) * 1000;
+            const qIdx = query_index ?? 0;
+            if (qIdx < 0) {
+                return {
+                    content: [{ type: "text", text: "query_index must be >= 0." }],
+                    isError: true,
+                };
+            }
+            // Get report name for default filename
+            const report = await client.get(`/reports/${report_token}`);
+            const reportName = report.name ?? "report";
+            const queryCount = report.query_count;
+            if (queryCount === 0) {
+                return {
+                    content: [{ type: "text", text: `Report "${reportName}" has no queries. Add queries in the Mode editor before running.` }],
+                    isError: true,
+                };
+            }
+            // 1. Trigger run
+            const body = {};
+            if (parameters)
+                body.parameters = parameters;
+            const run = await client.post(`/reports/${report_token}/runs`, Object.keys(body).length > 0 ? body : undefined);
+            const runToken = run.token;
+            // 2. Poll for completion
+            await client.pollUntilComplete(`/reports/${report_token}/runs/${runToken}`, timeoutMs);
+            // 3. Get query runs
+            const qrResp = await client.get(`/reports/${report_token}/runs/${runToken}/query_runs`);
+            const queryRuns = client.getEmbedded(qrResp, "query_runs");
+            if (queryRuns.length === 0) {
+                return {
+                    content: [{ type: "text", text: "Report run completed but no query runs found." }],
+                    isError: true,
+                };
+            }
+            if (qIdx >= queryRuns.length) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `query_index ${qIdx} is out of range. This report has ${queryRuns.length} queries (0-${queryRuns.length - 1}). Use mode_list_queries to see available queries.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const queryRun = queryRuns[qIdx];
+            const qrToken = queryRun.token;
+            const queryName = queryRun.query_name ?? `Query ${qIdx}`;
+            // 4. Fetch results
+            const csv = await client.get(`/reports/${report_token}/runs/${runToken}/query_runs/${qrToken}/results/content.csv`, { accept: "text/csv" });
+            const cleanCsv = csv.replace(/\r\n/g, "\n").trim();
+            if (!cleanCsv) {
+                return {
+                    content: [{ type: "text", text: `Report "${reportName}" query "${queryName}" returned no data. The response was empty.` }],
+                };
+            }
+            const csvLines = cleanCsv.split("\n");
+            const headers = parseCSVLine(csvLines[0] ?? "");
+            if (headers.every((h) => h.trim() === "")) {
+                return {
+                    content: [{ type: "text", text: `Report "${reportName}" query "${queryName}" returned malformed CSV data (no valid column headers).` }],
+                    isError: true,
+                };
+            }
+            const totalRows = csvLines.length - 1;
+            if (totalRows === 0) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Report: ${reportName}\nQuery: ${queryName}\nRun token: ${runToken}\n\nQuery returned no rows. The query completed successfully but produced an empty result set.`,
+                        }],
+                };
+            }
+            const dataLines = csvLines.slice(1, limit + 1);
+            const rows = dataLines.map((line) => {
+                const values = parseCSVLine(line);
+                const row = {};
+                headers.forEach((h, i) => {
+                    row[h] = values[i] ?? "";
+                });
+                return row;
+            });
+            const showing = rows.length < totalRows ? ` (showing ${rows.length})` : "";
+            const output = [
+                `Report: ${reportName}`,
+                `Query: ${queryName}`,
+                `Run token: ${runToken}`,
+                `Rows: ${totalRows} total${showing}`,
+                ``,
+                markdownTable(headers, rows),
+            ];
+            // Try saving CSV if output_dir provided
+            const outputFilename = filename ?? `${slugify(reportName)}.csv`;
+            const saveResult = await trySaveFile(cleanCsv, outputFilename, output_dir);
+            if (saveResult.saved) {
+                output.push("");
+                output.push(`Saved to: ${saveResult.path} (${formatBytes(saveResult.size_bytes)})`);
+            }
+            else if (output_dir) {
+                output.push("");
+                output.push(`Save failed: Could not write to ${output_dir}`);
+            }
+            return { content: [{ type: "text", text: truncateOutput(output.join("\n")) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: formatError(e) }], isError: true };
+        }
+    });
+    // --- mode_list_report_runs ---
+    server.tool("mode_list_report_runs", "List past runs for a Mode report. Returns run tokens, states, and timestamps.", {
+        report_token: z.string().describe("The report token"),
+    }, async ({ report_token }) => {
+        try {
+            const resp = await client.get(`/reports/${report_token}/runs`);
+            const runs = client.getEmbedded(resp, "report_runs");
+            if (runs.length === 0) {
+                return {
+                    content: [{ type: "text", text: "No runs found for this report. Use mode_run_report to trigger a new run." }],
+                };
+            }
+            const lines = [`Found ${runs.length} ${runs.length === 1 ? "run" : "runs"}:`, ""];
+            runs.forEach((r, i) => {
+                lines.push(`${i + 1}. Run ${r.token} — ${r.state}`);
+                lines.push(`   Created: ${formatDate(r.created_at)}`);
+                if (r.completed_at) {
+                    lines.push(`   Completed: ${formatDate(r.completed_at)}`);
+                }
+                lines.push("");
+            });
+            lines.push("");
+            lines.push("Next steps: Use mode_get_query_results with a run token to fetch data, or mode_get_run_status to check a specific run.");
+            return { content: [{ type: "text", text: truncateOutput(lines.join("\n").trimEnd()) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: formatError(e) }], isError: true };
+        }
+    });
+    // --- mode_get_query_run ---
+    server.tool("mode_get_query_run", "Get details on a specific query run, including state, error details if failed, timing, and data source.", {
+        report_token: z.string().describe("The report token"),
+        run_token: z.string().describe("The run token"),
+        query_run_token: z.string().describe("The query run token"),
+    }, async ({ report_token, run_token, query_run_token }) => {
+        try {
+            const qr = await client.get(`/reports/${report_token}/runs/${run_token}/query_runs/${query_run_token}`);
+            const lines = [
+                `Query run: ${qr.token}`,
+                `State: ${qr.state}`,
+                `Query name: ${qr.query_name ?? "N/A"}`,
+                `Data source ID: ${qr.data_source_id ?? "N/A"}`,
+                `Created: ${formatDate(qr.created_at)}`,
+                `Completed: ${formatDate(qr.completed_at)}`,
+            ];
+            if (qr.raw_source) {
+                const sql = String(qr.raw_source);
+                const preview = sql.length > 300 ? sql.slice(0, 300) + "..." : sql;
+                lines.push(`SQL: ${preview}`);
+            }
+            if (qr.state === "failed") {
+                if (qr.error_message)
+                    lines.push(`Error: ${qr.error_message}`);
+                if (qr.error_id)
+                    lines.push(`Error ID: ${qr.error_id}`);
+                lines.push("");
+                lines.push("Use mode_list_queries to check the SQL, or mode_run_report to retry.");
+            }
+            return { content: [{ type: "text", text: truncateOutput(lines.join("\n")) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: formatError(e) }], isError: true };
+        }
+    });
+    // --- mode_search_reports ---
+    server.tool("mode_search_reports", "Search reports by name (case-insensitive substring match). Optionally filter to a specific space.", {
+        query: z.string().describe("Search string to match against report names"),
+        space_token: z.string().optional().describe("Limit search to a specific space token"),
+    }, async ({ query, space_token }) => {
+        try {
+            const searchLower = query.toLowerCase();
+            const allReports = [];
+            if (space_token) {
+                const reportsResp = await client.get(`/spaces/${space_token}/reports`);
+                const reports = client.getEmbedded(reportsResp, "reports");
+                for (const r of reports) {
+                    allReports.push({
+                        token: r.token,
+                        name: r.name,
+                        description: r.description,
+                        space: space_token,
+                        space_token,
+                        last_successfully_run_at: r.last_successfully_run_at,
+                        query_count: r.query_count,
+                        is_archived: r.archived,
+                    });
+                }
+            }
+            else {
+                const spacesResp = await client.get("/spaces", { params: { filter: "all" } });
+                const spaces = client.getEmbedded(spacesResp, "spaces");
+                // Batch spaces 5 at a time for parallelism
+                for (let i = 0; i < spaces.length; i += 5) {
+                    const batch = spaces.slice(i, i + 5);
+                    const results = await Promise.allSettled(batch.map(async (space) => {
+                        const sToken = space.token;
+                        const sName = space.name;
+                        const reportsResp = await client.get(`/spaces/${sToken}/reports`);
+                        const reports = client.getEmbedded(reportsResp, "reports");
+                        return reports.map((r) => ({
+                            token: r.token,
+                            name: r.name,
+                            description: r.description,
+                            space: sName,
+                            space_token: sToken,
+                            last_successfully_run_at: r.last_successfully_run_at,
+                            query_count: r.query_count,
+                            is_archived: r.archived,
+                        }));
+                    }));
+                    for (const result of results) {
+                        if (result.status === "fulfilled") {
+                            allReports.push(...result.value);
+                        }
+                    }
+                }
+            }
+            const matches = allReports.filter((r) => {
+                const name = String(r.name ?? "").toLowerCase();
+                return name.includes(searchLower);
+            });
+            if (matches.length === 0) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `No reports found matching "${query}". Use mode_list_reports to see all available reports.`,
+                        }],
+                };
+            }
+            const text = truncateOutput(formatReportList(matches, `Matching "${query}"`) + "\n\nNext steps: Use mode_get_report with a report token to see details, then mode_execute_and_fetch to run it.");
+            return { content: [{ type: "text", text }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: formatError(e) }], isError: true };
+        }
+    });
+    // --- mode_get_report_parameters ---
+    server.tool("mode_get_report_parameters", "Discover what parameters a report accepts before running it. Returns parameter names, types, default values, and available options. IMPORTANT: Always call this before mode_execute_and_fetch or mode_run_report to check if the report requires parameters — reports run with defaults rarely produce the desired results.", {
+        report_token: z.string().describe("The report token"),
+    }, async ({ report_token }) => {
+        try {
+            // Get report details
+            const report = await client.get(`/reports/${report_token}`);
+            const reportName = report.name ?? "Untitled";
+            const lastRunToken = report.last_successful_run_token;
+            if (!lastRunToken) {
+                // No runs yet — try to discover params from SQL
+                const queriesResp = await client.get(`/reports/${report_token}/queries`);
+                const queries = client.getEmbedded(queriesResp, "queries");
+                const allParams = [];
+                for (const q of queries) {
+                    const sql = q.raw_query ?? "";
+                    const matches = sql.match(/\{\{(\w+)\}\}/g);
+                    if (matches) {
+                        for (const m of matches) {
+                            const name = m.replace(/\{\{|\}\}/g, "").trim();
+                            if (!allParams.includes(name))
+                                allParams.push(name);
+                        }
+                    }
+                }
+                if (allParams.length === 0) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `Report: ${reportName}\n\nThis report has no parameters. It can be run without any additional input.`,
+                            }],
+                    };
+                }
+                const lines = [
+                    `Report: ${reportName}`,
+                    "",
+                    `Found ${allParams.length} ${allParams.length === 1 ? "parameter" : "parameters"} in query SQL (no prior runs to get defaults from):`,
+                    "",
+                ];
+                allParams.forEach((p, i) => {
+                    lines.push(`${i + 1}. ${p} (discovered from SQL template)`);
+                });
+                lines.push("");
+                lines.push("Run the report with mode_run_report or mode_execute_and_fetch, passing these as parameters.");
+                return { content: [{ type: "text", text: truncateOutput(lines.join("\n")) }] };
+            }
+            // Get form fields from the last successful run
+            const run = await client.get(`/reports/${report_token}/runs/${lastRunToken}`);
+            const formFields = run.form_fields ?? [];
+            const parameters = run.parameters ?? {};
+            if (formFields.length === 0 && Object.keys(parameters).length === 0) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Report: ${reportName}\n\nThis report has no parameters. It can be run without any additional input.`,
+                        }],
+                };
+            }
+            const lines = [
+                `Report: ${reportName}`,
+                "",
+            ];
+            if (formFields.length > 0) {
+                lines.push(`${formFields.length} ${formFields.length === 1 ? "parameter" : "parameters"}:`);
+                lines.push("");
+                for (const field of formFields) {
+                    const name = field.name;
+                    const label = field.human_name ?? field.label ?? name;
+                    const type = field.type ?? "text";
+                    const defaultVal = field.default;
+                    const currentVal = field.value;
+                    const options = field.options ?? [];
+                    lines.push(`  ${label}`);
+                    lines.push(`    Name: ${name}`);
+                    lines.push(`    Type: ${type}`);
+                    if (defaultVal !== undefined && defaultVal !== null) {
+                        lines.push(`    Default: ${defaultVal}`);
+                    }
+                    if (currentVal !== undefined && currentVal !== null) {
+                        lines.push(`    Last used: ${currentVal}`);
+                    }
+                    if (options.length > 0) {
+                        const optionStrs = options.slice(0, 20).map((o) => Array.isArray(o) ? String(o[1] ?? o[0]) : String(o));
+                        lines.push(`    Options: ${optionStrs.join(", ")}${options.length > 20 ? ` ... (${options.length} total)` : ""}`);
+                    }
+                    lines.push("");
+                }
+            }
+            else {
+                // No form fields but has parameters — show from the parameters object
+                const paramKeys = Object.keys(parameters);
+                lines.push(`${paramKeys.length} ${paramKeys.length === 1 ? "parameter" : "parameters"}:`);
+                lines.push("");
+                for (const key of paramKeys) {
+                    lines.push(`  ${key}`);
+                    lines.push(`    Last used: ${parameters[key]}`);
+                    lines.push("");
+                }
+            }
+            lines.push("Pass these as the `parameters` argument to mode_execute_and_fetch or mode_run_report.");
+            lines.push(`Example: {"${formFields[0]?.name ?? Object.keys(parameters)[0] ?? "param"}": "your_value"}`);
+            return { content: [{ type: "text", text: truncateOutput(lines.join("\n")) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: formatError(e) }], isError: true };
+        }
+    });
+    // --- mode_list_report_filters ---
+    server.tool("mode_list_report_filters", "List filters (interactive parameters) configured on a Mode report. Shows filter names, types, and available options.", {
+        report_token: z.string().describe("The report token"),
+    }, async ({ report_token }) => {
+        try {
+            const resp = await client.get(`/reports/${report_token}/filters`);
+            const filters = client.getEmbedded(resp, "report_filters");
+            if (filters.length === 0) {
+                return {
+                    content: [{ type: "text", text: `No filters found for report ${report_token}. The report does not have interactive filter controls.` }],
+                };
+            }
+            const lines = [`Found ${filters.length} ${filters.length === 1 ? "filter" : "filters"}:`, ""];
+            filters.forEach((f, i) => {
+                const name = f.name ?? "Untitled";
+                const token = f.token ?? "unknown";
+                lines.push(`${i + 1}. ${name} (token: ${token})`);
+                if (f.filter_type)
+                    lines.push(`   Filter type: ${f.filter_type}`);
+                if (f.control_type)
+                    lines.push(`   Control type: ${f.control_type}`);
+                if (f.data_type)
+                    lines.push(`   Data type: ${f.data_type}`);
+                const options = f.options;
+                if (options && options.length > 0) {
+                    const preview = options.slice(0, 10).map(String).join(", ");
+                    lines.push(`   Options: ${preview}${options.length > 10 ? ` ... (${options.length} total)` : ""}`);
+                }
+                lines.push("");
+            });
+            return { content: [{ type: "text", text: truncateOutput(lines.join("\n").trimEnd()) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: formatError(e) }], isError: true };
+        }
+    });
+    // --- mode_list_report_charts ---
+    server.tool("mode_list_report_charts", "List charts (visualizations) in a specific query of a Mode report. Shows chart types and tokens.", {
+        report_token: z.string().describe("The report token"),
+        query_token: z.string().describe("The query token"),
+    }, async ({ report_token, query_token }) => {
+        try {
+            const resp = await client.get(`/reports/${report_token}/queries/${query_token}/charts`);
+            const charts = client.getEmbedded(resp, "charts");
+            if (charts.length === 0) {
+                return {
+                    content: [{ type: "text", text: `No charts found for query ${query_token} in report ${report_token}.` }],
+                };
+            }
+            const lines = [`Found ${charts.length} ${charts.length === 1 ? "chart" : "charts"}:`, ""];
+            charts.forEach((c, i) => {
+                const token = c.token ?? "unknown";
+                lines.push(`${i + 1}. Chart ${token}`);
+                const view = c.view;
+                if (view?.selectedChart) {
+                    lines.push(`   Type: ${view.selectedChart}`);
+                }
+                if (c.created_at)
+                    lines.push(`   Created: ${formatDate(c.created_at)}`);
+                lines.push("");
+            });
+            return { content: [{ type: "text", text: truncateOutput(lines.join("\n").trimEnd()) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: formatError(e) }], isError: true };
+        }
+    });
+}
+/** Shared formatter for report lists */
+function formatReportList(reports, label) {
+    const header = label
+        ? `Found ${reports.length} ${reports.length === 1 ? "report" : "reports"} ${label}:`
+        : `Found ${reports.length} ${reports.length === 1 ? "report" : "reports"}:`;
+    const lines = [header, ""];
+    reports.forEach((r, i) => {
+        const name = r.name ?? "Untitled";
+        const token = r.token ?? "unknown";
+        lines.push(`${i + 1}. ${name} (token: ${token})`);
+        const details = [];
+        if (r.space)
+            details.push(`Space: ${r.space}`);
+        if (r.query_count !== undefined && r.query_count !== null)
+            details.push(`Queries: ${r.query_count}`);
+        if (r.last_successfully_run_at)
+            details.push(`Last run: ${formatDate(r.last_successfully_run_at)}`);
+        if (r.is_archived)
+            details.push("ARCHIVED");
+        if (details.length > 0) {
+            lines.push(`   ${details.join(" | ")}`);
+        }
+        if (r.description) {
+            const desc = String(r.description);
+            if (desc.length > 0) {
+                lines.push(`   ${desc.length > 120 ? desc.slice(0, 120) + "..." : desc}`);
+            }
+        }
+        lines.push("");
+    });
+    return lines.join("\n").trimEnd();
+}