@cci-labs/mode-mcp 0.0.0-4a844de

package/dist/config.d.ts

@@ -0,0 +1,11 @@
+export interface ModeConfig {
+    workspace: string;
+    apiToken: string;
+    apiSecret: string;
+    baseUrl: string;
+    maxRowsDefault: number;
+    pollIntervalMs: number;
+    pollTimeoutMs: number;
+    maxOutputLength: number;
+}
+export declare function loadConfig(): ModeConfig;

package/dist/config.js

@@ -0,0 +1,27 @@
+import dotenv from "dotenv";
+import path from "path";
+import { fileURLToPath } from "url";
+// Load .env from project root
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+dotenv.config({ path: path.resolve(__dirname, "..", ".env"), quiet: true });
+export function loadConfig() {
+    const workspace = process.env.MODE_WORKSPACE;
+    const apiToken = process.env.MODE_API_TOKEN;
+    const apiSecret = process.env.MODE_API_SECRET;
+    if (!workspace)
+        throw new Error("MODE_WORKSPACE environment variable is required");
+    if (!apiToken)
+        throw new Error("MODE_API_TOKEN environment variable is required");
+    if (!apiSecret)
+        throw new Error("MODE_API_SECRET environment variable is required");
+    return {
+        workspace,
+        apiToken,
+        apiSecret,
+        baseUrl: process.env.MODE_BASE_URL ?? "https://app.mode.com",
+        maxRowsDefault: parseInt(process.env.MODE_MAX_ROWS ?? "100", 10) || 100,
+        pollIntervalMs: parseInt(process.env.MODE_POLL_INTERVAL_MS ?? "2000", 10) || 2000,
+        pollTimeoutMs: parseInt(process.env.MODE_POLL_TIMEOUT_MS ?? "300000", 10) || 300000,
+        maxOutputLength: parseInt(process.env.MODE_MAX_OUTPUT_LENGTH ?? "50000", 10) || 50000,
+    };
+}

package/dist/file-utils.d.ts

@@ -0,0 +1,7 @@
+export interface SaveResult {
+    saved: boolean;
+    path?: string;
+    size_bytes?: number;
+}
+export declare function slugify(name: string): string;
+export declare function trySaveFile(content: Buffer | string, filename: string, outputDir?: string): Promise<SaveResult>;

package/dist/file-utils.js

@@ -0,0 +1,47 @@
+import { writeFile, access, mkdir, constants } from "fs/promises";
+import path from "path";
+function resolveDir(dir) {
+    if (dir.startsWith("~")) {
+        const home = process.env.HOME ?? process.env.USERPROFILE ?? "/tmp";
+        return path.join(home, dir.slice(1));
+    }
+    return path.resolve(dir);
+}
+async function isWritable(dir) {
+    try {
+        await access(dir, constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function slugify(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+export async function trySaveFile(content, filename, outputDir) {
+    if (!outputDir)
+        return { saved: false };
+    const resolved = resolveDir(outputDir);
+    // Try to create the directory if it doesn't exist
+    if (!(await isWritable(resolved))) {
+        try {
+            await mkdir(resolved, { recursive: true });
+        }
+        catch {
+            return { saved: false };
+        }
+    }
+    const outputPath = path.join(resolved, path.basename(filename));
+    const buf = typeof content === "string" ? Buffer.from(content, "utf-8") : content;
+    try {
+        await writeFile(outputPath, buf);
+        return { saved: true, path: outputPath, size_bytes: buf.length };
+    }
+    catch {
+        return { saved: false };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { ModeClient } from "./mode-client.js";
+import { setMaxOutputLength } from "./truncate.js";
+import { registerAnalyticsTools } from "./tools/analytics.js";
+import { registerManagementTools } from "./tools/management.js";
+import { registerDistributionTools } from "./tools/distribution.js";
+import { registerDatasetTools } from "./tools/datasets.js";
+const config = loadConfig();
+setMaxOutputLength(config.maxOutputLength);
+const client = new ModeClient(config);
+const server = new McpServer({
+    name: "mode-analytics",
+    version: "1.0.0",
+});
+registerAnalyticsTools(server, client, config);
+registerManagementTools(server, client, config);
+registerDistributionTools(server, client, config);
+registerDatasetTools(server, client, config);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/mode-client.d.ts

@@ -0,0 +1,38 @@
+import { ModeConfig } from "./config.js";
+export interface ModeRequestOptions {
+    method?: string;
+    body?: Record<string, unknown>;
+    accept?: string;
+    params?: Record<string, string>;
+}
+export interface ModeErrorDetail {
+    id: string;
+    message: string;
+}
+export declare class ModeApiError extends Error {
+    readonly status: number;
+    readonly detail: ModeErrorDetail | string;
+    readonly endpoint: string;
+    constructor(status: number, detail: ModeErrorDetail | string, endpoint: string);
+    get suggestion(): string;
+}
+export declare class ModeClient {
+    private readonly authHeader;
+    private readonly baseApiUrl;
+    private readonly config;
+    private requestTimestamps;
+    private readonly maxRequests;
+    private readonly windowMs;
+    private rateLimitRemaining;
+    private rateLimitResetAt;
+    constructor(config: ModeConfig);
+    private parseRateLimitHeaders;
+    private rateLimit;
+    private calculateRetryWait;
+    request<T = unknown>(path: string, options?: ModeRequestOptions): Promise<T>;
+    get<T = unknown>(path: string, options?: Omit<ModeRequestOptions, "method">): Promise<T>;
+    post<T = unknown>(path: string, body?: Record<string, unknown>): Promise<T>;
+    getEmbedded<T>(response: Record<string, unknown>, key: string): T[];
+    getLink(response: Record<string, unknown>, rel: string): string | undefined;
+    pollUntilComplete<T extends Record<string, unknown>>(path: string, timeoutMs?: number, initialIntervalMs?: number): Promise<T>;
+}

package/dist/mode-client.js

@@ -0,0 +1,227 @@
+export class ModeApiError extends Error {
+    status;
+    detail;
+    endpoint;
+    constructor(status, detail, endpoint) {
+        const msg = typeof detail === "string" ? detail : detail.message;
+        super(`Mode API ${status} on ${endpoint}: ${msg}`);
+        this.status = status;
+        this.detail = detail;
+        this.endpoint = endpoint;
+        this.name = "ModeApiError";
+    }
+    get suggestion() {
+        if (this.status === 401) {
+            return "Check MODE_API_TOKEN and MODE_API_SECRET. Regenerate at app.mode.com/{workspace}/settings/api_tokens.";
+        }
+        if (this.status === 403) {
+            return "Your API token may lack permission for this operation. Workspace admin access may be required.";
+        }
+        if (this.status === 404) {
+            return "The resource was not found. Use mode_list_reports / mode_list_spaces to find valid tokens.";
+        }
+        if (this.status === 429) {
+            return "Rate limited. The server will automatically retry.";
+        }
+        if (this.status >= 500) {
+            return "Mode's API returned a server error. This is usually temporary — try again.";
+        }
+        return "";
+    }
+}
+export class ModeClient {
+    authHeader;
+    baseApiUrl;
+    config;
+    // Rate limiting state
+    requestTimestamps = [];
+    maxRequests = 35; // stay under Mode's 40/10s limit
+    windowMs = 10_000;
+    // Server-reported rate limit state
+    rateLimitRemaining = null;
+    rateLimitResetAt = null; // epoch ms
+    constructor(config) {
+        this.config = config;
+        const creds = Buffer.from(`${config.apiToken}:${config.apiSecret}`).toString("base64");
+        this.authHeader = `Basic ${creds}`;
+        this.baseApiUrl = `${config.baseUrl}/api/${config.workspace}`;
+        if (!config.apiToken.trim()) {
+            throw new Error("MODE_API_TOKEN is empty.");
+        }
+    }
+    parseRateLimitHeaders(headers) {
+        const remaining = headers.get("X-RateLimit-Remaining");
+        if (remaining !== null) {
+            this.rateLimitRemaining = parseInt(remaining, 10);
+        }
+        const reset = headers.get("X-RateLimit-Reset");
+        if (reset !== null) {
+            const resetValue = parseInt(reset, 10);
+            // If value looks like a unix timestamp (> year 2000 in seconds), convert to ms
+            this.rateLimitResetAt = resetValue > 1_000_000_000 ? resetValue * 1000 : Date.now() + resetValue * 1000;
+        }
+    }
+    async rateLimit() {
+        const now = Date.now();
+        // If the server told us we're running low, proactively wait
+        if (this.rateLimitRemaining !== null &&
+            this.rateLimitRemaining < 5 &&
+            this.rateLimitResetAt !== null &&
+            this.rateLimitResetAt > now) {
+            const waitMs = this.rateLimitResetAt - now + 200;
+            if (waitMs > 0 && waitMs < 30_000) {
+                await new Promise((resolve) => setTimeout(resolve, waitMs));
+            }
+        }
+        // Local sliding window rate limiter
+        this.requestTimestamps = this.requestTimestamps.filter((t) => now - t < this.windowMs);
+        if (this.requestTimestamps.length >= this.maxRequests) {
+            const oldest = this.requestTimestamps[0];
+            const waitMs = this.windowMs - (now - oldest) + 100;
+            await new Promise((resolve) => setTimeout(resolve, waitMs));
+        }
+        this.requestTimestamps.push(Date.now());
+    }
+    calculateRetryWait(response) {
+        // Try to use server-provided reset time
+        const resetHeader = response.headers.get("X-RateLimit-Reset");
+        if (resetHeader) {
+            const resetValue = parseInt(resetHeader, 10);
+            const resetAt = resetValue > 1_000_000_000 ? resetValue * 1000 : Date.now() + resetValue * 1000;
+            const waitMs = resetAt - Date.now() + 500;
+            if (waitMs > 0 && waitMs < 60_000) {
+                return waitMs;
+            }
+        }
+        // Try Retry-After header
+        const retryAfter = response.headers.get("Retry-After");
+        if (retryAfter) {
+            const seconds = parseInt(retryAfter, 10);
+            if (!isNaN(seconds) && seconds > 0 && seconds < 120) {
+                return seconds * 1000 + 500;
+            }
+        }
+        // Default backoff
+        return 3000;
+    }
+    async request(path, options = {}) {
+        const { method = "GET", body, accept = "application/hal+json", params } = options;
+        await this.rateLimit();
+        let url;
+        if (path.startsWith("http")) {
+            url = path;
+        }
+        else {
+            url = `${this.baseApiUrl}${path.startsWith("/") ? "" : "/"}${path}`;
+        }
+        if (params) {
+            const searchParams = new URLSearchParams(params);
+            url += `?${searchParams.toString()}`;
+        }
+        const headers = {
+            Authorization: this.authHeader,
+            Accept: accept,
+            "Accept-Encoding": "gzip",
+        };
+        const fetchOptions = { method, headers };
+        if (body) {
+            headers["Content-Type"] = "application/json";
+            fetchOptions.body = JSON.stringify(body);
+        }
+        // Retry logic: up to 3 retries for transient errors
+        let lastError;
+        for (let attempt = 0; attempt < 3; attempt++) {
+            try {
+                const response = await fetch(url, fetchOptions);
+                // Always parse rate limit headers from every response
+                this.parseRateLimitHeaders(response.headers);
+                if (response.status === 429) {
+                    // Rate limited — use server headers for exact wait time
+                    const waitMs = this.calculateRetryWait(response);
+                    await response.text().catch(() => { });
+                    await new Promise((resolve) => setTimeout(resolve, waitMs));
+                    continue;
+                }
+                if (response.status >= 500) {
+                    // Server error — retry with backoff
+                    await response.text().catch(() => { });
+                    await new Promise((resolve) => setTimeout(resolve, 1000 * Math.pow(2, attempt)));
+                    continue;
+                }
+                if (!response.ok) {
+                    let detail;
+                    try {
+                        detail = (await response.json());
+                    }
+                    catch {
+                        detail = await response.text();
+                    }
+                    throw new ModeApiError(response.status, detail, `${method} ${path}`);
+                }
+                // Handle different content types
+                const contentType = response.headers.get("content-type") ?? "";
+                if (contentType.includes("application/pdf") || accept === "application/pdf") {
+                    return (await response.arrayBuffer());
+                }
+                if (contentType.includes("text/csv") || accept === "text/csv") {
+                    return (await response.text());
+                }
+                if (contentType.includes("application/json") || contentType.includes("hal+json")) {
+                    return (await response.json());
+                }
+                return (await response.text());
+            }
+            catch (e) {
+                if (e instanceof ModeApiError)
+                    throw e;
+                lastError = e;
+                if (attempt < 2) {
+                    await new Promise((resolve) => setTimeout(resolve, 1000 * Math.pow(2, attempt)));
+                }
+            }
+        }
+        throw lastError ?? new Error(`Failed to fetch ${method} ${path} after 3 attempts`);
+    }
+    async get(path, options) {
+        return this.request(path, { ...options, method: "GET" });
+    }
+    async post(path, body) {
+        return this.request(path, { method: "POST", body });
+    }
+    // HAL+JSON helpers
+    getEmbedded(response, key) {
+        const embedded = response._embedded;
+        return embedded?.[key] ?? [];
+    }
+    getLink(response, rel) {
+        const links = response._links;
+        return links?.[rel]?.href;
+    }
+    // Polling helper for report runs — uses progressive backoff
+    // Starts at initialIntervalMs (default 2s), increases by 1.5x each poll,
+    // capped at maxIntervalMs (default 15s).
+    async pollUntilComplete(path, timeoutMs, initialIntervalMs) {
+        const timeout = timeoutMs ?? this.config.pollTimeoutMs;
+        const startInterval = initialIntervalMs ?? this.config.pollIntervalMs;
+        const maxInterval = 15_000;
+        const deadline = Date.now() + timeout;
+        let currentInterval = startInterval;
+        while (Date.now() < deadline) {
+            const result = await this.get(path);
+            const state = result.state;
+            if (state === "succeeded" || state === "completed") {
+                return result;
+            }
+            if (state === "failed" || state === "cancelled") {
+                throw new Error(`Run failed with state: ${state}. Path: ${path}`);
+            }
+            // Wait with progressive backoff
+            const waitMs = Math.min(currentInterval, deadline - Date.now());
+            if (waitMs <= 0)
+                break;
+            await new Promise((resolve) => setTimeout(resolve, waitMs));
+            currentInterval = Math.min(currentInterval * 1.5, maxInterval);
+        }
+        throw new Error(`Polling timed out after ${timeout}ms for ${path}`);
+    }
+}

package/dist/tools/analytics.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 registerAnalyticsTools(server: McpServer, client: ModeClient, config: ModeConfig): void;