qingflow-mcp 0.3.22 → 0.3.23

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.22
+npm i -g qingflow-mcp@0.3.23
 ```
 
 Or one-click installer:
@@ -153,7 +153,7 @@ MCP client config example:
 ## Recommended Flow
 
 1. `qf_apps_list` to pick app.
-2. `qf_form_get` to inspect field ids/titles.
+2. `qf_form_get` to inspect field ids/titles and `field_summaries[].write_format`.
 3. `qf_record_create` or `qf_record_update`.
 4. If create/update returns only `request_id`, call `qf_operation_get` to resolve async result.
 
@@ -180,6 +180,43 @@ Full calling contract (Chinese):
 
 - [MCP 调用规范](./docs/MCP_CALLING_SPEC.md)
 
+## Write Format Discovery
+
+For create/update, `0.3.23` now makes special write formats explicit:
+
+1. `qf_form_get`
+   - `field_summaries[].write_format` is populated for member/department fields.
+2. `qf_tool_spec_get`
+   - `qf_record_create` / `qf_record_update` include member/department examples in `limits.special_field_write_formats`.
+3. `qf_record_create` / `qf_record_update`
+   - invalid member/department values fail fast with `FIELD_VALUE_FORMAT_ERROR`.
+
+Examples:
+
+```json
+{
+  "fields": {
+    "归属销售": [
+      { "userId": "u_123", "userName": "张三" }
+    ],
+    "归属部门": [
+      { "deptId": 111, "deptName": "销售部" }
+    ]
+  }
+}
+```
+
+Invalid examples that will now fail:
+
+```json
+{
+  "fields": {
+    "归属销售": "张三",
+    "归属部门": "销售部"
+  }
+}
+```
+
 ## Unified Query (`qf_query`)
 
 `qf_query` is the recommended read entry for agents.
@@ -429,7 +466,7 @@ If you see runtime errors around `Headers` or missing web APIs:
 2. Upgrade package to latest:
 
 ```bash
-npm i -g qingflow-mcp@latest
+npm i -g qingflow-mcp@0.3.23
 ```
 
 3. Verify runtime:

package/dist/server.js

@@ -68,7 +68,9 @@ 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.22";
+const SERVER_VERSION = "0.3.23";
+const MEMBER_QUE_TYPE_KEYWORDS = ["member", "user", "成员", "人员"];
+const DEPARTMENT_QUE_TYPE_KEYWORDS = ["department", "dept", "部门"];
 const accessToken = process.env.QINGFLOW_ACCESS_TOKEN;
 const baseUrl = process.env.QINGFLOW_BASE_URL;
 if (!accessToken) {
@@ -192,6 +194,15 @@ const fieldSummarySchema = z.object({
     que_id: z.union([z.number(), z.string(), z.null()]),
     que_title: z.string().nullable(),
     que_type: z.unknown(),
+    write_format: z
+        .object({
+        kind: z.enum(["member_list", "department_list"]),
+        description: z.string(),
+        item_shape: z.record(z.string()),
+        example: z.array(z.record(z.unknown())),
+        resolution_hint: z.string()
+    })
+        .nullable(),
     has_sub_fields: z.boolean(),
     sub_field_count: z.number().int().nonnegative()
 });
@@ -2388,7 +2399,8 @@ server.registerTool("qf_record_create", {
 }, async (args) => {
     try {
         const parsedArgs = createInputSchema.parse(args);
-        const form = needsFormResolution(parsedArgs.fields) || Boolean(parsedArgs.force_refresh_form)
+        const shouldFetchForm = hasWritePayload(parsedArgs.answers, parsedArgs.fields) || Boolean(parsedArgs.force_refresh_form);
+        const form = shouldFetchForm
             ? await getFormCached(parsedArgs.app_key, parsedArgs.user_id, Boolean(parsedArgs.force_refresh_form))
             : null;
         const normalizedAnswers = resolveAnswers({
@@ -2464,16 +2476,18 @@ server.registerTool("qf_record_update", {
 }, async (args) => {
     try {
         const parsedArgs = updateInputSchema.parse(args);
-        const requiresForm = needsFormResolution(parsedArgs.fields);
-        if (requiresForm && !parsedArgs.app_key) {
+        const resolvedAppKey = parsedArgs.app_key ?? getCachedApplyAppKey(parsedArgs.apply_id);
+        const requiresFormByTitle = needsFormResolution(parsedArgs.fields);
+        if (requiresFormByTitle && !resolvedAppKey) {
             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))
+        const form = (hasWritePayload(parsedArgs.answers, parsedArgs.fields) || Boolean(parsedArgs.force_refresh_form)) &&
+            resolvedAppKey
+            ? await getFormCached(resolvedAppKey, parsedArgs.user_id, Boolean(parsedArgs.force_refresh_form))
             : null;
         const normalizedAnswers = resolveAnswers({
             explicitAnswers: parsedArgs.answers,
@@ -3534,7 +3548,8 @@ function buildToolSpecCatalog() {
             tool: "qf_form_get",
             required: ["app_key"],
             limits: {
-                app_key: "required string"
+                app_key: "required string",
+                write_format_hint: "field_summaries[].write_format is populated for member/department fields so agents can discover exact create/update payload shapes before writing."
             },
             aliases: collectAliasHints(["app_key", "user_id", "force_refresh"], {}),
             minimal_example: {
@@ -3751,7 +3766,11 @@ function buildToolSpecCatalog() {
                 write_mode: "Provide either answers[] or fields{}",
                 wait_result: "optional boolean; when true, polls qf_operation_get internally and returns resolved apply_id directly",
                 wait_timeout_ms: "optional int (max 20000); default 5000ms",
-                input_contract: "strict JSON only; answers must be array and fields must be object"
+                input_contract: "strict JSON only; answers must be array and fields must be object",
+                special_field_write_formats: {
+                    member_list: [{ userId: "u_123", userName: "张三" }],
+                    department_list: [{ deptId: 111, deptName: "销售部" }]
+                }
             },
             aliases: {},
             minimal_example: {
@@ -3769,7 +3788,11 @@ function buildToolSpecCatalog() {
                 write_mode: "Provide either answers[] or fields{}",
                 wait_result: "optional boolean; when true, polls qf_operation_get internally and returns resolved result directly",
                 wait_timeout_ms: "optional int (max 20000); default 5000ms",
-                input_contract: "strict JSON only; answers must be array and fields must be object"
+                input_contract: "strict JSON only; answers must be array and fields must be object",
+                special_field_write_formats: {
+                    member_list: [{ userId: "u_123", userName: "张三" }],
+                    department_list: [{ deptId: 111, deptName: "销售部" }]
+                }
             },
             aliases: {},
             minimal_example: {
@@ -7533,8 +7556,9 @@ function normalizeRecordItem(raw, includeAnswers) {
     return normalized;
 }
 function resolveAnswers(params) {
-    const normalizedFromFields = resolveFieldAnswers(params.fields, params.form, params.tool);
-    const normalizedExplicit = normalizeExplicitAnswers(params.explicitAnswers);
+    const index = params.form ? buildFieldIndex(params.form) : null;
+    const normalizedFromFields = resolveFieldAnswers(params.fields, index, params.tool);
+    const normalizedExplicit = normalizeExplicitAnswers(params.explicitAnswers, index, params.tool);
     const merged = new Map();
     for (const answer of normalizedFromFields) {
         merged.set(String(answer.queId), answer);
@@ -7547,12 +7571,12 @@ function resolveAnswers(params) {
     }
     return Array.from(merged.values());
 }
-function normalizeExplicitAnswers(answers) {
+function normalizeExplicitAnswers(answers, index, tool = "qf_record_create") {
     if (!answers?.length) {
         return [];
     }
     const output = [];
-    for (const item of answers) {
+    for (const [itemIndex, item] of answers.entries()) {
         const queId = item.que_id ?? item.queId;
         if (queId === undefined || queId === null || String(queId).trim() === "") {
             throw new Error("answer item requires que_id or queId");
@@ -7578,27 +7602,32 @@ function normalizeExplicitAnswers(answers) {
         if (values === undefined) {
             throw new Error(`answer item ${String(queId)} requires values or table_values`);
         }
-        normalized.values = values.map((value) => normalizeAnswerValue(value));
+        const field = resolveExplicitAnswerField(item, index);
+        normalized.values = values.map((value, valueIndex) => normalizeAnswerValue(value, {
+            field,
+            tool,
+            location: `answers[${itemIndex}].values[${valueIndex}]`
+        }));
         output.push(normalized);
     }
     return output;
 }
-function resolveFieldAnswers(fields, form, tool = "qf_record_create") {
+function resolveFieldAnswers(fields, index, tool = "qf_record_create") {
     const entries = Object.entries(fields ?? {});
     if (entries.length === 0) {
         return [];
     }
-    const index = buildFieldIndex(form);
+    const resolvedIndex = index ?? { byId: new Map(), byTitle: new Map() };
     const answers = [];
     for (const [fieldKey, fieldValue] of entries) {
         let field;
         if (isNumericKey(fieldKey)) {
-            field = resolveFieldByKey(fieldKey, index);
+            field = resolveFieldByKey(fieldKey, resolvedIndex);
         }
         else {
             field = resolveFieldSelectorStrict({
                 fieldKey,
-                index,
+                index: resolvedIndex,
                 tool,
                 location: `fields.${fieldKey}`
             });
@@ -7612,15 +7641,15 @@ function resolveFieldAnswers(fields, form, tool = "qf_record_create") {
                     tool,
                     location: `fields.${fieldKey}`,
                     requested: fieldKey,
-                    suggestions: buildFieldSuggestions(fieldKey, index)
+                    suggestions: buildFieldSuggestions(fieldKey, resolvedIndex)
                 }
             });
         }
-        answers.push(makeAnswerFromField(field, fieldValue));
+        answers.push(makeAnswerFromField(field, fieldValue, tool));
     }
     return answers;
 }
-function makeAnswerFromField(field, value) {
+function makeAnswerFromField(field, value, tool = "qf_record_create") {
     const base = {
         queId: field.queId
     };
@@ -7641,7 +7670,11 @@ function makeAnswerFromField(field, value) {
         if ("values" in objectValue) {
             return {
                 ...base,
-                values: asArray(objectValue.values).map((item) => normalizeAnswerValue(item))
+                values: asArray(objectValue.values).map((item, index) => normalizeAnswerValue(item, {
+                    field,
+                    tool,
+                    location: `fields.${String(field.queTitle ?? field.queId ?? "field")}.values[${index}]`
+                }))
             };
         }
     }
@@ -7654,10 +7687,38 @@ function makeAnswerFromField(field, value) {
     const valueArray = Array.isArray(value) ? value : [value];
     return {
         ...base,
-        values: valueArray.map((item) => normalizeAnswerValue(item))
+        values: valueArray.map((item, index) => normalizeAnswerValue(item, {
+            field,
+            tool,
+            location: `fields.${String(field.queTitle ?? field.queId ?? "field")}.values[${index}]`
+        }))
     };
 }
-function normalizeAnswerValue(value) {
+function resolveExplicitAnswerField(item, index) {
+    if (index) {
+        const rawQueId = item.que_id ?? item.queId;
+        if (rawQueId !== undefined && rawQueId !== null) {
+            const hit = index.byId.get(String(normalizeQueId(rawQueId)));
+            if (hit) {
+                return hit;
+            }
+        }
+        const rawQueTitle = item.que_title ?? item.queTitle;
+        if (typeof rawQueTitle === "string" && rawQueTitle.trim()) {
+            const candidates = index.byTitle.get(rawQueTitle.trim().toLowerCase()) ?? [];
+            if (candidates.length === 1) {
+                return candidates[0];
+            }
+        }
+    }
+    return {
+        queId: item.que_id ?? item.queId,
+        queTitle: item.que_title ?? item.queTitle,
+        queType: item.que_type ?? item.queType
+    };
+}
+function normalizeAnswerValue(value, params) {
+    validateWriteValueShape(params?.field ?? null, value, params);
     if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
         return {
             value,
@@ -7666,6 +7727,70 @@ function normalizeAnswerValue(value) {
     }
     return value;
 }
+function validateWriteValueShape(field, value, params) {
+    const writeFormat = field ? inferFieldWriteFormat(field) : null;
+    if (!writeFormat) {
+        return;
+    }
+    const validatedField = field;
+    if (!validatedField) {
+        return;
+    }
+    if (writeFormat.kind === "member_list" && !isValidMemberWriteValue(value)) {
+        throw fieldValueFormatError({
+            field: validatedField,
+            writeFormat,
+            value,
+            tool: params?.tool,
+            location: params?.location
+        });
+    }
+    if (writeFormat.kind === "department_list" && !isValidDepartmentWriteValue(value)) {
+        throw fieldValueFormatError({
+            field: validatedField,
+            writeFormat,
+            value,
+            tool: params?.tool,
+            location: params?.location
+        });
+    }
+}
+function isValidMemberWriteValue(value) {
+    const obj = asObject(value);
+    return Boolean(obj && asNullableString(obj.userId)?.trim());
+}
+function isValidDepartmentWriteValue(value) {
+    const obj = asObject(value);
+    if (!obj) {
+        return false;
+    }
+    const deptId = obj.deptId;
+    return ((typeof deptId === "string" && deptId.trim().length > 0) ||
+        (typeof deptId === "number" && Number.isFinite(deptId)));
+}
+function fieldValueFormatError(params) {
+    const fieldLabel = asNullableString(params.field.queTitle)?.trim() ||
+        String(params.field.queId ?? "unknown_field");
+    const formatName = params.writeFormat.kind === "member_list" ? "成员字段" : "部门字段";
+    return new InputValidationError({
+        message: `${formatName} "${fieldLabel}" 的写入值格式不正确`,
+        errorCode: "FIELD_VALUE_FORMAT_ERROR",
+        fixHint: params.writeFormat.kind === "member_list"
+            ? '传对象数组，例如 [{"userId":"u_123","userName":"张三"}]；不要传纯字符串或 user_id。'
+            : '传对象数组，例如 [{"deptId":111,"deptName":"销售部"}]；不要传纯字符串或 dept_id。',
+        details: {
+            tool: params.tool ?? "qf_record_create",
+            location: params.location ?? null,
+            field: {
+                que_id: params.field.queId ?? null,
+                que_title: asNullableString(params.field.queTitle),
+                que_type: params.field.queType ?? null
+            },
+            expected_format: params.writeFormat,
+            received_value: params.value
+        }
+    });
+}
 function needsFormResolution(fields) {
     const keys = Object.keys(fields ?? {});
     if (!keys.length) {
@@ -7697,11 +7822,95 @@ function extractFieldSummaries(form) {
             que_id: field.queId ?? null,
             que_title: asNullableString(field.queTitle),
             que_type: field.queType,
+            write_format: inferFieldWriteFormat(field),
             has_sub_fields: sub.length > 0,
             sub_field_count: sub.length
         };
     });
 }
+function inferFieldWriteFormat(field) {
+    const kind = inferFieldWriteFormatKind(field.queType);
+    if (kind === "member_list") {
+        return {
+            kind,
+            description: "Pass one or more member objects in values[]. Each item must contain userId.",
+            item_shape: {
+                userId: "string",
+                userName: "string? (recommended)",
+                name: "string? (accepted alias)"
+            },
+            example: [
+                {
+                    userId: "u_123",
+                    userName: "张三"
+                }
+            ],
+            resolution_hint: "Use qf_users_list or qf_department_users_list to resolve valid userId values before writing."
+        };
+    }
+    if (kind === "department_list") {
+        return {
+            kind,
+            description: "Pass one or more department objects in values[]. Each item must contain deptId.",
+            item_shape: {
+                deptId: "string|number",
+                deptName: "string? (recommended)",
+                name: "string? (accepted alias)"
+            },
+            example: [
+                {
+                    deptId: 111,
+                    deptName: "销售部"
+                }
+            ],
+            resolution_hint: "Use qf_departments_list to resolve valid deptId values before writing."
+        };
+    }
+    return null;
+}
+function inferFieldWriteFormatKind(queType) {
+    const tokens = collectQueTypeTokens(queType);
+    if (tokens.some((token) => MEMBER_QUE_TYPE_KEYWORDS.some((keyword) => token.includes(keyword)))) {
+        return "member_list";
+    }
+    if (tokens.some((token) => DEPARTMENT_QUE_TYPE_KEYWORDS.some((keyword) => token.includes(keyword)))) {
+        return "department_list";
+    }
+    return null;
+}
+function collectQueTypeTokens(queType) {
+    const tokens = new Set();
+    const queue = [queType];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current === null || current === undefined) {
+            continue;
+        }
+        if (typeof current === "string") {
+            const normalized = current.trim().toLowerCase();
+            if (normalized) {
+                tokens.add(normalized);
+            }
+            continue;
+        }
+        if (typeof current === "number" || typeof current === "boolean") {
+            tokens.add(String(current));
+            continue;
+        }
+        if (Array.isArray(current)) {
+            queue.push(...current);
+            continue;
+        }
+        const obj = asObject(current);
+        if (!obj) {
+            continue;
+        }
+        for (const value of Object.values(obj)) {
+            queue.push(value);
+        }
+    }
+    return Array.from(tokens);
+}
 function buildFieldIndex(form) {
     const byId = new Map();
     const byTitle = new Map();
@@ -8442,6 +8651,48 @@ function buildErrorExampleCalls(params) {
             }
         ];
     }
+    if (errorCode === "FIELD_VALUE_FORMAT_ERROR") {
+        const expectedFormat = asObject(params.details?.expected_format);
+        const kind = asNullableString(expectedFormat?.kind);
+        if (kind === "member_list") {
+            return [
+                {
+                    tool: "qf_form_get",
+                    arguments: {
+                        app_key: appKey
+                    },
+                    note: "先查看字段 write_format，确认成员字段写入 shape"
+                },
+                {
+                    tool: "qf_department_users_list",
+                    arguments: {
+                        dept_id: 111,
+                        fetch_child: false
+                    },
+                    note: "查询有效成员 userId，再按 [{userId,userName}] 写入"
+                }
+            ];
+        }
+        if (kind === "department_list") {
+            return [
+                {
+                    tool: "qf_form_get",
+                    arguments: {
+                        app_key: appKey
+                    },
+                    note: "先查看字段 write_format，确认部门字段写入 shape"
+                },
+                {
+                    tool: "qf_departments_list",
+                    arguments: {
+                        keyword: "销售",
+                        limit: 20
+                    },
+                    note: "查询有效部门 deptId，再按 [{deptId,deptName}] 写入"
+                }
+            ];
+        }
+    }
     if (errorCode === "INTERNAL_ERROR" || errorCode === "UNKNOWN_ERROR") {
         return [
             {

package/package.json

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