qingflow-mcp 0.2.4 → 0.2.6

package/README.md

@@ -6,6 +6,7 @@ This MCP server wraps Qingflow OpenAPI for:
 - `qf_form_get`
 - `qf_records_list`
 - `qf_record_get`
+- `qf_query` (unified read entry: list / record / summary)
 - `qf_record_create`
 - `qf_record_update`
 - `qf_operation_get`
@@ -52,6 +53,12 @@ npm run build
 npm start
 ```
 
+Run tests:
+
+```bash
+npm test
+```
+
 ## CLI Install
 
 Global install from GitHub:
@@ -103,8 +110,35 @@ 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.
 
+## Unified Query (`qf_query`)
+
+`qf_query` is the recommended read entry for agents.
+
+1. `query_mode=auto`:
+   - if `apply_id` is set, route to single-record query.
+   - if summary params are set (`amount_column` / `time_range` / `stat_policy` / `scan_max_pages`), route to summary query.
+   - otherwise route to list query.
+2. `query_mode=list|record|summary` forces explicit behavior.
+
+Summary mode output:
+
+1. `summary`: aggregated stats (`total_count`, `total_amount`, `by_day`, `missing_count`).
+2. `rows`: strict column rows (only requested `select_columns`).
+3. `meta`: field mapping, filter scope, stat policy, execution limits.
+
+Return shape:
+
+1. success: structured payload `{ "ok": true, "data": ..., "meta": ... }`
+2. failure: MCP `isError=true`, and text content is JSON payload like `{ "ok": false, "message": ..., ... }`
+
 ## List Query Tips
 
+Strict mode (`qf_records_list`):
+
+1. `select_columns` is required.
+2. `include_answers=false` is not allowed.
+3. Output `items[].answers` contains only selected columns, not full answers.
+
 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. Use `max_rows` (or `max_items`) to cap returned rows.

package/dist/server.js

@@ -36,7 +36,7 @@ const client = new QingflowClient({
 });
 const server = new McpServer({
     name: "qingflow-mcp",
-    version: "0.2.0"
+    version: "0.2.6"
 });
 const jsonPrimitiveSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
 const answerValueSchema = z.union([
@@ -120,7 +120,7 @@ const appsInputSchema = z.object({
     limit: z.number().int().positive().max(500).optional(),
     offset: z.number().int().nonnegative().optional()
 });
-const appsOutputSchema = z.object({
+const appsSuccessOutputSchema = z.object({
     ok: z.literal(true),
     data: z.object({
         total_apps: z.number().int().nonnegative(),
@@ -131,13 +131,14 @@ const appsOutputSchema = z.object({
     }),
     meta: apiMetaSchema
 });
+const appsOutputSchema = appsSuccessOutputSchema;
 const formInputSchema = z.object({
     app_key: z.string().min(1),
     user_id: z.string().min(1).optional(),
     force_refresh: z.boolean().optional(),
     include_raw: z.boolean().optional()
 });
-const formOutputSchema = z.object({
+const formSuccessOutputSchema = z.object({
     ok: z.literal(true),
     data: z.object({
         app_key: z.string(),
@@ -147,7 +148,9 @@ const formOutputSchema = z.object({
     }),
     meta: apiMetaSchema
 });
-const listInputSchema = z.object({
+const formOutputSchema = formSuccessOutputSchema;
+const listInputSchema = z
+    .object({
     app_key: z.string().min(1),
     user_id: z.string().min(1).optional(),
     page_num: z.number().int().positive().optional(),
@@ -193,14 +196,14 @@ const listInputSchema = z.object({
     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(),
+    // Strict mode: callers must explicitly choose columns.
+    select_columns: z.array(z.union([z.string().min(1), z.number().int()])).min(1).max(200),
     include_answers: z.boolean().optional()
+})
+    .refine((value) => value.include_answers !== false, {
+    message: "include_answers=false is not allowed in strict column mode"
 });
-const listOutputSchema = z.object({
+const listSuccessOutputSchema = z.object({
     ok: z.literal(true),
     data: z.object({
         app_key: z.string(),
@@ -216,12 +219,13 @@ const listOutputSchema = 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()
+            selected_columns: z.array(z.string())
         })
             .optional()
     }),
     meta: apiMetaSchema
 });
+const listOutputSchema = listSuccessOutputSchema;
 const recordGetInputSchema = z.object({
     apply_id: z.union([z.string().min(1), z.number().int()]),
     max_columns: z.number().int().positive().max(200).optional(),
@@ -231,7 +235,7 @@ const recordGetInputSchema = z.object({
         .max(200)
         .optional()
 });
-const recordGetOutputSchema = z.object({
+const recordGetSuccessOutputSchema = z.object({
     ok: z.literal(true),
     data: z.object({
         apply_id: z.union([z.string(), z.number(), z.null()]),
@@ -246,6 +250,7 @@ const recordGetOutputSchema = z.object({
     }),
     meta: apiMetaSchema
 });
+const recordGetOutputSchema = recordGetSuccessOutputSchema;
 const createInputSchema = z
     .object({
     app_key: z.string().min(1),
@@ -265,7 +270,7 @@ const createInputSchema = z
     .refine((value) => hasWritePayload(value.answers, value.fields), {
     message: "Either answers or fields is required"
 });
-const createOutputSchema = z.object({
+const createSuccessOutputSchema = z.object({
     ok: z.literal(true),
     data: z.object({
         request_id: z.string().nullable(),
@@ -274,6 +279,7 @@ const createOutputSchema = z.object({
     }),
     meta: apiMetaSchema
 });
+const createOutputSchema = createSuccessOutputSchema;
 const updateInputSchema = z
     .object({
     apply_id: z.union([z.string().min(1), z.number().int()]),
@@ -286,7 +292,7 @@ const updateInputSchema = z
     .refine((value) => hasWritePayload(value.answers, value.fields), {
     message: "Either answers or fields is required"
 });
-const updateOutputSchema = z.object({
+const updateSuccessOutputSchema = z.object({
     ok: z.literal(true),
     data: z.object({
         request_id: z.string().nullable(),
@@ -294,14 +300,144 @@ const updateOutputSchema = z.object({
     }),
     meta: apiMetaSchema
 });
+const updateOutputSchema = updateSuccessOutputSchema;
 const operationInputSchema = z.object({
     request_id: z.string().min(1)
 });
-const operationOutputSchema = z.object({
+const operationSuccessOutputSchema = z.object({
     ok: z.literal(true),
     data: operationResultSchema,
     meta: apiMetaSchema
 });
+const operationOutputSchema = operationSuccessOutputSchema;
+const queryInputSchema = z.object({
+    query_mode: z.enum(["auto", "list", "record", "summary"]).optional(),
+    app_key: z.string().min(1).optional(),
+    apply_id: z.union([z.string().min(1), z.number().int()]).optional(),
+    user_id: z.string().min(1).optional(),
+    page_num: z.number().int().positive().optional(),
+    page_size: z.number().int().positive().max(200).optional(),
+    mode: z
+        .enum([
+        "todo",
+        "done",
+        "mine_approved",
+        "mine_rejected",
+        "mine_draft",
+        "mine_need_improve",
+        "mine_processing",
+        "all",
+        "all_approved",
+        "all_rejected",
+        "all_processing",
+        "cc"
+    ])
+        .optional(),
+    type: z.number().int().min(1).max(12).optional(),
+    keyword: z.string().optional(),
+    query_logic: z.enum(["and", "or"]).optional(),
+    apply_ids: z.array(z.union([z.string(), z.number()])).optional(),
+    sort: z
+        .array(z.object({
+        que_id: z.union([z.string().min(1), z.number().int()]),
+        ascend: z.boolean().optional()
+    }))
+        .optional(),
+    filters: z
+        .array(z.object({
+        que_id: z.union([z.string().min(1), z.number().int()]).optional(),
+        search_key: z.string().optional(),
+        search_keys: z.array(z.string()).optional(),
+        min_value: z.string().optional(),
+        max_value: z.string().optional(),
+        scope: z.number().int().optional(),
+        search_options: z.array(z.union([z.string(), z.number()])).optional(),
+        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(),
+    amount_column: z.union([z.string().min(1), z.number().int()]).optional(),
+    time_range: z
+        .object({
+        column: z.union([z.string().min(1), z.number().int()]),
+        from: z.string().optional(),
+        to: z.string().optional(),
+        timezone: z.string().optional()
+    })
+        .optional(),
+    stat_policy: z
+        .object({
+        include_negative: z.boolean().optional(),
+        include_null: z.boolean().optional()
+    })
+        .optional(),
+    scan_max_pages: z.number().int().positive().max(500).optional()
+});
+const querySummaryOutputSchema = z.object({
+    summary: z.object({
+        total_count: z.number().int().nonnegative(),
+        total_amount: z.number().nullable(),
+        by_day: z.array(z.object({
+            day: z.string(),
+            count: z.number().int().nonnegative(),
+            amount_total: z.number().nullable()
+        })),
+        missing_count: z.number().int().nonnegative()
+    }),
+    rows: z.array(z.record(z.unknown())),
+    meta: z.object({
+        field_mapping: z.array(z.object({
+            role: z.enum(["row", "amount", "time"]),
+            requested: z.string(),
+            que_id: z.union([z.string(), z.number()]),
+            que_title: z.string().nullable(),
+            que_type: z.unknown()
+        })),
+        filters: z.object({
+            app_key: z.string(),
+            time_range: z
+                .object({
+                column: z.string(),
+                from: z.string().nullable(),
+                to: z.string().nullable(),
+                timezone: z.string()
+            })
+                .nullable()
+        }),
+        stat_policy: z.object({
+            include_negative: z.boolean(),
+            include_null: z.boolean()
+        }),
+        execution: z.object({
+            scanned_records: z.number().int().nonnegative(),
+            scanned_pages: z.number().int().nonnegative(),
+            truncated: z.boolean(),
+            row_cap: z.number().int().positive(),
+            column_cap: z.number().int().positive().nullable(),
+            scan_max_pages: z.number().int().positive()
+        })
+    })
+});
+const querySuccessOutputSchema = z.object({
+    ok: z.literal(true),
+    data: z.object({
+        mode: z.enum(["list", "record", "summary"]),
+        source_tool: z.enum(["qf_records_list", "qf_record_get", "qf_records_summary"]),
+        list: listSuccessOutputSchema.shape.data.optional(),
+        record: recordGetSuccessOutputSchema.shape.data.optional(),
+        summary: querySummaryOutputSchema.optional()
+    }),
+    meta: apiMetaSchema
+});
+const queryOutputSchema = querySuccessOutputSchema;
 server.registerTool("qf_apps_list", {
     title: "Qingflow Apps List",
     description: "List Qingflow apps with optional filtering and client-side slicing.",
@@ -389,68 +525,8 @@ 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 includeAnswers = Boolean(args.include_answers || (args.select_columns && args.select_columns.length > 0));
-        const payload = buildListPayload({
-            pageNum,
-            pageSize,
-            mode: args.mode,
-            type: args.type,
-            keyword: args.keyword,
-            queryLogic: args.query_logic,
-            applyIds: args.apply_ids,
-            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 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 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, columnProjection.reason, fitted.reason);
-        return okResult({
-            ok: true,
-            data: {
-                app_key: args.app_key,
-                pagination: {
-                    page_num: toPositiveInt(result?.pageNum) ?? pageNum,
-                    page_size: toPositiveInt(result?.pageSize) ?? pageSize,
-                    page_amount: toNonNegativeInt(result?.pageAmount),
-                    result_amount: toNonNegativeInt(result?.resultAmount) ?? fitted.items.length
-                },
-                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({
-            returned: fitted.items.length,
-            total: rawItems.length,
-            truncationReason
-        }));
+        const executed = await executeRecordsList(args);
+        return okResult(executed.payload, executed.message);
     }
     catch (error) {
         return errorResult(error);
@@ -467,31 +543,61 @@ server.registerTool("qf_record_get", {
     }
 }, async (args) => {
     try {
-        const response = await client.getRecord(String(args.apply_id));
-        const record = asObject(response.result) ?? {};
-        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;
+        const executed = await executeRecordGet(args);
+        return okResult(executed.payload, executed.message);
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+});
+server.registerTool("qf_query", {
+    title: "Qingflow Unified Query",
+    description: "Unified read entry for list/record/summary. Use query_mode=auto to route automatically.",
+    inputSchema: queryInputSchema,
+    outputSchema: queryOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true
+    }
+}, async (args) => {
+    try {
+        const routedMode = resolveQueryMode(args);
+        if (routedMode === "record") {
+            const recordArgs = buildRecordGetArgsFromQuery(args);
+            const executed = await executeRecordGet(recordArgs);
+            return okResult({
+                ok: true,
+                data: {
+                    mode: "record",
+                    source_tool: "qf_record_get",
+                    record: executed.payload.data
+                },
+                meta: executed.payload.meta
+            }, executed.message);
+        }
+        if (routedMode === "summary") {
+            const executed = await executeRecordsSummary(args);
+            return okResult({
+                ok: true,
+                data: {
+                    mode: "summary",
+                    source_tool: "qf_records_summary",
+                    summary: executed.data
+                },
+                meta: executed.meta
+            }, executed.message);
+        }
+        const listArgs = buildListArgsFromQuery(args);
+        const executed = await executeRecordsList(listArgs);
         return okResult({
             ok: true,
             data: {
-                apply_id: record.applyId ?? null,
-                answer_count: answerCount,
-                record: projectedRecord,
-                applied_limits: {
-                    column_cap: args.max_columns ?? null,
-                    selected_columns: projection.selectedColumns
-                }
+                mode: "list",
+                source_tool: "qf_records_list",
+                list: executed.payload.data
             },
-            meta: buildMeta(response)
-        }, `Fetched record ${String(args.apply_id)}`);
+            meta: executed.payload.meta
+        }, executed.message);
     }
     catch (error) {
         return errorResult(error);
@@ -618,6 +724,500 @@ function buildMeta(response) {
         base_url: baseUrl
     };
 }
+function resolveQueryMode(args) {
+    const requested = args.query_mode ?? "auto";
+    if (requested !== "auto") {
+        return requested;
+    }
+    if (args.apply_id !== undefined) {
+        return "record";
+    }
+    if (args.amount_column !== undefined ||
+        args.time_range !== undefined ||
+        args.stat_policy !== undefined ||
+        args.scan_max_pages !== undefined) {
+        return "summary";
+    }
+    return "list";
+}
+function buildListArgsFromQuery(args) {
+    if (!args.app_key) {
+        throw new Error("app_key is required for list query");
+    }
+    if (!args.select_columns?.length) {
+        throw new Error("select_columns is required for list query");
+    }
+    return listInputSchema.parse({
+        app_key: args.app_key,
+        user_id: args.user_id,
+        page_num: args.page_num,
+        page_size: args.page_size,
+        mode: args.mode,
+        type: args.type,
+        keyword: args.keyword,
+        query_logic: args.query_logic,
+        apply_ids: args.apply_ids,
+        sort: args.sort,
+        filters: args.filters,
+        max_rows: args.max_rows,
+        max_items: args.max_items,
+        max_columns: args.max_columns,
+        select_columns: args.select_columns,
+        include_answers: args.include_answers
+    });
+}
+function buildRecordGetArgsFromQuery(args) {
+    if (args.apply_id === undefined) {
+        throw new Error("apply_id is required for record query");
+    }
+    return recordGetInputSchema.parse({
+        apply_id: args.apply_id,
+        max_columns: args.max_columns,
+        select_columns: args.select_columns
+    });
+}
+async function executeRecordsList(args) {
+    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 = true;
+    const payload = buildListPayload({
+        pageNum,
+        pageSize,
+        mode: args.mode,
+        type: args.type,
+        keyword: args.keyword,
+        queryLogic: args.query_logic,
+        applyIds: args.apply_ids,
+        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 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 columnProjection = projectRecordItemsColumns({
+        items,
+        includeAnswers,
+        maxColumns: args.max_columns,
+        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.`);
+    }
+    const fitted = fitListItemsWithinSize({
+        items: columnProjection.items,
+        limitBytes: MAX_LIST_ITEMS_BYTES
+    });
+    const truncationReason = mergeTruncationReasons(listLimit.reason, columnProjection.reason, fitted.reason);
+    const responsePayload = {
+        ok: true,
+        data: {
+            app_key: args.app_key,
+            pagination: {
+                page_num: toPositiveInt(result?.pageNum) ?? pageNum,
+                page_size: toPositiveInt(result?.pageSize) ?? pageSize,
+                page_amount: toNonNegativeInt(result?.pageAmount),
+                result_amount: toNonNegativeInt(result?.resultAmount) ?? fitted.items.length
+            },
+            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)
+    };
+    return {
+        payload: responsePayload,
+        message: buildRecordsListMessage({
+            returned: fitted.items.length,
+            total: rawItems.length,
+            truncationReason
+        })
+    };
+}
+async function executeRecordGet(args) {
+    const response = await client.getRecord(String(args.apply_id));
+    const record = asObject(response.result) ?? {};
+    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 {
+        payload: {
+            ok: true,
+            data: {
+                apply_id: record.applyId ?? null,
+                answer_count: answerCount,
+                record: projectedRecord,
+                applied_limits: {
+                    column_cap: args.max_columns ?? null,
+                    selected_columns: projection.selectedColumns
+                }
+            },
+            meta: buildMeta(response)
+        },
+        message: `Fetched record ${String(args.apply_id)}`
+    };
+}
+async function executeRecordsSummary(args) {
+    if (!args.app_key) {
+        throw new Error("app_key is required for summary query");
+    }
+    if (!args.select_columns?.length) {
+        throw new Error("select_columns is required for summary query");
+    }
+    const includeNegative = args.stat_policy?.include_negative ?? true;
+    const includeNull = args.stat_policy?.include_null ?? false;
+    const scanMaxPages = args.scan_max_pages ?? 50;
+    const pageSize = args.page_size ?? DEFAULT_PAGE_SIZE;
+    const rowCap = Math.min(args.max_rows ?? DEFAULT_PAGE_SIZE, 200);
+    const timezone = args.time_range?.timezone ?? "Asia/Shanghai";
+    const form = await getFormCached(args.app_key, args.user_id, false);
+    const index = buildFieldIndex(form.result);
+    const selectedColumns = resolveSummaryColumns(args.select_columns, index, "select_columns");
+    const effectiveColumns = args.max_columns !== undefined ? selectedColumns.slice(0, args.max_columns) : selectedColumns;
+    if (effectiveColumns.length === 0) {
+        throw new Error("No output columns remain after max_columns cap");
+    }
+    const amountColumn = args.amount_column !== undefined
+        ? resolveSummaryColumn(args.amount_column, index, "amount_column")
+        : null;
+    const timeColumn = args.time_range ? resolveSummaryColumn(args.time_range.column, index, "time_range.column") : null;
+    const normalizedSort = await normalizeListSort(args.sort, args.app_key, args.user_id);
+    const summaryFilters = [...(args.filters ?? [])];
+    if (timeColumn && (args.time_range?.from || args.time_range?.to)) {
+        summaryFilters.push({
+            que_id: timeColumn.que_id,
+            ...(args.time_range.from ? { min_value: args.time_range.from } : {}),
+            ...(args.time_range.to ? { max_value: args.time_range.to } : {})
+        });
+    }
+    let currentPage = args.page_num ?? 1;
+    let scannedPages = 0;
+    let scannedRecords = 0;
+    let truncated = false;
+    let summaryMeta = null;
+    let totalAmount = 0;
+    let missingCount = 0;
+    const rows = [];
+    const byDay = new Map();
+    while (true) {
+        const payload = buildListPayload({
+            pageNum: currentPage,
+            pageSize,
+            mode: args.mode,
+            type: args.type,
+            keyword: args.keyword,
+            queryLogic: args.query_logic,
+            applyIds: args.apply_ids,
+            sort: normalizedSort,
+            filters: summaryFilters
+        });
+        const response = await client.listRecords(args.app_key, payload, { userId: args.user_id });
+        summaryMeta = summaryMeta ?? buildMeta(response);
+        scannedPages += 1;
+        const result = asObject(response.result);
+        const rawItems = asArray(result?.result);
+        const pageAmount = toPositiveInt(result?.pageAmount);
+        const hasMoreByAmount = pageAmount !== null ? currentPage < pageAmount : rawItems.length === pageSize;
+        for (const rawItem of rawItems) {
+            const record = asObject(rawItem) ?? {};
+            const answers = asArray(record.answers);
+            scannedRecords += 1;
+            if (rows.length < rowCap) {
+                rows.push(buildSummaryRow(answers, effectiveColumns));
+            }
+            let amountContribution = 0;
+            let hasAmountContribution = false;
+            if (amountColumn) {
+                const amountValue = extractSummaryColumnValue(answers, amountColumn);
+                const numericAmount = toFiniteAmount(amountValue);
+                if (numericAmount === null) {
+                    if (!includeNull) {
+                        missingCount += 1;
+                    }
+                    else {
+                        hasAmountContribution = true;
+                    }
+                }
+                else if (includeNegative || numericAmount >= 0) {
+                    amountContribution = numericAmount;
+                    hasAmountContribution = true;
+                }
+            }
+            if (hasAmountContribution) {
+                totalAmount += amountContribution;
+            }
+            const dayKey = timeColumn
+                ? toDayBucket(extractSummaryColumnValue(answers, timeColumn), timezone)
+                : "all";
+            const bucket = byDay.get(dayKey) ?? { count: 0, amount: 0 };
+            bucket.count += 1;
+            if (amountColumn && hasAmountContribution) {
+                bucket.amount += amountContribution;
+            }
+            byDay.set(dayKey, bucket);
+        }
+        if (!hasMoreByAmount) {
+            break;
+        }
+        if (scannedPages >= scanMaxPages) {
+            truncated = true;
+            break;
+        }
+        currentPage += 1;
+    }
+    const byDayStats = Array.from(byDay.entries())
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([day, bucket]) => ({
+        day,
+        count: bucket.count,
+        amount_total: amountColumn ? bucket.amount : null
+    }));
+    const fieldMapping = [
+        ...effectiveColumns.map((item) => ({
+            role: "row",
+            requested: item.requested,
+            que_id: item.que_id,
+            que_title: item.que_title,
+            que_type: item.que_type
+        })),
+        ...(amountColumn
+            ? [
+                {
+                    role: "amount",
+                    requested: amountColumn.requested,
+                    que_id: amountColumn.que_id,
+                    que_title: amountColumn.que_title,
+                    que_type: amountColumn.que_type
+                }
+            ]
+            : []),
+        ...(timeColumn
+            ? [
+                {
+                    role: "time",
+                    requested: timeColumn.requested,
+                    que_id: timeColumn.que_id,
+                    que_title: timeColumn.que_title,
+                    que_type: timeColumn.que_type
+                }
+            ]
+            : [])
+    ];
+    if (!summaryMeta) {
+        throw new Error("Failed to build summary metadata");
+    }
+    return {
+        data: {
+            summary: {
+                total_count: scannedRecords,
+                total_amount: amountColumn ? totalAmount : null,
+                by_day: byDayStats,
+                missing_count: missingCount
+            },
+            rows,
+            meta: {
+                field_mapping: fieldMapping,
+                filters: {
+                    app_key: args.app_key,
+                    time_range: timeColumn
+                        ? {
+                            column: timeColumn.requested,
+                            from: args.time_range?.from ?? null,
+                            to: args.time_range?.to ?? null,
+                            timezone
+                        }
+                        : null
+                },
+                stat_policy: {
+                    include_negative: includeNegative,
+                    include_null: includeNull
+                },
+                execution: {
+                    scanned_records: scannedRecords,
+                    scanned_pages: scannedPages,
+                    truncated,
+                    row_cap: rowCap,
+                    column_cap: args.max_columns ?? null,
+                    scan_max_pages: scanMaxPages
+                }
+            }
+        },
+        meta: summaryMeta,
+        message: `Summarized ${scannedRecords} records`
+    };
+}
+function resolveSummaryColumns(columns, index, label) {
+    return normalizeColumnSelectors(columns).map((requested) => resolveSummaryColumn(requested, index, label));
+}
+function resolveSummaryColumn(column, index, label) {
+    const requested = String(column).trim();
+    if (!requested) {
+        throw new Error(`${label} contains an empty column selector`);
+    }
+    if (isNumericKey(requested)) {
+        const hit = index.byId.get(String(Number(requested)));
+        if (!hit) {
+            throw new Error(`${label} references unknown que_id "${requested}"`);
+        }
+        return {
+            requested,
+            que_id: normalizeQueId(hit.queId),
+            que_title: asNullableString(hit.queTitle),
+            que_type: hit.queType
+        };
+    }
+    const hit = resolveFieldByKey(requested, index);
+    if (!hit || hit.queId === undefined || hit.queId === null) {
+        throw new Error(`${label} cannot resolve field "${requested}"`);
+    }
+    return {
+        requested,
+        que_id: normalizeQueId(hit.queId),
+        que_title: asNullableString(hit.queTitle),
+        que_type: hit.queType
+    };
+}
+function buildSummaryRow(answers, columns) {
+    const row = {};
+    for (const column of columns) {
+        row[column.requested] = extractSummaryColumnValue(answers, column);
+    }
+    return row;
+}
+function extractSummaryColumnValue(answers, column) {
+    const targetId = normalizeColumnSelector(String(column.que_id));
+    const targetTitle = column.que_title ? normalizeColumnSelector(column.que_title) : null;
+    for (const answerRaw of answers) {
+        const answer = asObject(answerRaw);
+        if (!answer) {
+            continue;
+        }
+        const answerQueId = asNullableString(answer.queId);
+        if (answerQueId && normalizeColumnSelector(answerQueId) === targetId) {
+            return extractAnswerDisplayValue(answer);
+        }
+        if (targetTitle) {
+            const answerQueTitle = asNullableString(answer.queTitle);
+            if (answerQueTitle && normalizeColumnSelector(answerQueTitle) === targetTitle) {
+                return extractAnswerDisplayValue(answer);
+            }
+        }
+    }
+    return null;
+}
+function extractAnswerDisplayValue(answer) {
+    const tableValues = answer.tableValues ?? answer.table_values;
+    if (tableValues !== undefined) {
+        return tableValues;
+    }
+    const values = asArray(answer.values);
+    if (values.length === 0) {
+        return null;
+    }
+    const normalized = values.map((item) => extractAnswerValueCell(item));
+    return normalized.length === 1 ? normalized[0] : normalized;
+}
+function extractAnswerValueCell(value) {
+    const obj = asObject(value);
+    if (!obj) {
+        return value;
+    }
+    if (obj.dataValue !== undefined) {
+        return obj.dataValue;
+    }
+    if (obj.value !== undefined) {
+        return obj.value;
+    }
+    if (obj.valueStr !== undefined) {
+        return obj.valueStr;
+    }
+    return obj;
+}
+function toFiniteAmount(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (Array.isArray(value)) {
+        if (value.length !== 1) {
+            return null;
+        }
+        return toFiniteAmount(value[0]);
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string") {
+        const normalized = value.replace(/,/g, "").trim();
+        if (!normalized) {
+            return null;
+        }
+        const parsed = Number(normalized);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+    return null;
+}
+function toDayBucket(value, timezone) {
+    const first = Array.isArray(value) ? value[0] : value;
+    if (first === null || first === undefined) {
+        return "unknown";
+    }
+    if (typeof first === "string") {
+        const trimmed = first.trim();
+        const direct = trimmed.match(/^(\d{4}-\d{2}-\d{2})/);
+        if (direct) {
+            return direct[1];
+        }
+        const parsed = new Date(trimmed);
+        if (!Number.isNaN(parsed.getTime())) {
+            return formatDateBucket(parsed, timezone);
+        }
+        return "unknown";
+    }
+    if (typeof first === "number") {
+        const parsed = new Date(first);
+        if (!Number.isNaN(parsed.getTime())) {
+            return formatDateBucket(parsed, timezone);
+        }
+    }
+    return "unknown";
+}
+function formatDateBucket(value, timezone) {
+    try {
+        return new Intl.DateTimeFormat("en-CA", {
+            timeZone: timezone,
+            year: "numeric",
+            month: "2-digit",
+            day: "2-digit"
+        }).format(value);
+    }
+    catch {
+        return value.toISOString().slice(0, 10);
+    }
+}
 function buildListPayload(params) {
     const payload = {
         pageNum: params.pageNum,
@@ -926,12 +1526,17 @@ function projectRecordItemsColumns(params) {
         return {
             items: params.items,
             reason: null,
-            selectedColumns: null
+            selectedColumns: [],
+            matchedAnswersCount: 0
         };
     }
     const normalizedSelectors = normalizeColumnSelectors(params.selectColumns);
+    if (normalizedSelectors.length === 0) {
+        throw new Error("select_columns must contain at least one non-empty column identifier");
+    }
     const selectorSet = new Set(normalizedSelectors.map((item) => normalizeColumnSelector(item)));
     let columnCapped = false;
+    let matchedAnswersCount = 0;
     const projectedItems = params.items.map((item) => {
         const answers = asArray(item.answers);
         let projected = answers;
@@ -942,6 +1547,7 @@ function projectRecordItemsColumns(params) {
             projected = projected.slice(0, params.maxColumns);
             columnCapped = true;
         }
+        matchedAnswersCount += projected.length;
         return {
             ...item,
             answers: projected
@@ -953,7 +1559,8 @@ function projectRecordItemsColumns(params) {
     return {
         items: projectedItems,
         reason,
-        selectedColumns: normalizedSelectors.length > 0 ? normalizedSelectors : null
+        selectedColumns: normalizedSelectors,
+        matchedAnswersCount
     };
 }
 function projectAnswersForOutput(params) {
@@ -1071,7 +1678,7 @@ function errorResult(error) {
     const payload = toErrorPayload(error);
     return {
         isError: true,
-        structuredContent: payload,
+        // Keep error payload in text to avoid outputSchema(success) validation conflicts across MCP clients.
         content: [
             {
                 type: "text",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qingflow-mcp",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "private": false,
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test \"test/*.test.js\"",
     "dev": "tsx src/server.ts",
     "start": "node dist/server.js",
     "prepublishOnly": "npm run build"