qingflow-mcp 0.3.18 → 0.3.20

package/README.md

@@ -3,6 +3,9 @@
 This MCP server wraps Qingflow OpenAPI for:
 
 - `qf_apps_list`
+- `qf_apps_info_list`
+- `qf_app_info_get`
+- `qf_app_packages_list`
 - `qf_departments_list`
 - `qf_department_users_list`
 - `qf_users_list`
@@ -17,6 +20,8 @@ This MCP server wraps Qingflow OpenAPI for:
 - `qf_export_json`
 - `qf_query` (unified read entry: list / record / summary)
 - `qf_records_aggregate` (deterministic grouped metrics)
+- `qf_apply_audit_records_list`
+- `qf_apply_audit_record_get`
 - `qf_record_create`
 - `qf_record_update`
 - `qf_operation_get`
@@ -112,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.18
+npm i -g qingflow-mcp@0.3.20
 ```
 
 Or one-click installer:
@@ -159,6 +164,18 @@ Directory / org flow:
 3. `qf_users_list` for workspace-wide pagination.
 4. `qf_user_get` for one exact user.
 
+Admin app flow:
+
+1. `qf_apps_list` for lightweight visible app listing.
+2. `qf_apps_info_list` for admin-level app detail listing.
+3. `qf_app_info_get` for one exact app.
+4. `qf_app_packages_list` for user-visible app packages.
+
+Audit flow:
+
+1. `qf_apply_audit_records_list` to inspect one record's workflow history.
+2. `qf_apply_audit_record_get` to inspect one audit record's field modifications.
+
 Full calling contract (Chinese):
 
 - [MCP 调用规范](./docs/MCP_CALLING_SPEC.md)
@@ -215,6 +232,51 @@ qingflow-mcp cli call qf_users_list --args '{"pageNum":1,"pageSize":100}'
 qingflow-mcp cli call qf_user_get --args '{"userId":"u_123"}'
 ```
 
+## Admin App Tools
+
+These tools expose admin-facing app and package metadata without routing through `qf_query`:
+
+1. `qf_apps_info_list`
+   - required `page_num`, `page_size`
+   - optional `app_key`
+   - aliases: `pageNum`, `pageSize`, `appKey`
+2. `qf_app_info_get`
+   - required `app_key`
+   - alias: `appKey`
+3. `qf_app_packages_list`
+   - required `user_id`
+   - optional `tag_id`, `keyword`, `limit`, `offset`
+   - aliases: `userId`, `tagId`
+
+CLI examples:
+
+```bash
+qingflow-mcp cli call qf_apps_info_list --args '{"pageNum":1,"pageSize":50}'
+
+qingflow-mcp cli call qf_app_info_get --args '{"appKey":"app_demo"}'
+
+qingflow-mcp cli call qf_app_packages_list --args '{"userId":"u_123","tagId":1001}'
+```
+
+## Audit Tools
+
+These tools expose workflow log history as read-only MCP tools:
+
+1. `qf_apply_audit_records_list`
+   - required `apply_id`
+   - alias: `applyId`
+2. `qf_apply_audit_record_get`
+   - required `apply_id`, `audit_rcd_id`
+   - aliases: `applyId`, `auditRcdId`
+
+CLI examples:
+
+```bash
+qingflow-mcp cli call qf_apply_audit_records_list --args '{"applyId":"50001234"}'
+
+qingflow-mcp cli call qf_apply_audit_record_get --args '{"applyId":"50001234","auditRcdId":"1111"}'
+```
+
 Return shape:
 
 1. success: structured payload `{ "ok": true, "data": ... }` (`meta` only in `output_profile=verbose`)

package/dist/qingflow-client.js

@@ -33,6 +33,42 @@ export class QingflowClient {
             }
         });
     }
+    listAppsInfo(options) {
+        return this.request({
+            method: "GET",
+            path: "/apps",
+            options: {
+                query: {
+                    appKey: options.appKey,
+                    pageNum: options.pageNum,
+                    pageSize: options.pageSize
+                }
+            }
+        });
+    }
+    listAppPackages(options) {
+        return this.request({
+            method: "GET",
+            path: "/tags",
+            options: {
+                query: {
+                    userId: options.userId
+                }
+            }
+        });
+    }
+    listApplyAuditRecords(applyId) {
+        return this.request({
+            method: "GET",
+            path: `/apply/${encodeURIComponent(applyId)}/auditRecord`
+        });
+    }
+    getApplyAuditRecord(applyId, auditRcdId) {
+        return this.request({
+            method: "GET",
+            path: `/apply/${encodeURIComponent(applyId)}/auditRecord/${encodeURIComponent(auditRcdId)}`
+        });
+    }
     listDepartments(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.18";
+const SERVER_VERSION = "0.3.20";
 const accessToken = process.env.QINGFLOW_ACCESS_TOKEN;
 const baseUrl = process.env.QINGFLOW_BASE_URL;
 if (!accessToken) {
@@ -353,6 +353,186 @@ const formSuccessOutputSchema = z.object({
 const formOutputSchema = formSuccessOutputSchema;
 const publicStringSchema = z.string().min(1);
 const publicFieldSelectorSchema = z.union([publicStringSchema, z.number().int()]);
+const appAuthUserSchema = z.object({
+    user_id: z.string().nullable(),
+    user_name: z.string().nullable()
+});
+const appAuthDepartmentSchema = z.object({
+    dept_id: z.number().int().nullable(),
+    dept_name: z.string().nullable()
+});
+const appAuthRoleSchema = z.object({
+    role_id: z.number().int().nullable(),
+    role_name: z.string().nullable()
+});
+const appAuthMembersSchema = z.object({
+    users: z.array(appAuthUserSchema),
+    departments: z.array(appAuthDepartmentSchema),
+    roles: z.array(appAuthRoleSchema)
+});
+const appCreatorSchema = z.object({
+    user_id: z.string().nullable(),
+    nick_name: z.string().nullable(),
+    head_img: z.string().nullable()
+});
+const appTagRefSchema = z.object({
+    tag_id: z.number().int().nullable(),
+    tag_name: z.string().nullable()
+});
+const appInfoSchema = z.object({
+    app_key: z.string().nullable(),
+    app_name: z.string().nullable(),
+    app_auth: z.number().int().nullable(),
+    app_icon: z.string().nullable(),
+    auth_members: appAuthMembersSchema,
+    creator: appCreatorSchema,
+    create_time: z.string().nullable(),
+    tags: z.array(appTagRefSchema),
+    app_publish_status: z.number().int().nullable()
+});
+const appInfoListInputPublicSchema = 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(),
+    app_key: publicStringSchema.optional(),
+    appKey: publicStringSchema.optional()
+});
+const appInfoListInputSchema = z.preprocess(normalizeAppInfoListInput, z.object({
+    page_num: z.number().int().positive().optional(),
+    page_size: z.number().int().positive().optional(),
+    app_key: z.string().min(1).optional()
+}));
+const appInfoListOutputSchema = 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()
+        }),
+        apps: z.array(appInfoSchema)
+    }),
+    meta: apiMetaSchema
+});
+const appInfoGetInputPublicSchema = z.object({
+    app_key: publicStringSchema.optional(),
+    appKey: publicStringSchema.optional()
+});
+const appInfoGetInputSchema = z.preprocess(normalizeAppInfoGetInput, z.object({
+    app_key: z.string().min(1).optional()
+}));
+const appInfoGetOutputSchema = z.object({
+    ok: z.literal(true),
+    data: z.object({
+        app: appInfoSchema
+    }),
+    meta: apiMetaSchema
+});
+const appPackageAppSchema = z.object({
+    app_key: z.string().nullable(),
+    app_name: z.string().nullable()
+});
+const dashboardRefSchema = z.object({
+    dash_key: z.string().nullable(),
+    dash_name: z.string().nullable()
+});
+const appPackageSchema = z.object({
+    tag_id: z.number().int().nullable(),
+    tag_name: z.string().nullable(),
+    tag_icon: z.string().nullable(),
+    apps: z.array(appPackageAppSchema),
+    dashboards: z.array(dashboardRefSchema)
+});
+const appPackageListInputPublicSchema = z.object({
+    user_id: publicStringSchema.optional(),
+    userId: publicStringSchema.optional(),
+    tag_id: publicDirectorySelectorSchema.optional(),
+    tagId: publicDirectorySelectorSchema.optional(),
+    keyword: publicStringSchema.optional(),
+    limit: z.number().int().positive().max(500).optional(),
+    offset: z.number().int().nonnegative().optional()
+});
+const appPackageListInputSchema = z.preprocess(normalizeAppPackageListInput, z.object({
+    user_id: z.string().min(1).optional(),
+    tag_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 appPackageListOutputSchema = z.object({
+    ok: z.literal(true),
+    data: z.object({
+        user_id: z.string(),
+        tag_id_filter: z.union([z.string(), z.number(), z.null()]),
+        total_packages: z.number().int().nonnegative(),
+        returned_packages: z.number().int().nonnegative(),
+        limit: z.number().int().positive(),
+        offset: z.number().int().nonnegative(),
+        packages: z.array(appPackageSchema)
+    }),
+    meta: apiMetaSchema
+});
+const auditUserInfoSchema = z.object({
+    user_id: z.string().nullable(),
+    user_name: z.string().nullable(),
+    nick_name: z.string().nullable(),
+    head_img: z.string().nullable()
+});
+const auditRecordSummarySchema = z.object({
+    audit_rcd_id: z.number().int().nullable(),
+    audit_node_id: z.number().int().nullable(),
+    audit_node_name: z.string().nullable(),
+    audit_time_ms: z.number().int().nullable(),
+    audit_result: z.unknown().nullable(),
+    audit_feedback: z.string().nullable(),
+    audit_user: auditUserInfoSchema.nullable(),
+    wait_audit_users: z.array(auditUserInfoSchema)
+});
+const applyAuditRecordsInputPublicSchema = z.object({
+    apply_id: publicStringSchema.optional(),
+    applyId: publicStringSchema.optional()
+});
+const applyAuditRecordsInputSchema = z.preprocess(normalizeApplyAuditRecordsInput, z.object({
+    apply_id: z.string().min(1).optional()
+}));
+const applyAuditRecordsOutputSchema = z.object({
+    ok: z.literal(true),
+    data: z.object({
+        apply_id: z.string(),
+        apply_status: z.unknown().nullable(),
+        audit_records: z.array(auditRecordSummarySchema),
+        current_nodes: z.array(auditRecordSummarySchema)
+    }),
+    meta: apiMetaSchema
+});
+const auditModifySchema = z.object({
+    que_id: z.union([z.number(), z.string(), z.null()]),
+    que_title: z.string().nullable(),
+    que_type: z.unknown().nullable(),
+    before_answer: z.array(z.unknown()),
+    after_answer: z.array(z.unknown())
+});
+const applyAuditRecordGetInputPublicSchema = z.object({
+    apply_id: publicStringSchema.optional(),
+    applyId: publicStringSchema.optional(),
+    audit_rcd_id: publicStringSchema.optional(),
+    auditRcdId: publicStringSchema.optional()
+});
+const applyAuditRecordGetInputSchema = z.preprocess(normalizeApplyAuditRecordGetInput, z.object({
+    apply_id: z.string().min(1).optional(),
+    audit_rcd_id: z.string().min(1).optional()
+}));
+const applyAuditRecordGetOutputSchema = z.object({
+    ok: z.literal(true),
+    data: z.object({
+        apply_id: z.string(),
+        audit_rcd_id: z.union([z.string(), z.number()]),
+        modifies: z.array(auditModifySchema)
+    }),
+    meta: apiMetaSchema
+});
 const publicSortItemSchema = z.object({
     que_id: publicFieldSelectorSchema,
     ascend: z.boolean().optional()
@@ -565,12 +745,14 @@ const listOutputSchema = listSuccessOutputSchema;
 const recordGetInputPublicSchema = z
     .object({
     apply_id: publicFieldSelectorSchema,
+    app_key: publicStringSchema.optional(),
     max_columns: z.number().int().positive().max(MAX_COLUMN_LIMIT).optional(),
     select_columns: z.array(publicFieldSelectorSchema).min(1).max(MAX_COLUMN_LIMIT),
     output_profile: outputProfileSchema.optional()
 });
 const recordGetInputSchema = z.preprocess(normalizeRecordGetInput, z.object({
     apply_id: z.union([z.string().min(1), z.number().int()]),
+    app_key: z.string().min(1).optional(),
     max_columns: z.number().int().positive().max(MAX_COLUMN_LIMIT).optional(),
     select_columns: z
         .array(z.union([z.string().min(1), z.number().int()]))
@@ -1418,6 +1600,300 @@ server.registerTool("qf_apps_list", {
         return errorResult(error);
     }
 });
+server.registerTool("qf_apps_info_list", {
+    title: "Qingflow Apps Info List",
+    description: "List app admin info with explicit pagination. Requires admin-level visibility.",
+    inputSchema: appInfoListInputPublicSchema,
+    outputSchema: appInfoListOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true
+    }
+}, async (args) => {
+    try {
+        const parsedArgs = appInfoListInputSchema.parse(args);
+        if (parsedArgs.page_num === undefined) {
+            throw missingRequiredFieldError({
+                field: "page_num",
+                tool: "qf_apps_info_list",
+                fixHint: "Provide page_num (or pageNum), for example: {\"page_num\":1,\"page_size\":50}."
+            });
+        }
+        if (parsedArgs.page_size === undefined) {
+            throw missingRequiredFieldError({
+                field: "page_size",
+                tool: "qf_apps_info_list",
+                fixHint: "Provide page_size (or pageSize), for example: {\"page_num\":1,\"page_size\":50}."
+            });
+        }
+        let response;
+        try {
+            response = await client.listAppsInfo({
+                appKey: parsedArgs.app_key,
+                pageNum: parsedArgs.page_num,
+                pageSize: parsedArgs.page_size
+            });
+        }
+        catch (error) {
+            if (parsedArgs.app_key) {
+                throw translateAdminApiError(error, {
+                    tool: "qf_apps_info_list",
+                    entity: "app",
+                    appKey: parsedArgs.app_key
+                });
+            }
+            throw error;
+        }
+        const result = asObject(response.result);
+        const apps = asArray(result?.apps).map((item) => normalizeAppInfo(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) ?? apps.length
+                },
+                apps
+            },
+            meta: buildMeta(response)
+        }, `Returned ${apps.length} app info rows`);
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+});
+server.registerTool("qf_app_info_get", {
+    title: "Qingflow App Info Get",
+    description: "Get one app's admin info by app_key. Requires admin-level visibility.",
+    inputSchema: appInfoGetInputPublicSchema,
+    outputSchema: appInfoGetOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true
+    }
+}, async (args) => {
+    try {
+        const parsedArgs = appInfoGetInputSchema.parse(args);
+        if (!parsedArgs.app_key) {
+            throw missingRequiredFieldError({
+                field: "app_key",
+                tool: "qf_app_info_get",
+                fixHint: "Provide app_key (or appKey), for example: {\"app_key\":\"21b3d559\"}."
+            });
+        }
+        let response;
+        try {
+            response = await client.listAppsInfo({
+                appKey: parsedArgs.app_key,
+                pageNum: 1,
+                pageSize: 1
+            });
+        }
+        catch (error) {
+            throw translateAdminApiError(error, {
+                tool: "qf_app_info_get",
+                entity: "app",
+                appKey: parsedArgs.app_key
+            });
+        }
+        const result = asObject(response.result);
+        const app = asArray(result?.apps)
+            .map((item) => normalizeAppInfo(item))
+            .find((item) => item.app_key === parsedArgs.app_key);
+        if (!app) {
+            throw new InputValidationError({
+                message: `App \"${parsedArgs.app_key}\" not found`,
+                errorCode: "APP_NOT_FOUND",
+                fixHint: "Call qf_apps_list or qf_apps_info_list first to confirm the exact app_key.",
+                details: {
+                    tool: "qf_app_info_get",
+                    app_key: parsedArgs.app_key
+                }
+            });
+        }
+        return okResult({
+            ok: true,
+            data: {
+                app
+            },
+            meta: buildMeta(response)
+        }, `Fetched app ${parsedArgs.app_key}`);
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+});
+server.registerTool("qf_app_packages_list", {
+    title: "Qingflow App Packages List",
+    description: "List app packages visible to one user, with optional local tag/keyword slicing.",
+    inputSchema: appPackageListInputPublicSchema,
+    outputSchema: appPackageListOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true
+    }
+}, async (args) => {
+    try {
+        const parsedArgs = appPackageListInputSchema.parse(args);
+        if (!parsedArgs.user_id) {
+            throw missingRequiredFieldError({
+                field: "user_id",
+                tool: "qf_app_packages_list",
+                fixHint: "Provide user_id (or userId), for example: {\"user_id\":\"u_123\"}."
+            });
+        }
+        const response = await client.listAppPackages({
+            userId: parsedArgs.user_id
+        });
+        const keyword = parsedArgs.keyword?.trim().toLowerCase() ?? null;
+        const limit = parsedArgs.limit ?? 50;
+        const offset = parsedArgs.offset ?? 0;
+        let packages = asArray(asObject(response.result)?.tagList).map((item) => normalizeAppPackage(item));
+        if (parsedArgs.tag_id !== undefined) {
+            packages = packages.filter((item) => String(item.tag_id ?? "") === String(parsedArgs.tag_id));
+            if (packages.length === 0) {
+                throw new InputValidationError({
+                    message: `App package \"${String(parsedArgs.tag_id)}\" not found`,
+                    errorCode: "APP_PACKAGE_NOT_FOUND",
+                    fixHint: "Call qf_app_packages_list without tag_id first to confirm the exact package id.",
+                    details: {
+                        tool: "qf_app_packages_list",
+                        tag_id: parsedArgs.tag_id,
+                        user_id: parsedArgs.user_id
+                    }
+                });
+            }
+        }
+        const filtered = keyword
+            ? packages.filter((item) => {
+                const values = [
+                    item.tag_name ?? "",
+                    ...item.apps.map((app) => app.app_name ?? ""),
+                    ...item.dashboards.map((dash) => dash.dash_name ?? "")
+                ];
+                return values.some((value) => value.toLowerCase().includes(keyword));
+            })
+            : packages;
+        const sliced = filtered.slice(offset, offset + limit);
+        return okResult({
+            ok: true,
+            data: {
+                user_id: parsedArgs.user_id,
+                tag_id_filter: parsedArgs.tag_id ?? null,
+                total_packages: filtered.length,
+                returned_packages: sliced.length,
+                limit,
+                offset,
+                packages: sliced
+            },
+            meta: buildMeta(response)
+        }, `Returned ${sliced.length}/${filtered.length} app packages`);
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+});
+server.registerTool("qf_apply_audit_records_list", {
+    title: "Qingflow Apply Audit Records List",
+    description: "List one record's workflow audit log and current pending nodes.",
+    inputSchema: applyAuditRecordsInputPublicSchema,
+    outputSchema: applyAuditRecordsOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true
+    }
+}, async (args) => {
+    try {
+        const parsedArgs = applyAuditRecordsInputSchema.parse(args);
+        if (!parsedArgs.apply_id) {
+            throw missingRequiredFieldError({
+                field: "apply_id",
+                tool: "qf_apply_audit_records_list",
+                fixHint: "Provide apply_id (or applyId), for example: {\"apply_id\":\"50001234\"}."
+            });
+        }
+        let response;
+        try {
+            response = await client.listApplyAuditRecords(parsedArgs.apply_id);
+        }
+        catch (error) {
+            throw translateAdminApiError(error, {
+                tool: "qf_apply_audit_records_list",
+                entity: "apply",
+                applyId: parsedArgs.apply_id
+            });
+        }
+        const result = asObject(response.result);
+        return okResult({
+            ok: true,
+            data: {
+                apply_id: parsedArgs.apply_id,
+                apply_status: result?.applyStatus ?? null,
+                audit_records: asArray(result?.auditRecords).map((item) => normalizeAuditRecordSummary(item)),
+                current_nodes: asArray(result?.currentNodes).map((item) => normalizeAuditRecordSummary(item))
+            },
+            meta: buildMeta(response)
+        }, `Fetched audit records for apply ${parsedArgs.apply_id}`);
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+});
+server.registerTool("qf_apply_audit_record_get", {
+    title: "Qingflow Apply Audit Record Get",
+    description: "Get one workflow audit record detail by apply_id and audit_rcd_id.",
+    inputSchema: applyAuditRecordGetInputPublicSchema,
+    outputSchema: applyAuditRecordGetOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true
+    }
+}, async (args) => {
+    try {
+        const parsedArgs = applyAuditRecordGetInputSchema.parse(args);
+        if (!parsedArgs.apply_id) {
+            throw missingRequiredFieldError({
+                field: "apply_id",
+                tool: "qf_apply_audit_record_get",
+                fixHint: "Provide apply_id (or applyId), for example: {\"apply_id\":\"50001234\",\"audit_rcd_id\":\"1111\"}."
+            });
+        }
+        if (!parsedArgs.audit_rcd_id) {
+            throw missingRequiredFieldError({
+                field: "audit_rcd_id",
+                tool: "qf_apply_audit_record_get",
+                fixHint: "Provide audit_rcd_id (or auditRcdId), for example: {\"apply_id\":\"50001234\",\"audit_rcd_id\":\"1111\"}."
+            });
+        }
+        let response;
+        try {
+            response = await client.getApplyAuditRecord(parsedArgs.apply_id, parsedArgs.audit_rcd_id);
+        }
+        catch (error) {
+            throw translateAdminApiError(error, {
+                tool: "qf_apply_audit_record_get",
+                entity: "audit_record",
+                applyId: parsedArgs.apply_id,
+                auditRcdId: parsedArgs.audit_rcd_id
+            });
+        }
+        const result = asObject(response.result);
+        return okResult({
+            ok: true,
+            data: {
+                apply_id: parsedArgs.apply_id,
+                audit_rcd_id: result?.auditRcdId ?? parsedArgs.audit_rcd_id,
+                modifies: normalizeAuditModifies(result?.auditModifies)
+            },
+            meta: buildMeta(response)
+        }, `Fetched audit record ${parsedArgs.audit_rcd_id} for apply ${parsedArgs.apply_id}`);
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+});
 server.registerTool("qf_departments_list", {
     title: "Qingflow Departments List",
     description: "List departments with optional dept_id filter and local keyword slicing.",
@@ -2358,6 +2834,17 @@ function buildMeta(response) {
         base_url: baseUrl
     };
 }
+async function fetchRecordsByApplyIds(params) {
+    const response = await client.listRecords(params.appKey, buildListPayload({
+        pageNum: 1,
+        pageSize: Math.min(Math.max(params.applyIds.length, 1), 200),
+        applyIds: params.applyIds
+    }), { userId: params.userId });
+    const records = asArray(asObject(response.result)?.result)
+        .map((item) => asObject(item))
+        .filter((item) => Boolean(item));
+    return { response, records };
+}
 function normalizeStringArray(value) {
     return uniqueStringList(asArray(value)
         .map((item) => asNullableString(item)?.trim() ?? "")
@@ -2391,6 +2878,174 @@ function normalizeUser(raw) {
         superior_id: asNullableString(obj.superiorId)
     };
 }
+function normalizeAppAuthMembers(raw) {
+    const obj = asObject(raw) ?? {};
+    return {
+        users: asArray(obj.users).map((item) => {
+            const entry = asObject(item) ?? {};
+            return {
+                user_id: asNullableString(entry.userId),
+                user_name: asNullableString(entry.userName)
+            };
+        }),
+        departments: asArray(obj.depts).map((item) => {
+            const entry = asObject(item) ?? {};
+            return {
+                dept_id: toNonNegativeInt(entry.deptId),
+                dept_name: asNullableString(entry.deptName)
+            };
+        }),
+        roles: asArray(obj.roles).map((item) => {
+            const entry = asObject(item) ?? {};
+            return {
+                role_id: toNonNegativeInt(entry.roleId),
+                role_name: asNullableString(entry.roleName)
+            };
+        })
+    };
+}
+function normalizeAppInfo(raw) {
+    const obj = asObject(raw) ?? {};
+    const creator = asObject(obj.creator) ?? {};
+    return {
+        app_key: asNullableString(obj.appKey),
+        app_name: asNullableString(obj.appName),
+        app_auth: toNonNegativeInt(obj.appAuth),
+        app_icon: asNullableString(obj.appIcon),
+        auth_members: normalizeAppAuthMembers(obj.authmembers ?? obj.authMembers),
+        creator: {
+            user_id: asNullableString(creator.userId),
+            nick_name: asNullableString(creator.nickName),
+            head_img: asNullableString(creator.headImg)
+        },
+        create_time: asNullableString(obj.createTime),
+        tags: asArray(obj.tags).map((item) => {
+            const entry = asObject(item) ?? {};
+            return {
+                tag_id: toNonNegativeInt(entry.tagId),
+                tag_name: asNullableString(entry.tagName)
+            };
+        }),
+        app_publish_status: toNonNegativeInt(obj.appPublishStatus)
+    };
+}
+function normalizeAppPackage(raw) {
+    const obj = asObject(raw) ?? {};
+    return {
+        tag_id: toNonNegativeInt(obj.tagId),
+        tag_name: asNullableString(obj.tagName),
+        tag_icon: asNullableString(obj.tagIcon),
+        apps: asArray(obj.appList).map((item) => {
+            const entry = asObject(item) ?? {};
+            return {
+                app_key: asNullableString(entry.appKey),
+                app_name: asNullableString(entry.appName)
+            };
+        }),
+        dashboards: asArray(obj.dashList).map((item) => {
+            const entry = asObject(item) ?? {};
+            return {
+                dash_key: asNullableString(entry.dashKey),
+                dash_name: asNullableString(entry.dashName)
+            };
+        })
+    };
+}
+function normalizeAuditUserInfo(raw) {
+    const obj = asObject(raw) ?? {};
+    return {
+        user_id: asNullableString(obj.userId),
+        user_name: asNullableString(obj.userName),
+        nick_name: asNullableString(obj.nickName),
+        head_img: asNullableString(obj.headImg)
+    };
+}
+function toNullableSpecialId(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return Math.trunc(value);
+    }
+    if (typeof value === "string" && value.trim()) {
+        const normalized = value.trim();
+        if (/^\d+$/.test(normalized)) {
+            return Number(normalized);
+        }
+        return normalized;
+    }
+    const obj = asObject(value);
+    if (!obj) {
+        return null;
+    }
+    const candidate = obj.queId ?? obj.id ?? obj.value ?? obj.dataValue ?? null;
+    return candidate === null ? null : toNullableSpecialId(candidate);
+}
+function normalizeAuditRecordSummary(raw) {
+    const obj = asObject(raw) ?? {};
+    return {
+        audit_rcd_id: toNonNegativeInt(obj.auditRcdId),
+        audit_node_id: toNonNegativeInt(obj.auditNodeId),
+        audit_node_name: asNullableString(obj.auditNodeName),
+        audit_time_ms: toNonNegativeInt(obj.auditTime),
+        audit_result: obj.auditResult ?? null,
+        audit_feedback: asNullableString(obj.auditFeedback),
+        audit_user: obj.auditUser ? normalizeAuditUserInfo(obj.auditUser) : null,
+        wait_audit_users: asArray(obj.waitAuditUserList).map((item) => normalizeAuditUserInfo(item))
+    };
+}
+function normalizeAuditModifies(raw) {
+    const source = Array.isArray(raw)
+        ? raw
+        : asObject(raw)
+            ? Object.values(raw)
+            : [];
+    return source.map((item) => {
+        const entry = asObject(item) ?? {};
+        return {
+            que_id: toNullableSpecialId(entry.queId),
+            que_title: asNullableString(entry.queTitle),
+            que_type: entry.queType ?? null,
+            before_answer: asArray(entry.beforeAnswer),
+            after_answer: asArray(entry.afterAnswer)
+        };
+    });
+}
+function translateAdminApiError(error, params) {
+    if (error instanceof QingflowApiError &&
+        (error.httpStatus === 404 || error.errCode === 404)) {
+        if (params.entity === "app") {
+            return new InputValidationError({
+                message: `App \"${params.appKey}\" not found`,
+                errorCode: "APP_NOT_FOUND",
+                fixHint: "Call qf_apps_list or qf_apps_info_list first to confirm the exact app_key.",
+                details: {
+                    tool: params.tool,
+                    app_key: params.appKey
+                }
+            });
+        }
+        if (params.entity === "apply") {
+            return new InputValidationError({
+                message: `Apply \"${params.applyId}\" not found`,
+                errorCode: "APPLY_NOT_FOUND",
+                fixHint: "Use qf_record_get or your record query tools first to confirm the exact apply_id.",
+                details: {
+                    tool: params.tool,
+                    apply_id: params.applyId
+                }
+            });
+        }
+        return new InputValidationError({
+            message: `Audit record \"${params.auditRcdId}\" for apply \"${params.applyId}\" not found`,
+            errorCode: "AUDIT_RECORD_NOT_FOUND",
+            fixHint: "Call qf_apply_audit_records_list first to confirm the exact audit_rcd_id.",
+            details: {
+                tool: params.tool,
+                apply_id: params.applyId,
+                audit_rcd_id: params.auditRcdId
+            }
+        });
+    }
+    return error instanceof Error ? error : new Error(String(error));
+}
 function translateDirectoryApiError(error, params) {
     if (error instanceof QingflowApiError &&
         (error.httpStatus === 404 || error.errCode === 404)) {
@@ -2437,6 +3092,7 @@ function missingRequiredFieldError(params) {
 const COMMON_INPUT_ALIASES = {
     appKey: "app_key",
     userId: "user_id",
+    tagId: "tag_id",
     pageNum: "page_num",
     pageSize: "page_size",
     pageToken: "page_token",
@@ -2448,6 +3104,7 @@ const COMMON_INPUT_ALIASES = {
     queryMode: "query_mode",
     queryLogic: "query_logic",
     applyId: "apply_id",
+    auditRcdId: "audit_rcd_id",
     applyIds: "apply_ids",
     maxRows: "max_rows",
     rowLimit: "max_rows",
@@ -2582,6 +3239,87 @@ function normalizeUserGetInput(raw) {
         user_id: coerceStringLike(normalizedObj.user_id)
     };
 }
+function normalizeAppInfoListInput(raw) {
+    const parsedRoot = parseJsonLikeDeep(raw);
+    const obj = asObject(parsedRoot);
+    if (!obj) {
+        return parsedRoot;
+    }
+    const normalizedObj = applyAliases(obj, {
+        appKey: "app_key",
+        pageNum: "page_num",
+        pageSize: "page_size"
+    });
+    return {
+        ...normalizedObj,
+        app_key: coerceStringLike(normalizedObj.app_key),
+        page_num: coerceNumberLike(normalizedObj.page_num),
+        page_size: coerceNumberLike(normalizedObj.page_size)
+    };
+}
+function normalizeAppInfoGetInput(raw) {
+    const parsedRoot = parseJsonLikeDeep(raw);
+    const obj = asObject(parsedRoot);
+    if (!obj) {
+        return parsedRoot;
+    }
+    const normalizedObj = applyAliases(obj, {
+        appKey: "app_key"
+    });
+    return {
+        ...normalizedObj,
+        app_key: coerceStringLike(normalizedObj.app_key)
+    };
+}
+function normalizeAppPackageListInput(raw) {
+    const parsedRoot = parseJsonLikeDeep(raw);
+    const obj = asObject(parsedRoot);
+    if (!obj) {
+        return parsedRoot;
+    }
+    const normalizedObj = applyAliases(obj, {
+        userId: "user_id",
+        tagId: "tag_id"
+    });
+    return {
+        ...normalizedObj,
+        user_id: coerceStringLike(normalizedObj.user_id),
+        tag_id: coerceNumberLike(normalizeSelectorInputValue(normalizedObj.tag_id)),
+        keyword: coerceStringLike(normalizedObj.keyword),
+        limit: coerceNumberLike(normalizedObj.limit),
+        offset: coerceNumberLike(normalizedObj.offset)
+    };
+}
+function normalizeApplyAuditRecordsInput(raw) {
+    const parsedRoot = parseJsonLikeDeep(raw);
+    const obj = asObject(parsedRoot);
+    if (!obj) {
+        return parsedRoot;
+    }
+    const normalizedObj = applyAliases(obj, {
+        applyId: "apply_id"
+    });
+    return {
+        ...normalizedObj,
+        apply_id: coerceStringLike(normalizedObj.apply_id)
+    };
+}
+function normalizeApplyAuditRecordGetInput(raw) {
+    const parsedRoot = parseJsonLikeDeep(raw);
+    const obj = asObject(parsedRoot);
+    if (!obj) {
+        return parsedRoot;
+    }
+    const normalizedObj = applyAliases(obj, {
+        applyId: "apply_id",
+        auditRcdId: "audit_rcd_id"
+    });
+    return {
+        ...normalizedObj,
+        apply_id: coerceStringLike(normalizedObj.apply_id),
+        audit_rcd_id: coerceStringLike(normalizedObj.audit_rcd_id)
+    };
+}
 function buildToolSpecCatalog() {
     return [
         {
@@ -2611,6 +3349,67 @@ function buildToolSpecCatalog() {
                 limit: 20
             }
         },
+        {
+            tool: "qf_apps_info_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", "app_key"], {}),
+            minimal_example: {
+                page_num: 1,
+                page_size: 50,
+                app_key: "21b3d559"
+            }
+        },
+        {
+            tool: "qf_app_info_get",
+            required: ["app_key"],
+            limits: {
+                input_contract: "strict JSON only; app_key must be a native JSON string"
+            },
+            aliases: collectAliasHints(["app_key"], {}),
+            minimal_example: {
+                app_key: "21b3d559"
+            }
+        },
+        {
+            tool: "qf_app_packages_list",
+            required: ["user_id"],
+            limits: {
+                limit_max: 500,
+                offset_min: 0,
+                input_contract: "strict JSON only; user_id must be a native JSON string when provided"
+            },
+            aliases: collectAliasHints(["user_id", "tag_id"], {}),
+            minimal_example: {
+                user_id: "u_123",
+                limit: 20
+            }
+        },
+        {
+            tool: "qf_apply_audit_records_list",
+            required: ["apply_id"],
+            limits: {
+                input_contract: "strict JSON only; apply_id must be a native JSON string"
+            },
+            aliases: collectAliasHints(["apply_id"], {}),
+            minimal_example: {
+                apply_id: "50001234"
+            }
+        },
+        {
+            tool: "qf_apply_audit_record_get",
+            required: ["apply_id", "audit_rcd_id"],
+            limits: {
+                input_contract: "strict JSON only; apply_id/audit_rcd_id must be native JSON strings"
+            },
+            aliases: collectAliasHints(["apply_id", "audit_rcd_id"], {}),
+            minimal_example: {
+                apply_id: "50001234",
+                audit_rcd_id: "1111"
+            }
+        },
         {
             tool: "qf_departments_list",
             required: [],
@@ -2997,6 +3796,7 @@ function normalizeRecordGetInput(raw) {
     return {
         ...normalizedObj,
         apply_id: coerceNumberLike(normalizedObj.apply_id),
+        app_key: coerceStringLike(normalizedObj.app_key),
         max_columns: coerceNumberLike(normalizedObj.max_columns),
         select_columns: normalizeSelectorListInput(selectColumns),
         output_profile: normalizeOutputProfileInput(normalizedObj.output_profile)
@@ -3117,6 +3917,7 @@ function normalizeBatchGetInput(raw) {
     const selectColumns = normalizedObj.select_columns ?? normalizedObj.keep_columns;
     return {
         ...normalizedObj,
+        app_key: coerceStringLike(normalizedObj.app_key),
         apply_ids: normalizeIdArrayInput(normalizedObj.apply_ids),
         max_columns: coerceNumberLike(normalizedObj.max_columns),
         select_columns: normalizeSelectorListInput(selectColumns),
@@ -4717,6 +5518,7 @@ function buildRecordGetArgsFromQuery(args) {
     }
     return recordGetInputSchema.parse({
         apply_id: args.apply_id,
+        app_key: args.app_key,
         max_columns: args.max_columns,
         select_columns: args.select_columns,
         output_profile: args.output_profile
@@ -4802,6 +5604,13 @@ async function executeQueryPlan(args) {
     };
 }
 async function executeRecordsBatchGet(args) {
+    if (!args.app_key) {
+        throw missingRequiredFieldError({
+            field: "app_key",
+            tool: "qf_records_batch_get",
+            fixHint: "Provide app_key, for example: {\"app_key\":\"21b3d559\",\"apply_ids\":[\"...\"],\"select_columns\":[0]}."
+        });
+    }
     if (!args.select_columns?.length) {
         throw missingRequiredFieldError({
             field: "select_columns",
@@ -4819,25 +5628,23 @@ async function executeRecordsBatchGet(args) {
     const rows = [];
     const missingApplyIds = [];
     let metaResponse = null;
+    const { response, records } = await fetchRecordsByApplyIds({
+        appKey: args.app_key,
+        applyIds: requestedApplyIds
+    });
+    metaResponse = buildMeta(response);
+    const byApplyId = new Map(records.map((record) => [String(record.applyId ?? ""), record]));
     for (const applyId of requestedApplyIds) {
-        try {
-            const response = await client.getRecord(applyId);
-            metaResponse = metaResponse ?? buildMeta(response);
-            const record = asObject(response.result) ?? {};
-            rows.push(buildFlatRowFromAnswers({
-                applyId: record.applyId ?? applyId,
-                answers: asArray(record.answers),
-                selectedColumns: selectedColumnsForRow
-            }));
-        }
-        catch (error) {
-            if (error instanceof QingflowApiError &&
-                (error.httpStatus === 404 || error.errCode === 404)) {
-                missingApplyIds.push(applyId);
-                continue;
-            }
-            throw error;
+        const record = byApplyId.get(String(applyId));
+        if (!record) {
+            missingApplyIds.push(applyId);
+            continue;
         }
+        rows.push(buildFlatRowFromAnswers({
+            applyId: record.applyId ?? applyId,
+            answers: asArray(record.answers),
+            selectedColumns: selectedColumnsForRow
+        }));
     }
     const completeness = {
         result_amount: requestedApplyIds.length,
@@ -5400,10 +6207,50 @@ async function executeRecordGet(args) {
     }
     const outputProfile = resolveOutputProfile(args.output_profile);
     const queryId = randomUUID();
-    const response = await client.getRecord(String(args.apply_id));
-    const record = asObject(response.result) ?? {};
+    let response;
+    let record = null;
+    try {
+        response = await client.getRecord(String(args.apply_id));
+        record = asObject(response.result) ?? {};
+    }
+    catch (error) {
+        const providerError = error instanceof QingflowApiError ? error : null;
+        const shouldFallback = providerError && (providerError.httpStatus === 404 || providerError.errCode === 404 || providerError.errCode === 49304);
+        if (!shouldFallback) {
+            throw error;
+        }
+        if (!args.app_key) {
+            throw new InputValidationError({
+                message: `qf_record_get could not read apply_id \"${String(args.apply_id)}\" through the direct record endpoint`,
+                errorCode: "APP_KEY_REQUIRED_FOR_RECORD_GET",
+                fixHint: "Retry qf_record_get with app_key, or use qf_query/qf_records_batch_get with explicit app_key for this record.",
+                details: {
+                    apply_id: String(args.apply_id),
+                    provider_err_code: providerError?.errCode ?? null,
+                    provider_err_msg: providerError?.errMsg ?? null
+                }
+            });
+        }
+        const fallback = await fetchRecordsByApplyIds({
+            appKey: args.app_key,
+            applyIds: [String(args.apply_id)]
+        });
+        response = fallback.response;
+        record = fallback.records.find((item) => String(item.applyId ?? "") === String(args.apply_id)) ?? null;
+        if (!record) {
+            throw new InputValidationError({
+                message: `Record \"${String(args.apply_id)}\" not found in app \"${args.app_key}\"`,
+                errorCode: "RECORD_NOT_FOUND",
+                fixHint: "Confirm apply_id and app_key, or fetch the row via qf_records_list/qf_query first.",
+                details: {
+                    apply_id: String(args.apply_id),
+                    app_key: args.app_key
+                }
+            });
+        }
+    }
     const projection = projectAnswersForOutput({
-        answers: asArray(record.answers),
+        answers: asArray(record?.answers),
         maxColumns: args.max_columns,
         selectColumns: args.select_columns
     });
@@ -5411,8 +6258,8 @@ async function executeRecordGet(args) {
         ? (projection.selectedColumns ?? []).slice(0, args.max_columns)
         : projection.selectedColumns ?? [];
     const row = buildFlatRowFromAnswers({
-        applyId: record.applyId ?? null,
-        answers: asArray(record.answers),
+        applyId: record?.applyId ?? null,
+        answers: asArray(record?.answers),
         selectedColumns: selectedColumnsForRow
     });
     const completeness = {
@@ -5437,7 +6284,7 @@ async function executeRecordGet(args) {
         payload: {
             ok: true,
             data: {
-                apply_id: record.applyId ?? null,
+                apply_id: record?.applyId ?? null,
                 row,
                 applied_limits: {
                     column_cap: args.max_columns ?? null,

package/package.json

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