@cci-labs/mode-mcp 1.0.1

package/dist/tools/datasets.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ModeClient } from "../mode-client.js";
+import { ModeConfig } from "../config.js";
+export declare function registerDatasetTools(server: McpServer, client: ModeClient, _config: ModeConfig): void;

package/dist/tools/datasets.js

@@ -0,0 +1,154 @@
+import { z } from "zod";
+import { truncateOutput } from "../truncate.js";
+import { formatError, formatDate } from "../utils.js";
+export function registerDatasetTools(server, client, _config) {
+    // --- mode_list_datasets ---
+    server.tool("mode_list_datasets", "List datasets in a Mode space. Datasets are curated tables/views that analysts can query without writing SQL.", {
+        space_token: z.string().describe("The space token to list datasets from"),
+        filter: z.string().optional().describe("Filter string"),
+        order: z.enum(["asc", "desc"]).optional().describe("Sort order"),
+        order_by: z.string().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 resp = await client.get(`/spaces/${space_token}/datasets`, { params });
+            const datasets = client.getEmbedded(resp, "datasets");
+            if (datasets.length === 0) {
+                return {
+                    content: [{ type: "text", text: `No datasets found in space ${space_token}.` }],
+                };
+            }
+            const lines = [`Found ${datasets.length} ${datasets.length === 1 ? "dataset" : "datasets"}:`, ""];
+            datasets.forEach((ds, i) => {
+                const name = ds.name ?? "Untitled";
+                const token = ds.token ?? "unknown";
+                lines.push(`${i + 1}. ${name} (token: ${token})`);
+                const details = [];
+                if (ds.data_source_id)
+                    details.push(`Data source ID: ${ds.data_source_id}`);
+                if (ds.created_at)
+                    details.push(`Created: ${formatDate(ds.created_at)}`);
+                if (details.length > 0) {
+                    lines.push(`   ${details.join(" | ")}`);
+                }
+                if (ds.description) {
+                    const desc = String(ds.description);
+                    if (desc.length > 0) {
+                        lines.push(`   ${desc.length > 120 ? desc.slice(0, 120) + "..." : desc}`);
+                    }
+                }
+                lines.push("");
+            });
+            lines.push("Next steps: Use mode_get_dataset with a dataset token to see fields and descriptions, or mode_list_dataset_reports to find reports using a dataset.");
+            return { content: [{ type: "text", text: truncateOutput(lines.join("\n").trimEnd()) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: formatError(e) }], isError: true };
+        }
+    });
+    // --- mode_get_dataset ---
+    server.tool("mode_get_dataset", "Get details of a specific dataset including its fields and field descriptions. Fields are enriched with descriptions when available.", {
+        dataset_token: z.string().describe("The dataset token"),
+        include_field_descriptions: z.boolean().optional().describe("Include field descriptions (default: true)"),
+    }, async ({ dataset_token, include_field_descriptions }) => {
+        try {
+            const includeDescs = include_field_descriptions !== false;
+            const [dataset, fieldsResp] = await Promise.all([
+                client.get(`/datasets/${dataset_token}`),
+                client.get(`/datasets/${dataset_token}/fields`),
+            ]);
+            const fields = client.getEmbedded(fieldsResp, "fields");
+            let descriptionMap;
+            if (includeDescs) {
+                try {
+                    const descsResp = await client.get(`/datasets/${dataset_token}/field_descriptions`);
+                    const descs = client.getEmbedded(descsResp, "dataset_field_descriptions");
+                    descriptionMap = new Map();
+                    for (const d of descs) {
+                        const fieldName = d.field_name;
+                        const desc = d.description;
+                        if (fieldName && desc) {
+                            descriptionMap.set(fieldName, desc);
+                        }
+                    }
+                }
+                catch {
+                    // Field descriptions may not be available — continue without them
+                }
+            }
+            const lines = [
+                `Dataset: ${dataset.name ?? "Untitled"}`,
+                `Token: ${dataset.token}`,
+            ];
+            if (dataset.description)
+                lines.push(`Description: ${dataset.description}`);
+            if (dataset.data_source_id)
+                lines.push(`Data source ID: ${dataset.data_source_id}`);
+            lines.push(`Created: ${formatDate(dataset.created_at)}`);
+            lines.push(`Updated: ${formatDate(dataset.updated_at)}`);
+            lines.push("");
+            if (fields.length === 0) {
+                lines.push("No fields found.");
+            }
+            else {
+                lines.push(`${fields.length} ${fields.length === 1 ? "field" : "fields"}:`);
+                lines.push("");
+                for (const f of fields) {
+                    const name = f.name ?? "unknown";
+                    const type = f.type ?? "unknown";
+                    let line = `  ${name} (${type})`;
+                    if (descriptionMap?.has(name)) {
+                        line += ` — ${descriptionMap.get(name)}`;
+                    }
+                    lines.push(line);
+                }
+            }
+            lines.push("");
+            lines.push("Next steps: Use mode_list_dataset_reports to find reports that use this dataset.");
+            return { content: [{ type: "text", text: truncateOutput(lines.join("\n")) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: formatError(e) }], isError: true };
+        }
+    });
+    // --- mode_list_dataset_reports ---
+    server.tool("mode_list_dataset_reports", "List reports that use a specific dataset. Useful for understanding dataset usage and finding relevant analyses.", {
+        dataset_token: z.string().describe("The dataset token"),
+    }, async ({ dataset_token }) => {
+        try {
+            const resp = await client.get(`/datasets/${dataset_token}/reports`);
+            const reports = client.getEmbedded(resp, "reports");
+            if (reports.length === 0) {
+                return {
+                    content: [{ type: "text", text: `No reports found using dataset ${dataset_token}.` }],
+                };
+            }
+            const lines = [`Found ${reports.length} ${reports.length === 1 ? "report" : "reports"} using this dataset:`, ""];
+            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.last_successfully_run_at)
+                    details.push(`Last run: ${formatDate(r.last_successfully_run_at)}`);
+                if (r.query_count !== undefined && r.query_count !== null)
+                    details.push(`Queries: ${r.query_count}`);
+                if (details.length > 0) {
+                    lines.push(`   ${details.join(" | ")}`);
+                }
+                lines.push("");
+            });
+            lines.push("Next 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: truncateOutput(lines.join("\n").trimEnd()) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: formatError(e) }], isError: true };
+        }
+    });
+}

package/dist/tools/distribution.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ModeClient } from "../mode-client.js";
+import { ModeConfig } from "../config.js";
+export declare function registerDistributionTools(server: McpServer, client: ModeClient, config: ModeConfig): void;

package/dist/tools/distribution.js

@@ -0,0 +1,175 @@
+import { z } from "zod";
+import { trySaveFile, slugify } from "../file-utils.js";
+import { truncateOutput } from "../truncate.js";
+import { formatError, formatBytes } from "../utils.js";
+export function registerDistributionTools(server, client, config) {
+    // --- mode_export_report ---
+    server.tool("mode_export_report", "Export a report as PDF or CSV. IMPORTANT: Before exporting, call mode_get_report_parameters to check if the report requires parameters. If it does, run it first with mode_run_report (passing the right parameters) and use the resulting run_token here — otherwise the export will use the last run's parameters which may not be what the user wants.", {
+        report_token: z.string().describe("The report token"),
+        format: z.enum(["pdf", "csv"]).describe("Export format: 'pdf' for a rendered report with charts, 'csv' for raw query data"),
+        run_token: z.string().optional().describe("The run token. If omitted, uses the last successful run."),
+        query_index: z.number().optional().describe("For CSV export: which query's results to export (0-based, default: 0). Ignored for PDF."),
+        filename: z.string().optional().describe("Output filename (e.g. 'my-report.pdf' or 'data.csv'). Defaults to the report name with appropriate extension."),
+        output_dir: z.string().optional().describe("Directory to save the file. If omitted or not writable, returns a download URL (PDF) or inline data (CSV) instead."),
+    }, async ({ report_token, format, run_token, query_index, filename, output_dir }) => {
+        try {
+            // Get report details for name and fallback run token
+            const report = await client.get(`/reports/${report_token}`);
+            const reportName = report.name ?? "report";
+            const safeName = slugify(reportName);
+            let resolvedRunToken = run_token;
+            if (!resolvedRunToken) {
+                resolvedRunToken = report.last_successful_run_token;
+                if (!resolvedRunToken) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: "No successful runs found for this report. Run the report first with mode_run_report (check mode_get_report_parameters for required parameters).",
+                            }],
+                        isError: true,
+                    };
+                }
+            }
+            if (format === "pdf") {
+                return await exportPdf(client, config, report_token, resolvedRunToken, reportName, safeName, filename, output_dir);
+            }
+            else {
+                return await exportCsv(client, config, report_token, resolvedRunToken, reportName, safeName, query_index ?? 0, filename, output_dir);
+            }
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: formatError(e) }], isError: true };
+        }
+    });
+}
+async function exportPdf(client, config, reportToken, runToken, reportName, safeName, filename, outputDir) {
+    // Trigger PDF generation with POST, then poll with GET
+    const exportPath = `/reports/${reportToken}/exports/runs/${runToken}/pdf.pdf`;
+    await client.post(exportPath);
+    // Poll until completed — progressive backoff
+    const deadline = Date.now() + config.pollTimeoutMs;
+    let exportStatus;
+    let pollInterval = config.pollIntervalMs;
+    const maxPollInterval = 15_000;
+    while (true) {
+        exportStatus = await client.get(exportPath);
+        const state = exportStatus.state;
+        if (state === "completed")
+            break;
+        if (state === "failed") {
+            const reason = exportStatus.error ?? "The report run may not support PDF export.";
+            return {
+                content: [{ type: "text", text: `PDF export failed: ${reason}` }],
+                isError: true,
+            };
+        }
+        if (state === "new" || state === "requested") {
+            // Still generating, continue polling
+        }
+        else if (!state || exportStatus.id === "not_found") {
+            return {
+                content: [{
+                        type: "text",
+                        text: "PDF export is not available for this run. Try running the report again with mode_run_report first, then export the new run.",
+                    }],
+                isError: true,
+            };
+        }
+        if (Date.now() > deadline) {
+            return {
+                content: [{ type: "text", text: `PDF export timed out after ${config.pollTimeoutMs / 1000}s. Try again later.` }],
+                isError: true,
+            };
+        }
+        const waitMs = Math.min(pollInterval, deadline - Date.now());
+        if (waitMs <= 0)
+            break;
+        await new Promise((resolve) => setTimeout(resolve, waitMs));
+        pollInterval = Math.min(pollInterval * 1.5, maxPollInterval);
+    }
+    // Build download URL
+    const downloadHref = client.getLink(exportStatus, "download");
+    const downloadPath = downloadHref
+        ?? `/api/${config.workspace}/reports/${reportToken}/exports/runs/${runToken}/pdf/download.pdf`;
+    const downloadUrl = `${config.baseUrl}${downloadPath}`;
+    const outputFilename = filename ?? `${safeName}.pdf`;
+    // Download and try to save locally
+    const pdfBuffer = await client.request(downloadUrl, { accept: "application/pdf" });
+    const buf = Buffer.from(pdfBuffer);
+    const saveResult = await trySaveFile(buf, outputFilename, outputDir);
+    const lines = [`PDF export ready: ${reportName}`, ""];
+    if (saveResult.saved) {
+        lines.push(`Saved to: ${saveResult.path} (${formatBytes(saveResult.size_bytes)})`);
+        lines.push("");
+        lines.push(`Download URL: ${downloadUrl}`);
+    }
+    else if (outputDir) {
+        lines.push(`Save failed: Could not write to ${outputDir}`);
+        lines.push("");
+        lines.push(`Download URL: ${downloadUrl}`);
+        lines.push(`Download command: curl -L -u "$MODE_API_TOKEN:$MODE_API_SECRET" -o "${outputFilename}" "${downloadUrl}"`);
+    }
+    else {
+        lines.push(`Download URL: ${downloadUrl}`);
+        lines.push(`Download command: curl -L -u "$MODE_API_TOKEN:$MODE_API_SECRET" -o "${outputFilename}" "${downloadUrl}"`);
+    }
+    return {
+        content: [{ type: "text", text: truncateOutput(lines.join("\n")) }],
+    };
+}
+async function exportCsv(client, _config, reportToken, runToken, reportName, safeName, queryIndex, filename, outputDir) {
+    // Get query runs for this report run
+    const qrResp = await client.get(`/reports/${reportToken}/runs/${runToken}/query_runs`);
+    const queryRuns = client.getEmbedded(qrResp, "query_runs");
+    if (queryRuns.length === 0) {
+        return {
+            content: [{ type: "text", text: "No query runs found for this report run." }],
+            isError: true,
+        };
+    }
+    if (queryIndex < 0 || queryIndex >= queryRuns.length) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `query_index ${queryIndex} 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[queryIndex];
+    const qrToken = queryRun.token;
+    const queryName = queryRun.query_name ?? `Query ${queryIndex}`;
+    // Fetch CSV data
+    const csv = await client.get(`/reports/${reportToken}/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: `Query "${queryName}" returned no data.` }],
+        };
+    }
+    const rowCount = cleanCsv.split("\n").length - 1;
+    const outputFilename = filename ?? `${safeName}.csv`;
+    const saveResult = await trySaveFile(cleanCsv, outputFilename, outputDir);
+    const lines = [`CSV export ready: ${reportName}`, `Query: ${queryName}`, `Rows: ${rowCount}`, ""];
+    if (saveResult.saved) {
+        lines.push(`Saved to: ${saveResult.path} (${formatBytes(saveResult.size_bytes)})`);
+    }
+    else if (outputDir) {
+        lines.push(`Save failed: Could not write to ${outputDir}`);
+        lines.push(`The CSV data (${rowCount} rows) is too large to display inline. Use mode_get_query_results to view a subset.`);
+    }
+    else {
+        // No output_dir — show a preview if small enough, otherwise suggest saving
+        if (cleanCsv.length < 5000) {
+            lines.push("```csv");
+            lines.push(cleanCsv);
+            lines.push("```");
+        }
+        else {
+            lines.push(`The CSV is ${formatBytes(cleanCsv.length)} — provide an output_dir to save it to disk, or use mode_get_query_results to view a subset.`);
+        }
+    }
+    return {
+        content: [{ type: "text", text: truncateOutput(lines.join("\n")) }],
+    };
+}

package/dist/tools/management.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ModeClient } from "../mode-client.js";
+import { ModeConfig } from "../config.js";
+export declare function registerManagementTools(server: McpServer, client: ModeClient, _config: ModeConfig): void;

package/dist/tools/management.js

@@ -0,0 +1,263 @@
+import { z } from "zod";
+import { truncateOutput } from "../truncate.js";
+import { formatError, formatDate } from "../utils.js";
+export function registerManagementTools(server, client, _config) {
+    // --- mode_list_spaces ---
+    server.tool("mode_list_spaces", "List all spaces (collections) in the Mode workspace. Spaces organize reports into groups.", {
+        filter: z.string().optional().describe("Filter: 'all' (default) or 'custom' (non-personal spaces only)"),
+    }, async ({ filter }) => {
+        try {
+            const params = { filter: filter ?? "all" };
+            const resp = await client.get("/spaces", { params });
+            const spaces = client.getEmbedded(resp, "spaces");
+            if (spaces.length === 0) {
+                return {
+                    content: [{ type: "text", text: "No spaces found in this workspace. The workspace may be empty or your API token may not have access to any spaces." }],
+                };
+            }
+            const lines = [`Found ${spaces.length} ${spaces.length === 1 ? "space" : "spaces"}:`, ""];
+            spaces.forEach((s, i) => {
+                const name = s.name ?? "Untitled";
+                const token = s.token ?? "unknown";
+                const spaceType = s.space_type ?? "unknown";
+                const restricted = s.restricted ? " (restricted)" : "";
+                lines.push(`${i + 1}. ${name} (token: ${token}) — ${spaceType}${restricted}`);
+            });
+            lines.push("");
+            lines.push("Next steps: Use mode_list_reports with a space_token to see reports in a space.");
+            return {
+                content: [{ type: "text", text: truncateOutput(lines.join("\n")) }],
+            };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: formatError(e) }], isError: true };
+        }
+    });
+    // --- mode_list_data_sources ---
+    server.tool("mode_list_data_sources", "List all connected data sources (databases) in the Mode workspace with connection details and status.", {}, async () => {
+        try {
+            const resp = await client.get("/data_sources");
+            const sources = client.getEmbedded(resp, "data_sources");
+            if (sources.length === 0) {
+                return {
+                    content: [{ type: "text", text: "No data sources found. The workspace may not have any databases connected." }],
+                };
+            }
+            const lines = [`Found ${sources.length} data ${sources.length === 1 ? "source" : "sources"}:`, ""];
+            sources.forEach((ds, i) => {
+                const name = ds.name ?? "Untitled";
+                const token = ds.token ?? "unknown";
+                lines.push(`${i + 1}. ${name} (token: ${token})`);
+                const details = [];
+                if (ds.adapter)
+                    details.push(`Adapter: ${ds.adapter}`);
+                if (ds.host)
+                    details.push(`Host: ${ds.host}`);
+                if (ds.database)
+                    details.push(`Database: ${ds.database}`);
+                if (details.length > 0) {
+                    lines.push(`   ${details.join(" | ")}`);
+                }
+                lines.push("");
+            });
+            lines.push("");
+            lines.push("Next steps: Use mode_get_data_source with a token for detailed connection info.");
+            return {
+                content: [{ type: "text", text: truncateOutput(lines.join("\n").trimEnd()) }],
+            };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: formatError(e) }], isError: true };
+        }
+    });
+    // --- mode_list_definitions ---
+    server.tool("mode_list_definitions", "List saved SQL definitions (reusable snippets/macros) in the Mode workspace.", {}, async () => {
+        try {
+            const resp = await client.get("/definitions");
+            const definitions = client.getEmbedded(resp, "definitions");
+            if (definitions.length === 0) {
+                return {
+                    content: [{ type: "text", text: "No SQL definitions found in this workspace." }],
+                };
+            }
+            const lines = [`Found ${definitions.length} ${definitions.length === 1 ? "definition" : "definitions"}:`, ""];
+            definitions.forEach((d, i) => {
+                const name = d.name ?? "Untitled";
+                const token = d.token ?? "unknown";
+                lines.push(`${i + 1}. ${name} (token: ${token})`);
+                if (d.description) {
+                    lines.push(`   ${d.description}`);
+                }
+                const details = [];
+                if (d.data_source_id)
+                    details.push(`Data source ID: ${d.data_source_id}`);
+                if (d.updated_at) {
+                    details.push(`Updated: ${formatDate(d.updated_at)}`);
+                }
+                if (details.length > 0) {
+                    lines.push(`   ${details.join(" | ")}`);
+                }
+                if (d.source) {
+                    const src = String(d.source);
+                    const preview = src.length > 200 ? src.slice(0, 200) + "..." : src;
+                    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_get_data_source ---
+    server.tool("mode_get_data_source", "Get detailed information about a specific data source (database connection), including adapter, host, port, SSL, and creation date.", {
+        data_source_token: z.string().describe("The data source token"),
+    }, async ({ data_source_token }) => {
+        try {
+            const ds = await client.get(`/data_sources/${data_source_token}`);
+            const lines = [
+                `Data source: ${ds.name ?? "Untitled"}`,
+                `Token: ${ds.token}`,
+            ];
+            if (ds.adapter)
+                lines.push(`Adapter: ${ds.adapter}`);
+            if (ds.host)
+                lines.push(`Host: ${ds.host}`);
+            if (ds.port)
+                lines.push(`Port: ${ds.port}`);
+            if (ds.database)
+                lines.push(`Database: ${ds.database}`);
+            if (ds.ssl !== undefined)
+                lines.push(`SSL: ${ds.ssl ? "yes" : "no"}`);
+            if (ds.provider)
+                lines.push(`Provider: ${ds.provider}`);
+            lines.push(`Created: ${formatDate(ds.created_at)}`);
+            return { content: [{ type: "text", text: truncateOutput(lines.join("\n")) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: formatError(e) }], isError: true };
+        }
+    });
+    // --- mode_list_report_schedules ---
+    server.tool("mode_list_report_schedules", "List schedules configured for a Mode report. Shows when reports are set to run automatically.", {
+        report_token: z.string().describe("The report token"),
+    }, async ({ report_token }) => {
+        try {
+            const resp = await client.get(`/reports/${report_token}/schedules`);
+            const schedules = client.getEmbedded(resp, "report_schedules");
+            if (schedules.length === 0) {
+                return {
+                    content: [{ type: "text", text: `No schedules found for report ${report_token}. The report is not set to run automatically.` }],
+                };
+            }
+            const lines = [`Found ${schedules.length} ${schedules.length === 1 ? "schedule" : "schedules"}:`, ""];
+            schedules.forEach((s, i) => {
+                const name = s.name ?? `Schedule ${i + 1}`;
+                const token = s.token ?? "unknown";
+                lines.push(`${i + 1}. ${name} (token: ${token})`);
+                if (s.next_scheduled_run)
+                    lines.push(`   Next run: ${formatDate(s.next_scheduled_run)}`);
+                if (s.last_run_at)
+                    lines.push(`   Last run: ${formatDate(s.last_run_at)}`);
+                if (s.subscriber_count !== undefined)
+                    lines.push(`   Subscribers: ${s.subscriber_count}`);
+                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_subscriptions ---
+    server.tool("mode_list_report_subscriptions", "List email subscriptions for a Mode report. Shows who receives scheduled report deliveries and in what format.", {
+        report_token: z.string().describe("The report token"),
+    }, async ({ report_token }) => {
+        try {
+            const resp = await client.get(`/reports/${report_token}/subscriptions`);
+            const subs = client.getEmbedded(resp, "report_subscriptions");
+            if (subs.length === 0) {
+                return {
+                    content: [{ type: "text", text: `No subscriptions found for report ${report_token}.` }],
+                };
+            }
+            const lines = [`Found ${subs.length} ${subs.length === 1 ? "subscription" : "subscriptions"}:`, ""];
+            subs.forEach((sub, i) => {
+                const token = sub.token ?? "unknown";
+                lines.push(`${i + 1}. Subscription ${token}`);
+                const details = [];
+                if (sub.csv !== undefined)
+                    details.push(`CSV: ${sub.csv ? "yes" : "no"}`);
+                if (sub.pdf !== undefined)
+                    details.push(`PDF: ${sub.pdf ? "yes" : "no"}`);
+                if (sub.data_previews !== undefined)
+                    details.push(`Data previews: ${sub.data_previews ? "yes" : "no"}`);
+                if (details.length > 0) {
+                    lines.push(`   Delivery: ${details.join(" | ")}`);
+                }
+                if (sub.user) {
+                    const user = sub.user;
+                    lines.push(`   User: ${user.name ?? user.username ?? "unknown"}`);
+                }
+                lines.push("");
+            });
+            return { content: [{ type: "text", text: truncateOutput(lines.join("\n").trimEnd()) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: formatError(e) }], isError: true };
+        }
+    });
+    // --- mode_get_audit_logs ---
+    server.tool("mode_get_audit_logs", "Retrieve audit logs for the workspace. Shows who did what and when. Requires admin permissions.", {
+        start_timestamp: z.string().describe("Start timestamp (ISO 8601, e.g. '2024-01-01T00:00:00Z')"),
+        end_timestamp: z.string().describe("End timestamp (ISO 8601, e.g. '2024-01-31T23:59:59Z')"),
+        action: z.string().optional().describe("Filter by action type"),
+        entity_type: z.string().optional().describe("Filter by entity type"),
+        username: z.string().optional().describe("Filter by username"),
+    }, async ({ start_timestamp, end_timestamp, action, entity_type, username }) => {
+        try {
+            const params = {
+                start_timestamp: start_timestamp,
+                end_timestamp: end_timestamp,
+            };
+            if (action)
+                params.action = action;
+            if (entity_type)
+                params.entity_type = entity_type;
+            if (username)
+                params.username = username;
+            const resp = await client.get("/audit_logs", { params });
+            // Audit logs may not follow standard HAL+JSON — try embedded first, then fallback
+            let events = client.getEmbedded(resp, "audit_events");
+            if (events.length === 0 && Array.isArray(resp.audit_logs)) {
+                events = resp.audit_logs;
+            }
+            if (events.length === 0) {
+                return {
+                    content: [{ type: "text", text: "No audit log events found for the specified time range and filters." }],
+                };
+            }
+            const lines = [`Found ${events.length} audit ${events.length === 1 ? "event" : "events"}:`, ""];
+            events.forEach((ev, i) => {
+                const eventAction = ev.action ?? "unknown";
+                const eventUser = ev.username ?? ev.user ?? "unknown";
+                const eventEntity = ev.entity_type ?? "";
+                const eventTime = formatDate(ev.timestamp ?? ev.created_at);
+                lines.push(`${i + 1}. [${eventTime}] ${eventUser} — ${eventAction}${eventEntity ? ` on ${eventEntity}` : ""}`);
+                if (ev.entity_name)
+                    lines.push(`   Entity: ${ev.entity_name}`);
+                if (ev.details) {
+                    const details = String(ev.details);
+                    lines.push(`   Details: ${details.length > 120 ? details.slice(0, 120) + "..." : details}`);
+                }
+            });
+            return { content: [{ type: "text", text: truncateOutput(lines.join("\n")) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: formatError(e) }], isError: true };
+        }
+    });
+}

package/dist/truncate.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Output truncation to prevent overwhelming the LLM context window.
+ * Keeps the TAIL of the output (most recent data is most relevant).
+ */
+export declare function setMaxOutputLength(maxLength: number): void;
+export declare function truncateOutput(text: string, maxLength?: number): string;

package/dist/truncate.js

@@ -0,0 +1,16 @@
+/**
+ * Output truncation to prevent overwhelming the LLM context window.
+ * Keeps the TAIL of the output (most recent data is most relevant).
+ */
+const DEFAULT_MAX_LENGTH = 50_000;
+let configuredMaxLength;
+export function setMaxOutputLength(maxLength) {
+    configuredMaxLength = maxLength;
+}
+export function truncateOutput(text, maxLength) {
+    const limit = maxLength ?? configuredMaxLength ?? DEFAULT_MAX_LENGTH;
+    if (text.length <= limit)
+        return text;
+    const warning = `[Truncated: showing last ${limit} of ${text.length} characters]\n\n`;
+    return warning + text.slice(-limit);
+}

package/dist/utils.d.ts

@@ -0,0 +1,6 @@
+export declare function formatError(e: unknown): string;
+export declare function formatDate(d: unknown): string;
+export declare function formatBytes(bytes: number): string;
+/** Build a markdown table from headers and rows */
+export declare function markdownTable(headers: string[], rows: Record<string, string>[]): string;
+export declare function parseCSVLine(line: string): string[];