qingflow-mcp 0.3.19 → 0.3.21

package/README.md

@@ -117,7 +117,7 @@ npm i -g git+https://github.com/853046310/qingflow-mcp.git
 Install from npm (pinned version):
 
 ```bash
-npm i -g qingflow-mcp@0.3.19
+npm i -g qingflow-mcp@0.3.21
 ```
 
 Or one-click installer:

package/dist/server.js

@@ -46,6 +46,9 @@ class InputValidationError extends Error {
 }
 const FORM_CACHE_TTL_MS = Number(process.env.QINGFLOW_FORM_CACHE_TTL_MS ?? "300000");
 const formCache = new Map();
+const APPLY_APP_KEY_CACHE_TTL_MS = Number(process.env.QINGFLOW_APPLY_APP_KEY_CACHE_TTL_MS ?? "1800000");
+const applyAppKeyCache = new Map();
+const requestAppKeyCache = new Map();
 const CONTINUATION_CACHE_TTL_MS = Number(process.env.QINGFLOW_CONTINUATION_CACHE_TTL_MS ?? "900000");
 const continuationCache = new Map();
 const DEFAULT_PAGE_SIZE = 50;
@@ -65,7 +68,7 @@ const REQUEST_TIMEOUT_MS = toPositiveInt(process.env.QINGFLOW_REQUEST_TIMEOUT_MS
 const EXECUTION_BUDGET_MS = toPositiveInt(process.env.QINGFLOW_EXECUTION_BUDGET_MS) ?? 20000;
 const WAIT_RESULT_DEFAULT_TIMEOUT_MS = toPositiveInt(process.env.QINGFLOW_WAIT_RESULT_TIMEOUT_MS) ?? 5000;
 const WAIT_RESULT_POLL_INTERVAL_MS = toPositiveInt(process.env.QINGFLOW_WAIT_RESULT_POLL_INTERVAL_MS) ?? 500;
-const SERVER_VERSION = "0.3.19";
+const SERVER_VERSION = "0.3.21";
 const accessToken = process.env.QINGFLOW_ACCESS_TOKEN;
 const baseUrl = process.env.QINGFLOW_BASE_URL;
 if (!accessToken) {
@@ -745,12 +748,14 @@ const listOutputSchema = listSuccessOutputSchema;
 const recordGetInputPublicSchema = z
     .object({
     apply_id: publicFieldSelectorSchema,
+    app_key: publicStringSchema.optional(),
     max_columns: z.number().int().positive().max(MAX_COLUMN_LIMIT).optional(),
     select_columns: z.array(publicFieldSelectorSchema).min(1).max(MAX_COLUMN_LIMIT),
     output_profile: outputProfileSchema.optional()
 });
 const recordGetInputSchema = z.preprocess(normalizeRecordGetInput, z.object({
     apply_id: z.union([z.string().min(1), z.number().int()]),
+    app_key: z.string().min(1).optional(),
     max_columns: z.number().int().positive().max(MAX_COLUMN_LIMIT).optional(),
     select_columns: z
         .array(z.union([z.string().min(1), z.number().int()]))
@@ -2404,6 +2409,8 @@ server.registerTool("qf_record_create", {
         const result = asObject(response.result);
         const requestId = asNullableString(result?.requestId);
         const immediateApplyId = result?.applyId ?? null;
+        rememberRequestAppKey(requestId, parsedArgs.app_key);
+        rememberApplyAppKey(immediateApplyId, parsedArgs.app_key);
         const shouldWaitForResult = (parsedArgs.wait_result ?? false) && requestId !== null && immediateApplyId === null;
         let finalApplyId = immediateApplyId;
         let waitStatus = immediateApplyId !== null ? "completed" : "pending";
@@ -2416,6 +2423,7 @@ server.registerTool("qf_record_create", {
             waitStatus = waited.status;
             rawOperationResult = waited.operationResult;
             finalApplyId = waited.applyId;
+            rememberApplyAppKey(waited.applyId, parsedArgs.app_key);
         }
         const createResource = finalApplyId !== null ? { type: "record", apply_id: finalApplyId } : null;
         const createNextAction = waitStatus === "pending" || waitStatus === "timeout"
@@ -2476,6 +2484,8 @@ server.registerTool("qf_record_update", {
         const response = await client.updateRecord(String(parsedArgs.apply_id), { answers: normalizedAnswers }, { userId: parsedArgs.user_id });
         const result = asObject(response.result);
         const updateRequestId = asNullableString(result?.requestId);
+        rememberRequestAppKey(updateRequestId, parsedArgs.app_key ?? null);
+        rememberApplyAppKey(parsedArgs.apply_id, parsedArgs.app_key ?? null);
         const shouldWaitForUpdate = (parsedArgs.wait_result ?? false) && updateRequestId !== null;
         let updateStatus = "pending";
         let updateRawOperationResult = null;
@@ -2491,6 +2501,7 @@ server.registerTool("qf_record_update", {
             if (waited.applyId !== null) {
                 updateApplyId = waited.applyId;
             }
+            rememberApplyAppKey(waited.applyId, parsedArgs.app_key ?? null);
         }
         else if (updateRequestId === null) {
             // No async operation — synchronous completion
@@ -2536,6 +2547,8 @@ server.registerTool("qf_operation_get", {
 }, async (args) => {
     try {
         const response = await client.getOperation(args.request_id);
+        const cachedAppKey = getCachedRequestAppKey(args.request_id);
+        rememberApplyAppKey(extractOperationApplyId(response.result), cachedAppKey);
         return okResult({
             ok: true,
             data: {
@@ -2832,6 +2845,69 @@ function buildMeta(response) {
         base_url: baseUrl
     };
 }
+function rememberApplyAppKey(applyId, appKey) {
+    const normalizedApplyId = asNullableString(applyId)?.trim();
+    const normalizedAppKey = asNullableString(appKey)?.trim();
+    if (!normalizedApplyId || !normalizedAppKey) {
+        return;
+    }
+    applyAppKeyCache.set(normalizedApplyId, {
+        appKey: normalizedAppKey,
+        expiresAt: Date.now() + APPLY_APP_KEY_CACHE_TTL_MS
+    });
+}
+function rememberRequestAppKey(requestId, appKey) {
+    const normalizedRequestId = asNullableString(requestId)?.trim();
+    const normalizedAppKey = asNullableString(appKey)?.trim();
+    if (!normalizedRequestId || !normalizedAppKey) {
+        return;
+    }
+    requestAppKeyCache.set(normalizedRequestId, {
+        appKey: normalizedAppKey,
+        expiresAt: Date.now() + APPLY_APP_KEY_CACHE_TTL_MS
+    });
+}
+function getCachedApplyAppKey(applyId) {
+    const normalizedApplyId = asNullableString(applyId)?.trim();
+    if (!normalizedApplyId) {
+        return null;
+    }
+    const hit = applyAppKeyCache.get(normalizedApplyId);
+    if (!hit) {
+        return null;
+    }
+    if (hit.expiresAt <= Date.now()) {
+        applyAppKeyCache.delete(normalizedApplyId);
+        return null;
+    }
+    return hit.appKey;
+}
+function getCachedRequestAppKey(requestId) {
+    const normalizedRequestId = asNullableString(requestId)?.trim();
+    if (!normalizedRequestId) {
+        return null;
+    }
+    const hit = requestAppKeyCache.get(normalizedRequestId);
+    if (!hit) {
+        return null;
+    }
+    if (hit.expiresAt <= Date.now()) {
+        requestAppKeyCache.delete(normalizedRequestId);
+        return null;
+    }
+    return hit.appKey;
+}
+async function fetchRecordsByApplyIds(params) {
+    const response = await client.listRecords(params.appKey, buildListPayload({
+        pageNum: 1,
+        pageSize: Math.min(Math.max(params.applyIds.length, 1), 200),
+        applyIds: params.applyIds
+    }), { userId: params.userId });
+    const records = asArray(asObject(response.result)?.result)
+        .map((item) => asObject(item))
+        .filter((item) => Boolean(item));
+    return { response, records };
+}
 function normalizeStringArray(value) {
     return uniqueStringList(asArray(value)
         .map((item) => asNullableString(item)?.trim() ?? "")
@@ -3783,6 +3859,7 @@ function normalizeRecordGetInput(raw) {
     return {
         ...normalizedObj,
         apply_id: coerceNumberLike(normalizedObj.apply_id),
+        app_key: coerceStringLike(normalizedObj.app_key),
         max_columns: coerceNumberLike(normalizedObj.max_columns),
         select_columns: normalizeSelectorListInput(selectColumns),
         output_profile: normalizeOutputProfileInput(normalizedObj.output_profile)
@@ -3903,6 +3980,7 @@ function normalizeBatchGetInput(raw) {
     const selectColumns = normalizedObj.select_columns ?? normalizedObj.keep_columns;
     return {
         ...normalizedObj,
+        app_key: coerceStringLike(normalizedObj.app_key),
         apply_ids: normalizeIdArrayInput(normalizedObj.apply_ids),
         max_columns: coerceNumberLike(normalizedObj.max_columns),
         select_columns: normalizeSelectorListInput(selectColumns),
@@ -5503,6 +5581,7 @@ function buildRecordGetArgsFromQuery(args) {
     }
     return recordGetInputSchema.parse({
         apply_id: args.apply_id,
+        app_key: args.app_key,
         max_columns: args.max_columns,
         select_columns: args.select_columns,
         output_profile: args.output_profile
@@ -5588,6 +5667,13 @@ async function executeQueryPlan(args) {
     };
 }
 async function executeRecordsBatchGet(args) {
+    if (!args.app_key) {
+        throw missingRequiredFieldError({
+            field: "app_key",
+            tool: "qf_records_batch_get",
+            fixHint: "Provide app_key, for example: {\"app_key\":\"21b3d559\",\"apply_ids\":[\"...\"],\"select_columns\":[0]}."
+        });
+    }
     if (!args.select_columns?.length) {
         throw missingRequiredFieldError({
             field: "select_columns",
@@ -5605,25 +5691,24 @@ async function executeRecordsBatchGet(args) {
     const rows = [];
     const missingApplyIds = [];
     let metaResponse = null;
+    const { response, records } = await fetchRecordsByApplyIds({
+        appKey: args.app_key,
+        applyIds: requestedApplyIds
+    });
+    metaResponse = buildMeta(response);
+    const byApplyId = new Map(records.map((record) => [String(record.applyId ?? ""), record]));
     for (const applyId of requestedApplyIds) {
-        try {
-            const response = await client.getRecord(applyId);
-            metaResponse = metaResponse ?? buildMeta(response);
-            const record = asObject(response.result) ?? {};
-            rows.push(buildFlatRowFromAnswers({
-                applyId: record.applyId ?? applyId,
-                answers: asArray(record.answers),
-                selectedColumns: selectedColumnsForRow
-            }));
-        }
-        catch (error) {
-            if (error instanceof QingflowApiError &&
-                (error.httpStatus === 404 || error.errCode === 404)) {
-                missingApplyIds.push(applyId);
-                continue;
-            }
-            throw error;
+        const record = byApplyId.get(String(applyId));
+        if (!record) {
+            missingApplyIds.push(applyId);
+            continue;
         }
+        rememberApplyAppKey(record.applyId ?? applyId, args.app_key);
+        rows.push(buildFlatRowFromAnswers({
+            applyId: record.applyId ?? applyId,
+            answers: asArray(record.answers),
+            selectedColumns: selectedColumnsForRow
+        }));
     }
     const completeness = {
         result_amount: requestedApplyIds.length,
@@ -6042,6 +6127,9 @@ async function executeRecordsList(args) {
     const items = collectedRawItems
         .slice(0, listLimit.limit)
         .map((raw) => normalizeRecordItem(raw, includeAnswers));
+    for (const item of items) {
+        rememberApplyAppKey(item.apply_id, args.app_key);
+    }
     const sourceItemsForRows = items.slice();
     const requestedSelectColumns = selectResolution.columns.map((item) => item.requested);
     const columnProjection = projectRecordItemsColumns({
@@ -6186,10 +6274,52 @@ async function executeRecordGet(args) {
     }
     const outputProfile = resolveOutputProfile(args.output_profile);
     const queryId = randomUUID();
-    const response = await client.getRecord(String(args.apply_id));
-    const record = asObject(response.result) ?? {};
+    let response;
+    let record = null;
+    try {
+        response = await client.getRecord(String(args.apply_id));
+        record = asObject(response.result) ?? {};
+    }
+    catch (error) {
+        const providerError = error instanceof QingflowApiError ? error : null;
+        const shouldFallback = providerError && (providerError.httpStatus === 404 || providerError.errCode === 404 || providerError.errCode === 49304);
+        if (!shouldFallback) {
+            throw error;
+        }
+        const fallbackAppKey = args.app_key ?? getCachedApplyAppKey(args.apply_id);
+        if (!fallbackAppKey) {
+            throw new InputValidationError({
+                message: `qf_record_get could not read apply_id \"${String(args.apply_id)}\" through the direct record endpoint`,
+                errorCode: "APP_KEY_REQUIRED_FOR_RECORD_GET",
+                fixHint: "Retry qf_record_get with app_key, or call qf_records_batch_get/qf_records_list/qf_record_update first so MCP can infer the app_key for this apply_id.",
+                details: {
+                    apply_id: String(args.apply_id),
+                    provider_err_code: providerError?.errCode ?? null,
+                    provider_err_msg: providerError?.errMsg ?? null
+                }
+            });
+        }
+        const fallback = await fetchRecordsByApplyIds({
+            appKey: fallbackAppKey,
+            applyIds: [String(args.apply_id)]
+        });
+        response = fallback.response;
+        record = fallback.records.find((item) => String(item.applyId ?? "") === String(args.apply_id)) ?? null;
+        if (!record) {
+            throw new InputValidationError({
+                message: `Record \"${String(args.apply_id)}\" not found in app \"${fallbackAppKey}\"`,
+                errorCode: "RECORD_NOT_FOUND",
+                fixHint: "Confirm apply_id and app_key, or fetch the row via qf_records_list/qf_query first.",
+                details: {
+                    apply_id: String(args.apply_id),
+                    app_key: fallbackAppKey
+                }
+            });
+        }
+        rememberApplyAppKey(record.applyId ?? args.apply_id, fallbackAppKey);
+    }
     const projection = projectAnswersForOutput({
-        answers: asArray(record.answers),
+        answers: asArray(record?.answers),
         maxColumns: args.max_columns,
         selectColumns: args.select_columns
     });
@@ -6197,8 +6327,8 @@ async function executeRecordGet(args) {
         ? (projection.selectedColumns ?? []).slice(0, args.max_columns)
         : projection.selectedColumns ?? [];
     const row = buildFlatRowFromAnswers({
-        applyId: record.applyId ?? null,
-        answers: asArray(record.answers),
+        applyId: record?.applyId ?? null,
+        answers: asArray(record?.answers),
         selectedColumns: selectedColumnsForRow
     });
     const completeness = {
@@ -6219,11 +6349,12 @@ async function executeRecordGet(args) {
         apply_id: String(args.apply_id),
         selected_columns: selectedColumnsForRow
     };
+    rememberApplyAppKey(record?.applyId ?? args.apply_id, args.app_key ?? getCachedApplyAppKey(args.apply_id));
     return {
         payload: {
             ok: true,
             data: {
-                apply_id: record.applyId ?? null,
+                apply_id: record?.applyId ?? null,
                 row,
                 applied_limits: {
                     column_cap: args.max_columns ?? null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qingflow-mcp",
-  "version": "0.3.19",
+  "version": "0.3.21",
   "private": false,
   "license": "MIT",
   "type": "module",