@wukongcrm/mcp-server 0.2.4 → 0.2.6

package/dist/server.js

@@ -2,60 +2,184 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { CrmClient } from "./client.js";
 import { createNocodeToolHandlers, nocodeToolDefinitions } from "./nocode.js";
+import { getToolDiscovery, TOOL_DISCOVERY_META_KEY } from "./tool-discovery.js";
 import { createToolHandlers } from "./tools.js";
 export const CRM_READ_SCOPE = "crm.read";
 export const CRM_WRITE_SCOPE = "crm.write";
 export const OFFLINE_ACCESS_SCOPE = "offline_access";
 export const MCP_RESOURCE_SCOPES = [CRM_READ_SCOPE, CRM_WRITE_SCOPE];
 export const OAUTH_SCOPES = [...MCP_RESOURCE_SCOPES, OFFLINE_ACCESS_SCOPE];
+// 工具名称不能可靠表达副作用（例如 workorder_update_record、favourOrCancel）。
+// 这里以显式清单作为 access/annotations 的唯一运行时来源；未列出的主工具一律按只读处理。
+const WRITE_TOOL_SAFETY = {
+    crm_toggle_address_book_attention: { destructive: true },
+    crm_write_hrm: { destructive: true },
+    crm_create_hrm_record: { destructive: false },
+    crm_update_hrm_record: { destructive: true },
+    crm_write_finance: { destructive: true },
+    crm_create_finance_voucher: { destructive: false },
+    crm_update_finance_voucher: { destructive: true },
+    crm_write_jxc: { destructive: true },
+    crm_create_jxc_record: { destructive: false },
+    crm_update_jxc_record: { destructive: true },
+    crm_create_oa_announcement: { destructive: false },
+    crm_update_oa_announcement: { destructive: true },
+    crm_delete_oa_announcement: { destructive: true },
+    crm_mark_oa_announcement_read: { destructive: false },
+    crm_create_record: { destructive: false },
+    crm_update_customer: { destructive: true },
+    crm_update_record_fields: { destructive: true },
+    crm_create_product: { destructive: false },
+    crm_update_product: { destructive: true },
+    crm_update_product_fields: { destructive: true },
+    crm_update_product_status: { destructive: true },
+    crm_transfer_products_owner: { destructive: true },
+    crm_delete_products: { destructive: true },
+    crm_create_contract: { destructive: false },
+    crm_update_contract: { destructive: true },
+    crm_create_receivables: { destructive: false },
+    crm_update_receivables: { destructive: true },
+    crm_create_receivables_plan: { destructive: false },
+    crm_update_receivables_plan: { destructive: true },
+    crm_create_invoice: { destructive: false },
+    crm_update_invoice: { destructive: true },
+    crm_create_quotation: { destructive: false },
+    crm_update_quotation: { destructive: true },
+    crm_create_calendar_event: { destructive: false },
+    crm_update_calendar_event: { destructive: true },
+    crm_create_oa_log: { destructive: false },
+    crm_update_oa_log: { destructive: true },
+    crm_delete_oa_log: { destructive: true },
+    crm_toggle_oa_log_favour: { destructive: true },
+    crm_create_oa_examine: { destructive: false },
+    crm_save_oa_examine_draft: { destructive: true },
+    crm_audit_oa_examine: { destructive: true },
+    crm_batch_audit_oa_examine: { destructive: true },
+    crm_create_oa_task: { destructive: false },
+    crm_update_oa_task_fields: { destructive: true },
+    crm_add_followup: { destructive: false },
+    crm_update_followup: { destructive: true },
+    workorder_create_record: { destructive: false },
+    workorder_update_record: { destructive: true }
+};
 const moduleSchema = z.union([z.string(), z.number()]);
-const idSchema = z.union([z.string(), z.number()]);
+const idSchema = z.string()
+    .regex(/^\d+$/, "ID 必须是数字字符串。")
+    .describe("ID 必须以数字字符串传入，禁止使用 JSON number，避免 Snowflake ID 精度丢失。");
 const passthroughSchema = z.object({}).passthrough();
 const toolOutputSchema = z.object({ result: z.unknown() });
 const searchFilterSchema = z.object({
-    fieldName: z.string().optional(),
-    name: z.string().optional(),
-    formType: z.string().optional(),
-    type: z.number().optional(),
-    searchEnum: z.union([z.string(), z.number()]).optional(),
-    values: z.array(z.unknown()).optional(),
-    groupId: z.number().optional()
+    fieldName: z.string().optional().describe("后端字段名；与兼容字段 name 至少提供一个。"),
+    name: z.string().optional().describe("fieldName 的兼容别名。"),
+    formType: z.string().optional().describe("字段类型。人员用 user/single_user；日期用 date，日期时间用 datetime。"),
+    type: z.number().int().min(1).max(14).optional().describe("高级筛选操作码；与 searchEnum 同义，同时提供时必须一致。人员 ID 匹配用 3，日期范围用 14。"),
+    searchEnum: z.union([
+        z.number().int().min(1).max(14),
+        z.enum(["1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14"])
+    ]).optional().describe("高级筛选操作码；与 type 同义，同时提供时必须一致。"),
+    values: z.array(z.unknown()).optional().describe("筛选值数组。ID 必须使用数字字符串；除为空/不为空操作 5/6 外必须提供；datetime 范围 14 使用 [YYYY-MM-DD HH:mm:ss, YYYY-MM-DD HH:mm:ss]。"),
+    groupId: z.number().int().optional().describe("同组条件为 AND，不同组为 OR。")
 }).passthrough();
 const crmCreateRecordSchema = z.object({
     module: moduleSchema,
-    entity: z.record(z.unknown()).optional().describe("CRM 实体字段；系统字段放在这里，例如 entity.customerName。"),
+    entity: z.record(z.unknown()).optional().describe("CRM 实体字段；系统字段放在这里，例如 entity.customerName；所有 *Id/*Ids 字段使用数字字符串。"),
     field: z.array(z.record(z.unknown())).optional().describe("CRM 自定义字段列表。"),
     saveType: z.number().optional(),
     fileId: idSchema.optional(),
     aiAnalysis: z.number().optional(),
     member: z.record(z.unknown()).optional(),
+    product: z.array(z.unknown()).optional().describe("商机等保存接口的关联产品列表；这是顶层字段，不放入 entity。"),
+    contactsId: idSchema.optional().describe("商机主联系人 ID；这是顶层字段，不放入 entity。"),
+    customerSuperior: z.record(z.unknown()).optional().describe("上级客户信息；这是顶层字段。"),
+    contacts: z.record(z.unknown()).optional().describe("企业微信联系人信息；这是顶层字段。"),
+    examineFlowData: z.record(z.unknown()).optional().describe("审批数据；这是顶层字段。"),
+    confirm: z.boolean().optional()
+}).strict();
+const followupActivityTypeSchema = z.union([
+    z.literal(1), z.literal(2), z.literal(3), z.literal(4), z.literal(5), z.literal(6),
+    z.literal(7), z.literal(14), z.literal(17), z.literal(18), z.literal(22)
+]).describe("关联模块类型：1线索、2客户、3联系人、4产品、5商机、6合同、7回款、14回款计划、17回访、18发票、22报价单。");
+const followupEntitySchema = z.object({
+    id: idSchema.optional().describe("更新跟进时的跟进记录 ID；必须使用数字字符串。"),
+    content: z.string().min(1).describe("跟进内容，不能为空。"),
+    category: z.string().min(1).describe("跟进方式/分类，不能为空。"),
+    activityType: followupActivityTypeSchema,
+    activityTypeId: idSchema.describe("被跟进 CRM 记录的 ID；必须使用数字字符串。"),
+    activityTypeName: z.string().optional(),
+    nextTime: z.string().optional(),
+    visitPlanId: idSchema.optional(),
+    remindTeamMembers: z.unknown().optional(),
+    atUserId: z.array(idSchema).optional(),
+    relateDataList: z.array(z.record(z.unknown())).optional()
+}).passthrough();
+const crmAddFollowupSchema = z.object({
+    entity: followupEntitySchema,
+    field: z.array(z.record(z.unknown())).optional(),
+    saveType: z.number().optional(),
+    fileId: idSchema.optional(),
+    aiAnalysis: z.number().optional(),
+    member: z.record(z.unknown()).optional(),
+    confirm: z.boolean().optional()
+}).strict();
+const crmUpdateFollowupSchema = z.object({
+    id: idSchema.optional(),
+    entity: followupEntitySchema.optional(),
+    field: z.array(z.record(z.unknown())).optional(),
+    saveType: z.number().optional(),
+    fileId: idSchema.optional(),
+    aiAnalysis: z.number().optional(),
+    member: z.record(z.unknown()).optional(),
+    useInformationUpdate: z.boolean().optional(),
+    list: z.array(z.record(z.unknown())).optional(),
+    fields: z.array(z.record(z.unknown())).optional(),
+    batchId: z.string().optional(),
     confirm: z.boolean().optional()
 }).strict();
 const crmUserSearchShape = {
-    ownerUserId: idSchema.optional(),
-    ownerUserIds: z.array(idSchema).optional(),
-    ownerUserName: z.string().optional(),
-    ownerUserNames: z.array(z.string()).optional(),
-    createUserId: idSchema.optional(),
-    createUserIds: z.array(idSchema).optional(),
-    createUserName: z.string().optional(),
-    createUserNames: z.array(z.string()).optional(),
-    filters: z.array(searchFilterSchema).optional(),
-    searchList: z.array(searchFilterSchema).optional()
+    ownerUserId: idSchema.optional().describe("负责人用户 ID；MCP 转为后端支持的人员包含操作 3。"),
+    ownerUserIds: z.array(idSchema).optional().describe("多个负责人用户 ID。"),
+    ownerUserName: z.string().optional().describe("负责人唯一昵称；MCP 先解析为用户 ID，重名时报错。"),
+    ownerUserNames: z.array(z.string()).optional().describe("多个负责人唯一昵称。"),
+    createUserId: idSchema.optional().describe("创建人用户 ID；查询跟进记录时表示跟进人员。"),
+    createUserIds: z.array(idSchema).optional().describe("多个创建人用户 ID。"),
+    createUserName: z.string().optional().describe("创建人唯一昵称；查询跟进记录时表示跟进人员。"),
+    createUserNames: z.array(z.string()).optional().describe("多个创建人唯一昵称。"),
+    filters: z.array(searchFilterSchema).optional().describe("高级筛选列表；与 searchList 二选一。"),
+    searchList: z.array(searchFilterSchema).optional().describe("filters 的兼容别名；不能与 filters 同时提供。")
 };
 const toolDefinitions = [
     ["crm_auth_status", "使用 CRM_API_KEY 自动换取 Admin-Token 后检查当前登录态，异常时提示检查 API Key。", z.object({}).optional()],
     ["crm_list_modules", "列出当前 MCP 固定支持的 72CRM 模块、label、路径和中英文操作边界。", z.object({}).optional()],
     ["crm_list_customer_pools", "查询当前账号有权限访问的客户公海，并统计每个公海下面有多少客户；只读，不领取、不分配、不流转。", z.object({ includeSamples: z.boolean().optional(), sampleLimit: z.number().optional() }).passthrough()],
-    ["crm_get_module_schema", "获取模块字段结构和列表头，供本地 AI 判断字段怎么填。", z.object({ module: moduleSchema, id: z.union([z.string(), z.number()]).optional() }).passthrough()],
+    ["crm_get_module_schema", "获取模块字段结构和列表头，供本地 AI 判断字段怎么填。", z.object({ module: moduleSchema, id: idSchema.optional() }).passthrough()],
+    ["crm_get_business_status_groups", "查询当前账号可用的商机状态组及阶段。新增商机前必须调用；entity.typeId 取 flowId，entity.statusId 取同一组 settingList 中的 settingId。存在多个状态组且用户未指定时必须询问，不能猜测。", z.object({ businessId: idSchema.optional() }).strict()],
     ["crm_validate_field", "调用固定字段校验接口，校验字段值或联系人查重。", passthroughSchema],
-    ["crm_search_records", "查询模块分页列表；支持 ownerUserId(s)/createUserId(s) 按用户 ID 筛选，也支持 ownerUserName(s)/createUserName(s) 将唯一昵称解析为用户 ID；用户类型 filters 的昵称值同样会先解析为 ID。", z.object({ module: moduleSchema, page: z.number().optional(), limit: z.number().optional(), ...crmUserSearchShape }).passthrough()],
-    ["crm_get_record", "按模块和 ID 查询单条 CRM 记录详情。", z.object({ module: moduleSchema, id: z.union([z.string(), z.number()]) }).passthrough()],
-    ["crm_get_record_information", "查询详情页字段展示数据，包含字段中文名和值。", z.object({ module: moduleSchema, id: z.union([z.string(), z.number()]) }).passthrough()],
-    ["crm_get_related_records", "查询固定白名单内的关联数据，例如商机产品、联系人商机、合同回款计划、产品上架列表。", z.object({ module: moduleSchema, id: z.union([z.string(), z.number()]).optional(), relation: z.string() }).passthrough()],
-    ["crm_get_record_timeline", "查询某条记录关联的跟进/活动时间线。", z.object({ module: moduleSchema, id: z.union([z.string(), z.number()]) }).passthrough()],
-    ["crm_get_action_records", "查询某条记录的操作记录。", z.object({ module: moduleSchema, id: z.union([z.string(), z.number()]) }).passthrough()],
-    ["crm_list_files", "只读查询附件元数据，不上传、不删除、不代理下载流。", z.object({ module: moduleSchema, id: z.union([z.string(), z.number()]) }).passthrough()],
+    ["crm_search_records", "查询模块分页列表。人员便捷参数和 user 筛选会解析为用户 ID，并使用后端支持的操作 3；日期/日期时间范围筛选必须使用操作 14。查询某人员某天的跟进记录时，module=activity，人员使用 createUserId(s)/createUserName(s)，createTime 使用 formType=datetime 和当天 00:00:00 至 23:59:59 的范围。", z.object({ module: moduleSchema, page: z.number().optional(), limit: z.number().optional(), ...crmUserSearchShape }).passthrough()],
+    ["crm_get_record", "按模块和 ID 查询单条 CRM 记录的完整对象；不返回详情页字段标签、记录动态、跟进列表或操作记录。", z.object({
+            module: moduleSchema.describe("CRM 模块 key、label 或别名；可先调用 crm_list_modules 获取。"),
+            id: idSchema.describe("目标 CRM 记录 ID；必须使用数字字符串。")
+        }).passthrough()],
+    ["crm_get_record_information", "查询 CRM 详情页字段展示数据，返回字段中文名和值；不返回完整记录对象、记录动态、跟进列表或操作记录。", z.object({
+            module: moduleSchema.describe("CRM 模块 key、label 或别名。"),
+            id: idSchema.describe("目标 CRM 记录 ID；必须使用数字字符串。")
+        }).passthrough()],
+    ["crm_get_related_records", "查询固定白名单内的 CRM 关联资料，例如商机产品、联系人商机、合同回款计划、产品上架列表；不查询记录动态、跟进记录或操作记录。", z.object({
+            module: moduleSchema.describe("CRM 模块 key、label 或别名。"),
+            id: idSchema.optional().describe("目标 CRM 记录 ID；具体 relation 不需要 ID 时可省略。"),
+            relation: z.string().describe("关联资料类型；必须是 MCP 固定白名单内的 relation。")
+        }).passthrough()],
+    ["crm_get_record_timeline", "查询某条 CRM 记录的系统动态时间线（如创建记录、字段变化、阶段变化）；固定调用 /crmActivity/queryActivityList，不返回跟进记录列表，也不是操作审计记录。", z.object({
+            module: moduleSchema.describe("CRM 模块 key、label 或别名，用于确定动态的 activityType。"),
+            id: idSchema.describe("目标 CRM 记录 ID；必须使用数字字符串。"),
+            page: z.number().int().positive().optional().describe("动态页码，默认 1。"),
+            limit: z.number().int().positive().max(200).optional().describe("每页动态条数，默认 15。"),
+            extra: z.record(z.unknown()).optional().describe("透传给动态查询接口的附加只读筛选参数。")
+        }).passthrough()],
+    ["crm_get_action_records", "查询某条 CRM 记录的操作审计记录；不返回记录动态或跟进记录列表。", z.object({
+            module: moduleSchema.describe("CRM 模块 key、label 或别名。"),
+            id: idSchema.describe("目标 CRM 记录 ID；必须使用数字字符串。")
+        }).passthrough()],
+    ["crm_list_files", "只读查询附件元数据，不上传、不删除、不代理下载流。", z.object({ module: moduleSchema, id: idSchema }).passthrough()],
     ["crm_search_products", "只读查询 CRM 产品列表；固定调用 /crmProduct/queryPageList，支持 keyword/categoryId/status 以及负责人、创建人的用户 ID 或唯一昵称筛选。", z.object({ page: z.number().optional(), limit: z.number().optional(), keyword: z.string().optional(), categoryId: idSchema.optional(), status: z.union([z.string(), z.number()]).optional(), ...crmUserSearchShape }).passthrough()],
     ["crm_search_sale_products", "只读查询 CRM 上架产品列表；固定调用 /crmProduct/querySaleProductPageList，支持负责人、创建人的用户 ID 或唯一昵称筛选。", z.object({ page: z.number().optional(), limit: z.number().optional(), keyword: z.string().optional(), categoryId: idSchema.optional(), ...crmUserSearchShape }).passthrough()],
     ["crm_get_product", "只读查询 CRM 产品详情；固定调用 /crmProduct/queryById/{productId}。", z.object({ productId: idSchema.optional(), id: idSchema.optional() }).passthrough()],
@@ -120,8 +244,8 @@ const toolDefinitions = [
     ["crm_write_jxc", "执行 JXC 域内固定路径写入；targetPath 必须以 /jxc 开头，或传 module+operation 组合，必须 confirm=true 才会写入。", z.object({ targetPath: z.string().optional(), path: z.string().optional(), endpoint: z.string().optional(), module: z.string().optional(), operation: z.string().optional(), confirm: z.boolean().optional() }).passthrough()],
     ["crm_create_jxc_record", "新增 JXC 产品、供应商或仓库主数据；固定调用对应 /add，必须 confirm=true。", z.object({ module: moduleSchema, confirm: z.boolean().optional() }).passthrough()],
     ["crm_update_jxc_record", "编辑 JXC 产品、供应商或仓库主数据；默认调用对应 /update，可传 useInformationUpdate=true 调用 /updateInformation，必须 confirm=true。", z.object({ module: moduleSchema, id: idSchema.optional(), confirm: z.boolean().optional(), useInformationUpdate: z.boolean().optional() }).passthrough()],
-    ["crm_list_calendar_events", "查询 OA 日历日程列表；固定调用 /oaEvent/queryList。startTime/endTime 使用 72CRM 接口要求的毫秒时间戳。", z.object({ startTime: z.union([z.string(), z.number()]), endTime: z.union([z.string(), z.number()]), typeIds: z.array(z.union([z.string(), z.number()])).optional(), userId: z.union([z.string(), z.number()]).optional() }).passthrough()],
-    ["crm_get_calendar_event", "查询 OA 日历单条日程详情；固定调用 /oaEvent/queryById。", z.object({ eventId: z.union([z.string(), z.number()]).optional(), id: z.union([z.string(), z.number()]).optional(), startTime: z.union([z.string(), z.number()]).optional(), endTime: z.union([z.string(), z.number()]).optional() }).passthrough()],
+    ["crm_list_calendar_events", "查询 OA 日历日程列表；固定调用 /oaEvent/queryList。startTime/endTime 使用 72CRM 接口要求的毫秒时间戳。", z.object({ startTime: z.union([z.string(), z.number()]), endTime: z.union([z.string(), z.number()]), typeIds: z.array(idSchema).optional(), userId: idSchema.optional() }).passthrough()],
+    ["crm_get_calendar_event", "查询 OA 日历单条日程详情；固定调用 /oaEvent/queryById。", z.object({ eventId: idSchema.optional(), id: idSchema.optional(), startTime: z.union([z.string(), z.number()]).optional(), endTime: z.union([z.string(), z.number()]).optional() }).passthrough()],
     ["crm_list_oa_announcements", "查询 OA 公告列表；固定调用 /oaAnnouncement/queryList。", z.object({ page: z.number().optional(), limit: z.number().optional(), type: z.union([z.string(), z.number()]).optional() }).passthrough()],
     ["crm_get_oa_announcement", "查询 OA 公告详情；固定调用 /oaAnnouncement/queryById/{announcementId}。", z.object({ announcementId: idSchema.optional(), id: idSchema.optional() }).passthrough()],
     ["crm_create_oa_announcement", "新增 OA 公告；固定调用 /oaAnnouncement/addAnnouncement，必须 confirm=true。", z.object({ confirm: z.boolean().optional() }).passthrough()],
@@ -146,11 +270,11 @@ const toolDefinitions = [
     ["crm_list_oa_examine_record_logs", "只读查询 OA 审批流转日志；固定调用 /examineRecord/queryExamineRecordLog。", z.object({ recordId: idSchema.optional(), examineRecordId: idSchema.optional(), id: idSchema.optional() }).passthrough()],
     ["crm_list_oa_examine_flow_records", "只读查询 OA 审批流程节点记录；固定调用 /examineSuperExamine/examine/record/list。", z.object({ recordId: idSchema.optional(), examineRecordId: idSchema.optional(), id: idSchema.optional() }).passthrough()],
     ["crm_list_oa_tasks", "查询 OA 任务列表；固定调用 /oaTask/queryTaskList。", z.object({ page: z.number().optional(), limit: z.number().optional(), type: z.number().optional(), status: z.number().optional(), priority: z.number().optional() }).passthrough()],
-    ["crm_list_related_oa_tasks", "按关联业务查询 OA 任务；固定调用 /oaTask/queryTypeTaskList。", z.object({ type: z.union([z.string(), z.number()]), typeId: z.union([z.string(), z.number()]) }).passthrough()],
+    ["crm_list_related_oa_tasks", "按关联业务查询 OA 任务；固定调用 /oaTask/queryTypeTaskList。", z.object({ type: z.union([z.string(), z.number()]), typeId: idSchema }).passthrough()],
     ["crm_preview_write", "写入前预览和校验，不调用 72CRM 写接口。", passthroughSchema],
-    ["crm_create_record", "新增线索、客户、联系人、产品、商机；系统字段放 entity，自定义字段放 field，不支持把 customerName 放在最外层；必须 confirm=true 才会写入。", crmCreateRecordSchema],
+    ["crm_create_record", "新增线索、客户、联系人、产品、商机；系统字段放 entity，自定义字段放 field，不支持把 customerName 放在最外层。新增商机必须先用 crm_get_business_status_groups 获取合法的 entity.typeId/statusId，并提供 businessName/customerId；必须 confirm=true 才会写入。", crmCreateRecordSchema],
     ["crm_update_customer", "按客户 ID 或手机号/客户名唯一匹配后更新客户字段；会自动补全字段结构并写后校验，必须 confirm=true 才会写入。", z.object({ confirm: z.boolean().optional() }).passthrough()],
-    ["crm_update_record_fields", "更新线索、客户、联系人、产品、商机基础字段；必须 confirm=true 才会写入。", z.object({ module: moduleSchema, id: z.union([z.string(), z.number()]), confirm: z.boolean().optional() }).passthrough()],
+    ["crm_update_record_fields", "更新线索、客户、联系人、产品、商机基础字段；必须 confirm=true 才会写入。", z.object({ module: moduleSchema, id: idSchema, confirm: z.boolean().optional() }).passthrough()],
     ["crm_create_product", "新增 CRM 产品；固定调用 /crmProduct/add，可直接传 72CRM payload 或 entity/field，必须 confirm=true。", z.object({ confirm: z.boolean().optional() }).passthrough()],
     ["crm_update_product", "编辑 CRM 产品；固定调用 /crmProduct/update，必须传 productId/id，必须 confirm=true。", z.object({ productId: idSchema.optional(), id: idSchema.optional(), confirm: z.boolean().optional() }).passthrough()],
     ["crm_update_product_fields", "更新 CRM 产品基础字段；固定调用 /crmProduct/updateInformation，会自动补字段结构，必须 confirm=true。", z.object({ productId: idSchema.optional(), id: idSchema.optional(), confirm: z.boolean().optional() }).passthrough()],
@@ -168,7 +292,7 @@ const toolDefinitions = [
     ["crm_create_quotation", "新增报价单；固定调用 /crmQuotation/add，可直接传 72CRM payload，或传 fields/updates 自动组装 entity/field/product/examineFlowData，必须 confirm=true。", z.object({ confirm: z.boolean().optional(), draft: z.boolean().optional() }).passthrough()],
     ["crm_update_quotation", "编辑报价单；固定调用 /crmQuotation/update，必须传 quotationId/id，可直接传 72CRM payload，或传 fields/updates 自动组装，必须 confirm=true。", z.object({ quotationId: idSchema.optional(), id: idSchema.optional(), confirm: z.boolean().optional(), draft: z.boolean().optional() }).passthrough()],
     ["crm_create_calendar_event", "新增 OA 日历日程；支持 72CRM SetEventBO 结构或顶层便捷字段，必须 confirm=true 才会写入。", z.object({ confirm: z.boolean().optional() }).passthrough()],
-    ["crm_update_calendar_event", "修改 OA 日历日程；支持 72CRM SetEventBO 结构或顶层便捷字段，必须 confirm=true 才会写入。", z.object({ eventId: z.union([z.string(), z.number()]).optional(), id: z.union([z.string(), z.number()]).optional(), confirm: z.boolean().optional() }).passthrough()],
+    ["crm_update_calendar_event", "修改 OA 日历日程；支持 72CRM SetEventBO 结构或顶层便捷字段，必须 confirm=true 才会写入。", z.object({ eventId: idSchema.optional(), id: idSchema.optional(), confirm: z.boolean().optional() }).passthrough()],
     ["crm_create_oa_log", "新增 OA 日志；固定调用 /oaLog/addOrUpdate，可直接传 payload，或传 categoryId+fields 自动组装日志模板字段，必须 confirm=true。", z.object({ categoryId: idSchema.optional(), confirm: z.boolean().optional() }).passthrough()],
     ["crm_update_oa_log", "编辑 OA 日志；固定调用 /oaLog/addOrUpdate，必须传 logId/id，可直接传 payload 或自动组装字段，必须 confirm=true。", z.object({ logId: idSchema.optional(), id: idSchema.optional(), categoryId: idSchema.optional(), confirm: z.boolean().optional() }).passthrough()],
     ["crm_delete_oa_log", "删除 OA 日志；固定调用 /oaLog/deleteById，logId 走查询参数，必须 confirm=true。", z.object({ logId: idSchema.optional(), id: idSchema.optional(), confirm: z.boolean().optional() }).passthrough()],
@@ -178,9 +302,9 @@ const toolDefinitions = [
     ["crm_audit_oa_examine", "处理单条 OA 审批；固定调用 /examineRecord/auditExamine，必须传 recordId/examineRecordId/id 且 confirm=true。", z.object({ recordId: idSchema.optional(), examineRecordId: idSchema.optional(), id: idSchema.optional(), confirm: z.boolean().optional() }).passthrough()],
     ["crm_batch_audit_oa_examine", "批量处理 OA 审批；固定调用 /examineRecord/batchAuditExamine，必须传 recordIds/examineRecordIds/ids 且 confirm=true。", z.object({ recordIds: z.array(idSchema).optional(), examineRecordIds: z.array(idSchema).optional(), ids: z.array(idSchema).optional(), confirm: z.boolean().optional() }).passthrough()],
     ["crm_create_oa_task", "新增 OA 主任务；固定调用 /workTask/saveWorkTask，支持 WorkTask 结构或顶层便捷字段，必须 confirm=true 才会写入。", z.object({ confirm: z.boolean().optional() }).passthrough()],
-    ["crm_update_oa_task_fields", "更新 OA 主任务字段；按字段映射到 /workTask 下的标题、描述、负责人、参与人、时间、标签、优先级、状态接口，必须 confirm=true 才会写入。", z.object({ taskId: z.union([z.string(), z.number()]).optional(), id: z.union([z.string(), z.number()]).optional(), confirm: z.boolean().optional() }).passthrough()],
-    ["crm_add_followup", "新增跟进记录；必须 confirm=true 才会写入。", z.object({ confirm: z.boolean().optional() }).passthrough()],
-    ["crm_update_followup", "更新跟进记录；必须 confirm=true 才会写入。", z.object({ id: z.union([z.string(), z.number()]).optional(), confirm: z.boolean().optional() }).passthrough()],
+    ["crm_update_oa_task_fields", "更新 OA 主任务字段；按字段映射到 /workTask 下的标题、描述、负责人、参与人、时间、标签、优先级、状态接口，必须 confirm=true 才会写入。", z.object({ taskId: idSchema.optional(), id: idSchema.optional(), confirm: z.boolean().optional() }).passthrough()],
+    ["crm_add_followup", "新增跟进记录；entity 必须提供 content、category、activityType 和 activityTypeId，MCP 会先回读关联记录再写入；必须 confirm=true 才会写入。", crmAddFollowupSchema],
+    ["crm_update_followup", "更新跟进记录；完整更新必须提供 entity，字段更新使用 useInformationUpdate=true 和 list；必须 confirm=true 才会写入。", crmUpdateFollowupSchema],
     ["workorder_search_records", "查询工单、工单池或线下工单；scope 可选 workorder、pool、offline。", z.object({ scope: z.enum(["workorder", "pool", "offline"]).optional(), page: z.number().optional(), limit: z.number().optional() }).passthrough()],
     ["workorder_get_record", "查询普通工单或线下工单详情及详情字段；不执行状态流转。", z.object({ scope: z.enum(["workorder", "offline"]).optional(), id: idSchema }).passthrough()],
     ["workorder_get_schema", "查询普通工单或线下工单字段结构，可传 id 获取编辑字段。", z.object({ scope: z.enum(["workorder", "offline"]).optional(), id: idSchema.optional() }).passthrough()],
@@ -192,9 +316,13 @@ export function createWukongMcpServer(config = {}) {
     const { oauth, ...crmConfig } = config;
     const server = new McpServer({
         name: "wukong-mcp",
-        version: "0.2.4"
+        version: "0.2.6"
     }, {
         instructions: "先使用只读工具确认模块、记录和字段，再执行写入。所有写入必须显式传 confirm=true；不要尝试任意 URL 请求。"
+            + "所有 ID 必须使用数字字符串，禁止把 Snowflake ID 作为 JSON number 传入。"
+            + "写工具正常返回且 writeOutcome=confirmed 即表示成功；data=null 只表示旧 CRM 未返回业务数据。"
+            + "工具返回错误时不得声称原操作成功，也不得未经用户明确同意改用 OA 任务等其他模块替代。"
+            + "写入错误若标记 writeOutcome=unknown，必须先回读原目标确认是否落库，禁止直接重放。"
     });
     const sharedClient = new CrmClient(crmConfig);
     const handlers = {
@@ -206,21 +334,23 @@ export function createWukongMcpServer(config = {}) {
             name,
             description,
             schema,
-            access: toolAccess(name, description),
-            destructive: isDestructiveTool(name)
+            access: toolAccess(name),
+            destructive: isDestructiveTool(name),
+            discovery: getToolDiscovery(name, description)
         })),
         ...nocodeToolDefinitions.map((definition) => ({
             ...definition,
-            destructive: definition.destructive ?? false
+            destructive: definition.destructive ?? false,
+            discovery: getToolDiscovery(definition.name, definition.description)
         }))
     ];
-    for (const { name, description, schema, access, destructive } of registeredTools) {
+    for (const { name, description, schema, access, destructive, discovery } of registeredTools) {
         const requiredScopes = access === "write"
             ? [CRM_READ_SCOPE, CRM_WRITE_SCOPE]
             : [CRM_READ_SCOPE];
         const securitySchemes = [{ type: "oauth2", scopes: requiredScopes }];
         server.registerTool(name, {
-            title: name,
+            title: discovery.title,
             description,
             inputSchema: schema,
             outputSchema: toolOutputSchema,
@@ -231,8 +361,9 @@ export function createWukongMcpServer(config = {}) {
                 ...(access === "read" ? { idempotentHint: true } : {})
             },
             _meta: {
-                // ChatGPT 在扫描工具时会读取这个兼容字段。
-                securitySchemes
+                // securitySchemes 供通用 MCP 客户端鉴权；命名空间字段供宿主做确定性发现，不进入业务参数。
+                securitySchemes,
+                [TOOL_DISCOVERY_META_KEY]: discovery.meta
             }
         }, async (args) => {
             const missingScopes = oauth
@@ -246,8 +377,9 @@ export function createWukongMcpServer(config = {}) {
                 if (!handler) {
                     throw new Error(`未找到工具实现：${name}`);
                 }
-                const result = await handler(args ?? {});
-                return toToolResult(result);
+                const normalizedArgs = normalizeToolArguments(args ?? {});
+                const result = await handler(normalizedArgs);
+                return toToolResult(access === "write" ? withSuccessfulWriteOutcome(result) : result);
             }
             catch (error) {
                 return {
@@ -275,14 +407,59 @@ function toToolResult(result) {
         ]
     };
 }
-function toolAccess(name, description) {
-    if (name === "crm_preview_write") {
-        return "read";
+function withSuccessfulWriteOutcome(result) {
+    if (isRecord(result) && result.preview === true) {
+        return result;
     }
-    return description.includes("confirm=true") ? "write" : "read";
+    const details = isRecord(result) ? result : { data: result ?? null };
+    return {
+        ...details,
+        success: true,
+        requestAccepted: true,
+        crmCode: 0,
+        writeOutcome: "confirmed"
+    };
+}
+function normalizeToolArguments(value, path = "arguments") {
+    if (Array.isArray(value)) {
+        return value.map((item, index) => normalizeToolArguments(item, `${path}[${index}]`));
+    }
+    if (!isRecord(value)) {
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => {
+        const itemPath = `${path}.${key}`;
+        return [key, isIdFieldName(key)
+                ? normalizeIdFieldValue(item, itemPath)
+                : normalizeToolArguments(item, itemPath)];
+    }));
+}
+function normalizeIdFieldValue(value, path) {
+    if (Array.isArray(value)) {
+        return value.map((item, index) => normalizeIdFieldValue(item, `${path}[${index}]`));
+    }
+    if (isRecord(value)) {
+        return normalizeToolArguments(value, path);
+    }
+    if (typeof value !== "number") {
+        return value;
+    }
+    if (!Number.isSafeInteger(value)) {
+        throw new Error(`${path} 使用了不安全的 JSON number，原始 ID 可能已丢失精度；请改用数字字符串。`);
+    }
+    return String(value);
+}
+function isIdFieldName(key) {
+    return key === "id" || key === "ids" || /Ids?$/.test(key) || /_ids?$/i.test(key);
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function toolAccess(name) {
+    return Object.hasOwn(WRITE_TOOL_SAFETY, name) ? "write" : "read";
 }
 function isDestructiveTool(name) {
-    return /^crm_(?:update|delete|transfer|toggle|audit|batch_audit|write|save)_/.test(name);
+    return WRITE_TOOL_SAFETY[name]?.destructive ?? false;
 }
 function insufficientScopeResult(requiredScopes, missingScopes, resourceMetadataUrl) {
     const requiredScopeText = requiredScopes.join(" ");

package/dist/tool-discovery.d.ts

@@ -0,0 +1,18 @@
+export declare const TOOL_DISCOVERY_META_KEY = "com.wukongcrm/tool-discovery";
+export interface ToolDiscoveryMeta {
+    version: 1;
+    domain: string;
+    module: string;
+    entities: string[];
+    actions: string[];
+    capability: string;
+    aliases: string[];
+    excludes?: string[];
+    requires?: string[];
+    verifiesWith?: string[];
+}
+export interface ToolDiscoveryDefinition {
+    title: string;
+    meta: ToolDiscoveryMeta;
+}
+export declare function getToolDiscovery(name: string, _description: string): ToolDiscoveryDefinition;

package/dist/tool-discovery.js

@@ -0,0 +1,186 @@
+import { CRM_MODULES } from "./modules.js";
+export const TOOL_DISCOVERY_META_KEY = "com.wukongcrm/tool-discovery";
+const CRM_ENTITIES = CRM_MODULES.flatMap((definition) => [definition.key, definition.name]);
+// 这批工具容易因“详情、动态、跟进、操作记录”等相邻概念误选，元数据按真实接口语义显式区分。
+const CORE_DISCOVERY = {
+    crm_search_records: {
+        title: "搜索 CRM 记录",
+        domain: "crm",
+        module: "record",
+        entities: CRM_ENTITIES,
+        actions: ["search", "list", "查询", "搜索"],
+        capability: "crm.record.search",
+        aliases: ["查询客户", "搜索联系人", "商机列表", "按负责人查询", "查询跟进记录"],
+        excludes: ["单条详情", "记录动态", "操作记录"]
+    },
+    crm_get_record: {
+        title: "查询 CRM 单条记录",
+        domain: "crm",
+        module: "record",
+        entities: CRM_ENTITIES,
+        actions: ["get", "read", "查询", "查看"],
+        capability: "crm.record.detail.read",
+        aliases: ["记录详情", "客户详情", "联系人详情", "商机详情", "按 ID 查询记录", "确认目标记录"],
+        excludes: ["详情页字段", "记录动态", "跟进记录列表", "操作记录", "关联资料"]
+    },
+    crm_get_record_information: {
+        title: "查询 CRM 详情页字段",
+        domain: "crm",
+        module: "record-information",
+        entities: CRM_ENTITIES,
+        actions: ["get", "read", "查询", "查看"],
+        capability: "crm.record.field-information.read",
+        aliases: ["详情页信息", "字段中文名和值", "基本信息字段", "详情字段展示"],
+        excludes: ["完整记录对象", "记录动态", "跟进记录列表", "操作记录"]
+    },
+    crm_get_related_records: {
+        title: "查询 CRM 关联资料",
+        domain: "crm",
+        module: "record-relation",
+        entities: CRM_ENTITIES,
+        actions: ["get", "read", "查询"],
+        capability: "crm.record.relation.read",
+        aliases: ["关联资料", "关联数据", "相关产品", "相关联系人", "回款计划"],
+        excludes: ["记录动态", "跟进记录", "操作记录"]
+    },
+    crm_get_record_timeline: {
+        title: "查询 CRM 记录动态",
+        domain: "crm",
+        module: "record-dynamics",
+        entities: CRM_ENTITIES,
+        actions: ["get", "read", "查询"],
+        capability: "crm.record.dynamics.read",
+        aliases: ["记录动态", "动态时间线", "创建记录", "字段变化", "阶段变化", "系统动态"],
+        excludes: ["跟进记录列表", "操作审计记录", "市场活动", "关联资料"]
+    },
+    crm_get_action_records: {
+        title: "查询 CRM 操作记录",
+        domain: "crm",
+        module: "record-audit",
+        entities: CRM_ENTITIES,
+        actions: ["get", "read", "查询"],
+        capability: "crm.record.audit-log.read",
+        aliases: ["操作记录", "变更日志", "审计记录", "操作审计"],
+        excludes: ["记录动态", "跟进记录列表"]
+    },
+    crm_get_business_status_groups: {
+        title: "查询商机状态组",
+        domain: "crm",
+        module: "business",
+        entities: ["business", "商机", "商机状态组", "商机阶段"],
+        actions: ["get", "read", "查询"],
+        capability: "crm.business.status.read",
+        aliases: ["商机状态组", "商机阶段", "创建商机前置", "typeId", "statusId"],
+        excludes: ["创建商机记录"]
+    },
+    crm_create_record: {
+        title: "新建 CRM 记录",
+        domain: "crm",
+        module: "record",
+        entities: ["leads", "线索", "customer", "客户", "contacts", "联系人", "product", "产品", "business", "商机"],
+        actions: ["create", "add", "创建", "新增"],
+        capability: "crm.record.create",
+        aliases: ["创建客户", "新增联系人", "新建产品", "创建商机", "新增线索"],
+        // 聚合创建只在目标实体为商机时需要该前置能力；消费者应结合依赖工具的 entities 判断是否联动发现。
+        requires: ["crm.business.status.read"],
+        verifiesWith: ["crm.record.detail.read"]
+    },
+    crm_add_followup: {
+        title: "新增 CRM 跟进记录",
+        domain: "crm",
+        module: "followup",
+        entities: ["activity", "跟进记录", "线索", "客户", "联系人", "产品", "商机", "合同", "回款", "回款计划", "回访", "报价单"],
+        actions: ["create", "add", "创建", "新增"],
+        capability: "crm.followup.create",
+        aliases: ["创建跟进记录", "新增跟进", "写跟进内容", "记录拜访结果"],
+        excludes: ["查询跟进记录", "记录动态"],
+        verifiesWith: ["crm.record.detail.read"]
+    },
+    nocode_search_records: {
+        title: "搜索无代码记录",
+        domain: "nocode",
+        module: "record",
+        entities: ["nocode-record", "无代码记录", "应用记录", "模块记录"],
+        actions: ["search", "list", "查询", "搜索"],
+        capability: "nocode.record.search",
+        aliases: ["查询无代码模块记录", "应用数据列表", "搜索模块数据"]
+    },
+    nocode_write_record: {
+        title: "写入无代码记录",
+        domain: "nocode",
+        module: "record",
+        entities: ["nocode-record", "无代码记录", "应用记录", "模块记录"],
+        actions: ["create", "update", "delete", "创建", "修改", "删除"],
+        capability: "nocode.record.write",
+        aliases: ["新增无代码记录", "修改应用数据", "删除模块记录"],
+        verifiesWith: ["nocode.record.search"]
+    }
+};
+const ACTION_BY_VERB = {
+    list: "list",
+    search: "search",
+    query: "query",
+    get: "get",
+    find: "search",
+    auth: "read",
+    validate: "validate",
+    preview: "preview",
+    calculate: "calculate",
+    check: "validate",
+    create: "create",
+    add: "create",
+    save: "create",
+    update: "update",
+    write: "write",
+    delete: "delete",
+    transfer: "transfer",
+    toggle: "update",
+    audit: "audit",
+    batch: "batch"
+};
+function inferDomainAndModule(name) {
+    if (name.startsWith("nocode_"))
+        return { domain: "nocode", module: "nocode" };
+    if (name.startsWith("workorder_"))
+        return { domain: "workorder", module: "workorder" };
+    if (name.startsWith("project_"))
+        return { domain: "project", module: "project" };
+    if (name.includes("_hrm_"))
+        return { domain: "hrm", module: "hrm" };
+    if (name.includes("_finance_"))
+        return { domain: "finance", module: "finance" };
+    if (name.includes("_jxc_"))
+        return { domain: "jxc", module: "jxc" };
+    if (name.includes("_oa_") || name.includes("_calendar_") || name.includes("_address_book_")) {
+        return { domain: "oa", module: "oa" };
+    }
+    return { domain: "crm", module: "crm" };
+}
+function inferAction(name) {
+    const prefix = name.startsWith("workorder_") ? "workorder_"
+        : name.startsWith("project_") ? "project_"
+            : name.startsWith("nocode_") ? "nocode_" : "crm_";
+    const verb = name.slice(prefix.length).split("_")[0] ?? "read";
+    return ACTION_BY_VERB[verb] ?? verb;
+}
+export function getToolDiscovery(name, _description) {
+    const inferred = inferDomainAndModule(name);
+    const override = CORE_DISCOVERY[name];
+    const action = inferAction(name);
+    return {
+        title: override?.title ?? name,
+        meta: {
+            version: 1,
+            domain: override?.domain ?? inferred.domain,
+            module: override?.module ?? inferred.module,
+            entities: override?.entities ?? [inferred.module],
+            actions: override?.actions ?? [action],
+            capability: override?.capability ?? `wukong.${name.replaceAll("_", ".")}`,
+            // 长尾工具先依靠标准 description/Schema 降级检索；未经源码确认的“同义词”不能伪装成 aliases。
+            aliases: override?.aliases ?? [],
+            ...(override?.excludes ? { excludes: override.excludes } : {}),
+            ...(override?.requires ? { requires: override.requires } : {}),
+            ...(override?.verifiesWith ? { verifiesWith: override.verifiesWith } : {})
+        }
+    };
+}