qingflow-mcp 0.2.1 → 0.2.3

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
@@ -97,8 +107,24 @@ MCP client config example:
 
 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`.
+3. Use `max_rows` (or `max_items`) to cap returned rows.
+4. Use `max_columns` to cap answers per row when `include_answers=true`.
+5. Use `select_columns` to return only specific columns (supports `que_id` or exact field title).
+6. When `include_answers=true`, the server still auto-limits by response size to protect MCP context.
+
+Example:
+
+```json
+{
+  "app_key": "your_app_key",
+  "mode": "all",
+  "page_size": 50,
+  "include_answers": true,
+  "max_rows": 10,
+  "max_columns": 5,
+  "select_columns": [1, "客户名称", "1003"]
+}
+```
 
 Optional env vars:
 
@@ -107,6 +133,23 @@ 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

@@ -190,7 +190,14 @@ const listInputSchema = z.object({
         search_user_ids: z.array(z.string()).optional()
     }))
         .optional(),
+    max_rows: z.number().int().positive().max(200).optional(),
     max_items: z.number().int().positive().max(200).optional(),
+    max_columns: z.number().int().positive().max(200).optional(),
+    select_columns: z
+        .array(z.union([z.string().min(1), z.number().int()]))
+        .min(1)
+        .max(200)
+        .optional(),
     include_answers: z.boolean().optional()
 });
 const listOutputSchema = z.object({
@@ -203,7 +210,15 @@ const listOutputSchema = z.object({
             page_amount: z.number().int().nonnegative().nullable(),
             result_amount: z.number().int().nonnegative()
         }),
-        items: z.array(recordItemSchema)
+        items: z.array(recordItemSchema),
+        applied_limits: z
+            .object({
+            include_answers: z.boolean(),
+            row_cap: z.number().int().nonnegative(),
+            column_cap: z.number().int().positive().nullable(),
+            selected_columns: z.array(z.string()).nullable()
+        })
+            .optional()
     }),
     meta: apiMetaSchema
 });
@@ -365,6 +380,7 @@ server.registerTool("qf_records_list", {
         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 includeAnswers = Boolean(args.include_answers || (args.select_columns && args.select_columns.length > 0));
         const payload = buildListPayload({
             pageNum,
             pageSize,
@@ -379,20 +395,26 @@ server.registerTool("qf_records_list", {
         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 listLimit = resolveListItemLimit({
             total: rawItems.length,
+            requestedMaxRows: args.max_rows,
             requestedMaxItems: args.max_items,
             includeAnswers
         });
         const items = rawItems
             .slice(0, listLimit.limit)
             .map((raw) => normalizeRecordItem(raw, includeAnswers));
-        const fitted = fitListItemsWithinSize({
+        const columnProjection = projectRecordItemsColumns({
             items,
+            includeAnswers,
+            maxColumns: args.max_columns,
+            selectColumns: args.select_columns
+        });
+        const fitted = fitListItemsWithinSize({
+            items: columnProjection.items,
             limitBytes: MAX_LIST_ITEMS_BYTES
         });
-        const truncationReason = mergeTruncationReasons(listLimit.reason, fitted.reason);
+        const truncationReason = mergeTruncationReasons(listLimit.reason, columnProjection.reason, fitted.reason);
         return okResult({
             ok: true,
             data: {
@@ -403,7 +425,13 @@ server.registerTool("qf_records_list", {
                     page_amount: toNonNegativeInt(result?.pageAmount),
                     result_amount: toNonNegativeInt(result?.resultAmount) ?? fitted.items.length
                 },
-                items: fitted.items
+                items: fitted.items,
+                applied_limits: {
+                    include_answers: includeAnswers,
+                    row_cap: listLimit.limit,
+                    column_cap: args.max_columns ?? null,
+                    selected_columns: columnProjection.selectedColumns
+                }
             },
             meta: buildMeta(response)
         }, buildRecordsListMessage({
@@ -841,12 +869,21 @@ function resolveListItemLimit(params) {
     if (params.total <= 0) {
         return { limit: 0, reason: null };
     }
+    const explicitLimits = [];
+    if (params.requestedMaxRows !== undefined) {
+        explicitLimits.push({ name: "max_rows", value: params.requestedMaxRows });
+    }
     if (params.requestedMaxItems !== undefined) {
-        const limit = Math.min(params.total, params.requestedMaxItems);
+        explicitLimits.push({ name: "max_items", value: params.requestedMaxItems });
+    }
+    if (explicitLimits.length > 0) {
+        const limit = Math.min(params.total, ...explicitLimits.map((item) => item.value));
         if (limit < params.total) {
             return {
                 limit,
-                reason: `limited by max_items=${params.requestedMaxItems}`
+                reason: `limited by ${explicitLimits
+                    .map((item) => `${item.name}=${item.value}`)
+                    .join(", ")} (effective=${limit})`
             };
         }
         return { limit, reason: null };
@@ -859,6 +896,41 @@ function resolveListItemLimit(params) {
     }
     return { limit: params.total, reason: null };
 }
+function projectRecordItemsColumns(params) {
+    if (!params.includeAnswers) {
+        return {
+            items: params.items,
+            reason: null,
+            selectedColumns: null
+        };
+    }
+    const normalizedSelectors = normalizeColumnSelectors(params.selectColumns);
+    const selectorSet = new Set(normalizedSelectors.map((item) => normalizeColumnSelector(item)));
+    let columnCapped = false;
+    const projectedItems = params.items.map((item) => {
+        const answers = asArray(item.answers);
+        let projected = answers;
+        if (selectorSet.size > 0) {
+            projected = answers.filter((answer) => answerMatchesAnySelector(answer, selectorSet));
+        }
+        if (params.maxColumns !== undefined && projected.length > params.maxColumns) {
+            projected = projected.slice(0, params.maxColumns);
+            columnCapped = true;
+        }
+        return {
+            ...item,
+            answers: projected
+        };
+    });
+    const reason = mergeTruncationReasons(selectorSet.size > 0 ? `selected columns=${normalizedSelectors.length}` : null, columnCapped && params.maxColumns !== undefined
+        ? `limited to max_columns=${params.maxColumns}`
+        : null);
+    return {
+        items: projectedItems,
+        reason,
+        selectedColumns: normalizedSelectors.length > 0 ? normalizedSelectors : null
+    };
+}
 function fitListItemsWithinSize(params) {
     let candidate = params.items;
     let size = jsonSizeBytes(candidate);
@@ -887,6 +959,44 @@ function buildRecordsListMessage(params) {
     }
     return `Fetched ${params.returned}/${params.total} records (${params.truncationReason})`;
 }
+function normalizeColumnSelectors(selectColumns) {
+    if (!selectColumns?.length) {
+        return [];
+    }
+    const deduped = new Set();
+    for (const value of selectColumns) {
+        const normalized = String(value).trim();
+        if (!normalized) {
+            continue;
+        }
+        deduped.add(normalized);
+    }
+    return Array.from(deduped);
+}
+function normalizeColumnSelector(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return `id:${Math.trunc(value)}`;
+    }
+    const normalized = String(value).trim();
+    if (!normalized) {
+        return "title:";
+    }
+    if (isNumericKey(normalized)) {
+        return `id:${Number(normalized)}`;
+    }
+    return `title:${normalized.toLowerCase()}`;
+}
+function answerMatchesAnySelector(answer, selectorSet) {
+    const obj = asObject(answer);
+    if (!obj) {
+        return false;
+    }
+    const candidates = [
+        normalizeColumnSelector(asNullableString(obj.queId) ?? ""),
+        normalizeColumnSelector(asNullableString(obj.queTitle) ?? "")
+    ];
+    return candidates.some((candidate) => selectorSet.has(candidate));
+}
 function normalizeQueId(queId) {
     if (typeof queId === "number" && Number.isInteger(queId)) {
         return queId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qingflow-mcp",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "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"