qingflow-mcp 0.3.16 → 0.3.17

package/dist/server.js

@@ -65,7 +65,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.16";
+const SERVER_VERSION = "0.3.17";
 const accessToken = process.env.QINGFLOW_ACCESS_TOKEN;
 const baseUrl = process.env.QINGFLOW_BASE_URL;
 if (!accessToken) {
@@ -517,12 +517,23 @@ const createInputSchema = z
 const createSuccessOutputSchema = z.object({
     ok: z.literal(true),
     data: z.object({
+        status: z.enum(["completed", "pending", "timeout", "failed"]),
         request_id: z.string().nullable(),
         apply_id: z.union([z.string(), z.number(), z.null()]),
-        resolved: z.boolean().optional(),
-        timed_out: z.boolean().optional(),
-        operation_result: z.unknown().optional(),
-        async_hint: z.string()
+        resource: z
+            .object({
+            type: z.literal("record"),
+            apply_id: z.union([z.string(), z.number()])
+        })
+            .nullable(),
+        next_action: z
+            .object({
+            tool: z.string(),
+            arguments: z.record(z.unknown()),
+            reason: z.string().optional()
+        })
+            .nullable(),
+        raw: z.object({ operation_result: z.unknown() }).nullable()
     }),
     meta: apiMetaSchema
 });
@@ -555,12 +566,23 @@ const updateInputSchema = z
 const updateSuccessOutputSchema = z.object({
     ok: z.literal(true),
     data: z.object({
+        status: z.enum(["completed", "pending", "timeout", "failed"]),
         request_id: z.string().nullable(),
-        apply_id: z.union([z.string(), z.number(), z.null()]).optional(),
-        resolved: z.boolean().optional(),
-        timed_out: z.boolean().optional(),
-        operation_result: z.unknown().optional(),
-        async_hint: z.string()
+        apply_id: z.union([z.string(), z.number(), z.null()]),
+        resource: z
+            .object({
+            type: z.literal("record"),
+            apply_id: z.union([z.string(), z.number()])
+        })
+            .nullable(),
+        next_action: z
+            .object({
+            tool: z.string(),
+            arguments: z.record(z.unknown()),
+            reason: z.string().optional()
+        })
+            .nullable(),
+        raw: z.object({ operation_result: z.unknown() }).nullable()
     }),
     meta: apiMetaSchema
 });
@@ -1578,30 +1600,36 @@ server.registerTool("qf_record_create", {
         const immediateApplyId = result?.applyId ?? null;
         const shouldWaitForResult = (parsedArgs.wait_result ?? false) && requestId !== null && immediateApplyId === null;
         let finalApplyId = immediateApplyId;
-        let isResolved = immediateApplyId !== null;
-        let isTimedOut = false;
-        let operationResult = null;
+        let waitStatus = immediateApplyId !== null ? "completed" : "pending";
+        let rawOperationResult = null;
         if (shouldWaitForResult) {
             const waited = await waitForOperationResolution({
                 requestId: requestId,
                 timeoutMs: parsedArgs.wait_timeout_ms ?? WAIT_RESULT_DEFAULT_TIMEOUT_MS
             });
-            isResolved = waited.resolved;
-            isTimedOut = waited.timedOut;
-            operationResult = waited.operationResult;
+            waitStatus = waited.status;
+            rawOperationResult = waited.operationResult;
             finalApplyId = waited.applyId;
         }
+        const createResource = finalApplyId !== null ? { type: "record", apply_id: finalApplyId } : null;
+        const createNextAction = waitStatus === "pending" || waitStatus === "timeout"
+            ? {
+                tool: "qf_operation_get",
+                arguments: { request_id: requestId },
+                reason: waitStatus === "timeout"
+                    ? "Operation timed out; poll again to check completion."
+                    : "Operation is async; poll to check completion."
+            }
+            : null;
         return okResult({
             ok: true,
             data: {
+                status: waitStatus,
                 request_id: requestId,
                 apply_id: finalApplyId,
-                resolved: isResolved,
-                ...(isTimedOut ? { timed_out: true } : {}),
-                ...(operationResult !== null ? { operation_result: operationResult } : {}),
-                async_hint: isResolved
-                    ? "Record created and resolved."
-                    : "Use qf_operation_get with request_id to fetch the result."
+                resource: createResource,
+                next_action: createNextAction,
+                raw: rawOperationResult !== null ? { operation_result: rawOperationResult } : null
             },
             meta: buildMeta(response)
         }, `Create request sent for app ${parsedArgs.app_key}`);
@@ -1624,7 +1652,11 @@ server.registerTool("qf_record_update", {
         const parsedArgs = updateInputSchema.parse(args);
         const requiresForm = needsFormResolution(parsedArgs.fields);
         if (requiresForm && !parsedArgs.app_key) {
-            throw new Error("app_key is required when fields uses title-based keys");
+            throw missingRequiredFieldError({
+                field: "app_key",
+                tool: "qf_record_update",
+                fixHint: "Provide app_key when fields uses title-based keys, or switch fields to numeric que_id."
+            });
         }
         const form = requiresForm && parsedArgs.app_key
             ? await getFormCached(parsedArgs.app_key, parsedArgs.user_id, Boolean(parsedArgs.force_refresh_form))
@@ -1639,31 +1671,45 @@ server.registerTool("qf_record_update", {
         const result = asObject(response.result);
         const updateRequestId = asNullableString(result?.requestId);
         const shouldWaitForUpdate = (parsedArgs.wait_result ?? false) && updateRequestId !== null;
-        let updateIsResolved = false;
-        let updateIsTimedOut = false;
-        let updateOperationResult = null;
-        let updateApplyId = null;
+        let updateStatus = "pending";
+        let updateRawOperationResult = null;
+        let updateApplyId = parsedArgs.apply_id;
         if (shouldWaitForUpdate) {
             const waited = await waitForOperationResolution({
                 requestId: updateRequestId,
                 timeoutMs: parsedArgs.wait_timeout_ms ?? WAIT_RESULT_DEFAULT_TIMEOUT_MS
             });
-            updateIsResolved = waited.resolved;
-            updateIsTimedOut = waited.timedOut;
-            updateOperationResult = waited.operationResult;
-            updateApplyId = waited.applyId;
+            updateStatus = waited.status;
+            updateRawOperationResult = waited.operationResult;
+            // For updates, the apply_id is already known from input; keep it unless operation returned a different one
+            if (waited.applyId !== null) {
+                updateApplyId = waited.applyId;
+            }
+        }
+        else if (updateRequestId === null) {
+            // No async operation — synchronous completion
+            updateStatus = "completed";
         }
+        // else: wait_result=false but has requestId — submitted, not polled, stays "pending"
+        const updateResource = updateApplyId !== null ? { type: "record", apply_id: updateApplyId } : null;
+        const updateNextAction = updateStatus === "pending" || updateStatus === "timeout"
+            ? {
+                tool: "qf_operation_get",
+                arguments: { request_id: updateRequestId },
+                reason: updateStatus === "timeout"
+                    ? "Operation timed out; poll again to check completion."
+                    : "Operation is async; poll to check completion."
+            }
+            : null;
         return okResult({
             ok: true,
             data: {
+                status: updateStatus,
                 request_id: updateRequestId,
-                ...(updateApplyId !== null ? { apply_id: updateApplyId } : {}),
-                resolved: updateIsResolved,
-                ...(updateIsTimedOut ? { timed_out: true } : {}),
-                ...(updateOperationResult !== null ? { operation_result: updateOperationResult } : {}),
-                async_hint: updateIsResolved
-                    ? "Record updated and resolved."
-                    : "Use qf_operation_get with request_id to fetch the update result."
+                apply_id: updateApplyId,
+                resource: updateResource,
+                next_action: updateNextAction,
+                raw: updateRawOperationResult !== null ? { operation_result: updateRawOperationResult } : null
             },
             meta: buildMeta(response)
         }, `Update request sent for apply ${String(parsedArgs.apply_id)}`);
@@ -3362,7 +3408,7 @@ function inferPlanMissingRequired(tool, args) {
                 missing.push("select_columns");
             }
         }
-        else {
+        else if (queryMode === "list") {
             if (!hasAppKey) {
                 missing.push("app_key");
             }
@@ -3370,6 +3416,9 @@ function inferPlanMissingRequired(tool, args) {
                 missing.push("select_columns");
             }
         }
+        else if (!hasAppKey) {
+            missing.push("app_key");
+        }
     }
     return missing;
 }
@@ -4516,12 +4565,12 @@ async function executeRecordsExport(format, args) {
         app_key: args.app_key,
         selected_columns: selectedColumnsForRows,
         filters: echoFilters(effectiveFilters),
-        time_range: args.time_range
+        time_range: timeRangeResolution.mapping
             ? {
-                column: String(args.time_range.column),
-                from: args.time_range.from ?? null,
-                to: args.time_range.to ?? null,
-                timezone: args.time_range.timezone ?? null
+                column: String(args.time_range?.column ?? timeRangeResolution.mapping.requested ?? ""),
+                from: timeRangeResolution.time_range?.from ?? null,
+                to: timeRangeResolution.time_range?.to ?? null,
+                timezone: timeRangeResolution.time_range?.timezone ?? null
             }
             : null
     }, sourcePages);
@@ -4547,7 +4596,6 @@ async function executeRecordsExport(format, args) {
                 ? {
                     completeness,
                     evidence,
-                    resolved_mappings: resolvedMappings,
                     execution: {
                         scanned_pages: fetchedPages,
                         requested_pages: requestedPages,
@@ -4562,6 +4610,7 @@ async function executeRecordsExport(format, args) {
             ? {
                 completeness,
                 evidence,
+                resolved_mappings: resolvedMappings,
                 error_code: null,
                 fix_hint: null
             }
@@ -6441,6 +6490,13 @@ function isPendingOperationStatus(status) {
     return ["PENDING", "PROCESSING", "RUNNING", "IN_PROGRESS", "QUEUED"].includes(status);
 }
 function extractOperationApplyId(operationResult) {
+    // Handle case where operationResult itself is a numeric string or number (the apply_id directly)
+    if (typeof operationResult === "string" && /^\d+$/.test(operationResult.trim())) {
+        return operationResult.trim();
+    }
+    if (typeof operationResult === "number" && Number.isFinite(operationResult)) {
+        return operationResult;
+    }
     const obj = asObject(operationResult);
     return obj?.applyId ?? obj?.apply_id ?? null;
 }
@@ -6450,15 +6506,14 @@ async function waitForOperationResolution(params) {
     while (Date.now() <= deadline) {
         const response = await client.getOperation(params.requestId);
         lastResult = response.result;
-        const status = extractOperationStatus(lastResult);
+        const opStatus = extractOperationStatus(lastResult);
         const applyId = extractOperationApplyId(lastResult);
-        if ((status && !isPendingOperationStatus(status)) || applyId !== null) {
-            return {
-                resolved: true,
-                timedOut: false,
-                operationResult: lastResult,
-                applyId
-            };
+        if (applyId !== null) {
+            return { status: "completed", operationResult: lastResult, applyId };
+        }
+        if (opStatus && !isPendingOperationStatus(opStatus)) {
+            // Non-pending status but no apply_id — treat as failed
+            return { status: "failed", operationResult: lastResult, applyId: null };
         }
         const remaining = deadline - Date.now();
         if (remaining <= 0) {
@@ -6466,12 +6521,12 @@ async function waitForOperationResolution(params) {
         }
         await delay(Math.min(WAIT_RESULT_POLL_INTERVAL_MS, remaining));
     }
-    return {
-        resolved: false,
-        timedOut: true,
-        operationResult: lastResult,
-        applyId: extractOperationApplyId(lastResult)
-    };
+    // Timed out — check if last result has apply_id anyway (edge case)
+    const finalApplyId = extractOperationApplyId(lastResult);
+    if (finalApplyId !== null) {
+        return { status: "completed", operationResult: lastResult, applyId: finalApplyId };
+    }
+    return { status: "timeout", operationResult: lastResult, applyId: null };
 }
 function resolveListItemLimit(params) {
     if (params.total <= 0) {

package/package.json

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