qingflow-mcp 0.3.2 → 0.3.3

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.3"
 });
 const jsonPrimitiveSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
 const answerValueSchema = z.union([
@@ -1226,9 +1229,10 @@ function missingRequiredFieldError(params) {
     });
 }
 function normalizeListInput(raw) {
-    const obj = asObject(raw);
+    const parsedRoot = parseJsonLikeDeep(raw);
+    const obj = asObject(parsedRoot);
     if (!obj) {
-        return raw;
+        return parsedRoot;
     }
     return {
         ...obj,
@@ -1250,9 +1254,10 @@ function normalizeListInput(raw) {
     };
 }
 function normalizeRecordGetInput(raw) {
-    const obj = asObject(raw);
+    const parsedRoot = parseJsonLikeDeep(raw);
+    const obj = asObject(parsedRoot);
     if (!obj) {
-        return raw;
+        return parsedRoot;
     }
     return {
         ...obj,
@@ -1262,9 +1267,10 @@ function normalizeRecordGetInput(raw) {
     };
 }
 function normalizeQueryInput(raw) {
-    const obj = asObject(raw);
+    const parsedRoot = parseJsonLikeDeep(raw);
+    const obj = asObject(parsedRoot);
     if (!obj) {
-        return raw;
+        return parsedRoot;
     }
     return {
         ...obj,
@@ -1287,9 +1293,10 @@ function normalizeQueryInput(raw) {
     };
 }
 function normalizeAggregateInput(raw) {
-    const obj = asObject(raw);
+    const parsedRoot = parseJsonLikeDeep(raw);
+    const obj = asObject(parsedRoot);
     if (!obj) {
-        return raw;
+        return parsedRoot;
     }
     return {
         ...obj,
@@ -1309,8 +1316,12 @@ function normalizeAggregateInput(raw) {
     };
 }
 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 +1329,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 +1345,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 +1403,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 +1417,7 @@ function normalizeIdArrayInput(value) {
     return parsed;
 }
 function normalizeSortInput(value) {
-    const parsed = parseJsonLike(value);
+    const parsed = parseJsonLikeDeep(value);
     if (!Array.isArray(parsed)) {
         return parsed;
     }
@@ -1406,7 +1434,7 @@ function normalizeSortInput(value) {
     });
 }
 function normalizeFiltersInput(value) {
-    const parsed = parseJsonLike(value);
+    const parsed = parseJsonLikeDeep(value);
     if (parsed === undefined || parsed === null) {
         return parsed;
     }
@@ -1425,7 +1453,7 @@ function normalizeFiltersInput(value) {
     });
 }
 function normalizeTimeRangeInput(value) {
-    const parsed = parseJsonLike(value);
+    const parsed = parseJsonLikeDeep(value);
     const obj = asObject(parsed);
     if (!obj) {
         return parsed;
@@ -1470,6 +1498,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,
@@ -1619,6 +1650,7 @@ async function executeRecordsList(args) {
     const effectiveFilters = appendTimeRangeFilter(args.filters, args.time_range);
     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 +1661,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 +1712,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,
@@ -1904,6 +1948,7 @@ async function executeRecordsSummary(args) {
             : null
     };
     let currentPage = startPage;
+    const startedAt = Date.now();
     let scannedPages = 0;
     let scannedRecords = 0;
     let hasMore = false;
@@ -1916,6 +1961,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,
@@ -2138,6 +2188,7 @@ async function executeRecordsAggregate(args) {
             : null
     };
     let currentPage = startPage;
+    const startedAt = Date.now();
     let scannedPages = 0;
     let scannedRecords = 0;
     let hasMore = false;
@@ -2148,6 +2199,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 +3037,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.3",
   "private": false,
   "license": "MIT",
   "type": "module",