@wukongcrm/mcp-server 0.2.5 → 0.2.6

package/README.md

@@ -16,6 +16,27 @@
 - 进销存 JXC 保留产品、供应商、仓库、库存和出入库明细查询，并开放 JXC 域内固定路径写入。
 - 无代码能力覆盖应用、模块、字段、数据、角色、流程、阶段、跟进、打印、消息、开放配置和应用市场的 JSON 业务接口。
 - 所有写入仍必须传 `confirm=true`；未确认时只返回预览，不调用 72CRM 写接口。
+- 所有业务、人员、部门等 ID 在 MCP Schema 中都使用数字字符串，禁止用 JSON number 传 Snowflake ID；动态 payload 中的不安全数字 ID 会在请求旧 CRM 前被拒绝。
+- 所有工具通过标准 `description`、Schema、annotations 和 `_meta["com.wukongcrm/tool-discovery"]` 暴露可检索的业务域、实体、动作、能力、别名与排除语义；不识别自定义 `_meta` 的 MCP 客户端可安全忽略该字段。
+
+## 商机与跟进写入约定
+
+新增商机不能只传名称和客户 ID。先调用 `crm_get_business_status_groups`，从同一状态组中取 `flowId` 作为
+`entity.typeId`、取其 `settingList[].settingId` 作为 `entity.statusId`，再调用 `crm_create_record`。商机名称、客户、
+状态组和阶段分别放在 `entity.businessName/customerId/typeId/statusId`；关联产品、主联系人和审批数据分别使用
+顶层 `product/contactsId/examineFlowData`，MCP 不会再静默丢弃这些字段。只有一个可用状态组时可采用其首个
+进行中阶段；存在多个状态组且用户没有指定时必须让用户选择，不能猜测。
+
+新增跟进使用 `crm_add_followup`，`entity` 必须包含 `content`、`category`、`activityType` 和
+`activityTypeId`。MCP 会先按 `activityType` 回读目标记录，确认类型、ID、权限和存在性，再调用写接口。
+
+旧 CRM 写接口返回 `code=0` 就表示执行成功，`data=null` 只表示没有返回业务数据。MCP 会统一补充
+`success=true`、`requestAccepted=true`、`crmCode=0` 和 `writeOutcome=confirmed`；回读只用于补充新记录 ID、
+检查重复或核验目标，不用于推翻 `code=0` 的成功语义。
+
+旧 CRM 返回 `code=500, msg=网络繁忙` 时，含义是后端未处理异常，不是已经确认的网络故障。MCP 错误会保留
+`path/httpStatus/code/retryable/writeOutcome`；若 `writeOutcome=unknown`，先回读原业务目标，禁止直接重放写请求，
+也不能擅自改用 OA 任务等其他模块并向用户声称原操作成功。
 
 ## ChatGPT 网页端（远程 MCP）
 
@@ -147,7 +168,7 @@ npm pack
 生成文件示例：
 
 ```text
-wukongcrm-mcp-server-0.2.4.tgz
+wukongcrm-mcp-server-0.2.6.tgz
 ```
 
 这个包只包含运行所需的 `dist`、`README.md` 和 `package.json`，不会携带源码、测试文件或用户 API Key。
@@ -155,7 +176,7 @@ wukongcrm-mcp-server-0.2.4.tgz
 使用者拿到 `.tgz` 后安装：
 
 ```powershell
-npm install -g .\wukongcrm-mcp-server-0.2.4.tgz
+npm install -g .\wukongcrm-mcp-server-0.2.6.tgz
 ```
 
 安装后可以直接用命令启动：
@@ -214,6 +235,7 @@ wukong-mcp
 - `crm_list_modules`
 - `crm_list_customer_pools`
 - `crm_get_module_schema`
+- `crm_get_business_status_groups`
 - `crm_validate_field`
 - `crm_search_records`
 - `crm_get_record`
@@ -374,8 +396,8 @@ wukong-mcp
 ```json
 {
   "module": "customer",
-  "ownerUserIds": [9, 10],
-  "createUserId": 11
+  "ownerUserIds": ["9", "10"],
+  "createUserId": "11"
 }
 ```
 
@@ -655,14 +677,14 @@ wukong-mcp
 
 ```json
 {
-  "categoryId": 7,
+  "categoryId": "7",
   "batchId": "可选附件批次ID",
   "fields": {
     "审批内容": "客户拜访报销",
     "金额": 128.5,
-    "申请人": [{ "userId": 9 }]
+    "申请人": [{ "userId": "9" }]
   },
-  "customerIds": [1001],
+  "customerIds": ["1001"],
   "confirm": true
 }
 ```
@@ -677,8 +699,8 @@ wukong-mcp
 {
   "startTime": 1782470400000,
   "endTime": 1782556799999,
-  "typeIds": [1, 2],
-  "userId": 9
+  "typeIds": ["1", "2"],
+  "userId": "9"
 }
 ```
 
@@ -687,9 +709,9 @@ wukong-mcp
 ```json
 {
   "event": {
-    "eventId": 12,
+    "eventId": "12",
     "title": "客户回访",
-    "typeId": 3,
+    "typeId": "3",
     "startTime": "2026-06-26 10:00:00",
     "endTime": "2026-06-26 11:00:00",
     "ownerUserIds": "9",
@@ -729,7 +751,7 @@ wukong-mcp
 {
   "title": "公告标题",
   "content": "公告内容",
-  "ownerUserIds": [9, 10],
+  "ownerUserIds": ["9", "10"],
   "confirm": true
 }
 ```
@@ -753,9 +775,9 @@ wukong-mcp
 
 ```json
 {
-  "categoryId": 7,
+  "categoryId": "7",
   "title": "日报",
-  "sendUserIds": [9],
+  "sendUserIds": ["9"],
   "fields": {
     "日志内容": "今天完成客户回访",
     "明日工作": "继续跟进报价",
@@ -779,7 +801,7 @@ OA 任务列表固定调用 `/oaTask/queryTaskList`，支持 72CRM 的 `OaTaskLi
   "status": 1,
   "priority": 3,
   "keyword": "客户回访",
-  "mainUserIds": [9, 10]
+  "mainUserIds": ["9", "10"]
 }
 ```
 
@@ -788,7 +810,7 @@ OA 任务列表固定调用 `/oaTask/queryTaskList`，支持 72CRM 的 `OaTaskLi
 ```json
 {
   "type": 2,
-  "typeId": 1001
+  "typeId": "1001"
 }
 ```
 
@@ -798,13 +820,13 @@ OA 任务列表固定调用 `/oaTask/queryTaskList`，支持 72CRM 的 `OaTaskLi
 {
   "name": "客户回访",
   "description": "确认续费计划",
-  "mainUserId": 9,
-  "ownerUserId": [9, 10],
+  "mainUserId": "9",
+  "ownerUserId": ["9", "10"],
   "startTime": "2026-06-27",
   "stopTime": "2026-06-28",
   "priority": 3,
-  "labelId": [1, 2],
-  "customerIds": [1001],
+  "labelId": ["1", "2"],
+  "customerIds": ["1001"],
   "confirm": true
 }
 ```
@@ -813,15 +835,15 @@ OA 任务列表固定调用 `/oaTask/queryTaskList`，支持 72CRM 的 `OaTaskLi
 
 ```json
 {
-  "taskId": 12,
+  "taskId": "12",
   "updates": {
     "name": "客户回访-已更新",
     "description": "带上报价单",
-    "mainUserId": 9,
-    "ownerUserId": [9, 10],
+    "mainUserId": "9",
+    "ownerUserId": ["9", "10"],
     "startTime": "2026-06-27",
     "stopTime": "2026-06-28",
-    "labelId": [1, 2],
+    "labelId": ["1", "2"],
     "priority": 3,
     "status": 5
   },

package/dist/client.d.ts

@@ -8,11 +8,43 @@ export interface CrmResult<T = unknown> {
     msg?: string;
     data?: T;
 }
+export type AuthFailureReason = "authentication_failed" | "transport_failed" | "api_error" | "protocol_error" | "unknown";
 export interface AuthStatusResult {
     ok: boolean;
     authMode?: "apiKey";
     data?: unknown;
     message?: string;
+    reason?: AuthFailureReason;
+    retryable?: boolean;
+}
+export type CrmWriteOutcome = "not_applied" | "unknown";
+export type CrmRequestEffect = "read" | "write";
+export declare class CrmApiError extends Error {
+    readonly path: string;
+    readonly httpStatus: number;
+    readonly crmCode: number;
+    readonly retryable: boolean;
+    readonly writeOutcome: CrmWriteOutcome;
+    constructor(options: {
+        path: string;
+        httpStatus: number;
+        crmCode: number;
+        message: string;
+        retryable: boolean;
+        writeOutcome: CrmWriteOutcome;
+    });
+}
+export declare class CrmTransportError extends Error {
+    readonly path: string;
+    readonly retryable = true;
+    readonly writeOutcome: CrmWriteOutcome;
+    constructor(path: string, effect: CrmRequestEffect, cause: unknown);
+}
+export declare class CrmProtocolError extends Error {
+    readonly path: string;
+    readonly retryable = false;
+    readonly writeOutcome: CrmWriteOutcome;
+    constructor(path: string, effect?: CrmRequestEffect);
 }
 export declare class CrmClient {
     private readonly baseUrl;
@@ -22,8 +54,10 @@ export declare class CrmClient {
     private loginPromise;
     constructor(config?: CrmClientConfig);
     authStatus(): Promise<AuthStatusResult>;
-    call<T = unknown>(method: "GET" | "POST", path: string, body?: unknown, query?: Record<string, unknown>): Promise<T>;
+    call<T = unknown>(method: "GET" | "POST", path: string, body?: unknown, query?: Record<string, unknown>, effect?: CrmRequestEffect): Promise<T>;
     post<T = unknown>(path: string, body?: unknown, query?: Record<string, unknown>): Promise<T>;
+    read<T = unknown>(path: string, body?: unknown, query?: Record<string, unknown>): Promise<T>;
+    write<T = unknown>(path: string, body?: unknown, query?: Record<string, unknown>): Promise<T>;
     private ensureToken;
     private loginWithApiKey;
     private requestOnce;

package/dist/client.js

@@ -1,5 +1,67 @@
+export class CrmApiError extends Error {
+    path;
+    httpStatus;
+    crmCode;
+    retryable;
+    writeOutcome;
+    constructor(options) {
+        const genericBackendNote = options.crmCode === 500 && options.message.includes("网络繁忙")
+            ? "这是旧 CRM 对未处理后端异常的通用提示，不代表已确认的网络故障。"
+            : "";
+        const guidance = options.writeOutcome === "unknown"
+            ? "写入结果未知；不要自动改写为 OA 任务等其他业务，也不要直接重放写请求，请先回读原目标确认是否已落库。"
+            : "请求未成功；请根据业务提示修正参数，不要用其他模块冒充本次操作成功。";
+        super(`72CRM API 请求失败：path=${options.path}，httpStatus=${options.httpStatus}，`
+            + `code=${options.crmCode}，retryable=${options.retryable}，writeOutcome=${options.writeOutcome}，`
+            + `message=${options.message}。${genericBackendNote}${guidance}`);
+        this.name = "CrmApiError";
+        this.path = options.path;
+        this.httpStatus = options.httpStatus;
+        this.crmCode = options.crmCode;
+        this.retryable = options.retryable;
+        this.writeOutcome = options.writeOutcome;
+    }
+}
+export class CrmTransportError extends Error {
+    path;
+    retryable = true;
+    writeOutcome;
+    constructor(path, effect, cause) {
+        const writeOutcome = writeOutcomeFor(effect);
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        super(`72CRM 传输失败：path=${path}，retryable=true，writeOutcome=${writeOutcome}，message=${reason}。`
+            + (writeOutcome === "unknown"
+                ? "请求可能已到达服务端；不要直接重放或改写为其他业务，请先回读原目标。"
+                : "可以在确认连接状态后重试只读请求。"));
+        this.name = "CrmTransportError";
+        this.path = path;
+        this.writeOutcome = writeOutcome;
+    }
+}
+export class CrmProtocolError extends Error {
+    path;
+    retryable = false;
+    writeOutcome;
+    constructor(path, effect = "read") {
+        const writeOutcome = writeOutcomeFor(effect);
+        super(`72CRM 接口响应格式异常：path=${path}，writeOutcome=${writeOutcome}。`
+            + (writeOutcome === "unknown"
+                ? "写请求可能已到达服务端，请先回读原目标，禁止直接重放。"
+                : "请检查 CRM_BASE_URL 是否指向旧 CRM API 根路径。"));
+        this.name = "CrmProtocolError";
+        this.path = path;
+        this.writeOutcome = writeOutcome;
+    }
+}
 const API_KEY_REQUIRED_MESSAGE = "请先配置 CRM_API_KEY，然后重新启动本地 MCP。";
 const AUTH_FAILURE_MESSAGE = "MCP 鉴权失败，请检查 CRM_API_KEY 是否正确或是否已被重置。";
+const AUTH_STATUS_MESSAGES = {
+    authentication_failed: AUTH_FAILURE_MESSAGE,
+    transport_failed: "无法连接旧 CRM 登录接口，请检查 CRM_BASE_URL、网络和证书。",
+    api_error: "旧 CRM 登录接口返回服务端错误，请稍后重试或检查旧 CRM 日志。",
+    protocol_error: "旧 CRM 登录接口返回了无法识别的响应，请检查 CRM_BASE_URL 是否指向 API 根路径。",
+    unknown: "旧 CRM 连接验证失败。"
+};
 export class CrmClient {
     baseUrl;
     apiKey;
@@ -17,14 +79,21 @@ export class CrmClient {
             return { ok: true, authMode: "apiKey", data };
         }
         catch (error) {
-            return { ok: false, authMode: "apiKey", message: errorMessage(error) };
+            const failure = classifyAuthFailure(error);
+            return {
+                ok: false,
+                authMode: "apiKey",
+                reason: failure.reason,
+                retryable: failure.retryable,
+                message: AUTH_STATUS_MESSAGES[failure.reason]
+            };
         }
     }
-    async call(method, path, body, query) {
+    async call(method, path, body, query, effect = "read") {
         assertFixedPath(path);
         await this.ensureToken();
         try {
-            return await this.requestOnce(method, path, body, query);
+            return await this.requestOnce(method, path, body, query, effect);
         }
         catch (error) {
             if (!(error instanceof CrmUnauthenticatedError)) {
@@ -33,7 +102,7 @@ export class CrmClient {
         }
         await this.ensureToken(true);
         try {
-            return await this.requestOnce(method, path, body, query);
+            return await this.requestOnce(method, path, body, query, effect);
         }
         catch (error) {
             if (error instanceof CrmUnauthenticatedError) {
@@ -43,7 +112,16 @@ export class CrmClient {
         }
     }
     async post(path, body, query) {
-        return this.call("POST", path, body, query);
+        // 兼容旧调用方；内部工具应显式选择 read()/write()，避免仅凭 URL 猜测写入结果。
+        return this.read(path, body, query);
+    }
+    // 旧 CRM 的查询和写入都大量使用 HTTP POST。这里的 read/write 表示业务副作用，
+    // 专门用于决定传输或协议失败时能否安全重试，而不是 HTTP method 的别名。
+    async read(path, body, query) {
+        return this.call("POST", path, body, query, "read");
+    }
+    async write(path, body, query) {
+        return this.call("POST", path, body, query, "write");
     }
     async ensureToken(force = false) {
         if (!this.apiKey.trim()) {
@@ -62,8 +140,9 @@ export class CrmClient {
         this.adminToken = await this.loginPromise;
     }
     async loginWithApiKey() {
+        let response;
         try {
-            const response = await this.fetchImpl(this.buildUrl("/login"), {
+            response = await this.fetchImpl(this.buildUrl("/login"), {
                 method: "POST",
                 headers: this.buildHeaders(true),
                 body: JSON.stringify({
@@ -72,38 +151,65 @@ export class CrmClient {
                     type: 4
                 })
             });
-            if (response.status === 401 || response.status === 403) {
-                throw new CrmAuthenticationError();
-            }
-            const result = await parseJsonResult(response);
-            const adminToken = typeof result.data?.adminToken === "string" ? result.data.adminToken.trim() : "";
-            if (result.code !== 0 || !adminToken) {
-                throw new CrmAuthenticationError();
-            }
-            return adminToken;
         }
         catch (error) {
-            if (error instanceof CrmAuthenticationError) {
-                throw error;
-            }
+            throw new CrmTransportError("/login", "read", error);
+        }
+        if (response.status === 401 || response.status === 403) {
+            throw new CrmAuthenticationError();
+        }
+        const result = await parseJsonResult(response, "/login", "read");
+        if (isAuthenticationCode(result.code)) {
             throw new CrmAuthenticationError();
         }
+        if (!response.ok || result.code !== 0) {
+            const crmCode = result.code || response.status;
+            throw new CrmApiError({
+                path: "/login",
+                httpStatus: response.status,
+                crmCode,
+                message: result.msg || response.statusText || "未返回错误说明",
+                retryable: response.status === 429 || response.status === 502
+                    || response.status === 503 || response.status === 504,
+                writeOutcome: "not_applied"
+            });
+        }
+        const adminToken = typeof result.data?.adminToken === "string" ? result.data.adminToken.trim() : "";
+        if (!adminToken) {
+            throw new CrmProtocolError("/login");
+        }
+        return adminToken;
     }
-    async requestOnce(method, path, body, query) {
-        const response = await this.fetchImpl(this.buildUrl(path, query), {
-            method,
-            headers: this.buildHeaders(body !== undefined, this.adminToken),
-            body: body === undefined ? undefined : JSON.stringify(body)
-        });
+    async requestOnce(method, path, body, query, effect = "read") {
+        let response;
+        try {
+            response = await this.fetchImpl(this.buildUrl(path, query), {
+                method,
+                headers: this.buildHeaders(body !== undefined, this.adminToken),
+                body: body === undefined ? undefined : JSON.stringify(body)
+            });
+        }
+        catch (error) {
+            throw new CrmTransportError(path, effect, error);
+        }
         if (response.status === 401 || response.status === 403) {
             throw new CrmUnauthenticatedError();
         }
-        const result = await parseJsonResult(response);
+        const result = await parseJsonResult(response, path, effect);
         if (result.code === 302) {
             throw new CrmUnauthenticatedError();
         }
-        if (result.code !== 0) {
-            throw new Error(result.msg || `72CRM 接口返回异常，code=${result.code}`);
+        if (!response.ok || result.code !== 0) {
+            const crmCode = result.code || response.status;
+            throw new CrmApiError({
+                path,
+                httpStatus: response.status,
+                crmCode,
+                message: result.msg || response.statusText || "未返回错误说明",
+                // 旧 CRM 的 code=500/networkError 是统一的后端异常兜底，不是网络诊断。
+                retryable: response.status === 429 || response.status === 502 || response.status === 503 || response.status === 504,
+                writeOutcome: writeOutcomeFor(effect)
+            });
         }
         return result.data;
     }
@@ -128,6 +234,27 @@ export class CrmClient {
         return headers;
     }
 }
+function writeOutcomeFor(effect) {
+    return effect === "write" ? "unknown" : "not_applied";
+}
+function isAuthenticationCode(code) {
+    return code === 302 || code === 401 || code === 403 || code === 1022 || code === 1023;
+}
+function classifyAuthFailure(error) {
+    if (error instanceof CrmAuthenticationError || errorMessage(error) === API_KEY_REQUIRED_MESSAGE) {
+        return { reason: "authentication_failed", retryable: false };
+    }
+    if (error instanceof CrmTransportError) {
+        return { reason: "transport_failed", retryable: true };
+    }
+    if (error instanceof CrmApiError) {
+        return { reason: "api_error", retryable: error.retryable };
+    }
+    if (error instanceof CrmProtocolError) {
+        return { reason: "protocol_error", retryable: false };
+    }
+    return { reason: "unknown", retryable: false };
+}
 class CrmUnauthenticatedError extends Error {
     constructor() {
         super("72CRM 当前登录态已失效。");
@@ -138,7 +265,7 @@ class CrmAuthenticationError extends Error {
         super(AUTH_FAILURE_MESSAGE);
     }
 }
-async function parseJsonResult(response) {
+async function parseJsonResult(response, path, effect) {
     const text = await response.text();
     if (!text) {
         return { code: response.ok ? 0 : response.status, msg: response.statusText, data: undefined };
@@ -147,7 +274,7 @@ async function parseJsonResult(response) {
         return JSON.parse(text);
     }
     catch {
-        throw new Error("72CRM 接口返回了非 JSON 内容，当前 MCP 不代理文件流或下载响应。");
+        throw new CrmProtocolError(path, effect);
     }
 }
 function normalizeBaseUrl(baseUrl) {