qingflow-mcp 0.3.16 → 0.3.18

package/README.md

@@ -3,6 +3,10 @@
 This MCP server wraps Qingflow OpenAPI for:
 
 - `qf_apps_list`
+- `qf_departments_list`
+- `qf_department_users_list`
+- `qf_users_list`
+- `qf_user_get`
 - `qf_form_get`
 - `qf_field_resolve`
 - `qf_query_plan`
@@ -108,7 +112,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.14
+npm i -g qingflow-mcp@0.3.18
 ```
 
 Or one-click installer:
@@ -148,6 +152,13 @@ MCP client config example:
 3. `qf_record_create` or `qf_record_update`.
 4. If create/update returns only `request_id`, call `qf_operation_get` to resolve async result.
 
+Directory / org flow:
+
+1. `qf_departments_list` to inspect department tree.
+2. `qf_department_users_list` to inspect one department's members.
+3. `qf_users_list` for workspace-wide pagination.
+4. `qf_user_get` for one exact user.
+
 Full calling contract (Chinese):
 
 - [MCP 调用规范](./docs/MCP_CALLING_SPEC.md)
@@ -165,14 +176,45 @@ Full calling contract (Chinese):
 4. In `list` mode, `select_columns` is required.
 5. In `list` mode, row cap defaults to 200 when `max_rows` and `max_items` are omitted.
 6. In `record` mode, `select_columns` is required.
-7. In `summary` mode, `select_columns` is required (`max_rows` defaults to 200 when omitted).
+7. In `summary` mode, `select_columns` is optional and can be auto-derived from `amount_column` / `time_range` (`max_rows` defaults to 200 when omitted).
 
 Summary mode output:
 
 1. `summary`: aggregated stats (`total_count`, `total_amount`, `by_day`, `missing_count`).
-2. `rows`: strict column rows (only requested `select_columns`).
+2. `rows`: strict column rows (requested `select_columns`, or auto-derived preview columns when omitted).
 3. `meta`: field mapping, filter scope, stat policy, execution limits (`output_profile=verbose` only).
 
+## Directory / Org Tools
+
+These tools expose department and member APIs without routing through `qf_query`:
+
+1. `qf_departments_list`
+   - optional `dept_id`
+   - local `keyword`, `limit`, `offset`
+   - aliases: `deptId`, `department_id`, `departmentId`
+2. `qf_department_users_list`
+   - required `dept_id`, `fetch_child`
+   - local `keyword`, `limit`, `offset`
+   - aliases: `deptId`, `department_id`, `departmentId`, `fetchChild`
+3. `qf_users_list`
+   - required `page_num`, `page_size`
+   - aliases: `pageNum`, `pageSize`
+4. `qf_user_get`
+   - required `user_id`
+   - alias: `userId`
+
+CLI examples:
+
+```bash
+qingflow-mcp cli call qf_departments_list --args '{"keyword":"销售","limit":20}'
+
+qingflow-mcp cli call qf_department_users_list --args '{"deptId":111,"fetchChild":true}'
+
+qingflow-mcp cli call qf_users_list --args '{"pageNum":1,"pageSize":100}'
+
+qingflow-mcp cli call qf_user_get --args '{"userId":"u_123"}'
+```
+
 Return shape:
 
 1. success: structured payload `{ "ok": true, "data": ... }` (`meta` only in `output_profile=verbose`)

package/dist/qingflow-client.js

@@ -33,6 +33,48 @@ export class QingflowClient {
             }
         });
     }
+    listDepartments(options = {}) {
+        return this.request({
+            method: "GET",
+            path: "/department",
+            options: {
+                query: {
+                    deptId: options.deptId !== undefined && options.deptId !== null
+                        ? String(options.deptId)
+                        : undefined
+                }
+            }
+        });
+    }
+    listDepartmentUsers(deptId, options) {
+        return this.request({
+            method: "GET",
+            path: `/department/${encodeURIComponent(deptId)}/user`,
+            options: {
+                query: {
+                    fetchChild: options.fetchChild
+                }
+            }
+        });
+    }
+    listUsers(options) {
+        return this.request({
+            method: "GET",
+            path: "/user",
+            options: {
+                query: {
+                    pageNum: options.pageNum,
+                    pageSize: options.pageSize
+                }
+            }
+        });
+    }
+    getUser(userId) {
+        return this.request({
+            method: "GET",
+            path: `/user/${encodeURIComponent(userId)}`
+        });
+    }
     getForm(appKey, options = {}) {
         return this.request({
             method: "GET",

package/dist/server.js

@@ -65,7 +65,7 @@ const REQUEST_TIMEOUT_MS = toPositiveInt(process.env.QINGFLOW_REQUEST_TIMEOUT_MS
 const EXECUTION_BUDGET_MS = toPositiveInt(process.env.QINGFLOW_EXECUTION_BUDGET_MS) ?? 20000;
 const WAIT_RESULT_DEFAULT_TIMEOUT_MS = toPositiveInt(process.env.QINGFLOW_WAIT_RESULT_TIMEOUT_MS) ?? 5000;
 const WAIT_RESULT_POLL_INTERVAL_MS = toPositiveInt(process.env.QINGFLOW_WAIT_RESULT_POLL_INTERVAL_MS) ?? 500;
-const SERVER_VERSION = "0.3.16";
+const SERVER_VERSION = "0.3.18";
 const accessToken = process.env.QINGFLOW_ACCESS_TOKEN;
 const baseUrl = process.env.QINGFLOW_BASE_URL;
 if (!accessToken) {
@@ -215,6 +215,125 @@ const appsSuccessOutputSchema = z.object({
     meta: apiMetaSchema
 });
 const appsOutputSchema = appsSuccessOutputSchema;
+const publicDirectorySelectorSchema = z.union([z.string().min(1), z.number().int()]);
+const departmentOutputSchema = z.object({
+    dept_id: z.number().int().nullable(),
+    name: z.string().nullable(),
+    parent_id: z.number().int().nullable(),
+    ordinal: z.number().int().nullable(),
+    dept_leader_ids: z.array(z.string())
+});
+const directoryUserSchema = z.object({
+    user_id: z.string().nullable(),
+    name: z.string().nullable(),
+    area_code: z.string().nullable(),
+    mobile_num: z.string().nullable(),
+    email: z.string().nullable(),
+    head_img: z.string().nullable(),
+    department_ids: z.array(z.string()),
+    role_ids: z.array(z.string()),
+    custom_role_ids: z.array(z.string()),
+    custom_department_ids: z.array(z.string()),
+    being_disabled: z.boolean().nullable(),
+    being_active: z.boolean().nullable(),
+    superior_id: z.string().nullable()
+});
+const departmentListInputPublicSchema = z.object({
+    dept_id: publicDirectorySelectorSchema.optional(),
+    deptId: publicDirectorySelectorSchema.optional(),
+    department_id: publicDirectorySelectorSchema.optional(),
+    departmentId: publicDirectorySelectorSchema.optional(),
+    keyword: z.string().min(1).optional(),
+    limit: z.number().int().positive().max(500).optional(),
+    offset: z.number().int().nonnegative().optional()
+});
+const departmentListInputSchema = z.preprocess(normalizeDepartmentListInput, z.object({
+    dept_id: z.union([z.string().min(1), z.number().int()]).optional(),
+    keyword: z.string().min(1).optional(),
+    limit: z.number().int().positive().max(500).optional(),
+    offset: z.number().int().nonnegative().optional()
+}));
+const departmentListOutputSchema = z.object({
+    ok: z.literal(true),
+    data: z.object({
+        total_departments: z.number().int().nonnegative(),
+        returned_departments: z.number().int().nonnegative(),
+        limit: z.number().int().positive(),
+        offset: z.number().int().nonnegative(),
+        dept_id_filter: z.union([z.string(), z.number(), z.null()]),
+        departments: z.array(departmentOutputSchema)
+    }),
+    meta: apiMetaSchema
+});
+const departmentUsersInputPublicSchema = z.object({
+    dept_id: publicDirectorySelectorSchema.optional(),
+    deptId: publicDirectorySelectorSchema.optional(),
+    department_id: publicDirectorySelectorSchema.optional(),
+    departmentId: publicDirectorySelectorSchema.optional(),
+    fetch_child: z.boolean().optional(),
+    fetchChild: z.boolean().optional(),
+    keyword: z.string().min(1).optional(),
+    limit: z.number().int().positive().max(500).optional(),
+    offset: z.number().int().nonnegative().optional()
+});
+const departmentUsersInputSchema = z.preprocess(normalizeDepartmentUsersInput, z.object({
+    dept_id: z.union([z.string().min(1), z.number().int()]).optional(),
+    fetch_child: z.boolean().optional(),
+    keyword: z.string().min(1).optional(),
+    limit: z.number().int().positive().max(500).optional(),
+    offset: z.number().int().nonnegative().optional()
+}));
+const departmentUsersOutputSchema = z.object({
+    ok: z.literal(true),
+    data: z.object({
+        dept_id: z.string(),
+        fetch_child: z.boolean(),
+        leader_ids: z.array(z.string()),
+        total_users: z.number().int().nonnegative(),
+        returned_users: z.number().int().nonnegative(),
+        limit: z.number().int().positive(),
+        offset: z.number().int().nonnegative(),
+        users: z.array(directoryUserSchema)
+    }),
+    meta: apiMetaSchema
+});
+const usersListInputPublicSchema = z.object({
+    page_num: z.number().int().positive().optional(),
+    pageNum: z.number().int().positive().optional(),
+    page_size: z.number().int().positive().optional(),
+    pageSize: z.number().int().positive().optional()
+});
+const usersListInputSchema = z.preprocess(normalizeUsersListInput, z.object({
+    page_num: z.number().int().positive().optional(),
+    page_size: z.number().int().positive().optional()
+}));
+const usersListOutputSchema = z.object({
+    ok: z.literal(true),
+    data: z.object({
+        pagination: z.object({
+            page_num: z.number().int().positive(),
+            page_size: z.number().int().positive(),
+            page_amount: z.number().int().nonnegative(),
+            result_amount: z.number().int().nonnegative()
+        }),
+        users: z.array(directoryUserSchema)
+    }),
+    meta: apiMetaSchema
+});
+const userGetInputPublicSchema = z.object({
+    user_id: z.string().min(1).optional(),
+    userId: z.string().min(1).optional()
+});
+const userGetInputSchema = z.preprocess(normalizeUserGetInput, z.object({
+    user_id: z.string().min(1).optional()
+}));
+const userGetOutputSchema = z.object({
+    ok: z.literal(true),
+    data: z.object({
+        user: directoryUserSchema
+    }),
+    meta: apiMetaSchema
+});
 const formInputSchema = z.object({
     app_key: z.string().min(1),
     user_id: z.string().min(1).optional(),
@@ -517,12 +636,23 @@ const createInputSchema = z
 const createSuccessOutputSchema = z.object({
     ok: z.literal(true),
     data: z.object({
+        status: z.enum(["completed", "pending", "timeout", "failed"]),
         request_id: z.string().nullable(),
         apply_id: z.union([z.string(), z.number(), z.null()]),
-        resolved: z.boolean().optional(),
-        timed_out: z.boolean().optional(),
-        operation_result: z.unknown().optional(),
-        async_hint: z.string()
+        resource: z
+            .object({
+            type: z.literal("record"),
+            apply_id: z.union([z.string(), z.number()])
+        })
+            .nullable(),
+        next_action: z
+            .object({
+            tool: z.string(),
+            arguments: z.record(z.unknown()),
+            reason: z.string().optional()
+        })
+            .nullable(),
+        raw: z.object({ operation_result: z.unknown() }).nullable()
     }),
     meta: apiMetaSchema
 });
@@ -555,12 +685,23 @@ const updateInputSchema = z
 const updateSuccessOutputSchema = z.object({
     ok: z.literal(true),
     data: z.object({
+        status: z.enum(["completed", "pending", "timeout", "failed"]),
         request_id: z.string().nullable(),
-        apply_id: z.union([z.string(), z.number(), z.null()]).optional(),
-        resolved: z.boolean().optional(),
-        timed_out: z.boolean().optional(),
-        operation_result: z.unknown().optional(),
-        async_hint: z.string()
+        apply_id: z.union([z.string(), z.number(), z.null()]),
+        resource: z
+            .object({
+            type: z.literal("record"),
+            apply_id: z.union([z.string(), z.number()])
+        })
+            .nullable(),
+        next_action: z
+            .object({
+            tool: z.string(),
+            arguments: z.record(z.unknown()),
+            reason: z.string().optional()
+        })
+            .nullable(),
+        raw: z.object({ operation_result: z.unknown() }).nullable()
     }),
     meta: apiMetaSchema
 });
@@ -1277,6 +1418,219 @@ server.registerTool("qf_apps_list", {
         return errorResult(error);
     }
 });
+server.registerTool("qf_departments_list", {
+    title: "Qingflow Departments List",
+    description: "List departments with optional dept_id filter and local keyword slicing.",
+    inputSchema: departmentListInputPublicSchema,
+    outputSchema: departmentListOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true
+    }
+}, async (args) => {
+    try {
+        const parsedArgs = departmentListInputSchema.parse(args);
+        let response;
+        try {
+            response = await client.listDepartments(parsedArgs.dept_id !== undefined ? { deptId: parsedArgs.dept_id } : {});
+        }
+        catch (error) {
+            if (parsedArgs.dept_id !== undefined) {
+                throw translateDirectoryApiError(error, {
+                    tool: "qf_departments_list",
+                    entity: "department",
+                    deptId: parsedArgs.dept_id
+                });
+            }
+            throw error;
+        }
+        const keyword = parsedArgs.keyword?.trim().toLowerCase() ?? null;
+        const limit = parsedArgs.limit ?? 50;
+        const offset = parsedArgs.offset ?? 0;
+        const departments = asArray(asObject(response.result)?.department).map((item) => normalizeDepartment(item));
+        const filtered = keyword
+            ? departments.filter((item) => (item.name ?? "").toLowerCase().includes(keyword) ||
+                String(item.dept_id ?? "").toLowerCase().includes(keyword))
+            : departments;
+        const sliced = filtered.slice(offset, offset + limit);
+        return okResult({
+            ok: true,
+            data: {
+                total_departments: filtered.length,
+                returned_departments: sliced.length,
+                limit,
+                offset,
+                dept_id_filter: parsedArgs.dept_id ?? null,
+                departments: sliced
+            },
+            meta: buildMeta(response)
+        }, `Returned ${sliced.length}/${filtered.length} departments`);
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+});
+server.registerTool("qf_department_users_list", {
+    title: "Qingflow Department Users List",
+    description: "List department members with optional child recursion and local keyword slicing.",
+    inputSchema: departmentUsersInputPublicSchema,
+    outputSchema: departmentUsersOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true
+    }
+}, async (args) => {
+    try {
+        const parsedArgs = departmentUsersInputSchema.parse(args);
+        if (parsedArgs.dept_id === undefined) {
+            throw missingRequiredFieldError({
+                field: "dept_id",
+                tool: "qf_department_users_list",
+                fixHint: "Provide dept_id (or deptId), for example: {\"dept_id\":111,\"fetch_child\":false}."
+            });
+        }
+        if (parsedArgs.fetch_child === undefined) {
+            throw missingRequiredFieldError({
+                field: "fetch_child",
+                tool: "qf_department_users_list",
+                fixHint: "Provide fetch_child as a native JSON boolean, for example: {\"dept_id\":111,\"fetch_child\":true}."
+            });
+        }
+        let response;
+        try {
+            response = await client.listDepartmentUsers(String(parsedArgs.dept_id), {
+                fetchChild: parsedArgs.fetch_child
+            });
+        }
+        catch (error) {
+            throw translateDirectoryApiError(error, {
+                tool: "qf_department_users_list",
+                entity: "department",
+                deptId: parsedArgs.dept_id
+            });
+        }
+        const keyword = parsedArgs.keyword?.trim().toLowerCase() ?? null;
+        const limit = parsedArgs.limit ?? 200;
+        const offset = parsedArgs.offset ?? 0;
+        const result = asObject(response.result);
+        const users = asArray(result?.userList).map((item) => normalizeUser(item));
+        const filtered = keyword
+            ? users.filter((item) => [item.user_id, item.name, item.email, item.mobile_num]
+                .map((value) => (value ?? "").toLowerCase())
+                .some((value) => value.includes(keyword)))
+            : users;
+        const sliced = filtered.slice(offset, offset + limit);
+        return okResult({
+            ok: true,
+            data: {
+                dept_id: String(parsedArgs.dept_id),
+                fetch_child: parsedArgs.fetch_child,
+                leader_ids: normalizeStringArray(result?.leaderIds),
+                total_users: filtered.length,
+                returned_users: sliced.length,
+                limit,
+                offset,
+                users: sliced
+            },
+            meta: buildMeta(response)
+        }, `Returned ${sliced.length}/${filtered.length} department users`);
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+});
+server.registerTool("qf_users_list", {
+    title: "Qingflow Users List",
+    description: "List workspace users with explicit pagination.",
+    inputSchema: usersListInputPublicSchema,
+    outputSchema: usersListOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true
+    }
+}, async (args) => {
+    try {
+        const parsedArgs = usersListInputSchema.parse(args);
+        if (parsedArgs.page_num === undefined) {
+            throw missingRequiredFieldError({
+                field: "page_num",
+                tool: "qf_users_list",
+                fixHint: "Provide page_num (or pageNum), for example: {\"page_num\":1,\"page_size\":100}."
+            });
+        }
+        if (parsedArgs.page_size === undefined) {
+            throw missingRequiredFieldError({
+                field: "page_size",
+                tool: "qf_users_list",
+                fixHint: "Provide page_size (or pageSize), for example: {\"page_num\":1,\"page_size\":100}."
+            });
+        }
+        const response = await client.listUsers({
+            pageNum: parsedArgs.page_num,
+            pageSize: parsedArgs.page_size
+        });
+        const result = asObject(response.result);
+        const users = asArray(result?.result).map((item) => normalizeUser(item));
+        return okResult({
+            ok: true,
+            data: {
+                pagination: {
+                    page_num: toPositiveInt(result?.pageNum) ?? parsedArgs.page_num,
+                    page_size: toPositiveInt(result?.pageSize) ?? parsedArgs.page_size,
+                    page_amount: toNonNegativeInt(result?.pageAmount) ?? 0,
+                    result_amount: toNonNegativeInt(result?.resultAmount) ?? users.length
+                },
+                users
+            },
+            meta: buildMeta(response)
+        }, `Returned ${users.length} users`);
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+});
+server.registerTool("qf_user_get", {
+    title: "Qingflow User Get",
+    description: "Get one workspace user by user_id.",
+    inputSchema: userGetInputPublicSchema,
+    outputSchema: userGetOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true
+    }
+}, async (args) => {
+    try {
+        const parsedArgs = userGetInputSchema.parse(args);
+        if (!parsedArgs.user_id) {
+            throw missingRequiredFieldError({
+                field: "user_id",
+                tool: "qf_user_get",
+                fixHint: "Provide user_id (or userId), for example: {\"user_id\":\"u_123\"}."
+            });
+        }
+        let response;
+        try {
+            response = await client.getUser(parsedArgs.user_id);
+        }
+        catch (error) {
+            throw translateDirectoryApiError(error, {
+                tool: "qf_user_get",
+                entity: "user",
+                userId: parsedArgs.user_id
+            });
+        }
+        return okResult({
+            ok: true,
+            data: {
+                user: normalizeUser(response.result)
+            },
+            meta: buildMeta(response)
+        }, `Fetched user ${parsedArgs.user_id}`);
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+});
 server.registerTool("qf_form_get", {
     title: "Qingflow Form Get",
     description: "Get form metadata and compact field summaries for one app.",
@@ -1578,30 +1932,36 @@ server.registerTool("qf_record_create", {
         const immediateApplyId = result?.applyId ?? null;
         const shouldWaitForResult = (parsedArgs.wait_result ?? false) && requestId !== null && immediateApplyId === null;
         let finalApplyId = immediateApplyId;
-        let isResolved = immediateApplyId !== null;
-        let isTimedOut = false;
-        let operationResult = null;
+        let waitStatus = immediateApplyId !== null ? "completed" : "pending";
+        let rawOperationResult = null;
         if (shouldWaitForResult) {
             const waited = await waitForOperationResolution({
                 requestId: requestId,
                 timeoutMs: parsedArgs.wait_timeout_ms ?? WAIT_RESULT_DEFAULT_TIMEOUT_MS
             });
-            isResolved = waited.resolved;
-            isTimedOut = waited.timedOut;
-            operationResult = waited.operationResult;
+            waitStatus = waited.status;
+            rawOperationResult = waited.operationResult;
             finalApplyId = waited.applyId;
         }
+        const createResource = finalApplyId !== null ? { type: "record", apply_id: finalApplyId } : null;
+        const createNextAction = waitStatus === "pending" || waitStatus === "timeout"
+            ? {
+                tool: "qf_operation_get",
+                arguments: { request_id: requestId },
+                reason: waitStatus === "timeout"
+                    ? "Operation timed out; poll again to check completion."
+                    : "Operation is async; poll to check completion."
+            }
+            : null;
         return okResult({
             ok: true,
             data: {
+                status: waitStatus,
                 request_id: requestId,
                 apply_id: finalApplyId,
-                resolved: isResolved,
-                ...(isTimedOut ? { timed_out: true } : {}),
-                ...(operationResult !== null ? { operation_result: operationResult } : {}),
-                async_hint: isResolved
-                    ? "Record created and resolved."
-                    : "Use qf_operation_get with request_id to fetch the result."
+                resource: createResource,
+                next_action: createNextAction,
+                raw: rawOperationResult !== null ? { operation_result: rawOperationResult } : null
             },
             meta: buildMeta(response)
         }, `Create request sent for app ${parsedArgs.app_key}`);
@@ -1624,7 +1984,11 @@ server.registerTool("qf_record_update", {
         const parsedArgs = updateInputSchema.parse(args);
         const requiresForm = needsFormResolution(parsedArgs.fields);
         if (requiresForm && !parsedArgs.app_key) {
-            throw new Error("app_key is required when fields uses title-based keys");
+            throw missingRequiredFieldError({
+                field: "app_key",
+                tool: "qf_record_update",
+                fixHint: "Provide app_key when fields uses title-based keys, or switch fields to numeric que_id."
+            });
         }
         const form = requiresForm && parsedArgs.app_key
             ? await getFormCached(parsedArgs.app_key, parsedArgs.user_id, Boolean(parsedArgs.force_refresh_form))
@@ -1639,31 +2003,45 @@ server.registerTool("qf_record_update", {
         const result = asObject(response.result);
         const updateRequestId = asNullableString(result?.requestId);
         const shouldWaitForUpdate = (parsedArgs.wait_result ?? false) && updateRequestId !== null;
-        let updateIsResolved = false;
-        let updateIsTimedOut = false;
-        let updateOperationResult = null;
-        let updateApplyId = null;
+        let updateStatus = "pending";
+        let updateRawOperationResult = null;
+        let updateApplyId = parsedArgs.apply_id;
         if (shouldWaitForUpdate) {
             const waited = await waitForOperationResolution({
                 requestId: updateRequestId,
                 timeoutMs: parsedArgs.wait_timeout_ms ?? WAIT_RESULT_DEFAULT_TIMEOUT_MS
             });
-            updateIsResolved = waited.resolved;
-            updateIsTimedOut = waited.timedOut;
-            updateOperationResult = waited.operationResult;
-            updateApplyId = waited.applyId;
+            updateStatus = waited.status;
+            updateRawOperationResult = waited.operationResult;
+            // For updates, the apply_id is already known from input; keep it unless operation returned a different one
+            if (waited.applyId !== null) {
+                updateApplyId = waited.applyId;
+            }
+        }
+        else if (updateRequestId === null) {
+            // No async operation — synchronous completion
+            updateStatus = "completed";
         }
+        // else: wait_result=false but has requestId — submitted, not polled, stays "pending"
+        const updateResource = updateApplyId !== null ? { type: "record", apply_id: updateApplyId } : null;
+        const updateNextAction = updateStatus === "pending" || updateStatus === "timeout"
+            ? {
+                tool: "qf_operation_get",
+                arguments: { request_id: updateRequestId },
+                reason: updateStatus === "timeout"
+                    ? "Operation timed out; poll again to check completion."
+                    : "Operation is async; poll to check completion."
+            }
+            : null;
         return okResult({
             ok: true,
             data: {
+                status: updateStatus,
                 request_id: updateRequestId,
-                ...(updateApplyId !== null ? { apply_id: updateApplyId } : {}),
-                resolved: updateIsResolved,
-                ...(updateIsTimedOut ? { timed_out: true } : {}),
-                ...(updateOperationResult !== null ? { operation_result: updateOperationResult } : {}),
-                async_hint: updateIsResolved
-                    ? "Record updated and resolved."
-                    : "Use qf_operation_get with request_id to fetch the update result."
+                apply_id: updateApplyId,
+                resource: updateResource,
+                next_action: updateNextAction,
+                raw: updateRawOperationResult !== null ? { operation_result: updateRawOperationResult } : null
             },
             meta: buildMeta(response)
         }, `Update request sent for apply ${String(parsedArgs.apply_id)}`);
@@ -1980,6 +2358,65 @@ function buildMeta(response) {
         base_url: baseUrl
     };
 }
+function normalizeStringArray(value) {
+    return uniqueStringList(asArray(value)
+        .map((item) => asNullableString(item)?.trim() ?? "")
+        .filter((item) => item.length > 0));
+}
+function normalizeDepartment(raw) {
+    const obj = asObject(raw) ?? {};
+    return {
+        dept_id: toNonNegativeInt(obj.deptId),
+        name: asNullableString(obj.name),
+        parent_id: toNonNegativeInt(obj.parentId),
+        ordinal: toNonNegativeInt(obj.ordinal),
+        dept_leader_ids: normalizeStringArray(obj.deptLeader)
+    };
+}
+function normalizeUser(raw) {
+    const obj = asObject(raw) ?? {};
+    return {
+        user_id: asNullableString(obj.userId),
+        name: asNullableString(obj.name),
+        area_code: asNullableString(obj.areaCode),
+        mobile_num: asNullableString(obj.mobileNum),
+        email: asNullableString(obj.email),
+        head_img: asNullableString(obj.headImg),
+        department_ids: normalizeStringArray(obj.department),
+        role_ids: normalizeStringArray(obj.role),
+        custom_role_ids: normalizeStringArray(obj.customRole),
+        custom_department_ids: normalizeStringArray(obj.customDepartment),
+        being_disabled: typeof obj.beingDisabled === "boolean" ? obj.beingDisabled : null,
+        being_active: typeof obj.beingActive === "boolean" ? obj.beingActive : null,
+        superior_id: asNullableString(obj.superiorId)
+    };
+}
+function translateDirectoryApiError(error, params) {
+    if (error instanceof QingflowApiError &&
+        (error.httpStatus === 404 || error.errCode === 404)) {
+        if (params.entity === "department") {
+            return new InputValidationError({
+                message: `Department \"${String(params.deptId)}\" not found`,
+                errorCode: "DEPARTMENT_NOT_FOUND",
+                fixHint: "Call qf_departments_list first to confirm the exact dept_id.",
+                details: {
+                    tool: params.tool,
+                    dept_id: params.deptId
+                }
+            });
+        }
+        return new InputValidationError({
+            message: `User \"${params.userId}\" not found`,
+            errorCode: "USER_NOT_FOUND",
+            fixHint: "Call qf_users_list or qf_department_users_list first to obtain a valid user_id.",
+            details: {
+                tool: params.tool,
+                user_id: params.userId
+            }
+        });
+    }
+    return error instanceof Error ? error : new Error(String(error));
+}
 function resolveOutputProfile(value) {
     return value === "verbose" ? "verbose" : DEFAULT_OUTPUT_PROFILE;
 }
@@ -2075,6 +2512,76 @@ function normalizeToolSpecInput(raw) {
         include_all: coerceBooleanLike(normalizedObj.include_all)
     };
 }
+function normalizeDepartmentListInput(raw) {
+    const parsedRoot = parseJsonLikeDeep(raw);
+    const obj = asObject(parsedRoot);
+    if (!obj) {
+        return parsedRoot;
+    }
+    const normalizedObj = applyAliases(obj, {
+        deptId: "dept_id",
+        department_id: "dept_id",
+        departmentId: "dept_id"
+    });
+    return {
+        ...normalizedObj,
+        dept_id: coerceNumberLike(normalizeSelectorInputValue(normalizedObj.dept_id)),
+        keyword: coerceStringLike(normalizedObj.keyword),
+        limit: coerceNumberLike(normalizedObj.limit),
+        offset: coerceNumberLike(normalizedObj.offset)
+    };
+}
+function normalizeDepartmentUsersInput(raw) {
+    const parsedRoot = parseJsonLikeDeep(raw);
+    const obj = asObject(parsedRoot);
+    if (!obj) {
+        return parsedRoot;
+    }
+    const normalizedObj = applyAliases(obj, {
+        deptId: "dept_id",
+        department_id: "dept_id",
+        departmentId: "dept_id",
+        fetchChild: "fetch_child"
+    });
+    return {
+        ...normalizedObj,
+        dept_id: coerceNumberLike(normalizeSelectorInputValue(normalizedObj.dept_id)),
+        fetch_child: coerceBooleanLike(normalizedObj.fetch_child),
+        keyword: coerceStringLike(normalizedObj.keyword),
+        limit: coerceNumberLike(normalizedObj.limit),
+        offset: coerceNumberLike(normalizedObj.offset)
+    };
+}
+function normalizeUsersListInput(raw) {
+    const parsedRoot = parseJsonLikeDeep(raw);
+    const obj = asObject(parsedRoot);
+    if (!obj) {
+        return parsedRoot;
+    }
+    const normalizedObj = applyAliases(obj, {
+        pageNum: "page_num",
+        pageSize: "page_size"
+    });
+    return {
+        ...normalizedObj,
+        page_num: coerceNumberLike(normalizedObj.page_num),
+        page_size: coerceNumberLike(normalizedObj.page_size)
+    };
+}
+function normalizeUserGetInput(raw) {
+    const parsedRoot = parseJsonLikeDeep(raw);
+    const obj = asObject(parsedRoot);
+    if (!obj) {
+        return parsedRoot;
+    }
+    const normalizedObj = applyAliases(obj, {
+        userId: "user_id"
+    });
+    return {
+        ...normalizedObj,
+        user_id: coerceStringLike(normalizedObj.user_id)
+    };
+}
 function buildToolSpecCatalog() {
     return [
         {
@@ -2104,6 +2611,63 @@ function buildToolSpecCatalog() {
                 limit: 20
             }
         },
+        {
+            tool: "qf_departments_list",
+            required: [],
+            limits: {
+                limit_max: 500,
+                offset_min: 0,
+                input_contract: "strict JSON only; dept_id must be a native JSON string or number when provided"
+            },
+            aliases: collectAliasHints(["dept_id"], {
+                dept_id: ["deptId", "department_id", "departmentId"]
+            }),
+            minimal_example: {
+                dept_id: 111,
+                limit: 20
+            }
+        },
+        {
+            tool: "qf_department_users_list",
+            required: ["dept_id", "fetch_child"],
+            limits: {
+                limit_max: 500,
+                offset_min: 0,
+                input_contract: "strict JSON only; fetch_child must be a native JSON boolean"
+            },
+            aliases: collectAliasHints(["dept_id", "fetch_child"], {
+                dept_id: ["deptId", "department_id", "departmentId"],
+                fetch_child: ["fetchChild"]
+            }),
+            minimal_example: {
+                dept_id: 111,
+                fetch_child: true,
+                limit: 50
+            }
+        },
+        {
+            tool: "qf_users_list",
+            required: ["page_num", "page_size"],
+            limits: {
+                input_contract: "strict JSON only; page_num/page_size must be native JSON numbers"
+            },
+            aliases: collectAliasHints(["page_num", "page_size"], {}),
+            minimal_example: {
+                page_num: 1,
+                page_size: 100
+            }
+        },
+        {
+            tool: "qf_user_get",
+            required: ["user_id"],
+            limits: {
+                input_contract: "strict JSON only; user_id must be a native JSON string"
+            },
+            aliases: collectAliasHints(["user_id"], {}),
+            minimal_example: {
+                user_id: "u_123"
+            }
+        },
         {
             tool: "qf_form_get",
             required: ["app_key"],
@@ -3362,7 +3926,7 @@ function inferPlanMissingRequired(tool, args) {
                 missing.push("select_columns");
             }
         }
-        else {
+        else if (queryMode === "list") {
             if (!hasAppKey) {
                 missing.push("app_key");
             }
@@ -3370,6 +3934,9 @@ function inferPlanMissingRequired(tool, args) {
                 missing.push("select_columns");
             }
         }
+        else if (!hasAppKey) {
+            missing.push("app_key");
+        }
     }
     return missing;
 }
@@ -4516,12 +5083,12 @@ async function executeRecordsExport(format, args) {
         app_key: args.app_key,
         selected_columns: selectedColumnsForRows,
         filters: echoFilters(effectiveFilters),
-        time_range: args.time_range
+        time_range: timeRangeResolution.mapping
             ? {
-                column: String(args.time_range.column),
-                from: args.time_range.from ?? null,
-                to: args.time_range.to ?? null,
-                timezone: args.time_range.timezone ?? null
+                column: String(args.time_range?.column ?? timeRangeResolution.mapping.requested ?? ""),
+                from: timeRangeResolution.time_range?.from ?? null,
+                to: timeRangeResolution.time_range?.to ?? null,
+                timezone: timeRangeResolution.time_range?.timezone ?? null
             }
             : null
     }, sourcePages);
@@ -4547,7 +5114,6 @@ async function executeRecordsExport(format, args) {
                 ? {
                     completeness,
                     evidence,
-                    resolved_mappings: resolvedMappings,
                     execution: {
                         scanned_pages: fetchedPages,
                         requested_pages: requestedPages,
@@ -4562,6 +5128,7 @@ async function executeRecordsExport(format, args) {
             ? {
                 completeness,
                 evidence,
+                resolved_mappings: resolvedMappings,
                 error_code: null,
                 fix_hint: null
             }
@@ -6441,6 +7008,13 @@ function isPendingOperationStatus(status) {
     return ["PENDING", "PROCESSING", "RUNNING", "IN_PROGRESS", "QUEUED"].includes(status);
 }
 function extractOperationApplyId(operationResult) {
+    // Handle case where operationResult itself is a numeric string or number (the apply_id directly)
+    if (typeof operationResult === "string" && /^\d+$/.test(operationResult.trim())) {
+        return operationResult.trim();
+    }
+    if (typeof operationResult === "number" && Number.isFinite(operationResult)) {
+        return operationResult;
+    }
     const obj = asObject(operationResult);
     return obj?.applyId ?? obj?.apply_id ?? null;
 }
@@ -6450,15 +7024,14 @@ async function waitForOperationResolution(params) {
     while (Date.now() <= deadline) {
         const response = await client.getOperation(params.requestId);
         lastResult = response.result;
-        const status = extractOperationStatus(lastResult);
+        const opStatus = extractOperationStatus(lastResult);
         const applyId = extractOperationApplyId(lastResult);
-        if ((status && !isPendingOperationStatus(status)) || applyId !== null) {
-            return {
-                resolved: true,
-                timedOut: false,
-                operationResult: lastResult,
-                applyId
-            };
+        if (applyId !== null) {
+            return { status: "completed", operationResult: lastResult, applyId };
+        }
+        if (opStatus && !isPendingOperationStatus(opStatus)) {
+            // Non-pending status but no apply_id — treat as failed
+            return { status: "failed", operationResult: lastResult, applyId: null };
         }
         const remaining = deadline - Date.now();
         if (remaining <= 0) {
@@ -6466,12 +7039,12 @@ async function waitForOperationResolution(params) {
         }
         await delay(Math.min(WAIT_RESULT_POLL_INTERVAL_MS, remaining));
     }
-    return {
-        resolved: false,
-        timedOut: true,
-        operationResult: lastResult,
-        applyId: extractOperationApplyId(lastResult)
-    };
+    // Timed out — check if last result has apply_id anyway (edge case)
+    const finalApplyId = extractOperationApplyId(lastResult);
+    if (finalApplyId !== null) {
+        return { status: "completed", operationResult: lastResult, applyId: finalApplyId };
+    }
+    return { status: "timeout", operationResult: lastResult, applyId: null };
 }
 function resolveListItemLimit(params) {
     if (params.total <= 0) {

package/package.json

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