qingflow-mcp 0.3.17 → 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.17";
+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(),
@@ -1299,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.",
@@ -2026,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;
 }
@@ -2121,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 [
         {
@@ -2150,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"],

package/package.json

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