coalesce-transform-mcp 0.1.0

package/dist/utils.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Type guard that narrows `unknown` to a plain key-value object.
+ * Used throughout the codebase to safely access dynamic API responses.
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;

package/dist/utils.js

@@ -0,0 +1,7 @@
+/**
+ * Type guard that narrows `unknown` to a plain key-value object.
+ * Used throughout the codebase to safely access dynamic API responses.
+ */
+export function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/workflows/get-environment-overview.d.ts

@@ -0,0 +1,9 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CoalesceClient } from "../client.js";
+export declare function getEnvironmentOverview(client: CoalesceClient, params: {
+    environmentID: string;
+}): Promise<{
+    environment: unknown;
+    nodes: unknown[];
+}>;
+export declare function registerGetEnvironmentOverview(server: McpServer, client: CoalesceClient): void;

package/dist/workflows/get-environment-overview.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { fetchAllEnvironmentNodes } from "../services/cache/snapshots.js";
+import { READ_ONLY_ANNOTATIONS, buildJsonToolResponse, validatePathSegment, handleToolError, } from "../coalesce/types.js";
+export async function getEnvironmentOverview(client, params) {
+    const environmentID = validatePathSegment(params.environmentID, "environmentID");
+    const basePath = `/api/v1/environments/${environmentID}`;
+    const [environment, nodes] = await Promise.all([
+        client.get(basePath),
+        fetchAllEnvironmentNodes(client, { environmentID }),
+    ]);
+    return { environment, nodes: nodes.items };
+}
+export function registerGetEnvironmentOverview(server, client) {
+    server.tool("get-environment-overview", "Get environment details and all its nodes in a single call", { environmentID: z.string().describe("The environment ID") }, READ_ONLY_ANNOTATIONS, async (params) => {
+        try {
+            const result = await getEnvironmentOverview(client, params);
+            return buildJsonToolResponse("get-environment-overview", result);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+}

package/dist/workflows/get-run-details.d.ts

@@ -0,0 +1,10 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CoalesceClient } from "../client.js";
+export declare function getRunDetails(client: CoalesceClient, params: {
+    runID: string;
+}): Promise<{
+    run: unknown;
+    results: unknown;
+    resultsError?: string;
+}>;
+export declare function registerGetRunDetails(server: McpServer, client: CoalesceClient): void;

package/dist/workflows/get-run-details.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { READ_ONLY_ANNOTATIONS, buildJsonToolResponse, sanitizeResponse, validatePathSegment, handleToolError, } from "../coalesce/types.js";
+export async function getRunDetails(client, params) {
+    const validRunID = validatePathSegment(params.runID, "runID");
+    let run;
+    let results = null;
+    let resultsError;
+    const runPromise = client.get(`/api/v1/runs/${validRunID}`);
+    const resultsPromise = client.get(`/api/v1/runs/${validRunID}/results`);
+    [run] = await Promise.all([
+        runPromise,
+        resultsPromise.then((data) => { results = data; }, (error) => { resultsError = error instanceof Error ? error.message : String(error); }),
+    ]);
+    return resultsError !== undefined
+        ? { run, results: null, resultsError }
+        : { run, results };
+}
+export function registerGetRunDetails(server, client) {
+    server.tool("get-run-details", "Get run metadata and results in a single call", { runID: z.string().describe("The numeric run ID (integer, e.g. '401'). Use the runCounter value from start-run or run-status responses — not the UUID from run URLs.") }, READ_ONLY_ANNOTATIONS, async (params) => {
+        try {
+            const result = await getRunDetails(client, params);
+            return buildJsonToolResponse("get-run-details", sanitizeResponse(result));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+}

package/dist/workflows/progress.d.ts

@@ -0,0 +1,20 @@
+export type WorkflowProgressNotification = {
+    method: "notifications/progress";
+    params: {
+        progressToken: string | number;
+        progress: number;
+        total?: number;
+        message?: string;
+    };
+};
+export type WorkflowProgressExtra = {
+    signal?: AbortSignal;
+    _meta?: {
+        progressToken?: string | number;
+    };
+    sendNotification?: (notification: WorkflowProgressNotification) => Promise<void>;
+};
+export type WorkflowProgressReporter = (message: string, total?: number) => Promise<void>;
+export declare function throwIfAborted(signal?: AbortSignal): void;
+export declare function sleepWithAbort(ms: number, signal?: AbortSignal): Promise<void>;
+export declare function createWorkflowProgressReporter(extra?: WorkflowProgressExtra): WorkflowProgressReporter | undefined;

package/dist/workflows/progress.js

@@ -0,0 +1,54 @@
+function createAbortError() {
+    const error = new Error("Request was cancelled");
+    error.name = "AbortError";
+    return error;
+}
+export function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw createAbortError();
+    }
+}
+export async function sleepWithAbort(ms, signal) {
+    throwIfAborted(signal);
+    if (!signal) {
+        await new Promise((resolve) => setTimeout(resolve, ms));
+        return;
+    }
+    await new Promise((resolve, reject) => {
+        const timeoutHandle = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timeoutHandle);
+            signal.removeEventListener("abort", onAbort);
+            reject(createAbortError());
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+export function createWorkflowProgressReporter(extra) {
+    const progressToken = extra?._meta?.progressToken;
+    const sendNotification = extra?.sendNotification;
+    if (progressToken === undefined || !sendNotification) {
+        return undefined;
+    }
+    let progress = 0;
+    return async (message, total) => {
+        progress += 1;
+        try {
+            await sendNotification({
+                method: "notifications/progress",
+                params: {
+                    progressToken,
+                    progress,
+                    ...(total !== undefined ? { total } : {}),
+                    ...(message ? { message } : {}),
+                },
+            });
+        }
+        catch {
+            // Progress is best-effort and should not fail the workflow.
+        }
+    };
+}

package/dist/workflows/retry-and-wait.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type CoalesceClient } from "../client.js";
+import { RerunParams } from "../coalesce/types.js";
+import { type WorkflowProgressReporter } from "./progress.js";
+export declare function retryAndWait(client: CoalesceClient, params: z.infer<typeof RerunParams> & {
+    pollInterval?: number;
+    timeout?: number;
+}, options?: {
+    signal?: AbortSignal;
+    reportProgress?: WorkflowProgressReporter;
+}): Promise<unknown>;
+export declare function registerRetryAndWait(server: McpServer, client: CoalesceClient): void;

package/dist/workflows/retry-and-wait.js

@@ -0,0 +1,139 @@
+import { z } from "zod";
+import { CoalesceApiError } from "../client.js";
+import { RerunParams, buildJsonToolResponse, buildRerunBody, WRITE_ANNOTATIONS, sanitizeResponse, handleToolError, } from "../coalesce/types.js";
+import { createWorkflowProgressReporter, sleepWithAbort, throwIfAborted, } from "./progress.js";
+import { formatRunStatusForMessage, isTerminalRunStatus, validateRunStatus, } from "./run-status.js";
+function remainingTimeMs(startedAt, totalTimeoutMs) {
+    return Math.max(0, totalTimeoutMs - (Date.now() - startedAt));
+}
+function serializeResultsError(error) {
+    if (error instanceof CoalesceApiError) {
+        return {
+            message: error.message,
+            status: error.status,
+            ...(error.detail !== undefined ? { detail: error.detail } : {}),
+        };
+    }
+    if (error instanceof Error) {
+        return { message: error.message };
+    }
+    return { message: "Unable to fetch run results", detail: error };
+}
+export async function retryAndWait(client, params, options = {}) {
+    const pollInterval = Math.max(5, Math.min(params.pollInterval ?? 10, 300)) * 1000;
+    const timeout = Math.max(30, Math.min(params.timeout ?? 1800, 3600)) * 1000;
+    const startedAt = Date.now();
+    const { signal, reportProgress } = options;
+    throwIfAborted(signal);
+    // Retry the run — response is { runCounter: number }
+    const body = buildRerunBody(params);
+    const rerunResult = (await client.post("/scheduler/rerun", body, undefined, {
+        timeoutMs: remainingTimeMs(startedAt, timeout),
+    }));
+    if (typeof rerunResult.runCounter !== "number") {
+        throw new Error(`rerun response did not include a numeric runCounter (got ${typeof rerunResult.runCounter})`);
+    }
+    const runCounter = rerunResult.runCounter;
+    await reportProgress?.(`Started retry run ${runCounter}. Polling every ${pollInterval / 1000}s for up to ${timeout / 1000}s.`);
+    // Poll for status
+    let lastStatus = null;
+    let pollCount = 0;
+    while (remainingTimeMs(startedAt, timeout) > 0) {
+        const nextPollDelay = Math.min(pollInterval, remainingTimeMs(startedAt, timeout));
+        await sleepWithAbort(nextPollDelay, signal);
+        const statusTimeoutMs = remainingTimeMs(startedAt, timeout);
+        if (statusTimeoutMs <= 0) {
+            break;
+        }
+        let status;
+        try {
+            status = (await client.get("/scheduler/runStatus", {
+                runCounter,
+            }, { timeoutMs: statusTimeoutMs }));
+        }
+        catch (error) {
+            if (error instanceof CoalesceApiError && error.status === 408) {
+                pollCount += 1;
+                await reportProgress?.(`Status check ${pollCount} for retry run ${runCounter} timed out. Retrying while time remains.`);
+                continue;
+            }
+            throw error;
+        }
+        lastStatus = status;
+        pollCount += 1;
+        const runStatus = status.runStatus;
+        await reportProgress?.(`Status check ${pollCount} for retry run ${runCounter}: ${formatRunStatusForMessage(runStatus)}.`);
+        const validatedRunStatus = validateRunStatus(runCounter, runStatus);
+        if (isTerminalRunStatus(validatedRunStatus)) {
+            // Fetch run results — runCounter is the numeric run ID
+            await reportProgress?.(`Retry run ${runCounter} reached terminal status ${validatedRunStatus}. Fetching results.`);
+            const resultsTimeoutMs = remainingTimeMs(startedAt, timeout);
+            if (resultsTimeoutMs <= 0) {
+                await reportProgress?.(`Workflow deadline reached before results could be fetched for retry run ${runCounter}.`);
+                return {
+                    status,
+                    results: null,
+                    resultsError: {
+                        message: "Workflow timeout reached before run results could be fetched",
+                        status: 408,
+                    },
+                    incomplete: true,
+                };
+            }
+            try {
+                const results = await client.get(`/api/v1/runs/${runCounter}/results`, undefined, { timeoutMs: resultsTimeoutMs });
+                await reportProgress?.(`Fetched results for retry run ${runCounter}.`);
+                return { status, results };
+            }
+            catch (error) {
+                const serializedError = serializeResultsError(error);
+                await reportProgress?.(`Retry run ${runCounter} finished, but fetching results failed: ${serializedError.message}.`);
+                return {
+                    status,
+                    results: null,
+                    resultsError: serializedError,
+                    incomplete: true,
+                };
+            }
+        }
+    }
+    // Timeout — return last known status
+    let finalStatus = lastStatus;
+    const finalStatusTimeoutMs = remainingTimeMs(startedAt, timeout);
+    if (finalStatusTimeoutMs > 0) {
+        try {
+            finalStatus = await client.get("/scheduler/runStatus", {
+                runCounter: runCounter,
+            }, { timeoutMs: finalStatusTimeoutMs });
+        }
+        catch (error) {
+            if (!(error instanceof CoalesceApiError && error.status === 408)) {
+                throw error;
+            }
+        }
+    }
+    if (finalStatus && typeof finalStatus === "object") {
+        validateRunStatus(runCounter, finalStatus.runStatus);
+    }
+    await reportProgress?.(`Timed out waiting for retry run ${runCounter}. Returning the last known status.`);
+    return { status: finalStatus, results: null, timedOut: true };
+}
+export function registerRetryAndWait(server, client) {
+    server.tool("retry-and-wait", "Retry a failed Coalesce run and wait for it to complete. Requires the runID from the original run. " +
+        "Requires Snowflake Key Pair auth; credentials are read from environment variables. Polls run status until finished or timeout.", RerunParams.extend({
+        pollInterval: z.number().optional().describe("Seconds between status checks (default: 10, min: 5, max: 300)"),
+        timeout: z.number().optional().describe("Max seconds to wait (default: 1800, min: 30, max: 3600)"),
+    }).shape, WRITE_ANNOTATIONS, async (params, extra) => {
+        try {
+            const progressReporter = createWorkflowProgressReporter(extra);
+            const result = await retryAndWait(client, params, {
+                signal: extra?.signal,
+                reportProgress: progressReporter,
+            });
+            return buildJsonToolResponse("retry-and-wait", sanitizeResponse(result));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+}

package/dist/workflows/run-and-wait.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type CoalesceClient } from "../client.js";
+import { StartRunParams } from "../coalesce/types.js";
+import { type WorkflowProgressReporter } from "./progress.js";
+export declare function runAndWait(client: CoalesceClient, params: z.infer<typeof StartRunParams> & {
+    pollInterval?: number;
+    timeout?: number;
+}, options?: {
+    signal?: AbortSignal;
+    reportProgress?: WorkflowProgressReporter;
+}): Promise<unknown>;
+export declare function registerRunAndWait(server: McpServer, client: CoalesceClient): void;

package/dist/workflows/run-and-wait.js

@@ -0,0 +1,141 @@
+import { z } from "zod";
+import { CoalesceApiError } from "../client.js";
+import { StartRunParams, buildJsonToolResponse, buildStartRunBody, WRITE_ANNOTATIONS, sanitizeResponse, handleToolError, } from "../coalesce/types.js";
+import { createWorkflowProgressReporter, sleepWithAbort, throwIfAborted, } from "./progress.js";
+import { formatRunStatusForMessage, isTerminalRunStatus, validateRunStatus, } from "./run-status.js";
+function remainingTimeMs(startedAt, totalTimeoutMs) {
+    return Math.max(0, totalTimeoutMs - (Date.now() - startedAt));
+}
+function serializeResultsError(error) {
+    if (error instanceof CoalesceApiError) {
+        return {
+            message: error.message,
+            status: error.status,
+            ...(error.detail !== undefined ? { detail: error.detail } : {}),
+        };
+    }
+    if (error instanceof Error) {
+        return { message: error.message };
+    }
+    return { message: "Unable to fetch run results", detail: error };
+}
+export async function runAndWait(client, params, options = {}) {
+    const pollInterval = Math.max(5, Math.min(params.pollInterval ?? 10, 300)) * 1000;
+    const timeout = Math.max(30, Math.min(params.timeout ?? 1800, 3600)) * 1000;
+    const startedAt = Date.now();
+    const { signal, reportProgress } = options;
+    throwIfAborted(signal);
+    // Start the run — response is { runCounter: number }
+    const body = buildStartRunBody(params);
+    const startResult = (await client.post("/scheduler/startRun", body, undefined, {
+        timeoutMs: remainingTimeMs(startedAt, timeout),
+    }));
+    if (typeof startResult.runCounter !== "number") {
+        throw new Error(`startRun response did not include a numeric runCounter (got ${typeof startResult.runCounter})`);
+    }
+    const runCounter = startResult.runCounter;
+    await reportProgress?.(`Started run ${runCounter}. Polling every ${pollInterval / 1000}s for up to ${timeout / 1000}s.`);
+    // Poll for status
+    let lastStatus = null;
+    let pollCount = 0;
+    while (remainingTimeMs(startedAt, timeout) > 0) {
+        const nextPollDelay = Math.min(pollInterval, remainingTimeMs(startedAt, timeout));
+        await sleepWithAbort(nextPollDelay, signal);
+        const statusTimeoutMs = remainingTimeMs(startedAt, timeout);
+        if (statusTimeoutMs <= 0) {
+            break;
+        }
+        let status;
+        try {
+            status = (await client.get("/scheduler/runStatus", {
+                runCounter,
+            }, { timeoutMs: statusTimeoutMs }));
+        }
+        catch (error) {
+            if (error instanceof CoalesceApiError && error.status === 408) {
+                pollCount += 1;
+                await reportProgress?.(`Status check ${pollCount} for run ${runCounter} timed out. Retrying while time remains.`);
+                continue;
+            }
+            throw error;
+        }
+        lastStatus = status;
+        pollCount += 1;
+        const runStatus = status.runStatus;
+        await reportProgress?.(`Status check ${pollCount} for run ${runCounter}: ${formatRunStatusForMessage(runStatus)}.`);
+        const validatedRunStatus = validateRunStatus(runCounter, runStatus);
+        if (isTerminalRunStatus(validatedRunStatus)) {
+            // Fetch run results — runCounter is the numeric run ID
+            await reportProgress?.(`Run ${runCounter} reached terminal status ${validatedRunStatus}. Fetching results.`);
+            const resultsTimeoutMs = remainingTimeMs(startedAt, timeout);
+            if (resultsTimeoutMs <= 0) {
+                await reportProgress?.(`Workflow deadline reached before results could be fetched for run ${runCounter}.`);
+                return {
+                    status,
+                    results: null,
+                    resultsError: {
+                        message: "Workflow timeout reached before run results could be fetched",
+                        status: 408,
+                    },
+                    incomplete: true,
+                };
+            }
+            try {
+                const results = await client.get(`/api/v1/runs/${runCounter}/results`, undefined, { timeoutMs: resultsTimeoutMs });
+                await reportProgress?.(`Fetched results for run ${runCounter}.`);
+                return { status, results };
+            }
+            catch (error) {
+                const serializedError = serializeResultsError(error);
+                await reportProgress?.(`Run ${runCounter} finished, but fetching results failed: ${serializedError.message}.`);
+                return {
+                    status,
+                    results: null,
+                    resultsError: serializedError,
+                    incomplete: true,
+                };
+            }
+        }
+    }
+    // Timeout — return last known status
+    let finalStatus = lastStatus;
+    const finalStatusTimeoutMs = remainingTimeMs(startedAt, timeout);
+    if (finalStatusTimeoutMs > 0) {
+        try {
+            finalStatus = await client.get("/scheduler/runStatus", {
+                runCounter,
+            }, { timeoutMs: finalStatusTimeoutMs });
+        }
+        catch (error) {
+            if (!(error instanceof CoalesceApiError && error.status === 408)) {
+                throw error;
+            }
+        }
+    }
+    if (finalStatus && typeof finalStatus === "object") {
+        validateRunStatus(runCounter, finalStatus.runStatus);
+    }
+    await reportProgress?.(`Timed out waiting for run ${runCounter}. Returning the last known status.`);
+    return { status: finalStatus, results: null, timedOut: true };
+}
+export function registerRunAndWait(server, client) {
+    server.tool("run-and-wait", "Start a Coalesce run and wait for completion. Requires a numeric environmentID and optionally a jobID (not job name). " +
+        "If the user provides a job name instead of an ID, ask them for the job ID. " +
+        "If the user doesn't know the environment ID, use list-environments to look it up by name. " +
+        "Requires Snowflake Key Pair auth; credentials are read from environment variables. Polls run status until finished or timeout.", StartRunParams.extend({
+        pollInterval: z.number().optional().describe("Seconds between status checks (default: 10, min: 5, max: 300)"),
+        timeout: z.number().optional().describe("Max seconds to wait (default: 1800, min: 30, max: 3600)"),
+    }).shape, WRITE_ANNOTATIONS, async (params, extra) => {
+        try {
+            const progressReporter = createWorkflowProgressReporter(extra);
+            const result = await runAndWait(client, params, {
+                signal: extra?.signal,
+                reportProgress: progressReporter,
+            });
+            return buildJsonToolResponse("run-and-wait", sanitizeResponse(result));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+}

package/dist/workflows/run-status.d.ts

@@ -0,0 +1,10 @@
+declare const TERMINAL_RUN_STATUS_VALUES: readonly ["completed", "failed", "canceled"];
+declare const NON_TERMINAL_RUN_STATUS_VALUES: readonly ["waitingToRun", "running"];
+export type TerminalRunStatus = (typeof TERMINAL_RUN_STATUS_VALUES)[number];
+export type NonTerminalRunStatus = (typeof NON_TERMINAL_RUN_STATUS_VALUES)[number];
+export type KnownRunStatus = TerminalRunStatus | NonTerminalRunStatus;
+export declare const DOCUMENTED_RUN_STATUSES: readonly ["waitingToRun", "running", "completed", "failed", "canceled"];
+export declare function formatRunStatusForMessage(runStatus: unknown): string;
+export declare function validateRunStatus(runCounter: number, runStatus: unknown): KnownRunStatus;
+export declare function isTerminalRunStatus(runStatus: KnownRunStatus): runStatus is TerminalRunStatus;
+export {};

package/dist/workflows/run-status.js

@@ -0,0 +1,27 @@
+const TERMINAL_RUN_STATUS_VALUES = ["completed", "failed", "canceled"];
+const NON_TERMINAL_RUN_STATUS_VALUES = ["waitingToRun", "running"];
+const TERMINAL_RUN_STATUSES = new Set(TERMINAL_RUN_STATUS_VALUES);
+const KNOWN_RUN_STATUSES = new Set([
+    ...TERMINAL_RUN_STATUS_VALUES,
+    ...NON_TERMINAL_RUN_STATUS_VALUES,
+]);
+export const DOCUMENTED_RUN_STATUSES = [
+    ...NON_TERMINAL_RUN_STATUS_VALUES,
+    ...TERMINAL_RUN_STATUS_VALUES,
+];
+export function formatRunStatusForMessage(runStatus) {
+    return typeof runStatus === "string" ? runStatus : "unknown";
+}
+export function validateRunStatus(runCounter, runStatus) {
+    const expected = DOCUMENTED_RUN_STATUSES.join(", ");
+    if (typeof runStatus !== "string") {
+        throw new Error(`Run ${runCounter} returned a non-string runStatus (${typeof runStatus}). Expected one of: ${expected}.`);
+    }
+    if (!KNOWN_RUN_STATUSES.has(runStatus)) {
+        throw new Error(`Run ${runCounter} returned unexpected runStatus '${runStatus}'. Expected one of: ${expected}.`);
+    }
+    return runStatus;
+}
+export function isTerminalRunStatus(runStatus) {
+    return TERMINAL_RUN_STATUSES.has(runStatus);
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "coalesce-transform-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for the Coalesce Transform API; run tools support Snowflake Key Pair auth only",
+  "main": "dist/index.js",
+  "bin": {
+    "coalesce-transform-mcp": "./dist/index.js"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "dev": "tsc --watch",
+    "import:node-type-corpus": "node scripts/import-node-type-corpus.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["mcp", "coalesce", "transform", "model-context-protocol"],
+  "files": ["dist", "README.md", "LICENSE"],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "yaml": "^2.8.3",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.1.0"
+  }
+}