qingflow-mcp 0.4.0 → 0.4.2

package/README.md

@@ -5,6 +5,7 @@ This MCP server wraps Qingflow OpenAPI for:
 - `qf_apps_list`
 - `qf_form_get`
 - `qf_field_resolve`
+- `qf_value_probe`
 - `qf_query_plan`
 - `qf_records_list`
 - `qf_record_get`
@@ -108,7 +109,7 @@ npm i -g git+https://github.com/853046310/qingflow-mcp.git
 Install from npm (pinned version):
 
 ```bash
-npm i -g qingflow-mcp@0.4.0
+npm i -g qingflow-mcp@0.4.2
 ```
 
 Or one-click installer:
@@ -145,8 +146,10 @@ MCP client config example:
 
 1. `qf_apps_list` to pick app.
 2. `qf_form_get` to inspect field ids/titles.
-3. `qf_record_create` or `qf_record_update`.
-4. If create/update returns only `request_id`, call `qf_operation_get` to resolve async result.
+3. `qf_field_resolve` for field-name to `que_id` mapping.
+4. `qf_value_probe` when the agent needs candidate field values and explicit match evidence.
+5. `qf_record_create` or `qf_record_update`.
+6. If create/update returns only `request_id`, call `qf_operation_get` to resolve async result.
 
 Full calling contract (Chinese):
 
@@ -214,7 +217,7 @@ Deterministic read protocol (list/summary/aggregate):
    - objects must be native JSON objects
    - booleans must be native JSON booleans
    - unknown fields are rejected by the MCP boundary
-7. Use `qf_query_plan` as the only preflight tool when the agent is unsure about arguments. It can normalize loose/model-shaped inputs before a real query is issued.
+7. Use `qf_query_plan` as the only preflight tool when the agent is unsure about arguments. It can normalize loose/model-shaped inputs before a real query is issued, but runtime aliases like `from`/`to`/`dateFrom`/`dateTo`/`searchKey`/`searchKeys` are rejected.
 
 For `qf_query(summary)` and `qf_records_aggregate`, read `data.summary.completeness` / `data.completeness` before concluding:
 

package/dist/qingflow-client.js

@@ -1,3 +1,5 @@
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
 export class QingflowApiError extends Error {
     errCode;
     errMsg;
@@ -94,25 +96,25 @@ export class QingflowClient {
         if (options.userId) {
             headers.userId = options.userId;
         }
-        const init = {
-            method: params.method,
-            headers
-        };
+        let requestBody;
         if (options.body !== undefined) {
             headers["content-type"] = "application/json";
-            init.body = JSON.stringify(options.body);
+            requestBody = JSON.stringify(options.body);
+            headers["content-length"] = String(Buffer.byteLength(requestBody));
         }
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
-        init.signal = controller.signal;
         try {
-            const response = await getFetch()(url, init);
-            const text = await response.text();
+            const response = await sendHttpRequest(url, {
+                method: params.method,
+                headers,
+                body: requestBody,
+                timeoutMs: this.timeoutMs
+            });
+            const text = response.text;
             const data = safeJsonParse(text);
-            if (!response.ok) {
+            if (response.statusCode < 200 || response.statusCode >= 300) {
                 throw new QingflowApiError({
-                    message: `Qingflow HTTP ${response.status}`,
-                    httpStatus: response.status,
+                    message: `Qingflow HTTP ${response.statusCode}`,
+                    httpStatus: response.statusCode,
                     errMsg: extractErrMsg(data, text),
                     details: data ?? text
                 });
@@ -120,7 +122,7 @@ export class QingflowClient {
             if (!data || typeof data !== "object") {
                 throw new QingflowApiError({
                     message: "Qingflow response is not JSON object",
-                    httpStatus: response.status,
+                    httpStatus: response.statusCode,
                     details: text
                 });
             }
@@ -128,7 +130,7 @@ export class QingflowClient {
             if (parsed.errCode === null) {
                 throw new QingflowApiError({
                     message: "Qingflow response missing code field",
-                    httpStatus: response.status,
+                    httpStatus: response.statusCode,
                     details: data
                 });
             }
@@ -137,7 +139,7 @@ export class QingflowClient {
                     message: `Qingflow API error ${parsed.errCode}: ${parsed.errMsg}`,
                     errCode: parsed.errCode,
                     errMsg: parsed.errMsg,
-                    httpStatus: response.status,
+                    httpStatus: response.statusCode,
                     details: data
                 });
             }
@@ -151,9 +153,9 @@ export class QingflowClient {
             if (error instanceof QingflowApiError) {
                 throw error;
             }
-            if (error instanceof Error && error.name === "AbortError") {
+            if (error instanceof Error && error.message.startsWith("Qingflow request timeout after")) {
                 throw new QingflowApiError({
-                    message: `Qingflow request timeout after ${this.timeoutMs}ms`
+                    message: error.message
                 });
             }
             throw new QingflowApiError({
@@ -161,9 +163,6 @@ export class QingflowClient {
                 details: error
             });
         }
-        finally {
-            clearTimeout(timer);
-        }
     }
 }
 function normalizeBaseUrl(url) {
@@ -254,12 +253,31 @@ 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."
+async function sendHttpRequest(url, params) {
+    const requestImpl = url.protocol === "https:" ? httpsRequest : httpRequest;
+    return await new Promise((resolve, reject) => {
+        const req = requestImpl(url, {
+            method: params.method,
+            headers: params.headers
+        }, (res) => {
+            const chunks = [];
+            res.on("data", (chunk) => {
+                chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            });
+            res.on("end", () => {
+                resolve({
+                    statusCode: res.statusCode ?? 0,
+                    text: Buffer.concat(chunks).toString("utf8")
+                });
+            });
+        });
+        req.setTimeout(params.timeoutMs, () => {
+            req.destroy(new Error(`Qingflow request timeout after ${params.timeoutMs}ms`));
+        });
+        req.on("error", reject);
+        if (params.body !== undefined) {
+            req.write(params.body);
+        }
+        req.end();
     });
 }

package/dist/server.js

@@ -66,7 +66,7 @@ const ADAPTIVE_TARGET_PAGE_MS = toPositiveInt(process.env.QINGFLOW_ADAPTIVE_TARG
 const MAX_LIST_ITEMS_BYTES = toPositiveInt(process.env.QINGFLOW_LIST_MAX_ITEMS_BYTES) ?? 400000;
 const REQUEST_TIMEOUT_MS = toPositiveInt(process.env.QINGFLOW_REQUEST_TIMEOUT_MS) ?? 18000;
 const EXECUTION_BUDGET_MS = toPositiveInt(process.env.QINGFLOW_EXECUTION_BUDGET_MS) ?? 20000;
-const SERVER_VERSION = "0.4.0";
+const SERVER_VERSION = "0.4.2";
 const accessToken = process.env.QINGFLOW_ACCESS_TOKEN;
 const baseUrl = process.env.QINGFLOW_BASE_URL;
 if (!accessToken) {
@@ -137,6 +137,8 @@ const apiMetaSchema = z.object({
     base_url: z.string()
 });
 const outputProfileSchema = z.enum(["compact", "verbose"]);
+const matchModeValues = ["exact", "normalized", "contains", "prefix", "fuzzy"];
+const matchModeSchema = z.enum(matchModeValues);
 const completenessSchema = z.object({
     result_amount: z.number().int().nonnegative(),
     returned_items: z.number().int().nonnegative(),
@@ -156,7 +158,12 @@ const completenessSchema = z.object({
     output_page_complete: z.boolean().optional(),
     raw_next_page_token: z.string().nullable().optional(),
     output_next_page_token: z.string().nullable().optional(),
-    stop_reason: z.string().nullable().optional()
+    stop_reason: z.string().nullable().optional(),
+    provider_result_amount: z.number().int().nonnegative().nullable().optional(),
+    source_record_count: z.number().int().nonnegative().optional(),
+    effective_record_count: z.number().int().nonnegative().optional(),
+    returned_group_count: z.number().int().nonnegative().optional(),
+    total_group_count: z.number().int().nonnegative().optional()
 });
 const evidenceSchema = z.object({
     query_id: z.string(),
@@ -237,7 +244,7 @@ const publicFieldSelectorSchema = z.union([publicStringSchema, z.number().int()]
 const publicSortItemSchema = z.object({
     que_id: publicFieldSelectorSchema,
     ascend: z.boolean().optional()
-});
+}).strict();
 const publicFilterItemSchema = z.object({
     que_id: publicFieldSelectorSchema.optional(),
     search_key: publicStringSchema.optional(),
@@ -247,17 +254,17 @@ const publicFilterItemSchema = z.object({
     scope: z.number().int().optional(),
     search_options: z.array(publicFieldSelectorSchema).optional(),
     search_user_ids: z.array(publicStringSchema).optional()
-});
+}).strict();
 const publicTimeRangeSchema = z.object({
     column: publicFieldSelectorSchema,
     from: publicStringSchema.optional(),
     to: publicStringSchema.optional(),
     timezone: publicStringSchema.optional()
-});
+}).strict();
 const publicStatPolicySchema = z.object({
     include_negative: z.boolean().optional(),
     include_null: z.boolean().optional()
-});
+}).strict();
 const publicAnswerInputSchema = z.object({
     que_id: publicFieldSelectorSchema.optional(),
     queId: publicFieldSelectorSchema.optional(),
@@ -342,7 +349,8 @@ const listInputPublicSchema = z
     include_answers: z.boolean().optional(),
     strict_full: z.boolean().optional(),
     output_profile: outputProfileSchema.optional()
-});
+})
+    .strict();
 const listInputSchema = z
     .preprocess(normalizeListInput, z.object({
     app_key: z.string().min(1).optional(),
@@ -603,7 +611,8 @@ const queryInputPublicSchema = z
     scan_max_pages: z.number().int().positive().max(500).optional(),
     strict_full: z.boolean().optional(),
     output_profile: outputProfileSchema.optional()
-});
+})
+    .strict();
 const queryInputSchema = z
     .preprocess(normalizeQueryInput, z.object({
     query_mode: z.enum(["auto", "list", "record", "summary"]).optional(),
@@ -785,7 +794,8 @@ const aggregateInputPublicSchema = z
     max_groups: z.number().int().positive().max(2000).optional(),
     strict_full: z.boolean().optional(),
     output_profile: outputProfileSchema.optional()
-});
+})
+    .strict();
 const aggregateInputSchema = z
     .preprocess(normalizeAggregateInput, z.object({
     app_key: z.string().min(1),
@@ -936,6 +946,60 @@ const fieldResolveOutputSchema = z.object({
     }),
     meta: apiMetaSchema
 });
+const valueProbeInputPublicSchema = z
+    .object({
+    app_key: publicStringSchema,
+    field: publicFieldSelectorSchema,
+    query: publicStringSchema.optional(),
+    match_mode: matchModeSchema.optional(),
+    limit: z.number().int().positive().max(50).optional(),
+    scan_max_pages: z.number().int().positive().max(20).optional(),
+    page_size: z.number().int().positive().max(200).optional()
+})
+    .strict();
+const valueProbeInputSchema = z.preprocess(normalizeValueProbeInput, z
+    .object({
+    app_key: z.string().min(1),
+    field: z.union([z.string().min(1), z.number().int()]),
+    query: z.string().optional(),
+    match_mode: matchModeSchema.optional(),
+    limit: z.number().int().positive().max(50).optional(),
+    scan_max_pages: z.number().int().positive().max(20).optional(),
+    page_size: z.number().int().positive().max(200).optional()
+})
+    .strict());
+const valueProbeOutputSchema = z.object({
+    ok: z.literal(true),
+    data: z.object({
+        app_key: z.string(),
+        field: z.object({
+            requested: z.string(),
+            que_id: z.union([z.string(), z.number()]),
+            que_title: z.string().nullable(),
+            que_type: z.unknown()
+        }),
+        query: z.string().nullable(),
+        requested_match_mode: matchModeSchema,
+        effective_match_mode: matchModeSchema,
+        provider_translation: z.string(),
+        scanned_pages: z.number().int().nonnegative(),
+        scanned_records: z.number().int().nonnegative(),
+        provider_result_amount: z.number().int().nonnegative().nullable(),
+        candidates: z.array(z.object({
+            value: z.unknown(),
+            display_value: z.string(),
+            count: z.number().int().nonnegative(),
+            match_strength: z.number().min(0).max(1),
+            matched_texts: z.array(z.string()),
+            matched_as: z.string()
+        })),
+        matched_values: z.array(z.unknown())
+    }),
+    meta: z.object({
+        version: z.string(),
+        generated_at: z.string()
+    })
+});
 const queryPlanInputPublicSchema = z
     .object({
     tool: publicStringSchema,
@@ -1072,7 +1136,8 @@ const exportInputPublicSchema = z
     output_profile: outputProfileSchema.optional(),
     export_dir: publicStringSchema.optional(),
     file_name: publicStringSchema.optional()
-});
+})
+    .strict();
 const exportInputSchema = z.preprocess(normalizeExportInput, z.object({
     app_key: z.string().min(1).optional(),
     user_id: z.string().min(1).optional(),
@@ -1168,13 +1233,7 @@ const exportOutputSchema = z.object({
     meta: apiMetaSchema.optional()
 });
 const canonicalFieldRefSchema = publicFieldSelectorSchema;
-const canonicalMatchModeSchema = z.enum([
-    "exact",
-    "normalized",
-    "contains",
-    "prefix",
-    "fuzzy"
-]);
+const canonicalMatchModeSchema = matchModeSchema;
 const canonicalWhereOpSchema = z.enum([
     "eq",
     "neq",
@@ -1199,6 +1258,7 @@ const canonicalWhereItemSchema = z
     to: z.union([z.string(), z.number()]).optional(),
     match: canonicalMatchModeSchema.optional()
 })
+    .strict()
     .superRefine((value, ctx) => {
     if (value.op === "between") {
         if (value.from === undefined && value.to === undefined) {
@@ -1228,13 +1288,16 @@ const canonicalWhereItemSchema = z
         });
     }
 });
-const canonicalSortItemSchema = z.object({
+const canonicalSortItemSchema = z
+    .object({
     field: canonicalFieldRefSchema,
     direction: canonicalSortDirectionSchema.optional()
-});
+})
+    .strict();
 const canonicalSelectSchema = z.array(canonicalFieldRefSchema).min(1).max(MAX_COLUMN_LIMIT);
 const canonicalGroupBySchema = z.array(canonicalFieldRefSchema).min(1).max(20);
-const canonicalBaseQueryInputSchema = z.object({
+const canonicalBaseQueryInputSchema = z
+    .object({
     app_key: z.string().min(1),
     select: canonicalSelectSchema.optional(),
     where: z.array(canonicalWhereItemSchema).optional(),
@@ -1263,27 +1326,35 @@ const canonicalBaseQueryInputSchema = z.object({
         "cc"
     ])
         .optional()
-});
-const canonicalPlanInputSchema = z.object({
+})
+    .strict();
+const canonicalPlanInputSchema = z
+    .object({
     kind: z.enum(["rows", "record", "aggregate", "export", "mutate"]),
     query: z.record(z.unknown()).optional(),
     action: z.record(z.unknown()).optional(),
     probe: z.boolean().optional(),
     resolve_fields: z.boolean().optional()
-});
-const canonicalRowsInputSchema = canonicalBaseQueryInputSchema.extend({
+})
+    .strict();
+const canonicalRowsInputSchema = canonicalBaseQueryInputSchema
+    .extend({
     select: canonicalSelectSchema
-});
-const canonicalRecordInputSchema = z.object({
+})
+    .strict();
+const canonicalRecordInputSchema = z
+    .object({
     apply_id: canonicalFieldRefSchema,
     select: canonicalSelectSchema,
     output_profile: outputProfileSchema.optional()
-});
+})
+    .strict();
 const canonicalAggregateMetricInputSchema = z
     .object({
     column: canonicalFieldRefSchema.optional(),
     op: z.enum(["count", "sum", "avg", "min", "max"])
 })
+    .strict()
     .superRefine((value, ctx) => {
     if (value.op !== "count" && value.column === undefined) {
         ctx.addIssue({
@@ -1292,13 +1363,16 @@ const canonicalAggregateMetricInputSchema = z
         });
     }
 });
-const canonicalAggregateInputSchema = canonicalBaseQueryInputSchema.extend({
+const canonicalAggregateInputSchema = canonicalBaseQueryInputSchema
+    .extend({
     group_by: canonicalGroupBySchema,
     metrics: z.array(canonicalAggregateMetricInputSchema).min(1).max(10),
     time_bucket: z.enum(["day", "week", "month"]).optional(),
     top_n: z.number().int().positive().max(2000).optional()
-});
-const canonicalMutateInputSchema = z.object({
+})
+    .strict();
+const canonicalMutateInputSchema = z
+    .object({
     action: z.enum(["create", "update"]),
     app_key: z.string().min(1).optional(),
     apply_id: canonicalFieldRefSchema.optional(),
@@ -1306,24 +1380,33 @@ const canonicalMutateInputSchema = z.object({
     fields: z.record(z.unknown()).optional(),
     answers: z.array(publicAnswerInputSchema).optional(),
     force_refresh_form: z.boolean().optional()
-});
-const canonicalExportInputSchema = canonicalBaseQueryInputSchema.extend({
+})
+    .strict();
+const canonicalExportInputSchema = canonicalBaseQueryInputSchema
+    .extend({
     select: canonicalSelectSchema,
     format: z.enum(["csv", "json"]).optional(),
     file_name: z.string().min(1).optional(),
     export_dir: z.string().min(1).optional()
-});
+})
+    .strict();
 const canonicalResourceRefSchema = z.object({
     uri: z.string(),
     name: z.string(),
     mime_type: z.string(),
     description: z.string().nullable().optional()
 });
+const canonicalExecutionPlanSchema = z.object({
+    tool: z.string().nullable(),
+    arguments: z.record(z.unknown()).nullable(),
+    direct_execute: z.boolean()
+});
 const canonicalPlanOutputSchema = z.object({
     ok: z.literal(true),
     data: z.object({
         kind: z.string(),
         normalized_query: z.record(z.unknown()),
+        plan: canonicalExecutionPlanSchema,
         internal_tool: z.string().nullable(),
         internal_arguments: z.record(z.unknown()).nullable(),
         field_mapping: z.array(z.record(z.unknown())),
@@ -1382,6 +1465,9 @@ const canonicalAggregateOutputSchema = z.object({
         primary_metric_column: z.string().nullable(),
         summary: z.object({
             record_count: z.number().int().nonnegative(),
+            provider_result_amount: z.number().int().nonnegative().nullable(),
+            returned_group_count: z.number().int().nonnegative(),
+            total_group_count: z.number().int().nonnegative(),
             metrics_by_column: z.record(z.record(z.union([z.number(), z.null()])))
         }),
         groups: z.array(z.record(z.unknown())),
@@ -1567,6 +1653,25 @@ server.registerTool("qf_field_resolve", {
         return errorResult(error);
     }
 });
+server.registerTool("qf_value_probe", {
+    title: "Qingflow Value Probe",
+    description: "Probe likely field values for one app field, with explicit match mode and matched value evidence.",
+    inputSchema: valueProbeInputPublicSchema,
+    outputSchema: valueProbeOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true
+    }
+}, async (args) => {
+    try {
+        const parsedArgs = valueProbeInputSchema.parse(args);
+        const payload = await executeValueProbe(parsedArgs);
+        return okResult(payload, `Probed values for ${parsedArgs.app_key}:${String(parsedArgs.field)}`);
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+});
 server.registerTool("qf_query_plan", {
     title: "Qingflow Query Plan",
     description: "Preflight query arguments: normalize inputs, validate required fields, resolve mappings and estimate scan limits before execution.",
@@ -1598,6 +1703,7 @@ server.registerTool("qf.query.plan", {
 }, async (args) => {
     try {
         const parsedArgs = canonicalPlanInputSchema.parse(args);
+        const canonicalTool = canonicalExecutorToolForKind(parsedArgs.kind);
         const normalizedLoose = normalizeCanonicalLooseInput(parsedArgs.kind, parsedArgs.kind === "mutate" ? parsedArgs.action : parsedArgs.query);
         let normalizedQuery = normalizedLoose;
         let internalTool = parsedArgs.kind === "rows"
@@ -1664,6 +1770,11 @@ server.registerTool("qf.query.plan", {
                 data: {
                     kind: parsedArgs.kind,
                     normalized_query: normalizedQuery,
+                    plan: {
+                        tool: canonicalTool,
+                        arguments: normalizedQuery,
+                        direct_execute: false
+                    },
                     internal_tool: internalTool,
                     internal_arguments: internalArguments,
                     field_mapping: [],
@@ -1700,6 +1811,13 @@ server.registerTool("qf.query.plan", {
             data: {
                 kind: parsedArgs.kind,
                 normalized_query: normalizedQuery,
+                plan: {
+                    tool: canonicalTool,
+                    arguments: normalizedQuery,
+                    direct_execute: parsedArgs.kind === "mutate"
+                        ? true
+                        : Boolean(plannedPayload?.data.validation.valid && internalArguments)
+                },
                 internal_tool: internalTool,
                 internal_arguments: internalArguments,
                 field_mapping: plannedPayload?.data.field_mapping ?? [],
@@ -1912,6 +2030,9 @@ server.registerTool("qf.query.aggregate", {
                 metrics_by_column: asObject(group.metrics) ?? {}
             };
         });
+        const providerResultAmount = toNonNegativeInt(completeness.provider_result_amount ?? completeness.result_amount);
+        const returnedGroupCount = toNonNegativeInt(completeness.returned_group_count) ?? groups.length;
+        const totalGroupCount = toNonNegativeInt(completeness.total_group_count) ?? groups.length;
         const snapshotUri = buildQuerySnapshotResourceUri(queryId);
         const normalizedUri = buildQueryNormalizedResourceUri(queryId);
         const snapshot = {
@@ -1921,6 +2042,9 @@ server.registerTool("qf.query.aggregate", {
             primary_metric_column: built.primaryMetricColumn,
             summary: {
                 record_count: toNonNegativeInt(data.summary.total_count) ?? 0,
+                provider_result_amount: providerResultAmount,
+                returned_group_count: returnedGroupCount,
+                total_group_count: totalGroupCount,
                 metrics_by_column: summaryMetrics
             },
             groups,
@@ -1948,6 +2072,9 @@ server.registerTool("qf.query.aggregate", {
                 primary_metric_column: built.primaryMetricColumn,
                 summary: {
                     record_count: toNonNegativeInt(data.summary.total_count) ?? 0,
+                    provider_result_amount: providerResultAmount,
+                    returned_group_count: returnedGroupCount,
+                    total_group_count: totalGroupCount,
                     metrics_by_column: summaryMetrics
                 },
                 groups,
@@ -3017,6 +3144,88 @@ function applyAliases(obj, aliases) {
     }
     return out;
 }
+const FORBIDDEN_FILTER_RUNTIME_ALIASES = {
+    from: "min_value",
+    to: "max_value",
+    dateFrom: "min_value",
+    dateTo: "max_value",
+    searchKey: "search_key",
+    searchKeys: "search_keys"
+};
+const FORBIDDEN_TOP_LEVEL_TIME_ALIASES = {
+    from: "time_range.from",
+    to: "time_range.to",
+    dateFrom: "time_range.from",
+    dateTo: "time_range.to"
+};
+function throwForbiddenRuntimeAliasError(params) {
+    throw new InputValidationError({
+        message: `${params.tool} no longer accepts runtime alias "${params.alias}" at ${params.path}`,
+        errorCode: "FORBIDDEN_RUNTIME_ALIAS",
+        fixHint: params.fixHint,
+        details: {
+            tool: params.tool,
+            path: params.path,
+            alias: params.alias,
+            replacement: params.replacement
+        }
+    });
+}
+function assertNoForbiddenAliases(obj, aliasMap, params) {
+    for (const [alias, replacement] of Object.entries(aliasMap)) {
+        if (obj[alias] !== undefined) {
+            throwForbiddenRuntimeAliasError({
+                tool: params.tool,
+                path: `${params.pathPrefix}.${alias}`,
+                alias,
+                replacement,
+                fixHint: params.fixHint
+            });
+        }
+    }
+}
+function assertNoLegacyFilterAliases(value, tool) {
+    const parsed = parseJsonLikeDeep(value);
+    const list = Array.isArray(parsed) ? parsed : parsed === undefined || parsed === null ? [] : [parsed];
+    for (let index = 0; index < list.length; index += 1) {
+        const item = list[index];
+        const obj = asObject(item);
+        if (!obj) {
+            continue;
+        }
+        assertNoForbiddenAliases(obj, FORBIDDEN_FILTER_RUNTIME_ALIASES, {
+            tool,
+            pathPrefix: `filters[${index}]`,
+            fixHint: 'Use legacy filter keys "min_value"/"max_value"/"search_key"/"search_keys", or switch to canonical qf.query.* where clauses.'
+        });
+        const valueObject = asObject(parseJsonLikeDeep(obj.value));
+        if (!valueObject) {
+            continue;
+        }
+        assertNoForbiddenAliases(valueObject, FORBIDDEN_FILTER_RUNTIME_ALIASES, {
+            tool,
+            pathPrefix: `filters[${index}].value`,
+            fixHint: 'Use legacy filter keys "min_value"/"max_value"/"search_key"/"search_keys", or switch to canonical qf.query.* where clauses.'
+        });
+    }
+}
+function assertNoTopLevelTimeAliases(obj, tool) {
+    assertNoForbiddenAliases(obj, FORBIDDEN_TOP_LEVEL_TIME_ALIASES, {
+        tool,
+        pathPrefix: "arguments",
+        fixHint: 'Use time_range: {"column": ..., "from": "...", "to": "..."} instead of top-level date aliases.'
+    });
+}
+function assertNoValueProbeAliases(obj, tool) {
+    assertNoForbiddenAliases(obj, {
+        searchKey: "query",
+        searchKeys: "query"
+    }, {
+        tool,
+        pathPrefix: "arguments",
+        fixHint: 'Use "query" instead of "searchKey"/"searchKeys".'
+    });
+}
 function normalizeToolSpecInput(raw) {
     const parsedRoot = parseJsonLikeDeep(raw);
     const obj = asObject(parsedRoot);
@@ -3089,12 +3298,31 @@ function buildToolSpecCatalog() {
                 top_k: 3
             }
         },
+        {
+            tool: "qf_value_probe",
+            required: ["app_key", "field"],
+            limits: {
+                limit_max: 50,
+                scan_max_pages_max: 20,
+                page_size_max: 200,
+                match_mode: Array.from(matchModeValues),
+                input_contract: 'strict JSON only; use field plus optional query and match_mode. "searchKey"/"searchKeys" are rejected.'
+            },
+            aliases: {},
+            minimal_example: {
+                app_key: "21b3d559",
+                field: "归属部门",
+                query: "北斗",
+                match_mode: "contains",
+                limit: 10
+            }
+        },
         {
             tool: "qf_query_plan",
             required: ["tool"],
             limits: {
                 tool: "qf_records_list|qf_record_get|qf_query|qf_records_aggregate|qf_records_batch_get|qf_export_csv|qf_export_json",
-                input_contract: "strict JSON only; arguments must be a native JSON object"
+                input_contract: 'strict JSON only; arguments must be a native JSON object. Target tools reject runtime aliases like from/to/dateFrom/dateTo/searchKey/searchKeys.'
             },
             aliases: {},
             minimal_example: {
@@ -3112,7 +3340,7 @@ function buildToolSpecCatalog() {
             required: ["kind"],
             limits: {
                 kind: "rows|record|aggregate|export|mutate",
-                input_contract: "plan accepts loose model-shaped query objects and normalizes them before execution"
+                input_contract: "plan accepts loose model-shaped query objects, but rejects runtime aliases like from/to/dateFrom/dateTo/searchKey/searchKeys before execution"
             },
             aliases: {},
             minimal_example: {
@@ -3221,7 +3449,7 @@ function buildToolSpecCatalog() {
                 max_columns_max: MAX_COLUMN_LIMIT,
                 select_columns_max: MAX_COLUMN_LIMIT,
                 output_profile: "compact|verbose (default compact)",
-                input_contract: "strict JSON only; numbers/arrays/objects/booleans must use native JSON types"
+                input_contract: "strict JSON only; numbers/arrays/objects/booleans must use native JSON types, and runtime aliases from/to/dateFrom/dateTo/searchKey/searchKeys are rejected"
             },
             aliases: {},
             minimal_example: {
@@ -3276,7 +3504,7 @@ function buildToolSpecCatalog() {
                 max_rows_max: EXPORT_MAX_ROWS,
                 max_columns_max: MAX_COLUMN_LIMIT,
                 select_columns_max: MAX_COLUMN_LIMIT,
-                input_contract: "strict JSON only; select_columns/time_range must use native JSON types"
+                input_contract: "strict JSON only; select_columns/time_range must use native JSON types, and runtime aliases from/to/dateFrom/dateTo/searchKey/searchKeys are rejected"
             },
             aliases: {},
             minimal_example: {
@@ -3298,7 +3526,7 @@ function buildToolSpecCatalog() {
                 max_rows_max: EXPORT_MAX_ROWS,
                 max_columns_max: MAX_COLUMN_LIMIT,
                 select_columns_max: MAX_COLUMN_LIMIT,
-                input_contract: "strict JSON only; select_columns/time_range must use native JSON types"
+                input_contract: "strict JSON only; select_columns/time_range must use native JSON types, and runtime aliases from/to/dateFrom/dateTo/searchKey/searchKeys are rejected"
             },
             aliases: {},
             minimal_example: {
@@ -3327,7 +3555,7 @@ function buildToolSpecCatalog() {
                 max_columns_max: MAX_COLUMN_LIMIT,
                 select_columns_max: MAX_COLUMN_LIMIT,
                 output_profile: "compact|verbose (default compact)",
-                input_contract: "strict JSON only; select_columns/time_range/stat_policy must use native JSON types"
+                input_contract: "strict JSON only; select_columns/time_range/stat_policy must use native JSON types, and runtime aliases from/to/dateFrom/dateTo/searchKey/searchKeys are rejected"
             },
             aliases: {},
             minimal_example: {
@@ -3357,7 +3585,7 @@ function buildToolSpecCatalog() {
                 metrics_supported: ["count", "sum", "avg", "min", "max"],
                 time_bucket_supported: ["day", "week", "month"],
                 output_profile: "compact|verbose (default compact)",
-                input_contract: "strict JSON only; group_by/amount_columns/time_range must use native JSON types"
+                input_contract: "strict JSON only; group_by/amount_columns/time_range must use native JSON types, and runtime aliases from/to/dateFrom/dateTo/searchKey/searchKeys are rejected"
             },
             aliases: {},
             minimal_example: {
@@ -3455,6 +3683,8 @@ function normalizeListInput(raw) {
     if (!obj) {
         return parsedRoot;
     }
+    assertNoTopLevelTimeAliases(obj, "qf_records_list");
+    assertNoLegacyFilterAliases(obj.filters, "qf_records_list");
     const normalizedObj = applyAliases(obj, COMMON_INPUT_ALIASES);
     const selectColumns = normalizedObj.select_columns ?? normalizedObj.keep_columns;
     const timeRange = buildFriendlyTimeRangeInput(normalizedObj);
@@ -3500,6 +3730,8 @@ function normalizeQueryInput(raw) {
     if (!obj) {
         return parsedRoot;
     }
+    assertNoTopLevelTimeAliases(obj, "qf_query");
+    assertNoLegacyFilterAliases(obj.filters, "qf_query");
     const normalizedObj = applyAliases(obj, COMMON_INPUT_ALIASES);
     const selectColumns = normalizedObj.select_columns ?? normalizedObj.keep_columns;
     const timeRange = buildFriendlyTimeRangeInput(normalizedObj);
@@ -3532,6 +3764,8 @@ function normalizeAggregateInput(raw) {
     if (!obj) {
         return parsedRoot;
     }
+    assertNoTopLevelTimeAliases(obj, "qf_records_aggregate");
+    assertNoLegacyFilterAliases(obj.filters, "qf_records_aggregate");
     const normalizedObj = applyAliases(obj, COMMON_INPUT_ALIASES);
     const timeRange = buildFriendlyTimeRangeInput(normalizedObj);
     const amountColumns = normalizeAmountColumnsInput(normalizedObj.amount_columns ?? normalizedObj.amount_column);
@@ -3579,6 +3813,38 @@ function normalizeFieldResolveInput(raw) {
         fuzzy: coerceBooleanLike(normalizedObj.fuzzy)
     };
 }
+function normalizeValueProbeInput(raw) {
+    const parsedRoot = parseJsonLikeDeep(raw);
+    const obj = asObject(parsedRoot);
+    if (!obj) {
+        return parsedRoot;
+    }
+    assertNoValueProbeAliases(obj, "qf_value_probe");
+    const normalizedObj = applyAliases(obj, {
+        appKey: "app_key",
+        fieldId: "field",
+        fieldTitle: "field",
+        name: "field",
+        value: "query",
+        search: "query",
+        prefix: "query",
+        match: "match_mode",
+        matchMode: "match_mode",
+        scanMaxPages: "scan_max_pages",
+        pageSize: "page_size"
+    });
+    return {
+        ...normalizedObj,
+        field: normalizeSelectorInputValue(normalizedObj.field),
+        query: normalizedObj.query !== undefined ? coerceStringLike(normalizedObj.query) : undefined,
+        match_mode: typeof normalizedObj.match_mode === "string" && normalizedObj.match_mode.trim()
+            ? normalizedObj.match_mode.trim().toLowerCase()
+            : undefined,
+        limit: coerceNumberLike(normalizedObj.limit),
+        scan_max_pages: coerceNumberLike(normalizedObj.scan_max_pages),
+        page_size: coerceNumberLike(normalizedObj.page_size)
+    };
+}
 function normalizeQueryPlanInput(raw) {
     const parsedRoot = parseJsonLikeDeep(raw);
     const obj = asObject(parsedRoot);
@@ -3621,6 +3887,8 @@ function normalizeExportInput(raw) {
     if (!obj) {
         return parsedRoot;
     }
+    assertNoTopLevelTimeAliases(obj, "qf_export");
+    assertNoLegacyFilterAliases(obj.filters, "qf_export");
     const normalizedObj = applyAliases(obj, COMMON_INPUT_ALIASES);
     const selectColumns = normalizedObj.select_columns ?? normalizedObj.keep_columns;
     const timeRange = buildFriendlyTimeRangeInput(normalizedObj);
@@ -3800,8 +4068,6 @@ function normalizeFiltersInput(value) {
             column: "que_id",
             columnId: "que_id",
             columnTitle: "que_title",
-            searchKey: "search_key",
-            searchKeys: "search_keys",
             minValue: "min_value",
             maxValue: "max_value",
             compareType: "compare_type",
@@ -3810,10 +4076,8 @@ function normalizeFiltersInput(value) {
             users: "search_user_ids",
             options: "search_options",
             start: "min_value",
-            from: "min_value",
             min: "min_value",
             end: "max_value",
-            to: "max_value",
             max: "max_value"
         });
         const normalizedCompareType = typeof normalizedObj.compare_type === "string"
@@ -3835,17 +4099,11 @@ function normalizeFiltersInput(value) {
         if (valueObject) {
             const valueAliases = applyAliases(valueObject, {
                 start: "min_value",
-                from: "min_value",
                 min: "min_value",
                 date_from: "min_value",
-                dateFrom: "min_value",
                 end: "max_value",
-                to: "max_value",
                 max: "max_value",
                 date_to: "max_value",
-                dateTo: "max_value",
-                searchKey: "search_key",
-                searchKeys: "search_keys",
                 searchOptions: "search_options",
                 searchUserIds: "search_user_ids"
             });
@@ -4010,8 +4268,8 @@ function buildFriendlyTimeRangeInput(obj) {
     const normalizedRawTimeRange = normalizeTimeRangeInput(obj.time_range);
     const normalizedTimeRange = asObject(normalizedRawTimeRange);
     const columnCandidate = firstPresent(obj.date_field, obj.dateField, obj.time_field, obj.timeField, obj.time_column, obj.timeColumn, obj.date_column, obj.dateColumn, normalizedTimeRange?.column);
-    const fromCandidate = firstPresent(obj.date_from, obj.dateFrom, obj.time_from, obj.timeFrom, obj.start, obj.start_date, obj.startDate, obj.from, normalizedTimeRange?.from);
-    const toCandidate = firstPresent(obj.date_to, obj.dateTo, obj.time_to, obj.timeTo, obj.end, obj.end_date, obj.endDate, obj.to, normalizedTimeRange?.to);
+    const fromCandidate = firstPresent(obj.date_from, obj.time_from, obj.timeFrom, obj.start, obj.start_date, obj.startDate, normalizedTimeRange?.from);
+    const toCandidate = firstPresent(obj.date_to, obj.time_to, obj.timeTo, obj.end, obj.end_date, obj.endDate, normalizedTimeRange?.to);
     const timezoneCandidate = firstPresent(obj.timezone, obj.timeZone, obj.tz, normalizedTimeRange?.timezone);
     if (columnCandidate === undefined &&
         fromCandidate === undefined &&
@@ -4280,7 +4538,14 @@ function buildExtendedCompleteness(params) {
         output_page_complete: outputPageComplete,
         raw_next_page_token: params.rawNextPageToken ?? params.nextPageToken,
         output_next_page_token: params.outputNextPageToken ?? null,
-        stop_reason: params.stopReason ?? null
+        stop_reason: params.stopReason ?? null,
+        provider_result_amount: params.providerResultAmount ?? params.resultAmount,
+        source_record_count: params.sourceRecordCount ?? params.returnedItems,
+        effective_record_count: params.effectiveRecordCount ?? params.returnedItems,
+        ...(params.returnedGroupCount !== undefined
+            ? { returned_group_count: params.returnedGroupCount }
+            : {}),
+        ...(params.totalGroupCount !== undefined ? { total_group_count: params.totalGroupCount } : {})
     };
 }
 function normalizePlanToolName(tool) {
@@ -5070,6 +5335,10 @@ function buildRecordGetArgsFromQuery(args) {
 }
 function normalizeCanonicalLooseInput(kind, raw) {
     const parsed = asObject(parseJsonLikeDeep(raw)) ?? {};
+    if (kind === "rows" || kind === "aggregate" || kind === "export") {
+        assertNoTopLevelTimeAliases(parsed, "qf.query.plan");
+        assertNoLegacyFilterAliases(parsed.filters, "qf.query.plan");
+    }
     const out = { ...parsed };
     const assignAlias = (target, aliases) => {
         if (out[target] !== undefined) {
@@ -5208,6 +5477,39 @@ function normalizeCanonicalLooseInput(kind, raw) {
             };
         });
     }
+    return pickCanonicalLooseFields(kind, out);
+}
+function pickCanonicalLooseFields(kind, value) {
+    const commonKeys = [
+        "app_key",
+        "select",
+        "where",
+        "sort",
+        "limit",
+        "cursor",
+        "page_size",
+        "requested_pages",
+        "scan_max_pages",
+        "strict_full",
+        "output_profile",
+        "user_id",
+        "mode"
+    ];
+    const allowedKeys = kind === "rows"
+        ? commonKeys
+        : kind === "record"
+            ? ["apply_id", "select", "output_profile"]
+            : kind === "aggregate"
+                ? [...commonKeys.filter((item) => item !== "select"), "group_by", "metrics", "time_bucket", "top_n"]
+                : kind === "export"
+                    ? [...commonKeys, "format", "file_name", "export_dir"]
+                    : ["action", "app_key", "apply_id", "user_id", "fields", "answers", "force_refresh_form"];
+    const out = {};
+    for (const key of allowedKeys) {
+        if (value[key] !== undefined) {
+            out[key] = value[key];
+        }
+    }
     return out;
 }
 function legacyFiltersToCanonicalWhere(filters, timeRange) {
@@ -5414,7 +5716,7 @@ async function buildCanonicalAggregateExecution(input) {
         filters: translation.filters,
         sort: translateCanonicalSortToLegacy(input.sort),
         group_by: input.group_by,
-        amount_columns: amountColumns,
+        ...(amountColumns.length > 0 ? { amount_columns: amountColumns } : {}),
         metrics: metricNames,
         time_bucket: input.time_bucket,
         max_groups: input.top_n,
@@ -5475,7 +5777,9 @@ async function buildCanonicalExportExecution(input) {
             scan_max_pages: input.scan_max_pages ?? (input.requested_pages ?? EXPORT_DEFAULT_PAGES),
             strict_full: input.strict_full ?? false,
             mode: input.mode ?? "all",
-            format
+            format,
+            ...(input.file_name ? { file_name: input.file_name } : {}),
+            ...(input.export_dir ? { export_dir: input.export_dir } : {})
         },
         internalTool: format === "csv" ? "qf_export_csv" : "qf_export_json",
         internalArguments,
@@ -5495,7 +5799,10 @@ async function buildCanonicalMutateExecution(input) {
             normalizedQuery: {
                 action: input.action,
                 app_key: input.app_key ?? null,
-                fields: input.fields ?? null
+                user_id: input.user_id ?? null,
+                fields: input.fields ?? null,
+                answers: input.answers ?? null,
+                force_refresh_form: input.force_refresh_form ?? false
             },
             internalTool: "qf_record_create",
             internalArguments
@@ -5514,12 +5821,30 @@ async function buildCanonicalMutateExecution(input) {
             action: input.action,
             app_key: input.app_key ?? null,
             apply_id: input.apply_id ?? null,
-            fields: input.fields ?? null
+            user_id: input.user_id ?? null,
+            fields: input.fields ?? null,
+            answers: input.answers ?? null,
+            force_refresh_form: input.force_refresh_form ?? false
         },
         internalTool: "qf_record_update",
         internalArguments
     };
 }
+function canonicalExecutorToolForKind(kind) {
+    if (kind === "rows") {
+        return "qf.query.rows";
+    }
+    if (kind === "record") {
+        return "qf.query.record";
+    }
+    if (kind === "aggregate") {
+        return "qf.query.aggregate";
+    }
+    if (kind === "export") {
+        return "qf.query.export";
+    }
+    return "qf.records.mutate";
+}
 async function executeFieldResolve(args) {
     const response = await getFormCached(args.app_key, undefined, false);
     const index = buildFieldIndex(response.result);
@@ -5544,6 +5869,42 @@ async function executeFieldResolve(args) {
         meta: buildMeta(response)
     };
 }
+async function executeValueProbe(args) {
+    const details = await collectFieldValueCandidatesDetailed({
+        appKey: args.app_key,
+        field: String(args.field),
+        prefix: args.query,
+        match: args.match_mode,
+        limit: args.limit,
+        scanMaxPages: args.scan_max_pages,
+        pageSize: args.page_size
+    });
+    return {
+        ok: true,
+        data: {
+            app_key: args.app_key,
+            field: {
+                requested: details.field.requested,
+                que_id: details.field.que_id,
+                que_title: details.field.que_title,
+                que_type: details.field.que_type
+            },
+            query: details.query || null,
+            requested_match_mode: details.requested_match_mode,
+            effective_match_mode: details.effective_match_mode,
+            provider_translation: details.provider_translation,
+            scanned_pages: details.scanned_pages,
+            scanned_records: details.scanned_records,
+            provider_result_amount: details.provider_result_amount,
+            candidates: details.candidates,
+            matched_values: details.candidates.map((item) => item.value)
+        },
+        meta: {
+            version: SERVER_VERSION,
+            generated_at: new Date().toISOString()
+        }
+    };
+}
 async function executeQueryPlan(args) {
     const normalizedTool = normalizePlanToolName(args.tool);
     const rawArguments = asObject(parseJsonLikeDeep(args.arguments)) ?? {};
@@ -5648,7 +6009,10 @@ async function executeRecordsBatchGet(args) {
         is_complete: missingApplyIds.length === 0,
         partial: missingApplyIds.length > 0,
         omitted_items: missingApplyIds.length,
-        omitted_chars: 0
+        omitted_chars: 0,
+        provider_result_amount: requestedApplyIds.length,
+        source_record_count: rows.length,
+        effective_record_count: rows.length
     };
     const evidence = buildEvidencePayload({
         query_id: queryId,
@@ -5862,7 +6226,10 @@ async function executeRecordsExport(format, args) {
         is_complete: !hasMore && omittedItems === 0,
         partial: hasMore || omittedItems > 0,
         omitted_items: omittedItems,
-        omitted_chars: 0
+        omitted_chars: 0,
+        provider_result_amount: knownResultAmount,
+        source_record_count: rows.length,
+        effective_record_count: rows.length
     };
     const evidence = buildEvidencePayload({
         query_id: queryId,
@@ -6085,7 +6452,10 @@ async function executeRecordsList(args) {
         is_complete: isComplete,
         partial: !isComplete,
         omitted_items: omittedItems,
-        omitted_chars: fittedRows.omittedChars
+        omitted_chars: fittedRows.omittedChars,
+        provider_result_amount: knownResultAmount,
+        source_record_count: collectedRawItems.length,
+        effective_record_count: fittedRows.items.length
     };
     const listState = {
         query_id: queryId,
@@ -6197,7 +6567,10 @@ async function executeRecordGet(args) {
         is_complete: true,
         partial: false,
         omitted_items: 0,
-        omitted_chars: 0
+        omitted_chars: 0,
+        provider_result_amount: 1,
+        source_record_count: 1,
+        effective_record_count: 1
     };
     const evidence = {
         query_id: queryId,
@@ -6622,7 +6995,10 @@ async function executeRecordsSummary(args) {
         outputPageComplete,
         rawNextPageToken,
         outputNextPageToken: null,
-        stopReason
+        stopReason,
+        providerResultAmount: knownResultAmount,
+        sourceRecordCount: scannedRecords,
+        effectiveRecordCount: scannedRecords
     });
     const evidence = buildEvidencePayload(listState, sourcePages);
     if (strictFull && !rawScanComplete) {
@@ -6924,7 +7300,12 @@ async function executeRecordsAggregate(args) {
         outputPageComplete,
         rawNextPageToken,
         outputNextPageToken: null,
-        stopReason
+        stopReason,
+        providerResultAmount: knownResultAmount,
+        sourceRecordCount: scannedRecords,
+        effectiveRecordCount: scannedRecords,
+        returnedGroupCount: Math.min(groupsTotal, maxGroups),
+        totalGroupCount: groupsTotal
     });
     const evidence = buildEvidencePayload(listState, sourcePages);
     if (strictFull && !completeness.is_complete) {
@@ -7528,38 +7909,77 @@ async function completeFieldCandidates(appKey, prefix) {
         .slice(0, 20);
 }
 async function collectFieldValueCandidates(params) {
+    const details = await collectFieldValueCandidatesDetailed(params);
+    return details.candidates;
+}
+async function collectFieldValueCandidatesDetailed(params) {
     const appKey = params.appKey.trim();
     const fieldSelector = params.field.trim();
     if (!appKey || !fieldSelector) {
-        return [];
+        throw new InputValidationError({
+            message: "app_key and field are required for qf_value_probe",
+            errorCode: "MISSING_REQUIRED_FIELD",
+            fixHint: "Pass app_key plus field (que_id or field title).",
+            details: {
+                app_key: appKey || null,
+                field: fieldSelector || null
+            }
+        });
     }
     const form = await getFormCached(appKey, undefined, false);
     const index = buildFieldIndex(form.result);
     const column = resolveSummaryColumn(fieldSelector, index, "field");
     const counts = new Map();
     let currentPage = 1;
-    for (let fetched = 0; fetched < 5; fetched += 1) {
+    let scannedPages = 0;
+    let scannedRecords = 0;
+    let providerResultAmount = null;
+    const query = (params.prefix ?? "").trim();
+    const requestedMatchMode = normalizeMatchMode(params.match);
+    const limit = params.limit ?? 20;
+    const scanMaxPages = params.scanMaxPages ?? 5;
+    const pageSize = params.pageSize ?? 50;
+    for (let fetched = 0; fetched < scanMaxPages; fetched += 1) {
         const payload = buildListPayload({
             pageNum: currentPage,
-            pageSize: 50,
+            pageSize,
             mode: "all"
         });
         const response = await client.listRecords(appKey, payload, {});
         const result = asObject(response.result);
         const rawItems = asArray(result?.result);
+        providerResultAmount = providerResultAmount ?? toNonNegativeInt(result?.resultAmount);
+        scannedPages += 1;
+        scannedRecords += rawItems.length;
         for (const rawItem of rawItems) {
             const record = asObject(rawItem) ?? {};
             const value = extractSummaryColumnValue(asArray(record.answers), column);
-            const candidates = Array.isArray(value) ? value : [value];
-            for (const candidate of candidates) {
-                if (candidate === null || candidate === undefined) {
-                    continue;
-                }
-                const normalized = String(candidate).trim();
-                if (!normalized) {
-                    continue;
+            if (value === null || value === undefined) {
+                continue;
+            }
+            const normalized = normalizeProbeValue(value);
+            if (!normalized.display_value) {
+                continue;
+            }
+            const matchDetails = scoreProbeValueMatch(value, query, requestedMatchMode);
+            const existing = counts.get(normalized.key);
+            if (existing) {
+                existing.count += 1;
+                if (matchDetails.match_strength > existing.match_strength) {
+                    existing.match_strength = matchDetails.match_strength;
+                    existing.matched_texts = matchDetails.matched_texts;
+                    existing.matched_as = matchDetails.matched_as;
                 }
-                counts.set(normalized, (counts.get(normalized) ?? 0) + 1);
+            }
+            else {
+                counts.set(normalized.key, {
+                    value: normalized.value,
+                    display_value: normalized.display_value,
+                    count: 1,
+                    match_strength: matchDetails.match_strength,
+                    matched_texts: matchDetails.matched_texts,
+                    matched_as: matchDetails.matched_as
+                });
             }
         }
         const pageAmount = toPositiveInt(result?.pageAmount);
@@ -7568,20 +7988,21 @@ async function collectFieldValueCandidates(params) {
         }
         currentPage += 1;
     }
-    const normalizedPrefix = (params.prefix ?? "").trim().toLowerCase();
-    const match = (params.match ?? "contains").trim().toLowerCase();
-    const limit = params.limit ?? 20;
-    return Array.from(counts.entries())
-        .map(([value, count]) => ({
-        value,
-        count,
-        match_strength: normalizedPrefix.length === 0
-            ? 1
-            : scoreTextMatch(value, normalizedPrefix, match)
-    }))
+    const candidates = Array.from(counts.values())
         .filter((item) => item.match_strength > 0)
         .sort((a, b) => b.match_strength - a.match_strength || b.count - a.count)
         .slice(0, limit);
+    return {
+        field: column,
+        query,
+        requested_match_mode: requestedMatchMode,
+        effective_match_mode: requestedMatchMode,
+        provider_translation: "local_distinct_scan",
+        scanned_pages: scannedPages,
+        scanned_records: scannedRecords,
+        provider_result_amount: providerResultAmount,
+        candidates
+    };
 }
 function scoreTextMatch(candidate, prefix, match) {
     const normalizedCandidate = candidate.trim().toLowerCase();
@@ -7602,6 +8023,84 @@ function scoreTextMatch(candidate, prefix, match) {
     }
     return normalizedCandidate.includes(prefix) ? 0.9 : 0;
 }
+function normalizeMatchMode(value) {
+    if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase();
+        if (matchModeValues.includes(normalized)) {
+            return normalized;
+        }
+    }
+    return "contains";
+}
+function normalizeProbeValue(value) {
+    if (value === null || value === undefined) {
+        return {
+            key: "null",
+            value,
+            display_value: ""
+        };
+    }
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        return {
+            key: stableJson(value),
+            value,
+            display_value: String(value).trim()
+        };
+    }
+    return {
+        key: stableJson(value),
+        value,
+        display_value: stableJson(value)
+    };
+}
+function scoreProbeValueMatch(value, query, matchMode) {
+    if (!query) {
+        return {
+            match_strength: 1,
+            matched_texts: [],
+            matched_as: "all"
+        };
+    }
+    const normalizedQuery = query.trim().toLowerCase();
+    const normalized = normalizeProbeValue(value);
+    let bestScore = scoreTextMatch(normalized.display_value.toLowerCase(), normalizedQuery, matchMode);
+    let matchedTexts = bestScore > 0 ? [normalized.display_value] : [];
+    let matchedAs = bestScore > 0 ? matchMode : "none";
+    const leafTexts = flattenProbeLeafTexts(value);
+    for (const leaf of leafTexts) {
+        const score = scoreTextMatch(leaf.toLowerCase(), normalizedQuery, matchMode);
+        if (score > bestScore) {
+            bestScore = score;
+            matchedTexts = [leaf];
+            matchedAs = Array.isArray(value)
+                ? `array_${matchMode}`
+                : value && typeof value === "object"
+                    ? `object_${matchMode}`
+                    : matchMode;
+        }
+    }
+    return {
+        match_strength: Number(Math.min(1, Math.max(0, bestScore)).toFixed(4)),
+        matched_texts: uniqueStringList(matchedTexts),
+        matched_as: matchedAs
+    };
+}
+function flattenProbeLeafTexts(value, depth = 0) {
+    if (depth > 4 || value === null || value === undefined) {
+        return [];
+    }
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        const text = String(value).trim();
+        return text ? [text] : [];
+    }
+    if (Array.isArray(value)) {
+        return uniqueStringList(value.flatMap((item) => flattenProbeLeafTexts(item, depth + 1)));
+    }
+    if (typeof value === "object") {
+        return uniqueStringList(Object.values(value).flatMap((item) => flattenProbeLeafTexts(item, depth + 1)));
+    }
+    return [];
+}
 async function completeFieldValueCandidates(appKey, field, prefix, match) {
     const candidates = await collectFieldValueCandidates({
         appKey,
@@ -7610,7 +8109,7 @@ async function completeFieldValueCandidates(appKey, field, prefix, match) {
         match,
         limit: 10
     });
-    return candidates.map((item) => item.value);
+    return candidates.map((item) => item.display_value);
 }
 function completeQueryIdCandidates(prefix) {
     cleanupArtifactCaches();
@@ -7657,17 +8156,29 @@ async function readFieldValuesResource(uri, variables) {
     if (!appKey || !field) {
         throw new Error("app_key and field are required");
     }
-    return jsonResourceResponse(uri, {
-        app_key: appKey,
+    const details = await collectFieldValueCandidatesDetailed({
+        appKey,
         field,
-        match,
         prefix,
-        candidates: await collectFieldValueCandidates({
-            appKey,
-            field,
-            prefix,
-            match
-        })
+        match
+    });
+    return jsonResourceResponse(uri, {
+        app_key: appKey,
+        field: {
+            requested: details.field.requested,
+            que_id: details.field.que_id,
+            que_title: details.field.que_title,
+            que_type: details.field.que_type
+        },
+        query: details.query || null,
+        requested_match_mode: details.requested_match_mode,
+        effective_match_mode: details.effective_match_mode,
+        provider_translation: details.provider_translation,
+        scanned_pages: details.scanned_pages,
+        scanned_records: details.scanned_records,
+        provider_result_amount: details.provider_result_amount,
+        candidates: details.candidates,
+        matched_values: details.candidates.map((item) => item.value)
     });
 }
 async function readQueryNormalizedResource(uri, variables) {

package/package.json

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