@fluentcommerce/fluent-mcp-extn 0.7.2 → 0.7.4

package/README.md

@@ -50,7 +50,7 @@ The official `fluent mcp server` (bundled with Fluent CLI) covers core GraphQL a
 | Auto-paginated GraphQL (`graphql_queryAll`) | | Yes |
 | GraphQL planning helpers (`graphql_planOperation` / `graphql_buildQuery` / `graphql_generateFull`) | | Yes |
 | Batch mutations (`graphql_batchMutate`) | | Yes |
-| Batch ingestion (`batch.*`) | | Yes |
+| Batch ingestion (`batch_*`) | | Yes |
 | Batch payload planning (`batch_describePayload`) | | Yes |
 | Prometheus metrics (`metrics_query`) | | Yes |
 | Metrics health assessment (`metrics_healthCheck`) | | Yes |
@@ -295,6 +295,14 @@ npx @fluentcommerce/fluent-mcp-extn
 
 This starts the MCP stdio server process. In a plain terminal it appears idle because it is waiting for MCP JSON-RPC input from your IDE/agent.
 
+To run with **Streamable HTTP** transport instead of stdio:
+
+```bash
+FLUENT_MCP_TRANSPORT=http npx @fluentcommerce/fluent-mcp-extn
+```
+
+This starts an HTTP server (default port 3100, override with `FLUENT_MCP_HTTP_PORT`). Set `FLUENT_MCP_AUTH_TOKEN` to enable bearer token authentication. Useful for remote MCP clients or multi-agent setups where stdio is not practical.
+
 Or install as a project dependency:
 
 ```bash
@@ -419,7 +427,7 @@ Example:
 }
 ```
 
-Typical category values: `config`, `health`, `connection`, `event`, `metrics`, `workflow`, `plugin`, `graphql`, `batch`, `webhook`, `entity`, `setting`, `environment`, `test`, `cache`.
+Typical category values: `config`, `health`, `time`, `connection`, `event`, `metrics`, `workflow`, `plugin`, `graphql`, `batch`, `webhook`, `entity`, `setting`, `environment`, `test`, `cache`.
 
 This is a prompt-budget optimization, not an access-control boundary. It reduces what the MCP client discovers, but it does not block an explicit low-level `tools/call` if a caller already knows a hidden tool name.
 
@@ -538,7 +546,7 @@ Compare workflow versions across retailers:
 ```
 1. workflow_get { entityType: "ORDER", entitySubtype: "HD", profile: "STAGING/UK" }
 2. workflow_get { entityType: "ORDER", entitySubtype: "HD", profile: "STAGING/US" }
-3. workflow_diff { left: <uk-workflow>, right: <us-workflow> }
+3. workflow_diff { base: <uk-workflow>, target: <us-workflow> }
 ```
 
 ### Cache
@@ -988,7 +996,7 @@ With `outputDir`, each workflow is saved as `{TYPE}-{SUBTYPE}.json` (e.g., `ORDE
 
 | Tool | Description |
 |---|---|
-| `setting_get` | Fetch settings by name (`%` wildcards supported), optionally save to local file to keep large JSON out of LLM context |
+| `setting_get` | Fetch settings by name (`%` wildcards supported). Auto-paginates wildcard queries via edge cursors (up to 500 records). Warns when results are truncated. Optionally save to local file to keep large JSON out of LLM context. |
 | `setting_upsert` | Create or update a setting with upsert semantics — queries existing by name + context + contextId first |
 | `setting_bulkUpsert` | Batch create/update up to 50 settings with per-setting error handling |
 
@@ -1198,7 +1206,7 @@ See the [Getting Started](https://www.npmjs.com/package/@fluentcommerce/ai-skill
 ```bash
 git clone https://bitbucket.org/fluentcommerce/fluent-mcp-extn.git
 cd fluent-mcp-extn
-npm install && npm run build && npm test   # 524 unit tests across 23 test files
+npm install && npm run build && npm test   # 601 unit tests across 25 test files
 npm run dev                                # hot-reload via tsx
 ```
 

package/dist/event-tools.js

@@ -473,7 +473,15 @@ export async function handleEventList(args, ctx) {
         const analysis = analyzeEvents(events.results, events.hasMore ?? false);
         return { ok: true, analyze: true, ...analysis };
     }
-    return { ok: true, events };
+    const hasMore = events.hasMore ?? false;
+    return {
+        ok: true,
+        events,
+        ...(hasMore ? {
+            _truncated: true,
+            _truncationWarning: `More events exist beyond this page. Use 'start' parameter to fetch the next page, or narrow filters (entityType, from/to, eventStatus) to reduce results.`,
+        } : {}),
+    };
 }
 /**
  * Handle event_flowInspect tool call.
@@ -493,6 +501,7 @@ export async function handleEventFlowInspect(args, ctx) {
     if (parsed.rootEntityId !== undefined) {
         baseParams["context.rootEntityId"] = parsed.rootEntityId;
     }
+    let _paginationTruncated = false;
     const fetchPaged = async (extraParams) => {
         const all = [];
         let page = 1;
@@ -505,8 +514,10 @@ export async function handleEventFlowInspect(args, ctx) {
             };
             const result = await client.getEvents(reqParams);
             const rows = Array.isArray(result?.results) ? result.results : [];
-            if (rows.length === 0)
+            if (rows.length === 0) {
+                hasMore = false;
                 break;
+            }
             for (const row of rows) {
                 const rec = asRecord(row);
                 if (rec)
@@ -515,6 +526,8 @@ export async function handleEventFlowInspect(args, ctx) {
             hasMore = result.hasMore ?? rows.length >= 500;
             page += 1;
         }
+        if (hasMore)
+            _paginationTruncated = true;
         return all;
     };
     const orchestrationEvents = await fetchPaged({
@@ -920,6 +933,10 @@ export async function handleEventFlowInspect(args, ctx) {
         window: { from: parsed.from ?? null, to: parsed.to ?? null },
         paging: { maxPages: parsed.maxPages, pageSize: 500 },
         compact: parsed.compact,
+        ...(_paginationTruncated ? {
+            _truncated: true,
+            _truncationWarning: `Results truncated at ${parsed.maxPages} pages (${parsed.maxPages * 500} events max). Increase maxPages to fetch more, or narrow the time window.`,
+        } : {}),
     };
     // ========= COMPACT MODE =========
     if (parsed.compact) {

package/dist/graphql-query-tools.js

@@ -147,6 +147,55 @@ function requireClient(ctx) {
     }
     return ctx.client;
 }
+function analyzePaginationLimits(pagination, limits) {
+    if (!pagination)
+        return { truncated: false };
+    const totalPages = typeof pagination.totalPages === "number" ? pagination.totalPages : null;
+    const totalRecords = typeof pagination.totalRecords === "number" ? pagination.totalRecords : null;
+    const pagesReached = typeof pagination.pagesFetched === "number"
+        ? pagination.pagesFetched >= limits.maxPages
+        : totalPages !== null
+            ? totalPages >= limits.maxPages
+            : false;
+    const recordsReached = typeof pagination.recordsFetched === "number"
+        ? pagination.recordsFetched >= limits.maxRecords
+        : totalRecords !== null
+            ? totalRecords >= limits.maxRecords
+            : false;
+    if (!pagesReached && !recordsReached) {
+        return { truncated: false };
+    }
+    const reasons = [];
+    if (pagesReached)
+        reasons.push(`page cap ${limits.maxPages}`);
+    if (recordsReached)
+        reasons.push(`record cap ${limits.maxRecords}`);
+    return {
+        truncated: true,
+        warning: `Auto-pagination may be truncated by the ${reasons.join(" and ")}. Narrow the query or raise the limit if you need a complete result.`,
+    };
+}
+/**
+ * Count actual edges in the merged response data.
+ * Guards against SDK metadata bugs where totalRecords is computed
+ * as totalPages × pageSize instead of the true accumulated count.
+ */
+function countConnectionEdges(result) {
+    if (!result || typeof result !== "object")
+        return null;
+    const data = result.data;
+    if (!data || typeof data !== "object")
+        return null;
+    for (const val of Object.values(data)) {
+        if (!val || typeof val !== "object")
+            continue;
+        const connection = val;
+        if (Array.isArray(connection.edges)) {
+            return connection.edges.length;
+        }
+    }
+    return null;
+}
 // ---------------------------------------------------------------------------
 // Handlers
 // ---------------------------------------------------------------------------
@@ -189,14 +238,60 @@ export async function handleGraphQLQueryAll(args, ctx) {
         errorHandling: parsed.errorHandling,
     };
     const result = await client.graphqlPaginated(payload);
-    const pagination = result.extensions?.autoPagination ?? null;
+    const rawPagination = result.extensions?.autoPagination ?? null;
+    // Reconcile SDK metadata: the SDK may report totalRecords as
+    // totalPages × pageSize instead of the true accumulated count.
+    // Count the actual edges in the merged response to detect and fix this.
+    const actualEdgeCount = countConnectionEdges(result);
+    let pagination = rawPagination;
+    if (rawPagination &&
+        typeof rawPagination === "object" &&
+        actualEdgeCount !== null) {
+        const sdkTotal = rawPagination.totalRecords;
+        if (typeof sdkTotal === "number" && sdkTotal !== actualEdgeCount) {
+            const corrected = {
+                ...rawPagination,
+                totalRecords: actualEdgeCount,
+                _sdkReportedRecords: sdkTotal,
+            };
+            pagination = corrected;
+        }
+    }
+    const paginationInfo = pagination && typeof pagination === "object"
+        ? pagination
+        : null;
+    const paginationAnalysis = analyzePaginationLimits(paginationInfo, {
+        maxPages: parsed.maxPages,
+        maxRecords: parsed.maxRecords,
+    });
     if (parsed.summarize) {
         const summary = summarizeConnection(result);
         if (summary) {
-            return { ok: true, summarized: true, ...summary, pagination };
+            return {
+                ok: true,
+                summarized: true,
+                ...summary,
+                pagination,
+                ...(paginationAnalysis.truncated
+                    ? {
+                        _truncated: true,
+                        _truncationWarning: paginationAnalysis.warning,
+                    }
+                    : {}),
+            };
         }
     }
-    return { ok: true, response: result, pagination };
+    return {
+        ok: true,
+        response: result,
+        pagination,
+        ...(paginationAnalysis.truncated
+            ? {
+                _truncated: true,
+                _truncationWarning: paginationAnalysis.warning,
+            }
+            : {}),
+    };
 }
 /**
  * Handle graphql_batchMutate tool call.

package/dist/metrics-tools.js

@@ -10,6 +10,7 @@ import { GraphQLIntrospectionService, } from "@fluentcommerce/fc-connect-sdk";
 import { ToolError } from "./errors.js";
 import { classifyMutationOperations, listMutationCatalog, } from "./mutation-taxonomy.js";
 import { parseWindowMs, recommendStep } from "./time-window.js";
+const MAX_METRICS_RANGE_POINTS = 5_000;
 // ---------------------------------------------------------------------------
 // Input schemas
 // ---------------------------------------------------------------------------
@@ -204,6 +205,13 @@ export const METRICS_TOOL_DEFINITIONS = [
 // ---------------------------------------------------------------------------
 // Math helpers
 // ---------------------------------------------------------------------------
+function parseIsoTimestamp(value, field) {
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime())) {
+        throw new ToolError("VALIDATION_ERROR", `metrics_query range ${field} must be a valid ISO-8601 timestamp.`);
+    }
+    return parsed;
+}
 function round1(value) {
     return Math.round(value * 10) / 10;
 }
@@ -1022,6 +1030,7 @@ async function aggregateEventsFromApi(client, params) {
     return {
         totalEvents: allEvents.length,
         totalPages: page - 1,
+        truncated: hasMore,
         statusBreakdown: Object.fromEntries(statusCounts),
         groups,
         uniqueNames: new Set(allEvents.map((e) => e.name)),
@@ -1064,6 +1073,28 @@ export async function handleMetricsQuery(args, ctx) {
     if (parsed.type === "range" && (!parsed.start || !parsed.end || !parsed.step)) {
         throw new ToolError("VALIDATION_ERROR", "Range queries require start, end, and step.");
     }
+    if (parsed.type === "range") {
+        const start = parseIsoTimestamp(parsed.start, "start");
+        const end = parseIsoTimestamp(parsed.end, "end");
+        const durationMs = end.getTime() - start.getTime();
+        if (durationMs <= 0) {
+            throw new ToolError("VALIDATION_ERROR", "metrics_query range end must be after start.");
+        }
+        const stepMs = parseWindowMs(parsed.step);
+        const estimatedPoints = Math.ceil(durationMs / stepMs);
+        if (estimatedPoints > MAX_METRICS_RANGE_POINTS) {
+            const hint = recommendStep(durationMs, Math.min(500, MAX_METRICS_RANGE_POINTS));
+            throw new ToolError("VALIDATION_ERROR", `Range query would request about ${estimatedPoints} points, which exceeds the safety limit of ${MAX_METRICS_RANGE_POINTS}. Increase step to at least ${hint.step}.`, {
+                details: {
+                    estimatedPoints,
+                    maxPoints: MAX_METRICS_RANGE_POINTS,
+                    recommendedStep: hint.step,
+                    recommendedStepMs: hint.stepMs,
+                    recommendedEstimatedPoints: hint.estimatedPoints,
+                },
+            });
+        }
+    }
     const client = requireClient(ctx);
     const response = await client.queryPrometheus(parsed);
     const vectors = extractPrometheusVectors(response);
@@ -1092,6 +1123,7 @@ export async function handleMetricsHealthCheck(args, ctx) {
     let statusBreakdown = {};
     let totalEvents = 0;
     let topEvents = [];
+    let eventApiTruncated = false;
     try {
         // Query 1: status breakdown
         const statusResponse = await client.queryPrometheus({
@@ -1154,6 +1186,7 @@ export async function handleMetricsHealthCheck(args, ctx) {
         });
         totalEvents = agg.totalEvents;
         statusBreakdown = agg.statusBreakdown;
+        eventApiTruncated = agg.truncated;
         if (parsed.includeTopEvents) {
             topEvents = rankTopEvents(agg.groups, agg.totalEvents, parsed.topN);
         }
@@ -1230,6 +1263,10 @@ export async function handleMetricsHealthCheck(args, ctx) {
         ok: true,
         healthy,
         source,
+        ...(eventApiTruncated ? {
+            _truncated: true,
+            _truncationWarning: "Event API results truncated — counts may be approximate. Narrow the time window for accuracy.",
+        } : {}),
         summary: {
             window,
             totalEvents,
@@ -1268,6 +1305,7 @@ export async function handleMetricsSloReport(args, ctx) {
     let pendingEvents = 0;
     let runtimeP95Seconds = null;
     let inflightP95Seconds = null;
+    let eventApiTruncated = false;
     try {
         const [totalResponse, failedResponse, noMatchResponse, pendingResponse, runtimeP95Response, inflightP95Response,] = await Promise.all([
             client.queryPrometheus({
@@ -1316,6 +1354,7 @@ export async function handleMetricsSloReport(args, ctx) {
         pendingEvents = agg.statusBreakdown["PENDING"] ?? 0;
         runtimeP95Seconds = null;
         inflightP95Seconds = null;
+        eventApiTruncated = agg.truncated;
     }
     let topFailingEvents;
     if (parsed.includeTopFailingEvents) {
@@ -1401,6 +1440,10 @@ export async function handleMetricsSloReport(args, ctx) {
         ok: true,
         source,
         healthy: findings.length === 0,
+        ...(eventApiTruncated ? {
+            _truncated: true,
+            _truncationWarning: "Event API results truncated — counts may be approximate. Narrow the time window or increase maxPages for accuracy.",
+        } : {}),
         summary: {
             window,
             timeWindow: { from, to },
@@ -1837,6 +1880,10 @@ export async function handleMetricsTopEvents(args, ctx) {
     const failedCount = agg.statusBreakdown["FAILED"] ?? 0;
     return {
         ok: true,
+        ...(agg.truncated ? {
+            _truncated: true,
+            _truncationWarning: `Event API results truncated at ${agg.totalPages} pages (${agg.totalEvents} events fetched). Counts may be approximate. Narrow the time window or increase maxPages for accuracy.`,
+        } : {}),
         analytics: {
             timeWindow: { from: parsed.from, to: toTime },
             totalEvents: agg.totalEvents,

package/dist/settings-tools.js

@@ -63,9 +63,9 @@ export const SettingGetInputSchema = z.object({
         .number()
         .int()
         .min(1)
-        .max(100)
-        .default(10)
-        .describe("Max results (default: 10, max: 100)."),
+        .max(500)
+        .default(25)
+        .describe("Max results per page (default: 25, max: 500). Auto-paginates wildcard queries using edge cursors."),
     digest: z
         .boolean()
         .default(false)
@@ -320,7 +320,10 @@ function digestSetting(setting) {
         digest,
     };
 }
-function buildSettingGetResponse(parsed, settings, cacheMeta) {
+function buildSettingGetResponse(parsed, settings, cacheMeta, truncated = false) {
+    const truncationWarning = truncated
+        ? `Results truncated at ${settings.length} settings. More exist on the server. Use graphql_queryAll with a settings query to fetch all, or narrow your filter.`
+        : undefined;
     if (settings.length === 0) {
         return {
             ok: true,
@@ -370,6 +373,7 @@ function buildSettingGetResponse(parsed, settings, cacheMeta) {
             count: settings.length,
             savedTo: outputDir,
             files: savedFiles,
+            ...(truncationWarning ? { warning: truncationWarning } : {}),
             ...(cacheMeta ? { _cache: cacheMeta } : {}),
             settings: settings.map((s) => ({
                 id: s.id,
@@ -387,6 +391,7 @@ function buildSettingGetResponse(parsed, settings, cacheMeta) {
             ok: true,
             count: settings.length,
             digested: true,
+            ...(truncationWarning ? { warning: truncationWarning } : {}),
             ...(cacheMeta ? { _cache: cacheMeta } : {}),
             settings: settings.map((s) => digestSetting(s)),
         };
@@ -394,6 +399,7 @@ function buildSettingGetResponse(parsed, settings, cacheMeta) {
     return {
         ok: true,
         count: settings.length,
+        ...(truncationWarning ? { warning: truncationWarning } : {}),
         ...(cacheMeta ? { _cache: cacheMeta } : {}),
         settings: settings.map((s) => ({
             id: s.id,
@@ -565,7 +571,7 @@ export async function handleSettingGet(args, ctx) {
     if (cacheable && ctx.cache) {
         const cached = await ctx.cache.get(cacheKey);
         if (cached.hit && Array.isArray(cached.data)) {
-            return buildSettingGetResponse(parsed, cached.data, { hit: true, ageMs: cached.ageMs ?? 0 });
+            return buildSettingGetResponse(parsed, cached.data, { hit: true, ageMs: cached.ageMs ?? 0 }, false);
         }
     }
     // Build variables — only include context/contextId if provided
@@ -585,10 +591,11 @@ export async function handleSettingGet(args, ctx) {
     else if (parsed.context === "ACCOUNT") {
         variables.contextId = [0];
     }
-    // Build query — include lobValue for full content
-    const query = `query GetSettings($name: [String!], $context: [String!], $contextId: [Int!], $first: Int) {
-  settings(name: $name, context: $context, contextId: $contextId, first: $first) {
+    // Build query — edge cursors for Fluent-style pagination
+    const query = `query GetSettings($name: [String!], $context: [String!], $contextId: [Int!], $first: Int, $after: String) {
+  settings(name: $name, context: $context, contextId: $contextId, first: $first, after: $after) {
     edges {
+      cursor
       node {
         id
         name
@@ -599,20 +606,49 @@ export async function handleSettingGet(args, ctx) {
         valueType
       }
     }
+    pageInfo {
+      hasNextPage
+    }
   }
 }`;
-    const response = await client.graphql({
-        query,
-        variables: variables,
-    });
-    const data = response?.data;
-    const connection = data?.settings;
-    const edges = (connection?.edges ?? []);
-    const settings = edges.map((e) => e.node);
+    // Auto-paginate wildcard queries using edge cursors; single-page for exact names
+    const MAX_TOTAL = 500;
+    const isWildcard = isWildcardSettingName(parsed.name);
+    const allSettings = [];
+    let cursor = null;
+    let hasNextPage = true;
+    while (hasNextPage && allSettings.length < MAX_TOTAL) {
+        const pageVars = { ...variables };
+        if (cursor)
+            pageVars.after = cursor;
+        const response = await client.graphql({
+            query,
+            variables: pageVars,
+        });
+        const data = response?.data;
+        const connection = data?.settings;
+        const edges = (connection?.edges ?? []);
+        const pageInfo = connection?.pageInfo;
+        for (const edge of edges) {
+            if (allSettings.length >= MAX_TOTAL)
+                break;
+            allSettings.push(edge.node);
+        }
+        hasNextPage = Boolean(pageInfo?.hasNextPage) && edges.length > 0;
+        // Fluent pagination: cursor lives on the edge, not in pageInfo
+        if (hasNextPage && edges.length > 0) {
+            cursor = edges[edges.length - 1].cursor ?? null;
+        }
+        // Non-wildcard: one page is enough
+        if (!isWildcard)
+            break;
+    }
+    const settings = allSettings;
+    const truncated = hasNextPage && allSettings.length >= MAX_TOTAL;
     if (cacheable && ctx.cache) {
         await ctx.cache.set(cacheKey, "setting", settings);
     }
-    return buildSettingGetResponse(parsed, settings, cacheable && ctx.cache ? { hit: false, stored: true } : undefined);
+    return buildSettingGetResponse(parsed, settings, cacheable && ctx.cache ? { hit: false, stored: true } : undefined, truncated);
 }
 /**
  * Handle setting_upsert tool call.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluentcommerce/fluent-mcp-extn",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "[Experimental] MCP (Model Context Protocol) extension server for Fluent Commerce. Exposes event dispatch, transition actions, GraphQL execution, Prometheus metrics, batch ingestion, and webhook validation as MCP tools.",
   "type": "module",
   "main": "dist/index.js",
@@ -52,7 +52,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@fluentcommerce/fc-connect-sdk": "^0.1.54",
+    "@fluentcommerce/fc-connect-sdk": "^0.1.55",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "graphql": "^16.13.1",
     "zod": "^4.3.6"