qingflow-mcp 0.3.12 → 0.3.13

package/README.md

@@ -108,7 +108,7 @@ npm i -g git+https://github.com/853046310/qingflow-mcp.git
 Install from npm (pinned version):
 
 ```bash
-npm i -g qingflow-mcp@0.3.12
+npm i -g qingflow-mcp@0.3.13
 ```
 
 Or one-click installer:
@@ -184,6 +184,7 @@ Deterministic read protocol (list/summary/aggregate):
 1. output profile:
    - default `output_profile=compact`: return core data only (`rows/row/groups/summary` + `next_page_token`)
    - `output_profile=verbose`: include full contract (`completeness` + `evidence` + `meta`)
+   - exception: `qf_query(summary)` and `qf_records_aggregate` always return `completeness`, even in `compact`, so agents can block on incomplete statistics
 2. when `output_profile=verbose`, `completeness` fields are:
    - `result_amount`
    - `returned_items`
@@ -204,9 +205,17 @@ Deterministic read protocol (list/summary/aggregate):
    - `time_range`
    - `source_pages`
 4. `strict_full=true` makes incomplete results fail fast with `NEED_MORE_DATA`.
+   - for `qf_query(summary)`, `strict_full` enforces raw source scan completeness; sample rows may still be capped by `max_rows`, which is reflected by `output_page_complete=false`
 5. Error payloads expose `error_code` and `fix_hint` for actionable retries.
 6. Parameter tolerance supports stringified JSON and numeric/boolean strings for key query fields.
 
+For `qf_query(summary)` and `qf_records_aggregate`, read `data.summary.completeness` / `data.completeness` before concluding:
+
+1. `raw_scan_complete=false`: source data is not fully scanned, do not produce a final conclusion.
+2. `scan_limit_hit=true`: query stopped because scan budget was hit.
+3. `output_page_complete=false`: source may be complete, but output was truncated by `max_rows` or `max_groups`.
+4. `raw_next_page_token`: use this token to continue raw scan pagination (`next_page_token` remains as a backward-compatible alias).
+
 ## List Query Tips
 
 Strict mode (`qf_records_list`):

package/dist/server.js

@@ -61,7 +61,7 @@ const ADAPTIVE_TARGET_PAGE_MS = toPositiveInt(process.env.QINGFLOW_ADAPTIVE_TARG
 const MAX_LIST_ITEMS_BYTES = toPositiveInt(process.env.QINGFLOW_LIST_MAX_ITEMS_BYTES) ?? 400000;
 const REQUEST_TIMEOUT_MS = toPositiveInt(process.env.QINGFLOW_REQUEST_TIMEOUT_MS) ?? 18000;
 const EXECUTION_BUDGET_MS = toPositiveInt(process.env.QINGFLOW_EXECUTION_BUDGET_MS) ?? 20000;
-const SERVER_VERSION = "0.3.12";
+const SERVER_VERSION = "0.3.13";
 const accessToken = process.env.QINGFLOW_ACCESS_TOKEN;
 const baseUrl = process.env.QINGFLOW_BASE_URL;
 if (!accessToken) {
@@ -143,7 +143,15 @@ const completenessSchema = z.object({
     is_complete: z.boolean(),
     partial: z.boolean(),
     omitted_items: z.number().int().nonnegative(),
-    omitted_chars: z.number().int().nonnegative()
+    omitted_chars: z.number().int().nonnegative(),
+    raw_scan_complete: z.boolean().optional(),
+    scan_limit_hit: z.boolean().optional(),
+    scanned_pages: z.number().int().nonnegative().optional(),
+    scan_limit: z.number().int().positive().optional(),
+    output_page_complete: z.boolean().optional(),
+    raw_next_page_token: z.string().nullable().optional(),
+    output_next_page_token: z.string().nullable().optional(),
+    stop_reason: z.string().nullable().optional()
 });
 const evidenceSchema = z.object({
     query_id: z.string(),
@@ -2846,6 +2854,35 @@ function applyAdaptivePaging(params) {
     }
     return { shouldStop: false };
 }
+function resolveScanLimit(requestedPages, scanMaxPages) {
+    return Math.max(1, Math.min(requestedPages, scanMaxPages));
+}
+function buildExtendedCompleteness(params) {
+    const rawScanComplete = params.rawScanComplete ?? (!params.hasMore && params.omittedItems === 0);
+    const outputPageComplete = params.outputPageComplete ?? (params.omittedItems === 0 && params.omittedChars === 0);
+    const isComplete = rawScanComplete && outputPageComplete;
+    return {
+        result_amount: params.resultAmount,
+        returned_items: params.returnedItems,
+        fetched_pages: params.fetchedPages,
+        requested_pages: params.requestedPages,
+        actual_scanned_pages: params.fetchedPages,
+        has_more: params.hasMore,
+        next_page_token: params.nextPageToken,
+        is_complete: isComplete,
+        partial: !isComplete,
+        omitted_items: params.omittedItems,
+        omitted_chars: params.omittedChars,
+        raw_scan_complete: rawScanComplete,
+        scan_limit_hit: params.scanLimitHit ?? false,
+        scanned_pages: params.scannedPages ?? params.fetchedPages,
+        scan_limit: params.scanLimit,
+        output_page_complete: outputPageComplete,
+        raw_next_page_token: params.rawNextPageToken ?? params.nextPageToken,
+        output_next_page_token: params.outputNextPageToken ?? null,
+        stop_reason: params.stopReason ?? null
+    };
+}
 function normalizePlanToolName(tool) {
     const normalized = tool.trim().replace(/^qingflow-mcp__/, "");
     const allowed = new Set([
@@ -4360,6 +4397,7 @@ async function executeRecordsSummary(args) {
     let nextPageNum = null;
     let resultAmount = null;
     let summaryMeta = null;
+    let stopReason = null;
     let totalAmount = 0;
     let missingCount = 0;
     const sourcePages = [];
@@ -4369,6 +4407,7 @@ async function executeRecordsSummary(args) {
         if (scannedPages > 0 && isExecutionBudgetExceeded(startedAt)) {
             hasMore = true;
             nextPageNum = currentPage;
+            stopReason = "execution_budget";
             break;
         }
         const activePageSize = adaptivePaging.current_page_size;
@@ -4442,9 +4481,11 @@ async function executeRecordsSummary(args) {
         });
         if (adaptiveDecision.shouldStop && hasMore) {
             nextPageNum = nextPageNum ?? currentPage + 1;
+            stopReason = "adaptive_budget";
             break;
         }
         if (!hasMore) {
+            stopReason = "source_exhausted";
             break;
         }
         currentPage = currentPage + 1;
@@ -4491,30 +4532,41 @@ async function executeRecordsSummary(args) {
         throw new Error("Failed to build summary metadata");
     }
     const knownResultAmount = resultAmount ?? scannedRecords;
-    const omittedItems = Math.max(0, knownResultAmount - scannedRecords);
-    const isComplete = !hasMore && omittedItems === 0;
-    const nextPageToken = hasMore && nextPageNum
+    const omittedSourceItems = Math.max(0, knownResultAmount - scannedRecords);
+    const rawNextPageToken = hasMore && nextPageNum
         ? encodeContinuationToken({
             app_key: args.app_key,
             next_page_num: nextPageNum,
             page_size: adaptivePaging.current_page_size
         })
         : null;
-    const completeness = {
-        result_amount: knownResultAmount,
-        returned_items: scannedRecords,
-        fetched_pages: scannedPages,
-        requested_pages: requestedPages,
-        actual_scanned_pages: scannedPages,
-        has_more: hasMore,
-        next_page_token: nextPageToken,
-        is_complete: isComplete,
-        partial: !isComplete,
-        omitted_items: omittedItems,
-        omitted_chars: 0
-    };
+    const rawScanComplete = !hasMore && omittedSourceItems === 0;
+    const outputPageComplete = rows.length >= scannedRecords;
+    const scanLimit = resolveScanLimit(requestedPages, scanMaxPages);
+    const scanLimitHit = !rawScanComplete &&
+        (scannedPages >= scanLimit ||
+            stopReason === "execution_budget" ||
+            stopReason === "adaptive_budget");
+    const completeness = buildExtendedCompleteness({
+        resultAmount: knownResultAmount,
+        returnedItems: scannedRecords,
+        fetchedPages: scannedPages,
+        requestedPages,
+        hasMore,
+        nextPageToken: rawNextPageToken,
+        omittedItems: omittedSourceItems,
+        omittedChars: 0,
+        rawScanComplete,
+        scanLimitHit,
+        scannedPages,
+        scanLimit,
+        outputPageComplete,
+        rawNextPageToken,
+        outputNextPageToken: null,
+        stopReason
+    });
     const evidence = buildEvidencePayload(listState, sourcePages);
-    if (strictFull && !isComplete) {
+    if (strictFull && !rawScanComplete) {
         throw new NeedMoreDataError("Summary is incomplete. Continue with next_page_token or increase requested_pages/scan_max_pages.", {
             code: "NEED_MORE_DATA",
             completeness,
@@ -4530,9 +4582,9 @@ async function executeRecordsSummary(args) {
                 missing_count: missingCount
             },
             rows,
+            completeness,
             ...(isVerboseProfile(outputProfile)
                 ? {
-                    completeness,
                     evidence,
                     meta: {
                         field_mapping: fieldMapping,
@@ -4554,7 +4606,7 @@ async function executeRecordsSummary(args) {
                         execution: {
                             scanned_records: scannedRecords,
                             scanned_pages: scannedPages,
-                            truncated: !isComplete,
+                            truncated: !completeness.is_complete,
                             row_cap: rowCap,
                             column_cap: args.max_columns ?? null,
                             scan_max_pages: scanMaxPages
@@ -4564,7 +4616,7 @@ async function executeRecordsSummary(args) {
                 : {})
         },
         meta: summaryMeta,
-        message: isComplete
+        message: completeness.is_complete
             ? `Summarized ${scannedRecords} records`
             : `Summarized ${scannedRecords}/${knownResultAmount} records (partial)`,
         completeness,
@@ -4636,6 +4688,7 @@ async function executeRecordsAggregate(args) {
     let nextPageNum = null;
     let resultAmount = null;
     let responseMeta = null;
+    let stopReason = null;
     let totalAmount = 0;
     const sourcePages = [];
     const groupStats = new Map();
@@ -4644,6 +4697,7 @@ async function executeRecordsAggregate(args) {
         if (scannedPages > 0 && isExecutionBudgetExceeded(startedAt)) {
             hasMore = true;
             nextPageNum = currentPage;
+            stopReason = "execution_budget";
             break;
         }
         const activePageSize = adaptivePaging.current_page_size;
@@ -4723,9 +4777,11 @@ async function executeRecordsAggregate(args) {
         });
         if (adaptiveDecision.shouldStop && hasMore) {
             nextPageNum = nextPageNum ?? currentPage + 1;
+            stopReason = "adaptive_budget";
             break;
         }
         if (!hasMore) {
+            stopReason = "source_exhausted";
             break;
         }
         currentPage = currentPage + 1;
@@ -4734,30 +4790,42 @@ async function executeRecordsAggregate(args) {
         throw new Error("Failed to fetch aggregate pages");
     }
     const knownResultAmount = resultAmount ?? scannedRecords;
-    const omittedItems = Math.max(0, knownResultAmount - scannedRecords);
-    const isComplete = !hasMore && omittedItems === 0;
-    const nextPageToken = hasMore && nextPageNum
+    const omittedSourceItems = Math.max(0, knownResultAmount - scannedRecords);
+    const rawNextPageToken = hasMore && nextPageNum
         ? encodeContinuationToken({
             app_key: args.app_key,
             next_page_num: nextPageNum,
             page_size: adaptivePaging.current_page_size
         })
         : null;
-    const completeness = {
-        result_amount: knownResultAmount,
-        returned_items: scannedRecords,
-        fetched_pages: scannedPages,
-        requested_pages: requestedPages,
-        actual_scanned_pages: scannedPages,
-        has_more: hasMore,
-        next_page_token: nextPageToken,
-        is_complete: isComplete,
-        partial: !isComplete,
-        omitted_items: omittedItems,
-        omitted_chars: 0
-    };
+    const groupsTotal = groupStats.size;
+    const rawScanComplete = !hasMore && omittedSourceItems === 0;
+    const outputPageComplete = groupsTotal <= maxGroups;
+    const scanLimit = resolveScanLimit(requestedPages, scanMaxPages);
+    const scanLimitHit = !rawScanComplete &&
+        (scannedPages >= scanLimit ||
+            stopReason === "execution_budget" ||
+            stopReason === "adaptive_budget");
+    const completeness = buildExtendedCompleteness({
+        resultAmount: knownResultAmount,
+        returnedItems: scannedRecords,
+        fetchedPages: scannedPages,
+        requestedPages,
+        hasMore,
+        nextPageToken: rawNextPageToken,
+        omittedItems: omittedSourceItems,
+        omittedChars: 0,
+        rawScanComplete,
+        scanLimitHit,
+        scannedPages,
+        scanLimit,
+        outputPageComplete,
+        rawNextPageToken,
+        outputNextPageToken: null,
+        stopReason
+    });
     const evidence = buildEvidencePayload(listState, sourcePages);
-    if (strictFull && !isComplete) {
+    if (strictFull && !completeness.is_complete) {
         throw new NeedMoreDataError("Aggregate result is incomplete. Continue with next_page_token or increase requested_pages/scan_max_pages.", {
             code: "NEED_MORE_DATA",
             completeness,
@@ -4835,9 +4903,9 @@ async function executeRecordsAggregate(args) {
                         : {})
                 },
                 groups,
+                completeness,
                 ...(isVerboseProfile(outputProfile)
                     ? {
-                        completeness,
                         evidence,
                         meta: {
                             field_mapping: fieldMapping,
@@ -4867,7 +4935,7 @@ async function executeRecordsAggregate(args) {
                 }
                 : {})
         },
-        message: isComplete
+        message: completeness.is_complete
             ? `Aggregated ${scannedRecords} records`
             : `Aggregated ${scannedRecords}/${knownResultAmount} records (partial)`
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qingflow-mcp",
-  "version": "0.3.12",
+  "version": "0.3.13",
   "private": false,
   "license": "MIT",
   "type": "module",