qingflow-mcp 0.4.1 → 0.4.2

package/README.md

@@ -109,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.1
+npm i -g qingflow-mcp@0.4.2
 ```
 
 Or one-click installer:
@@ -217,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/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.1";
+const SERVER_VERSION = "0.4.2";
 const accessToken = process.env.QINGFLOW_ACCESS_TOKEN;
 const baseUrl = process.env.QINGFLOW_BASE_URL;
 if (!accessToken) {
@@ -244,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(),
@@ -254,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(),
@@ -349,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(),
@@ -610,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(),
@@ -792,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),
@@ -1133,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(),
@@ -3140,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);
@@ -3220,7 +3306,7 @@ function buildToolSpecCatalog() {
                 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"
+                input_contract: 'strict JSON only; use field plus optional query and match_mode. "searchKey"/"searchKeys" are rejected.'
             },
             aliases: {},
             minimal_example: {
@@ -3236,7 +3322,7 @@ function buildToolSpecCatalog() {
             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: {
@@ -3254,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: {
@@ -3363,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: {
@@ -3418,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: {
@@ -3440,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: {
@@ -3469,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: {
@@ -3499,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: {
@@ -3597,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);
@@ -3642,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);
@@ -3674,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);
@@ -3727,6 +3819,7 @@ function normalizeValueProbeInput(raw) {
     if (!obj) {
         return parsedRoot;
     }
+    assertNoValueProbeAliases(obj, "qf_value_probe");
     const normalizedObj = applyAliases(obj, {
         appKey: "app_key",
         fieldId: "field",
@@ -3734,7 +3827,6 @@ function normalizeValueProbeInput(raw) {
         name: "field",
         value: "query",
         search: "query",
-        searchKey: "query",
         prefix: "query",
         match: "match_mode",
         matchMode: "match_mode",
@@ -3795,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);
@@ -3974,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",
@@ -3984,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"
@@ -4009,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"
             });
@@ -4184,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 &&
@@ -5251,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) {

package/package.json

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