@wukongcrm/mcp-server 0.2.4 → 0.2.5

package/README.md

@@ -397,13 +397,34 @@ wukong-mcp
     {
       "fieldName": "ownerUserId",
       "formType": "user",
-      "type": 1,
+      "type": 3,
       "values": ["张三"]
     }
   ]
 }
 ```
 
+旧 CRM 的人员筛选只会处理操作 `3`（包含）、`4`（不包含）、`5`（为空）和 `6`（不为空）；其中按人员 ID 匹配必须使用 `type=3`。MCP 的人员便捷参数会固定生成操作 `3`，显式传入未实现的人员操作会在请求后端前报错，避免返回未按人员过滤的数据。
+
+日期字段必须明确传 `formType=date` 或 `formType=datetime`。固定范围使用操作 `14`，`values` 按开始、结束顺序提供两个值；`date` 使用 `YYYY-MM-DD`，`datetime` 使用 `YYYY-MM-DD HH:mm:ss`。查询完整自然日时，边界为当天 `00:00:00` 和 `23:59:59`，后端范围两端均包含：
+
+```json
+{
+  "module": "activity",
+  "createUserName": "<人员唯一昵称>",
+  "filters": [
+    {
+      "fieldName": "createTime",
+      "formType": "datetime",
+      "type": 14,
+      "values": ["YYYY-MM-DD 00:00:00", "YYYY-MM-DD 23:59:59"]
+    }
+  ]
+}
+```
+
+`filters` 和 `searchList` 是同一个高级筛选参数的两个名称，只能选一个。每项必须提供字段名和 `type`/`searchEnum`；两种操作码同时出现时必须相同。除操作 `5`/`6` 外必须提供非空 `values`。日期范围也可传后端已有的单个预设时间值（例如 `today`、`week`、`month`）；不支持的操作、无效日期、倒置边界和缺失值会明确报错。
+
 如需单独核对用户 ID，可调用 `crm_find_user_id`：
 
 ```json

package/dist/server.js

@@ -13,13 +13,16 @@ const idSchema = z.union([z.string(), z.number()]);
 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("筛选值数组。除为空/不为空操作 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,
@@ -32,16 +35,16 @@ const crmCreateRecordSchema = z.object({
     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()],
@@ -49,7 +52,7 @@ const toolDefinitions = [
     ["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_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_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, 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()],
@@ -192,7 +195,7 @@ export function createWukongMcpServer(config = {}) {
     const { oauth, ...crmConfig } = config;
     const server = new McpServer({
         name: "wukong-mcp",
-        version: "0.2.4"
+        version: "0.2.5"
     }, {
         instructions: "先使用只读工具确认模块、记录和字段，再执行写入。所有写入必须显式传 confirm=true；不要尝试任意 URL 请求。"
     });

package/dist/tools.js

@@ -1746,6 +1746,10 @@ function extractSavedWorkorderId(data, prepared) {
     return data?.workorderId ?? prepared.body.entity?.workorderId;
 }
 const FIELD_SEARCH_CONTAINS = 3;
+const FIELD_SEARCH_NOT_CONTAINS = 4;
+const FIELD_SEARCH_IS_NULL = 5;
+const FIELD_SEARCH_IS_NOT_NULL = 6;
+const FIELD_SEARCH_RANGE = 14;
 const QUICK_SEARCH_FIELDS = {
     leads: [
         { fieldName: "leadsName", formType: "text" },
@@ -1822,6 +1826,42 @@ const NAME_FIELD_BY_MODULE = {
 };
 const USER_FILTER_FORM_TYPES = new Set(["user", "single_user"]);
 const USER_FILTER_FIELD_NAMES = new Set(["ownerUserId", "createUserId"]);
+const DATE_FILTER_FORM_TYPES = new Set(["date", "datetime"]);
+const NUMBER_RANGE_FORM_TYPES = new Set(["number", "floatnumber", "percent", "field_attention"]);
+const USER_FILTER_OPERATIONS = new Set([
+    FIELD_SEARCH_CONTAINS,
+    FIELD_SEARCH_NOT_CONTAINS,
+    FIELD_SEARCH_IS_NULL,
+    FIELD_SEARCH_IS_NOT_NULL
+]);
+const DATE_FILTER_OPERATIONS = new Set([1, 2, 5, 6, 7, 8, 9, 10, FIELD_SEARCH_RANGE]);
+const PRESET_DATE_RANGES = new Set([
+    "year",
+    "lastYear",
+    "quarter",
+    "lastQuarter",
+    "month",
+    "lastMonth",
+    "week",
+    "lastWeek",
+    "today",
+    "yesterday",
+    "nextYear",
+    "firstHalfYear",
+    "nextHalfYear",
+    "nextQuarter",
+    "nextMonth",
+    "nextWeek",
+    "tomorrow",
+    "previous7day",
+    "previous30day",
+    "future7day",
+    "future30day",
+    "recently7day",
+    "recently30day",
+    "recently60day",
+    "recentlyHalfYear"
+]);
 const USER_FILTER_ARGUMENTS = [
     {
         fieldName: "ownerUserId",
@@ -1837,9 +1877,13 @@ const USER_FILTER_ARGUMENTS = [
 async function buildResolvedSearchList(client, args, moduleDefinition) {
     const searchList = buildSearchList(args, moduleDefinition);
     const userSearchList = buildConvenienceUserSearchList(args);
-    return resolveUserSearchFilters(client, combineSearchLists(searchList, userSearchList), args.companyId);
+    const validatedSearchList = validateSearchFilters(combineSearchLists(searchList, userSearchList));
+    return resolveUserSearchFilters(client, validatedSearchList, args.companyId);
 }
 function buildSearchList(args, moduleDefinition) {
+    if (args.filters !== undefined && args.searchList !== undefined) {
+        throw new Error("filters 和 searchList 不能同时提供，请只使用其中一个高级筛选参数。");
+    }
     const explicitSearchList = toArray(args.filters ?? args.searchList);
     const semanticSearchList = buildSemanticSearchList(args, moduleDefinition);
     return combineSearchLists(explicitSearchList, semanticSearchList);
@@ -1853,12 +1897,126 @@ function buildConvenienceUserSearchList(args) {
         return [{
                 fieldName,
                 formType: "user",
-                type: 1,
-                searchEnum: 1,
+                // 旧 CRM 的 EsUtil.userSearch 只有 CONTAINS(3) 才会生成用户 ID terms 查询。
+                type: FIELD_SEARCH_CONTAINS,
+                searchEnum: FIELD_SEARCH_CONTAINS,
                 values
             }];
     });
 }
+function validateSearchFilters(filters) {
+    return filters.map((filter, index) => {
+        if (!isPlainObject(filter)) {
+            throw new Error(`高级筛选第 ${index + 1} 项必须是对象。`);
+        }
+        const fieldName = firstTextValue(filter.fieldName, filter.name);
+        if (!fieldName) {
+            throw new Error(`高级筛选第 ${index + 1} 项请提供 fieldName（或兼容字段 name）。`);
+        }
+        const typeOperation = parseSearchOperation(filter.type, "type", fieldName);
+        const enumOperation = parseSearchOperation(filter.searchEnum, "searchEnum", fieldName);
+        if (typeOperation !== undefined && enumOperation !== undefined && typeOperation !== enumOperation) {
+            throw new Error(`筛选“${fieldName}”的 type=${typeOperation} 与 searchEnum=${enumOperation} 冲突，请保持一致或只提供一个。`);
+        }
+        const operation = enumOperation ?? typeOperation;
+        if (operation === undefined) {
+            throw new Error(`筛选“${fieldName}”请提供 type 或 searchEnum。`);
+        }
+        if (filter.values !== undefined && !Array.isArray(filter.values)) {
+            throw new Error(`筛选“${fieldName}”的 values 必须是数组。`);
+        }
+        const values = valueArray(filter.values);
+        const isNullOperation = operation === FIELD_SEARCH_IS_NULL || operation === FIELD_SEARCH_IS_NOT_NULL;
+        if (!isNullOperation && values.length === 0) {
+            throw new Error(`筛选“${fieldName}”使用操作 ${operation} 时请提供 values。`);
+        }
+        const formType = String(filter.formType ?? "").trim().toLowerCase();
+        const userFilter = USER_FILTER_FORM_TYPES.has(formType) || USER_FILTER_FIELD_NAMES.has(fieldName);
+        if (userFilter && !USER_FILTER_OPERATIONS.has(operation)) {
+            throw new Error(`人员筛选“${fieldName}”使用了后端未实现的操作 ${operation}；仅支持 3、4、5、6。按人员 ID 匹配请使用操作 3。`);
+        }
+        if (DATE_FILTER_FORM_TYPES.has(formType)) {
+            validateDateFilter(fieldName, formType, operation, values);
+        }
+        else if (operation === FIELD_SEARCH_RANGE) {
+            if (!NUMBER_RANGE_FORM_TYPES.has(formType)) {
+                throw new Error(`筛选“${fieldName}”的范围操作 14 仅支持 date、datetime 或数字类型 formType。`);
+            }
+            if (values.length !== 2 || values.some((value) => !isFiniteNumberValue(value))) {
+                throw new Error(`数字筛选“${fieldName}”的范围操作 14 必须提供两个有效数字边界值。`);
+            }
+        }
+        // formType 大小写错误会让后端退回文本搜索；这里统一为契约中的小写值。
+        const normalizedFilter = formType ? { ...filter, formType } : filter;
+        return DATE_FILTER_FORM_TYPES.has(formType) && values.length > 0
+            ? { ...normalizedFilter, values: values.map((value) => String(value).trim()) }
+            : normalizedFilter;
+    });
+}
+function parseSearchOperation(value, key, fieldName) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    const text = String(value).trim();
+    if (!/^\d+$/.test(text)) {
+        throw new Error(`筛选“${fieldName}”的 ${key} 必须是 1 到 14 的整数操作码。`);
+    }
+    const operation = Number(text);
+    if (!Number.isInteger(operation) || operation < 1 || operation > 14) {
+        throw new Error(`筛选“${fieldName}”的 ${key}=${text} 不受支持；操作码范围为 1 到 14。`);
+    }
+    return operation;
+}
+function validateDateFilter(fieldName, formType, operation, values) {
+    if (!DATE_FILTER_OPERATIONS.has(operation)) {
+        throw new Error(`日期筛选“${fieldName}”的操作 ${operation} 不受后端支持；范围筛选请使用操作 14。`);
+    }
+    if (operation === FIELD_SEARCH_IS_NULL || operation === FIELD_SEARCH_IS_NOT_NULL) {
+        return;
+    }
+    if (operation === FIELD_SEARCH_RANGE && values.length === 1) {
+        const preset = typeof values[0] === "string" ? values[0].trim() : "";
+        if (PRESET_DATE_RANGES.has(preset)) {
+            return;
+        }
+        throw new Error(`日期筛选“${fieldName}”的范围操作 14 请提供两个边界值，或单个受支持的预设时间值。`);
+    }
+    const expectedValueCount = operation === FIELD_SEARCH_RANGE ? 2 : 1;
+    if (values.length !== expectedValueCount) {
+        throw new Error(`日期筛选“${fieldName}”的操作 ${operation} 必须提供 ${expectedValueCount} 个时间值。`);
+    }
+    const normalizedValues = values.map((value) => typeof value === "string" ? value.trim() : "");
+    if (normalizedValues.some((value) => !isValidDateValue(value, formType))) {
+        const format = formType === "datetime" ? "YYYY-MM-DD HH:mm:ss" : "YYYY-MM-DD";
+        throw new Error(`日期筛选“${fieldName}”的 values 必须使用 ${format} 格式，并且是有效日期。`);
+    }
+    if (operation === FIELD_SEARCH_RANGE && normalizedValues[0] > normalizedValues[1]) {
+        throw new Error(`日期筛选“${fieldName}”的开始值不能晚于结束值。`);
+    }
+}
+function isValidDateValue(value, formType) {
+    const match = formType === "datetime"
+        ? /^(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2})$/.exec(value)
+        : /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+    if (!match) {
+        return false;
+    }
+    const [, yearText, monthText, dayText, hourText = "0", minuteText = "0", secondText = "0"] = match;
+    const year = Number(yearText);
+    const month = Number(monthText);
+    const day = Number(dayText);
+    const hour = Number(hourText);
+    const minute = Number(minuteText);
+    const second = Number(secondText);
+    const maxDay = month >= 1 && month <= 12 ? new Date(Date.UTC(year, month, 0)).getUTCDate() : 0;
+    return day >= 1 && day <= maxDay && hour <= 23 && minute <= 59 && second <= 59;
+}
+function isFiniteNumberValue(value) {
+    if (typeof value === "number") {
+        return Number.isFinite(value);
+    }
+    return typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value));
+}
 function argumentValues(args, keys) {
     return keys.flatMap((key) => valueArray(args[key]));
 }
@@ -1922,7 +2080,9 @@ async function resolveUserSearchFilters(client, searchList, companyId) {
         }
         resolvedFilters.push({
             ...filter,
-            formType: filter.formType ?? "user",
+            formType: USER_FILTER_FORM_TYPES.has(String(filter.formType ?? "").trim().toLowerCase())
+                ? String(filter.formType).trim().toLowerCase()
+                : "user",
             values: [...new Set(values)]
         });
     }
@@ -2051,7 +2211,7 @@ function toArray(value) {
     return [];
 }
 async function resolveUniqueRecord(client, moduleDefinition, args) {
-    const searchList = await resolveUserSearchFilters(client, buildSearchList(args, moduleDefinition), args.companyId);
+    const searchList = await resolveUserSearchFilters(client, validateSearchFilters(buildSearchList(args, moduleDefinition)), args.companyId);
     if (searchList.length === 0) {
         throw new Error(`请提供可定位${moduleDefinition.name}的 customerId/id、phone/mobile、name/customerName 或 keyword。`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wukongcrm/mcp-server",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Local and remote MCP server for fixed 72CRM API access.",
   "type": "module",
   "main": "./dist/index.js",