qingflow-mcp 0.3.2 → 0.3.4

package/README.md

@@ -37,6 +37,8 @@ Optional:
 
 ```bash
 export QINGFLOW_FORM_CACHE_TTL_MS=300000
+export QINGFLOW_REQUEST_TIMEOUT_MS=18000
+export QINGFLOW_EXECUTION_BUDGET_MS=20000
 ```
 
 ## Run
@@ -247,8 +249,8 @@ Aggregate example (`qf_records_aggregate`):
   "app_key": "your_app_key",
   "group_by": ["归属部门", "归属销售"],
   "amount_column": "报价总金额",
-  "requested_pages": 50,
-  "scan_max_pages": 50,
+  "requested_pages": 10,
+  "scan_max_pages": 10,
   "strict_full": true
 }
 ```

package/dist/server.js

@@ -44,9 +44,11 @@ class InputValidationError extends Error {
 const FORM_CACHE_TTL_MS = Number(process.env.QINGFLOW_FORM_CACHE_TTL_MS ?? "300000");
 const formCache = new Map();
 const DEFAULT_PAGE_SIZE = 50;
-const DEFAULT_SCAN_MAX_PAGES = 50;
+const DEFAULT_SCAN_MAX_PAGES = 10;
 const DEFAULT_ROW_LIMIT = 200;
 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 accessToken = process.env.QINGFLOW_ACCESS_TOKEN;
 const baseUrl = process.env.QINGFLOW_BASE_URL;
 if (!accessToken) {
@@ -57,11 +59,12 @@ if (!baseUrl) {
 }
 const client = new QingflowClient({
     accessToken,
-    baseUrl
+    baseUrl,
+    timeoutMs: REQUEST_TIMEOUT_MS
 });
 const server = new McpServer({
     name: "qingflow-mcp",
-    version: "0.3.1"
+    version: "0.3.4"
 });
 const jsonPrimitiveSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
 const answerValueSchema = z.union([
@@ -1225,92 +1228,149 @@ function missingRequiredFieldError(params) {
         }
     });
 }
+const COMMON_INPUT_ALIASES = {
+    appKey: "app_key",
+    userId: "user_id",
+    pageNum: "page_num",
+    pageSize: "page_size",
+    pageToken: "page_token",
+    requestedPages: "requested_pages",
+    scanMaxPages: "scan_max_pages",
+    queryMode: "query_mode",
+    queryLogic: "query_logic",
+    applyId: "apply_id",
+    applyIds: "apply_ids",
+    maxRows: "max_rows",
+    maxItems: "max_items",
+    maxColumns: "max_columns",
+    selectColumns: "select_columns",
+    keepColumns: "keep_columns",
+    keep_columns: "select_columns",
+    includeAnswers: "include_answers",
+    amountColumn: "amount_column",
+    amountColumns: "amount_column",
+    amount_columns: "amount_column",
+    timeRange: "time_range",
+    statPolicy: "stat_policy",
+    groupBy: "group_by",
+    strictFull: "strict_full",
+    forceRefresh: "force_refresh",
+    forceRefreshForm: "force_refresh_form",
+    applyUser: "apply_user"
+};
+function applyAliases(obj, aliases) {
+    const out = { ...obj };
+    for (const [alias, canonical] of Object.entries(aliases)) {
+        if (out[canonical] === undefined && out[alias] !== undefined) {
+            out[canonical] = out[alias];
+        }
+    }
+    return out;
+}
 function normalizeListInput(raw) {
-    const obj = asObject(raw);
+    const parsedRoot = parseJsonLikeDeep(raw);
+    const obj = asObject(parsedRoot);
     if (!obj) {
-        return raw;
+        return parsedRoot;
     }
+    const normalizedObj = applyAliases(obj, COMMON_INPUT_ALIASES);
+    const selectColumns = normalizedObj.select_columns ?? normalizedObj.keep_columns;
     return {
-        ...obj,
-        page_num: coerceNumberLike(obj.page_num),
-        page_size: coerceNumberLike(obj.page_size),
-        requested_pages: coerceNumberLike(obj.requested_pages),
-        scan_max_pages: coerceNumberLike(obj.scan_max_pages),
-        type: coerceNumberLike(obj.type),
-        max_rows: coerceNumberLike(obj.max_rows),
-        max_items: coerceNumberLike(obj.max_items),
-        max_columns: coerceNumberLike(obj.max_columns),
-        strict_full: coerceBooleanLike(obj.strict_full),
-        include_answers: coerceBooleanLike(obj.include_answers),
-        apply_ids: normalizeIdArrayInput(obj.apply_ids),
-        sort: normalizeSortInput(obj.sort),
-        filters: normalizeFiltersInput(obj.filters),
-        select_columns: normalizeSelectorListInput(obj.select_columns),
-        time_range: normalizeTimeRangeInput(obj.time_range)
+        ...normalizedObj,
+        page_num: coerceNumberLike(normalizedObj.page_num),
+        page_size: coerceNumberLike(normalizedObj.page_size),
+        requested_pages: coerceNumberLike(normalizedObj.requested_pages),
+        scan_max_pages: coerceNumberLike(normalizedObj.scan_max_pages),
+        type: coerceNumberLike(normalizedObj.type),
+        max_rows: coerceNumberLike(normalizedObj.max_rows),
+        max_items: coerceNumberLike(normalizedObj.max_items),
+        max_columns: coerceNumberLike(normalizedObj.max_columns),
+        strict_full: coerceBooleanLike(normalizedObj.strict_full),
+        include_answers: coerceBooleanLike(normalizedObj.include_answers),
+        apply_ids: normalizeIdArrayInput(normalizedObj.apply_ids),
+        sort: normalizeSortInput(normalizedObj.sort),
+        filters: normalizeFiltersInput(normalizedObj.filters),
+        select_columns: normalizeSelectorListInput(selectColumns),
+        time_range: normalizeTimeRangeInput(normalizedObj.time_range)
     };
 }
 function normalizeRecordGetInput(raw) {
-    const obj = asObject(raw);
+    const parsedRoot = parseJsonLikeDeep(raw);
+    const obj = asObject(parsedRoot);
     if (!obj) {
-        return raw;
+        return parsedRoot;
     }
+    const normalizedObj = applyAliases(obj, COMMON_INPUT_ALIASES);
+    const selectColumns = normalizedObj.select_columns ?? normalizedObj.keep_columns;
     return {
-        ...obj,
-        apply_id: coerceNumberLike(obj.apply_id),
-        max_columns: coerceNumberLike(obj.max_columns),
-        select_columns: normalizeSelectorListInput(obj.select_columns)
+        ...normalizedObj,
+        apply_id: coerceNumberLike(normalizedObj.apply_id),
+        max_columns: coerceNumberLike(normalizedObj.max_columns),
+        select_columns: normalizeSelectorListInput(selectColumns)
     };
 }
 function normalizeQueryInput(raw) {
-    const obj = asObject(raw);
+    const parsedRoot = parseJsonLikeDeep(raw);
+    const obj = asObject(parsedRoot);
     if (!obj) {
-        return raw;
+        return parsedRoot;
     }
+    const normalizedObj = applyAliases(obj, COMMON_INPUT_ALIASES);
+    const selectColumns = normalizedObj.select_columns ?? normalizedObj.keep_columns;
     return {
-        ...obj,
-        page_num: coerceNumberLike(obj.page_num),
-        page_size: coerceNumberLike(obj.page_size),
-        requested_pages: coerceNumberLike(obj.requested_pages),
-        scan_max_pages: coerceNumberLike(obj.scan_max_pages),
-        type: coerceNumberLike(obj.type),
-        max_rows: coerceNumberLike(obj.max_rows),
-        max_items: coerceNumberLike(obj.max_items),
-        max_columns: coerceNumberLike(obj.max_columns),
-        apply_id: coerceNumberLike(obj.apply_id),
-        strict_full: coerceBooleanLike(obj.strict_full),
-        include_answers: coerceBooleanLike(obj.include_answers),
-        apply_ids: normalizeIdArrayInput(obj.apply_ids),
-        sort: normalizeSortInput(obj.sort),
-        filters: normalizeFiltersInput(obj.filters),
-        select_columns: normalizeSelectorListInput(obj.select_columns),
-        time_range: normalizeTimeRangeInput(obj.time_range)
+        ...normalizedObj,
+        page_num: coerceNumberLike(normalizedObj.page_num),
+        page_size: coerceNumberLike(normalizedObj.page_size),
+        requested_pages: coerceNumberLike(normalizedObj.requested_pages),
+        scan_max_pages: coerceNumberLike(normalizedObj.scan_max_pages),
+        type: coerceNumberLike(normalizedObj.type),
+        max_rows: coerceNumberLike(normalizedObj.max_rows),
+        max_items: coerceNumberLike(normalizedObj.max_items),
+        max_columns: coerceNumberLike(normalizedObj.max_columns),
+        apply_id: coerceNumberLike(normalizedObj.apply_id),
+        strict_full: coerceBooleanLike(normalizedObj.strict_full),
+        include_answers: coerceBooleanLike(normalizedObj.include_answers),
+        amount_column: coerceNumberLike(normalizedObj.amount_column),
+        apply_ids: normalizeIdArrayInput(normalizedObj.apply_ids),
+        sort: normalizeSortInput(normalizedObj.sort),
+        filters: normalizeFiltersInput(normalizedObj.filters),
+        select_columns: normalizeSelectorListInput(selectColumns),
+        time_range: normalizeTimeRangeInput(normalizedObj.time_range),
+        stat_policy: normalizeStatPolicyInput(normalizedObj.stat_policy)
     };
 }
 function normalizeAggregateInput(raw) {
-    const obj = asObject(raw);
+    const parsedRoot = parseJsonLikeDeep(raw);
+    const obj = asObject(parsedRoot);
     if (!obj) {
-        return raw;
+        return parsedRoot;
     }
+    const normalizedObj = applyAliases(obj, COMMON_INPUT_ALIASES);
     return {
-        ...obj,
-        page_num: coerceNumberLike(obj.page_num),
-        page_size: coerceNumberLike(obj.page_size),
-        requested_pages: coerceNumberLike(obj.requested_pages),
-        scan_max_pages: coerceNumberLike(obj.scan_max_pages),
-        type: coerceNumberLike(obj.type),
-        max_groups: coerceNumberLike(obj.max_groups),
-        strict_full: coerceBooleanLike(obj.strict_full),
-        group_by: normalizeSelectorListInput(obj.group_by),
-        amount_column: coerceNumberLike(obj.amount_column),
-        apply_ids: normalizeIdArrayInput(obj.apply_ids),
-        sort: normalizeSortInput(obj.sort),
-        filters: normalizeFiltersInput(obj.filters),
-        time_range: normalizeTimeRangeInput(obj.time_range)
+        ...normalizedObj,
+        page_num: coerceNumberLike(normalizedObj.page_num),
+        page_size: coerceNumberLike(normalizedObj.page_size),
+        requested_pages: coerceNumberLike(normalizedObj.requested_pages),
+        scan_max_pages: coerceNumberLike(normalizedObj.scan_max_pages),
+        type: coerceNumberLike(normalizedObj.type),
+        max_groups: coerceNumberLike(normalizedObj.max_groups),
+        strict_full: coerceBooleanLike(normalizedObj.strict_full),
+        group_by: normalizeSelectorListInput(normalizedObj.group_by),
+        amount_column: coerceNumberLike(normalizedObj.amount_column),
+        apply_ids: normalizeIdArrayInput(normalizedObj.apply_ids),
+        sort: normalizeSortInput(normalizedObj.sort),
+        filters: normalizeFiltersInput(normalizedObj.filters),
+        time_range: normalizeTimeRangeInput(normalizedObj.time_range),
+        stat_policy: normalizeStatPolicyInput(normalizedObj.stat_policy)
     };
 }
 function coerceNumberLike(value) {
-    if (typeof value === "string") {
-        const trimmed = value.trim();
+    const parsed = parseJsonLikeDeep(value);
+    if (typeof parsed === "number" && Number.isFinite(parsed)) {
+        return parsed;
+    }
+    if (typeof parsed === "string") {
+        const trimmed = parsed.trim();
         if (/^-?\d+(\.\d+)?$/.test(trimmed)) {
             const parsed = Number(trimmed);
             if (Number.isFinite(parsed)) {
@@ -1318,11 +1378,15 @@ function coerceNumberLike(value) {
             }
         }
     }
-    return value;
+    return parsed;
 }
 function coerceBooleanLike(value) {
-    if (typeof value === "string") {
-        const trimmed = value.trim().toLowerCase();
+    const parsed = parseJsonLikeDeep(value);
+    if (typeof parsed === "boolean") {
+        return parsed;
+    }
+    if (typeof parsed === "string") {
+        const trimmed = parsed.trim().toLowerCase();
         if (trimmed === "true") {
             return true;
         }
@@ -1330,28 +1394,41 @@ function coerceBooleanLike(value) {
             return false;
         }
     }
-    return value;
+    return parsed;
 }
-function parseJsonLike(value) {
-    if (typeof value !== "string") {
-        return value;
-    }
-    const trimmed = value.trim();
-    if (!trimmed) {
-        return value;
-    }
-    if (!trimmed.startsWith("[") && !trimmed.startsWith("{")) {
-        return value;
-    }
-    try {
-        return JSON.parse(trimmed);
-    }
-    catch {
-        return value;
+function parseJsonLikeDeep(value, maxDepth = 4) {
+    let current = value;
+    for (let i = 0; i < maxDepth; i += 1) {
+        if (typeof current !== "string") {
+            return current;
+        }
+        const trimmed = current.trim();
+        if (!trimmed) {
+            return current;
+        }
+        const singleQuoted = trimmed.startsWith("'") && trimmed.endsWith("'") && trimmed.length >= 2;
+        const candidate = singleQuoted ? trimmed.slice(1, -1) : trimmed;
+        const shouldTryJson = candidate.startsWith("{") ||
+            candidate.startsWith("[") ||
+            (candidate.startsWith('"') && candidate.endsWith('"'));
+        if (!shouldTryJson) {
+            return current;
+        }
+        try {
+            const parsed = JSON.parse(candidate);
+            if (Object.is(parsed, current)) {
+                return current;
+            }
+            current = parsed;
+        }
+        catch {
+            return current;
+        }
     }
+    return current;
 }
 function normalizeSelectorListInput(value) {
-    const parsed = parseJsonLike(value);
+    const parsed = parseJsonLikeDeep(value);
     if (Array.isArray(parsed)) {
         return parsed.map((item) => coerceNumberLike(item));
     }
@@ -1375,7 +1452,7 @@ function normalizeSelectorListInput(value) {
     return parsed;
 }
 function normalizeIdArrayInput(value) {
-    const parsed = parseJsonLike(value);
+    const parsed = parseJsonLikeDeep(value);
     if (Array.isArray(parsed)) {
         return parsed.map((item) => coerceNumberLike(item));
     }
@@ -1389,7 +1466,7 @@ function normalizeIdArrayInput(value) {
     return parsed;
 }
 function normalizeSortInput(value) {
-    const parsed = parseJsonLike(value);
+    const parsed = parseJsonLikeDeep(value);
     if (!Array.isArray(parsed)) {
         return parsed;
     }
@@ -1398,15 +1475,16 @@ function normalizeSortInput(value) {
         if (!obj) {
             return item;
         }
+        const normalizedObj = applyAliases(obj, { queId: "que_id", isAscend: "ascend" });
         return {
-            ...obj,
-            que_id: coerceNumberLike(obj.que_id),
-            ascend: coerceBooleanLike(obj.ascend)
+            ...normalizedObj,
+            que_id: coerceNumberLike(normalizedObj.que_id),
+            ascend: coerceBooleanLike(normalizedObj.ascend)
         };
     });
 }
 function normalizeFiltersInput(value) {
-    const parsed = parseJsonLike(value);
+    const parsed = parseJsonLikeDeep(value);
     if (parsed === undefined || parsed === null) {
         return parsed;
     }
@@ -1416,23 +1494,53 @@ function normalizeFiltersInput(value) {
         if (!obj) {
             return item;
         }
+        const normalizedObj = applyAliases(obj, {
+            queId: "que_id",
+            searchKey: "search_key",
+            searchKeys: "search_keys",
+            minValue: "min_value",
+            maxValue: "max_value",
+            searchOptions: "search_options",
+            searchUserIds: "search_user_ids"
+        });
         return {
-            ...obj,
-            que_id: coerceNumberLike(obj.que_id),
-            scope: coerceNumberLike(obj.scope),
-            search_options: normalizeIdArrayInput(obj.search_options)
+            ...normalizedObj,
+            que_id: coerceNumberLike(normalizedObj.que_id),
+            scope: coerceNumberLike(normalizedObj.scope),
+            search_options: normalizeIdArrayInput(normalizedObj.search_options)
         };
     });
 }
 function normalizeTimeRangeInput(value) {
-    const parsed = parseJsonLike(value);
+    const parsed = parseJsonLikeDeep(value);
+    const obj = asObject(parsed);
+    if (!obj) {
+        return parsed;
+    }
+    const normalizedObj = applyAliases(obj, {
+        queId: "column",
+        que_id: "column",
+        timeZone: "timezone"
+    });
+    return {
+        ...normalizedObj,
+        column: coerceNumberLike(normalizedObj.column)
+    };
+}
+function normalizeStatPolicyInput(value) {
+    const parsed = parseJsonLikeDeep(value);
     const obj = asObject(parsed);
     if (!obj) {
         return parsed;
     }
+    const normalizedObj = applyAliases(obj, {
+        includeNegative: "include_negative",
+        includeNull: "include_null"
+    });
     return {
-        ...obj,
-        column: coerceNumberLike(obj.column)
+        ...normalizedObj,
+        include_negative: coerceBooleanLike(normalizedObj.include_negative),
+        include_null: coerceBooleanLike(normalizedObj.include_null)
     };
 }
 function resolveStartPage(pageNum, pageToken, appKey) {
@@ -1470,6 +1578,9 @@ function decodeContinuationToken(token) {
         page_size: pageSize
     };
 }
+function isExecutionBudgetExceeded(startedAt) {
+    return Date.now() - startedAt >= EXECUTION_BUDGET_MS;
+}
 function buildEvidencePayload(state, sourcePages) {
     return {
         query_id: state.query_id,
@@ -1575,6 +1686,98 @@ function appendTimeRangeFilter(inputFilters, timeRange) {
     }
     return filters.length > 0 ? filters : undefined;
 }
+function isLikelyDateLiteral(value) {
+    if (!value) {
+        return false;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return false;
+    }
+    return /^\d{4}-\d{2}-\d{2}(?:[ T]\d{2}:\d{2}:\d{2})?$/.test(trimmed);
+}
+function isDateLikeQueType(queType) {
+    if (typeof queType === "number" && Number.isInteger(queType)) {
+        return queType === 4;
+    }
+    if (typeof queType === "string") {
+        const trimmed = queType.trim().toLowerCase();
+        if (trimmed === "date" || trimmed === "datetime") {
+            return true;
+        }
+        if (/^\d+$/.test(trimmed)) {
+            return Number(trimmed) === 4;
+        }
+    }
+    return false;
+}
+function pickDateFieldSuggestion(index) {
+    for (const field of index.byId.values()) {
+        if (!isDateLikeQueType(field.queType) || field.queId === undefined || field.queId === null) {
+            continue;
+        }
+        const normalizedQueId = normalizeQueId(field.queId);
+        if (typeof normalizedQueId === "number" && normalizedQueId <= 0) {
+            continue;
+        }
+        return {
+            que_id: normalizedQueId,
+            que_title: asNullableString(field.queTitle)
+        };
+    }
+    return null;
+}
+function hasDateLikeRangeFilters(filters) {
+    return (filters ?? []).some((item) => item.que_id !== undefined &&
+        (isLikelyDateLiteral(item.min_value) || isLikelyDateLiteral(item.max_value)));
+}
+function validateDateRangeFilters(filters, index, tool) {
+    for (const filter of filters ?? []) {
+        if (filter.que_id === undefined ||
+            (!isLikelyDateLiteral(filter.min_value) && !isLikelyDateLiteral(filter.max_value))) {
+            continue;
+        }
+        let resolved;
+        try {
+            resolved = resolveFieldByKey(String(filter.que_id), index);
+        }
+        catch (error) {
+            throw new InputValidationError({
+                message: `Cannot resolve filter field "${String(filter.que_id)}"`,
+                errorCode: "INVALID_FILTER_FIELD",
+                fixHint: "Use qf_form_get to confirm exact que_id/que_title before passing filters.",
+                details: {
+                    tool,
+                    filter,
+                    reason: error instanceof Error ? error.message : String(error)
+                }
+            });
+        }
+        if (!resolved || resolved.queType === undefined || resolved.queType === null) {
+            continue;
+        }
+        if (isDateLikeQueType(resolved.queType)) {
+            continue;
+        }
+        const suggestion = pickDateFieldSuggestion(index);
+        throw new InputValidationError({
+            message: `Date-like filter range targets non-date field "${String(filter.que_id)}"`,
+            errorCode: "FILTER_FIELD_TYPE_MISMATCH",
+            fixHint: suggestion
+                ? `Use a date field for date range filters, e.g. que_id=${String(suggestion.que_id)} (${suggestion.que_title ?? "date field"}).`
+                : "Use a date field (queType=4) for date range filters.",
+            details: {
+                tool,
+                filter,
+                resolved_field: {
+                    que_id: resolved.queId ?? null,
+                    que_title: asNullableString(resolved.queTitle),
+                    que_type: resolved.queType
+                }
+            }
+        });
+    }
+}
 function buildRecordGetArgsFromQuery(args) {
     if (args.apply_id === undefined) {
         throw missingRequiredFieldError({
@@ -1617,8 +1820,14 @@ async function executeRecordsList(args) {
     const requestedPages = args.requested_pages ?? 1;
     const scanMaxPages = args.scan_max_pages ?? requestedPages;
     const effectiveFilters = appendTimeRangeFilter(args.filters, args.time_range);
+    if (hasDateLikeRangeFilters(effectiveFilters)) {
+        const form = await getFormCached(args.app_key, args.user_id, false);
+        const index = buildFieldIndex(form.result);
+        validateDateRangeFilters(effectiveFilters, index, "qf_records_list");
+    }
     const normalizedSort = await normalizeListSort(args.sort, args.app_key, args.user_id);
     const includeAnswers = true;
+    const startedAt = Date.now();
     let currentPage = pageNum;
     let fetchedPages = 0;
     let hasMore = false;
@@ -1629,6 +1838,11 @@ async function executeRecordsList(args) {
     const sourcePages = [];
     const collectedRawItems = [];
     while (fetchedPages < requestedPages && fetchedPages < scanMaxPages) {
+        if (fetchedPages > 0 && isExecutionBudgetExceeded(startedAt)) {
+            hasMore = true;
+            nextPageNum = currentPage;
+            break;
+        }
         const payload = buildListPayload({
             pageNum: currentPage,
             pageSize,
@@ -1675,9 +1889,16 @@ async function executeRecordsList(args) {
         selectColumns: args.select_columns
     });
     if (items.length > 0 && columnProjection.matchedAnswersCount === 0) {
-        throw new Error(`No answers matched select_columns (${args.select_columns
-            .map((item) => String(item))
-            .join(", ")}). Check que_id/title from qf_form_get.`);
+        throw new InputValidationError({
+            message: `No answers matched select_columns (${args.select_columns
+                .map((item) => String(item))
+                .join(", ")}).`,
+            errorCode: "COLUMN_SELECTOR_NOT_FOUND",
+            fixHint: "Use qf_form_get to confirm que_id/que_title. If parameters were stringified, pass native JSON arrays (or plain arrays) for select_columns.",
+            details: {
+                select_columns: args.select_columns
+            }
+        });
     }
     const fitted = fitListItemsWithinSize({
         items: columnProjection.items,
@@ -1889,6 +2110,7 @@ async function executeRecordsSummary(args) {
             ...(args.time_range.to ? { max_value: args.time_range.to } : {})
         });
     }
+    validateDateRangeFilters(summaryFilters, index, "qf_query(summary)");
     const listState = {
         query_id: queryId,
         app_key: args.app_key,
@@ -1904,6 +2126,7 @@ async function executeRecordsSummary(args) {
             : null
     };
     let currentPage = startPage;
+    const startedAt = Date.now();
     let scannedPages = 0;
     let scannedRecords = 0;
     let hasMore = false;
@@ -1916,6 +2139,11 @@ async function executeRecordsSummary(args) {
     const rows = [];
     const byDay = new Map();
     while (scannedPages < requestedPages && scannedPages < scanMaxPages) {
+        if (scannedPages > 0 && isExecutionBudgetExceeded(startedAt)) {
+            hasMore = true;
+            nextPageNum = currentPage;
+            break;
+        }
         const payload = buildListPayload({
             pageNum: currentPage,
             pageSize,
@@ -2123,6 +2351,7 @@ async function executeRecordsAggregate(args) {
             ...(args.time_range.to ? { max_value: args.time_range.to } : {})
         });
     }
+    validateDateRangeFilters(aggregateFilters, index, "qf_records_aggregate");
     const listState = {
         query_id: queryId,
         app_key: args.app_key,
@@ -2138,6 +2367,7 @@ async function executeRecordsAggregate(args) {
             : null
     };
     let currentPage = startPage;
+    const startedAt = Date.now();
     let scannedPages = 0;
     let scannedRecords = 0;
     let hasMore = false;
@@ -2148,6 +2378,11 @@ async function executeRecordsAggregate(args) {
     const sourcePages = [];
     const groupStats = new Map();
     while (scannedPages < requestedPages && scannedPages < scanMaxPages) {
+        if (scannedPages > 0 && isExecutionBudgetExceeded(startedAt)) {
+            hasMore = true;
+            nextPageNum = currentPage;
+            break;
+        }
         const payload = buildListPayload({
             pageNum: currentPage,
             pageSize,
@@ -2981,14 +3216,17 @@ function toErrorPayload(error) {
         };
     }
     if (error instanceof QingflowApiError) {
+        const timeoutHint = /timeout/i.test(error.message) || /timeout/i.test(error.errMsg);
         return {
             ok: false,
-            error_code: "QINGFLOW_API_ERROR",
+            error_code: timeoutHint ? "UPSTREAM_TIMEOUT" : "QINGFLOW_API_ERROR",
             message: error.message,
             err_code: error.errCode,
             err_msg: error.errMsg || null,
             http_status: error.httpStatus,
-            fix_hint: "Check app_key/accessToken and request body against qf_form_get field definitions.",
+            fix_hint: timeoutHint
+                ? "Upstream request timed out. Reduce page_size/requested_pages, narrow filters, or continue with next_page_token."
+                : "Check app_key/accessToken and request body against qf_form_get field definitions.",
             next_page_token: null,
             details: error.details ?? null
         };

package/package.json

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