qingflow-mcp 0.2.2 → 0.2.4

package/README.md

@@ -107,8 +107,34 @@ 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"]
+}
+```
+
+For single record details (`qf_record_get`), the same column controls are supported:
+
+```json
+{
+  "apply_id": "497600278750478338",
+  "max_columns": 5,
+  "select_columns": [1, "客户名称"]
+}
+```
 
 Optional env vars:
 

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,19 +210,39 @@ 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
 });
 const recordGetInputSchema = z.object({
-    apply_id: z.union([z.string().min(1), z.number().int()])
+    apply_id: z.union([z.string().min(1), z.number().int()]),
+    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()
 });
 const recordGetOutputSchema = z.object({
     ok: z.literal(true),
     data: z.object({
         apply_id: z.union([z.string(), z.number(), z.null()]),
         answer_count: z.number().int().nonnegative(),
-        record: z.unknown()
+        record: z.unknown(),
+        applied_limits: z
+            .object({
+            column_cap: z.number().int().positive().nullable(),
+            selected_columns: z.array(z.string()).nullable()
+        })
+            .optional()
     }),
     meta: apiMetaSchema
 });
@@ -365,6 +392,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 +407,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 +437,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({
@@ -429,13 +469,26 @@ server.registerTool("qf_record_get", {
     try {
         const response = await client.getRecord(String(args.apply_id));
         const record = asObject(response.result) ?? {};
-        const answerCount = asArray(record.answers).length;
+        const projection = projectAnswersForOutput({
+            answers: asArray(record.answers),
+            maxColumns: args.max_columns,
+            selectColumns: args.select_columns
+        });
+        const projectedRecord = {
+            ...record,
+            answers: projection.answers
+        };
+        const answerCount = projection.answers.length;
         return okResult({
             ok: true,
             data: {
                 apply_id: record.applyId ?? null,
                 answer_count: answerCount,
-                record: response.result
+                record: projectedRecord,
+                applied_limits: {
+                    column_cap: args.max_columns ?? null,
+                    selected_columns: projection.selectedColumns
+                }
             },
             meta: buildMeta(response)
         }, `Fetched record ${String(args.apply_id)}`);
@@ -841,12 +894,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 +921,56 @@ 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 projectAnswersForOutput(params) {
+    const normalizedSelectors = normalizeColumnSelectors(params.selectColumns);
+    const selectorSet = new Set(normalizedSelectors.map((item) => normalizeColumnSelector(item)));
+    let projected = params.answers;
+    if (selectorSet.size > 0) {
+        projected = projected.filter((answer) => answerMatchesAnySelector(answer, selectorSet));
+    }
+    if (params.maxColumns !== undefined && projected.length > params.maxColumns) {
+        projected = projected.slice(0, params.maxColumns);
+    }
+    return {
+        answers: projected,
+        selectedColumns: normalizedSelectors.length > 0 ? normalizedSelectors : null
+    };
+}
 function fitListItemsWithinSize(params) {
     let candidate = params.items;
     let size = jsonSizeBytes(candidate);
@@ -887,6 +999,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.2",
+  "version": "0.2.4",
   "private": false,
   "license": "MIT",
   "type": "module",