qingflow-mcp 0.2.0 → 0.2.2

package/README.md

@@ -14,6 +14,10 @@ It intentionally excludes delete for now.
 
 ## Setup
 
+Runtime requirement:
+
+- Node.js `>=18`
+
 1. Install dependencies:
 
 ```bash
@@ -56,6 +60,12 @@ Global install from GitHub:
 npm i -g git+https://github.com/853046310/qingflow-mcp.git
 ```
 
+Install latest from npm:
+
+```bash
+npm i -g qingflow-mcp@latest
+```
+
 Or one-click installer:
 
 ```bash
@@ -93,6 +103,37 @@ MCP client config example:
 3. `qf_record_create` or `qf_record_update`.
 4. If create/update returns only `request_id`, call `qf_operation_get` to resolve async result.
 
+## List Query Tips
+
+1. For `qf_records_list.sort[].que_id`, use a real field `que_id` (numeric) or exact field title from `qf_form_get`.
+2. Avoid aliases like `create_time`; Qingflow often rejects them.
+3. When `include_answers=true`, the server auto-limits returned items to protect MCP context size.
+4. You can override item count with `max_items` in `qf_records_list`.
+
+Optional env vars:
+
+```bash
+export QINGFLOW_LIST_MAX_ITEMS_WITH_ANSWERS=5
+export QINGFLOW_LIST_MAX_ITEMS_BYTES=400000
+```
+
+## Troubleshooting
+
+If you see runtime errors around `Headers` or missing web APIs:
+
+1. Upgrade Node to `>=18`.
+2. Upgrade package to latest:
+
+```bash
+npm i -g qingflow-mcp@latest
+```
+
+3. Verify runtime:
+
+```bash
+node -e "console.log(process.version, typeof fetch, typeof Headers)"
+```
+
 ## Publish
 
 ```bash

package/dist/qingflow-client.js

@@ -88,24 +88,25 @@ export class QingflowClient {
         const options = params.options ?? {};
         const url = new URL(params.path, this.baseUrl);
         appendQuery(url, options.query);
-        const headers = new Headers();
-        headers.set("accessToken", this.accessToken);
+        const headers = {
+            accessToken: this.accessToken
+        };
         if (options.userId) {
-            headers.set("userId", options.userId);
+            headers.userId = options.userId;
         }
         const init = {
             method: params.method,
             headers
         };
         if (options.body !== undefined) {
-            headers.set("content-type", "application/json");
+            headers["content-type"] = "application/json";
             init.body = JSON.stringify(options.body);
         }
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), this.timeoutMs);
         init.signal = controller.signal;
         try {
-            const response = await fetch(url, init);
+            const response = await getFetch()(url, init);
             const text = await response.text();
             const data = safeJsonParse(text);
             if (!response.ok) {
@@ -253,3 +254,12 @@ function toFiniteNumber(value) {
     }
     return null;
 }
+function getFetch() {
+    const runtimeFetch = globalThis.fetch;
+    if (typeof runtimeFetch === "function") {
+        return runtimeFetch.bind(globalThis);
+    }
+    throw new QingflowApiError({
+        message: "Global fetch is not available. Use Node.js >= 18."
+    });
+}

package/dist/server.js

@@ -19,6 +19,9 @@ const MODE_TO_TYPE = {
 };
 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_MAX_ITEMS_WITH_ANSWERS = toPositiveInt(process.env.QINGFLOW_LIST_MAX_ITEMS_WITH_ANSWERS) ?? 5;
+const MAX_LIST_ITEMS_BYTES = toPositiveInt(process.env.QINGFLOW_LIST_MAX_ITEMS_BYTES) ?? 400000;
 const accessToken = process.env.QINGFLOW_ACCESS_TOKEN;
 const baseUrl = process.env.QINGFLOW_BASE_URL;
 if (!accessToken) {
@@ -187,6 +190,7 @@ const listInputSchema = z.object({
         search_user_ids: z.array(z.string()).optional()
     }))
         .optional(),
+    max_items: z.number().int().positive().max(200).optional(),
     include_answers: z.boolean().optional()
 });
 const listOutputSchema = z.object({
@@ -358,36 +362,55 @@ server.registerTool("qf_records_list", {
     }
 }, async (args) => {
     try {
+        const pageNum = args.page_num ?? 1;
+        const pageSize = args.page_size ?? DEFAULT_PAGE_SIZE;
+        const normalizedSort = await normalizeListSort(args.sort, args.app_key, args.user_id);
         const payload = buildListPayload({
-            pageNum: args.page_num ?? 1,
-            pageSize: args.page_size ?? 50,
+            pageNum,
+            pageSize,
             mode: args.mode,
             type: args.type,
             keyword: args.keyword,
             queryLogic: args.query_logic,
             applyIds: args.apply_ids,
-            sort: args.sort,
+            sort: normalizedSort,
             filters: args.filters
         });
         const response = await client.listRecords(args.app_key, payload, { userId: args.user_id });
         const result = asObject(response.result);
         const rawItems = asArray(result?.result);
         const includeAnswers = Boolean(args.include_answers);
-        const items = rawItems.map((raw) => normalizeRecordItem(raw, includeAnswers));
+        const listLimit = resolveListItemLimit({
+            total: rawItems.length,
+            requestedMaxItems: args.max_items,
+            includeAnswers
+        });
+        const items = rawItems
+            .slice(0, listLimit.limit)
+            .map((raw) => normalizeRecordItem(raw, includeAnswers));
+        const fitted = fitListItemsWithinSize({
+            items,
+            limitBytes: MAX_LIST_ITEMS_BYTES
+        });
+        const truncationReason = mergeTruncationReasons(listLimit.reason, fitted.reason);
         return okResult({
             ok: true,
             data: {
                 app_key: args.app_key,
                 pagination: {
-                    page_num: toPositiveInt(result?.pageNum) ?? (args.page_num ?? 1),
-                    page_size: toPositiveInt(result?.pageSize) ?? (args.page_size ?? 50),
+                    page_num: toPositiveInt(result?.pageNum) ?? pageNum,
+                    page_size: toPositiveInt(result?.pageSize) ?? pageSize,
                     page_amount: toNonNegativeInt(result?.pageAmount),
-                    result_amount: toNonNegativeInt(result?.resultAmount) ?? items.length
+                    result_amount: toNonNegativeInt(result?.resultAmount) ?? fitted.items.length
                 },
-                items
+                items: fitted.items
             },
             meta: buildMeta(response)
-        }, `Fetched ${items.length} records`);
+        }, buildRecordsListMessage({
+            returned: fitted.items.length,
+            total: rawItems.length,
+            truncationReason
+        }));
     }
     catch (error) {
         return errorResult(error);
@@ -789,6 +812,97 @@ function resolveFieldByKey(fieldKey, index) {
     }
     return null;
 }
+async function normalizeListSort(sort, appKey, userId) {
+    if (!sort?.length) {
+        return sort;
+    }
+    // Fast path for numeric que_id, which can be passed through directly.
+    if (sort.every((item) => isNumericKey(String(item.que_id)))) {
+        return sort.map((item) => ({
+            que_id: Number(item.que_id),
+            ...(item.ascend !== undefined ? { ascend: item.ascend } : {})
+        }));
+    }
+    const form = await getFormCached(appKey, userId, false);
+    const index = buildFieldIndex(form.result);
+    return sort.map((item) => {
+        const rawKey = String(item.que_id).trim();
+        const resolved = resolveFieldByKey(rawKey, index);
+        if (!resolved || resolved.queId === undefined || resolved.queId === null) {
+            throw new Error(`Cannot resolve sort.que_id "${rawKey}". Use numeric que_id or exact field title from qf_form_get.`);
+        }
+        return {
+            que_id: normalizeQueId(resolved.queId),
+            ...(item.ascend !== undefined ? { ascend: item.ascend } : {})
+        };
+    });
+}
+function resolveListItemLimit(params) {
+    if (params.total <= 0) {
+        return { limit: 0, reason: null };
+    }
+    if (params.requestedMaxItems !== undefined) {
+        const limit = Math.min(params.total, params.requestedMaxItems);
+        if (limit < params.total) {
+            return {
+                limit,
+                reason: `limited by max_items=${params.requestedMaxItems}`
+            };
+        }
+        return { limit, reason: null };
+    }
+    if (params.includeAnswers && params.total > DEFAULT_MAX_ITEMS_WITH_ANSWERS) {
+        return {
+            limit: DEFAULT_MAX_ITEMS_WITH_ANSWERS,
+            reason: `auto-limited to ${DEFAULT_MAX_ITEMS_WITH_ANSWERS} items because include_answers=true`
+        };
+    }
+    return { limit: params.total, reason: null };
+}
+function fitListItemsWithinSize(params) {
+    let candidate = params.items;
+    let size = jsonSizeBytes(candidate);
+    if (size <= params.limitBytes) {
+        return { items: candidate, reason: null };
+    }
+    while (candidate.length > 1) {
+        candidate = candidate.slice(0, candidate.length - 1);
+        size = jsonSizeBytes(candidate);
+        if (size <= params.limitBytes) {
+            return {
+                items: candidate,
+                reason: `auto-limited to ${candidate.length} items to keep response <= ${params.limitBytes} bytes`
+            };
+        }
+    }
+    throw new Error(`qf_records_list response is too large (${size} bytes > ${params.limitBytes}) even with 1 item. Use qf_record_get(apply_id).`);
+}
+function mergeTruncationReasons(...reasons) {
+    const list = reasons.filter((item) => Boolean(item));
+    return list.length > 0 ? list.join("; ") : null;
+}
+function buildRecordsListMessage(params) {
+    if (!params.truncationReason) {
+        return `Fetched ${params.returned} records`;
+    }
+    return `Fetched ${params.returned}/${params.total} records (${params.truncationReason})`;
+}
+function normalizeQueId(queId) {
+    if (typeof queId === "number" && Number.isInteger(queId)) {
+        return queId;
+    }
+    if (typeof queId === "string") {
+        const normalized = queId.trim();
+        if (!normalized) {
+            throw new Error("Resolved que_id is empty");
+        }
+        return isNumericKey(normalized) ? Number(normalized) : normalized;
+    }
+    throw new Error(`Resolved que_id has unsupported type: ${typeof queId}`);
+}
+function jsonSizeBytes(value) {
+    return Buffer.byteLength(JSON.stringify(value), "utf8");
+}
 function isNumericKey(value) {
     return /^\d+$/.test(value.trim());
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qingflow-mcp",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "private": false,
   "license": "MIT",
   "type": "module",
@@ -35,6 +35,9 @@
     "start": "node dist/server.js",
     "prepublishOnly": "npm run build"
   },
+  "engines": {
+    "node": ">=18"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.17.4",
     "zod": "^3.25.76"