@fluentcommerce/fluent-mcp-extn 0.1.0

package/dist/errors.js

@@ -0,0 +1,150 @@
+/**
+ * Typed application error that captures an explicit code and retry hint.
+ */
+export class ToolError extends Error {
+    code;
+    retryable;
+    details;
+    constructor(code, message, options) {
+        super(message, options?.cause ? { cause: options.cause } : undefined);
+        this.name = "ToolError";
+        this.code = code;
+        this.retryable = options?.retryable ?? false;
+        this.details = options?.details;
+    }
+}
+/**
+ * Extract an HTTP status code from an error object.
+ * SDK errors commonly expose status via `.statusCode`, `.status`, or
+ * `.response.status` — all of which are safer than substring matching
+ * on the free-form message text.
+ */
+function extractHttpStatus(error) {
+    if (!error || typeof error !== "object")
+        return null;
+    const rec = error;
+    // Nested response.status (axios-style errors)
+    const resp = rec.response;
+    if (resp && typeof resp === "object") {
+        const respRec = resp;
+        const val = respRec.status ?? respRec.statusCode;
+        if (typeof val === "number" && val >= 100 && val < 600)
+            return val;
+        if (typeof val === "string") {
+            const parsed = Number(val.trim());
+            if (Number.isFinite(parsed) && parsed >= 100 && parsed < 600)
+                return parsed;
+        }
+    }
+    // Top-level statusCode is common in Node HTTP errors; avoid generic top-level
+    // "status" fields because they often represent non-HTTP domain statuses.
+    const statusCode = rec.statusCode;
+    if (typeof statusCode === "number" && statusCode >= 100 && statusCode < 600) {
+        return statusCode;
+    }
+    if (typeof statusCode === "string") {
+        const parsed = Number(statusCode.trim());
+        if (Number.isFinite(parsed) && parsed >= 100 && parsed < 600) {
+            return parsed;
+        }
+    }
+    return null;
+}
+/**
+ * Maps unknown runtime errors to our stable tool error contract.
+ *
+ * Classification priority:
+ * 1. ToolError pass-through
+ * 2. HTTP status code from error properties (safe, no false positives)
+ * 3. Error code string (Node.js network errors like ECONNRESET)
+ * 4. Keyword-based message classification (conservative patterns)
+ * 5. Fallback to SDK_ERROR or UNKNOWN_ERROR
+ */
+function normalizeUnknownError(error) {
+    if (error instanceof ToolError)
+        return error;
+    const message = error instanceof Error
+        ? error.message
+        : error && typeof error === "object" && typeof error.message === "string"
+            ? String(error.message)
+            : String(error);
+    const normalized = message.toLowerCase();
+    // ---- Phase 1: HTTP status code from error properties (safe) ----
+    const httpStatus = extractHttpStatus(error);
+    if (httpStatus !== null) {
+        if (httpStatus === 401 || httpStatus === 403) {
+            return new ToolError("AUTH_ERROR", message, { retryable: false });
+        }
+        if (httpStatus === 429) {
+            return new ToolError("RATE_LIMIT", message, { retryable: true });
+        }
+        if (httpStatus >= 500 && httpStatus <= 599) {
+            return new ToolError("UPSTREAM_UNAVAILABLE", message, { retryable: true });
+        }
+    }
+    // ---- Phase 2: Error code (Node.js system errors) ----
+    const errorCode = error && typeof error === "object" ? error.code : undefined;
+    if (typeof errorCode === "string") {
+        const code = errorCode.toUpperCase();
+        if (code === "ECONNRESET" ||
+            code === "ECONNREFUSED" ||
+            code === "EAI_AGAIN" ||
+            code === "ENOTFOUND" ||
+            code === "ETIMEDOUT" ||
+            code === "EPIPE") {
+            return new ToolError("NETWORK_ERROR", message, { retryable: true });
+        }
+        if (code === "ABORT_ERR" || code === "ETIMEOUT") {
+            return new ToolError("TIMEOUT_ERROR", message, { retryable: true });
+        }
+    }
+    // ---- Phase 3: Keyword-based classification (conservative patterns) ----
+    if (/\bzod(error)?\b/i.test(message)) {
+        return new ToolError("VALIDATION_ERROR", message, { retryable: false });
+    }
+    if (/\btimeout\b/i.test(message) || normalized.includes("timed out")) {
+        return new ToolError("TIMEOUT_ERROR", message, { retryable: true });
+    }
+    if (/\brate[\s-]?limit(?:ed|ing)?\b/i.test(message) ||
+        normalized.includes("too many requests")) {
+        return new ToolError("RATE_LIMIT", message, { retryable: true });
+    }
+    if (normalized.includes("econnreset") ||
+        normalized.includes("econnrefused") ||
+        normalized.includes("eai_again") ||
+        normalized.includes("enotfound") ||
+        normalized.includes("network error") ||
+        normalized.includes("fetch failed")) {
+        return new ToolError("NETWORK_ERROR", message, { retryable: true });
+    }
+    // ---- Phase 4: Fallback ----
+    if (error instanceof Error) {
+        return new ToolError("SDK_ERROR", error.message, {
+            retryable: false,
+            cause: error,
+        });
+    }
+    return new ToolError("UNKNOWN_ERROR", message, { retryable: false });
+}
+/**
+ * Single source of truth for retryability.
+ * Normalizes unknown errors and checks the retryable flag.
+ */
+export function isRetryable(error) {
+    return normalizeUnknownError(error).retryable;
+}
+/**
+ * Converts any thrown value into a MCP-safe failure payload.
+ */
+export function toToolFailure(error) {
+    const normalized = normalizeUnknownError(error);
+    return {
+        ok: false,
+        error: {
+            code: normalized.code,
+            message: normalized.message,
+            retryable: normalized.retryable,
+            details: normalized.details,
+        },
+    };
+}

package/dist/event-payload.js

@@ -0,0 +1,22 @@
+/**
+ * Builds a normalized event payload using input overrides plus config defaults.
+ */
+export function buildEventPayload(input, config) {
+    // MCP tool input is JSON-compatible; we cast to SDK AttributeValue shape.
+    const attributes = (input.attributes ?? {});
+    return {
+        name: input.name,
+        entityRef: input.entityRef,
+        entityId: input.entityId,
+        entityType: input.entityType,
+        entitySubtype: input.entitySubtype,
+        rootEntityRef: input.rootEntityRef ?? input.entityRef,
+        rootEntityType: input.rootEntityType ?? "ORDER",
+        rootEntityId: input.rootEntityId,
+        retailerId: input.retailerId ?? config.retailerId ?? undefined,
+        accountId: input.accountId ?? config.accountId ?? undefined,
+        source: input.source ?? "fluent-mcp-extn",
+        type: input.type ?? "NORMAL",
+        attributes,
+    };
+}

package/dist/fluent-client.js

@@ -0,0 +1,229 @@
+import { ToolError } from "./errors.js";
+import { withRetry, withTimeout } from "./resilience.js";
+function hasFunction(target, key) {
+    if (!target || typeof target !== "object")
+        return false;
+    const value = target[key];
+    return typeof value === "function";
+}
+function toSdkClientSurface(rawClient) {
+    if (hasFunction(rawClient, "sendEvent") &&
+        hasFunction(rawClient, "getEvents") &&
+        hasFunction(rawClient, "getEventById") &&
+        hasFunction(rawClient, "graphql") &&
+        hasFunction(rawClient, "createJob") &&
+        hasFunction(rawClient, "sendBatch") &&
+        hasFunction(rawClient, "getJobStatus") &&
+        hasFunction(rawClient, "getBatchStatus") &&
+        hasFunction(rawClient, "getJobResults")) {
+        return rawClient;
+    }
+    return null;
+}
+/**
+ * Typed wrapper around SDK APIs with shared timeout/retry behavior.
+ */
+export class FluentClientAdapter {
+    client;
+    config;
+    retryPolicy;
+    constructor(client, config) {
+        this.client = client;
+        this.config = config;
+        this.retryPolicy = {
+            attempts: config.retryAttempts,
+            initialDelayMs: config.retryInitialDelayMs,
+            maxDelayMs: config.retryMaxDelayMs,
+            factor: config.retryFactor,
+        };
+    }
+    /**
+     * Read-path wrapper: timeout + retry with exponential backoff.
+     * Safe for idempotent reads (getEvents, getEventById, graphql queries,
+     * getJobStatus, getBatchStatus, getJobResults).
+     */
+    async execute(operationName, operation) {
+        return withRetry(operationName, this.retryPolicy, () => withTimeout(operationName, this.config.requestTimeoutMs, operation));
+    }
+    /**
+     * Write-path wrapper: timeout only, NO retry.
+     * Prevents duplicate side effects for non-idempotent operations
+     * (sendEvent, createJob, sendBatch, batchMutate).
+     *
+     * Timeout errors are marked non-retryable so callers don't
+     * accidentally retry them either.
+     */
+    async executeOnce(operationName, operation) {
+        return withTimeout(operationName, this.config.requestTimeoutMs, operation);
+    }
+    /**
+     * Long-running wrapper: custom timeout with retry.
+     * Used for auto-paginated queries that may take longer than a single request.
+     */
+    async executeLong(operationName, timeoutMs, operation) {
+        return withRetry(operationName, this.retryPolicy, () => withTimeout(operationName, timeoutMs, operation));
+    }
+    // ---- Write operations (executeOnce — no retry) --------------------------
+    async sendEvent(event, mode = "async") {
+        return this.executeOnce("sendEvent", () => this.client.sendEvent(event, mode));
+    }
+    async createJob(payload) {
+        return this.executeOnce("createJob", () => this.client.createJob(payload));
+    }
+    async sendBatch(jobId, payload) {
+        return this.executeOnce("sendBatch", () => this.client.sendBatch(jobId, payload));
+    }
+    // ---- Read operations (execute — timeout + retry) ------------------------
+    async getEvents(params = {}) {
+        return this.execute("getEvents", () => this.client.getEvents(params));
+    }
+    async getEventById(eventId) {
+        return this.execute("getEventById", () => this.client.getEventById(eventId));
+    }
+    async graphql(payload, options) {
+        if (options?.retry === false) {
+            return this.executeOnce("graphql", () => this.client.graphql(payload));
+        }
+        return this.execute("graphql", () => this.client.graphql(payload));
+    }
+    async getJobStatus(jobId) {
+        return this.execute("getJobStatus", () => this.client.getJobStatus(jobId));
+    }
+    async getBatchStatus(jobId, batchId) {
+        return this.execute("getBatchStatus", () => this.client.getBatchStatus(jobId, batchId));
+    }
+    async getJobResults(jobId) {
+        return this.execute("getJobResults", () => this.client.getJobResults(jobId));
+    }
+    /**
+     * Require the raw `request` method on the SDK client.
+     * Used for APIs not yet wrapped by first-class SDK methods.
+     */
+    requireRequestClient(apiName) {
+        if (!hasFunction(this.client, "request")) {
+            throw new ToolError("SDK_ERROR", `${apiName} is not supported by current SDK client (request method missing).`);
+        }
+        return this.client;
+    }
+    /**
+     * Unwrap SDK response: if it has a `data` property, return that; otherwise the whole response.
+     */
+    static unwrapResponse(response) {
+        if (response && typeof response === "object" && "data" in response) {
+            return response.data;
+        }
+        return response;
+    }
+    /**
+     * Query User Action transitions from /api/v4.1/transition.
+     * Although this endpoint uses POST, it is read-only and safe to retry.
+     */
+    async getTransitions(payload) {
+        const requestClient = this.requireRequestClient("Transition API");
+        return this.execute("getTransitions", async () => {
+            const response = await requestClient.request("/api/v4.1/transition", {
+                method: "POST",
+                body: payload,
+            });
+            return FluentClientAdapter.unwrapResponse(response);
+        });
+    }
+    /**
+     * Fetch the orchestration plugin/rule registry from /orchestration/rest/v1/plugin.
+     * Returns a map of rule names → metadata (description, accepts, produces, params).
+     * Read-only — safe to retry.
+     */
+    async getPlugins() {
+        const requestClient = this.requireRequestClient("Plugin API");
+        return this.execute("getPlugins", async () => {
+            const response = await requestClient.request("/orchestration/rest/v1/plugin", { method: "GET" });
+            return FluentClientAdapter.unwrapResponse(response);
+        });
+    }
+    /**
+     * Query Prometheus metrics via GraphQL metricInstant / metricRange queries.
+     * The Fluent platform does NOT expose raw Prometheus REST endpoints
+     * (/api/v1/query returns 400). All PromQL goes through the GraphQL proxy.
+     * Read-only operation; safe to retry.
+     */
+    async queryPrometheus(payload) {
+        const isRange = payload.type === "range";
+        const query = isRange
+            ? `query MetricRange($query: String!, $start: DateTime!, $end: DateTime!, $step: String!) {
+          metricRange(query: $query, start: $start, end: $end, step: $step) {
+            status
+            data { resultType result { metric values } }
+            errorType error warnings
+          }
+        }`
+            : `query MetricInstant($query: String!${payload.time ? ", $time: DateTime" : ""}) {
+          metricInstant(query: $query${payload.time ? ", time: $time" : ""}) {
+            status
+            data { resultType result { metric value } }
+            errorType error warnings
+          }
+        }`;
+        const variables = { query: payload.query };
+        if (isRange) {
+            if (payload.start)
+                variables.start = payload.start;
+            if (payload.end)
+                variables.end = payload.end;
+            if (payload.step)
+                variables.step = payload.step;
+        }
+        else if (payload.time) {
+            variables.time = payload.time;
+        }
+        return this.execute("queryPrometheus", async () => {
+            const gqlResponse = await this.client.graphql({
+                query,
+                variables,
+            });
+            // Extract the metricInstant or metricRange result
+            const data = gqlResponse?.data;
+            const metricResult = data?.[isRange ? "metricRange" : "metricInstant"];
+            if (metricResult && typeof metricResult === "object" && "status" in metricResult) {
+                return metricResult;
+            }
+            // Handle GraphQL errors
+            const errors = gqlResponse?.errors;
+            if (errors) {
+                return {
+                    status: "error",
+                    errorType: "graphql",
+                    error: JSON.stringify(errors),
+                };
+            }
+            return { status: "success", data: metricResult ?? data };
+        });
+    }
+    // ---- Long-running operations (executeLong — custom timeout + retry) -----
+    /**
+     * Execute a GraphQL query with explicit pagination config.
+     * Uses the pagination timeoutMs (or a generous default) instead of the
+     * per-request timeout, since multi-page fetches can legitimately run
+     * for minutes.
+     */
+    async graphqlPaginated(payload) {
+        const paginationTimeout = payload.pagination?.timeoutMs ?? 300_000; // 5 min default
+        return this.executeLong("graphqlPaginated", paginationTimeout, () => this.client.graphql(payload));
+    }
+    /**
+     * Returns a lightweight object implementing GraphQLCapable.
+     * Standalone SDK services (FluentConnectionTester, GraphQLIntrospectionService)
+     * only need graphql() — this adapter satisfies that contract.
+     */
+    asGraphQLCapable() {
+        return {
+            graphql: (payload) => this.graphql(payload),
+        };
+    }
+}
+export function createFluentClientAdapter(rawClient, config) {
+    const client = toSdkClientSurface(rawClient);
+    if (!client) {
+        throw new ToolError("SDK_ERROR", "SDK client does not expose the required methods for MCP tools.");
+    }
+    return new FluentClientAdapter(client, config);
+}

package/dist/index.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createRequire } from "node:module";
+import { loadConfig } from "./config.js";
+import { loadResponseBudget } from "./response-shaper.js";
+import { initSDKClient } from "./sdk-client.js";
+import { registerToolHandlers, TOOL_NAMES } from "./tools.js";
+const require = createRequire(import.meta.url);
+const { version: PKG_VERSION } = require("../package.json");
+/**
+ * Process entrypoint:
+ * - load runtime config
+ * - initialize SDK adapter
+ * - register MCP tools
+ * - attach stdio transport
+ */
+async function start() {
+    const config = await loadConfig();
+    const client = await initSDKClient(config);
+    const server = new Server({
+        name: "fluent-mcp-extn",
+        version: PKG_VERSION,
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    const responseBudget = loadResponseBudget();
+    registerToolHandlers(server, { client, config, responseBudget });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`[fluent-mcp-extn] v${PKG_VERSION} running on stdio`);
+    console.error(`[fluent-mcp-extn] tools: ${TOOL_NAMES.join(", ")}`);
+    console.error(`[fluent-mcp-extn] sdk adapter: ${client ? "ready" : "not configured"}`);
+    const shutdown = async () => {
+        await server.close();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+start().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[fluent-mcp-extn] failed to start: ${message}`);
+    process.exit(1);
+});

package/dist/resilience.js

@@ -0,0 +1,52 @@
+import { ToolError, isRetryable } from "./errors.js";
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Wraps async operations with a hard timeout.
+ */
+export async function withTimeout(operationName, timeoutMs, operation) {
+    let timeoutId = null;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+            reject(new ToolError("TIMEOUT_ERROR", `${operationName} timed out after ${timeoutMs}ms`, { retryable: true }));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([operation(), timeoutPromise]);
+    }
+    finally {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+    }
+}
+/**
+ * Retries transient failures using exponential backoff.
+ */
+export async function withRetry(operationName, policy, operation) {
+    // 0 = single attempt with no retry; minimum 1 actual execution.
+    const attempts = Math.max(1, policy.attempts);
+    let lastError;
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt >= attempts || !isRetryable(error))
+                break;
+            // Exponential backoff with jitter and a hard cap.
+            const baseDelay = Math.min(policy.maxDelayMs, Math.round(policy.initialDelayMs * Math.pow(policy.factor, attempt - 1)));
+            const delay = Math.round(baseDelay * (0.5 + Math.random() * 0.5));
+            await sleep(delay);
+        }
+    }
+    if (lastError instanceof ToolError)
+        throw lastError;
+    if (lastError instanceof Error)
+        throw lastError;
+    throw new ToolError("SDK_ERROR", `${operationName} failed after retries`, {
+        retryable: false,
+        details: { attempts },
+    });
+}