@wukongcrm/mcp-server 0.2.0 → 0.2.2

package/README.md

@@ -147,7 +147,7 @@ npm pack
 生成文件示例：
 
 ```text
-wukongcrm-mcp-server-0.2.0.tgz
+wukongcrm-mcp-server-0.2.2.tgz
 ```
 
 这个包只包含运行所需的 `dist`、`README.md` 和 `package.json`，不会携带源码、测试文件或用户 API Key。
@@ -155,7 +155,7 @@ wukongcrm-mcp-server-0.2.0.tgz
 使用者拿到 `.tgz` 后安装：
 
 ```powershell
-npm install -g .\wukongcrm-mcp-server-0.2.0.tgz
+npm install -g .\wukongcrm-mcp-server-0.2.2.tgz
 ```
 
 安装后可以直接用命令启动：
@@ -198,6 +198,12 @@ wukong-mcp
 - 打印与消息：`nocode_query_printing`、`nocode_write_printing`、`nocode_query_messages`、`nocode_write_message`
 - 开放能力与应用市场：`nocode_query_integrations`、`nocode_write_integration`、`nocode_query_marketplace`、`nocode_write_marketplace`
 
+常见保存动作必须使用旧前端对应的聚合 BO，而不是把单个字段或单个值直接作为 `payload`：
+
+- 字段保存：`ModuleFieldSaveBO`，至少包含 `moduleId`、实际 `version`、`mainFieldId`/`tempMainFieldId` 和非空 `moduleFieldList`。
+- 记录保存：`ModuleFieldDataSaveBO`，至少包含 `moduleId`、实际 `version` 和非空 `fieldDataList`；字段值使用 `fieldId`、`fieldName`、`name`、`type`、`value`，修改时增加 `dataId`。
+- 新建模块的实际版本通常从 `0` 开始，应先用 `nocode_get_module` 读取并显式传入，不能根据已发布老模块猜测为 `1`。
+
 文件流仍有意不经 MCP 代理，因此应用导入/导出、Excel 导入/导出、跟进导出、打印 PDF/Word 下载不在工具中；打印内容生成和预览 JSON 接口仍可使用。内部测试接口 `/moduleMQ/send` 也不会暴露。
 
 ### CRM、OA、HRM、财务、进销存与工单工具

package/dist/client.d.ts

@@ -19,6 +19,7 @@ export declare class CrmClient {
     private readonly apiKey;
     private readonly fetchImpl;
     private adminToken;
+    private loginPromise;
     constructor(config?: CrmClientConfig);
     authStatus(): Promise<AuthStatusResult>;
     call<T = unknown>(method: "GET" | "POST", path: string, body?: unknown, query?: Record<string, unknown>): Promise<T>;

package/dist/client.js

@@ -5,6 +5,7 @@ export class CrmClient {
     apiKey;
     fetchImpl;
     adminToken = "";
+    loginPromise;
     constructor(config = {}) {
         this.baseUrl = normalizeBaseUrl(config.baseUrl ?? process.env.CRM_BASE_URL ?? "https://www.72crm.com/api-11/");
         this.apiKey = config.apiKey ?? process.env.CRM_API_KEY ?? "";
@@ -51,7 +52,14 @@ export class CrmClient {
         if (!force && this.adminToken.trim()) {
             return;
         }
-        this.adminToken = await this.loginWithApiKey();
+        // Schema 聚合会并发请求多个只读接口。首次调用时必须把 API Key 登录合并成一次，
+        // 否则旧 CRM 会在短时间内收到多次登录并让部分请求鉴权失败。
+        if (!this.loginPromise) {
+            this.loginPromise = this.loginWithApiKey().finally(() => {
+                this.loginPromise = undefined;
+            });
+        }
+        this.adminToken = await this.loginPromise;
     }
     async loginWithApiKey() {
         try {

package/dist/nocode.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { type CrmClientConfig } from "./client.js";
+import { CrmClient, type CrmClientConfig } from "./client.js";
 export type NocodeToolAccess = "read" | "write";
 export interface NocodeToolDefinition {
     name: string;
@@ -12,5 +12,5 @@ type AnyArgs = Record<string, any>;
 type Handler = (args: AnyArgs) => Promise<any> | any;
 export type NocodeToolHandlers = Record<string, Handler>;
 export declare const nocodeToolDefinitions: NocodeToolDefinition[];
-export declare function createNocodeToolHandlers(config?: CrmClientConfig): NocodeToolHandlers;
+export declare function createNocodeToolHandlers(config?: CrmClientConfig, sharedClient?: CrmClient): NocodeToolHandlers;
 export {};

package/dist/nocode.js

@@ -1,6 +1,9 @@
 import { z } from "zod";
 import { CrmClient } from "./client.js";
-const idSchema = z.union([z.string(), z.number()]);
+const idSchema = z.union([
+    z.string().regex(/^\d+$/, "ID 必须是数字字符串。"),
+    z.number().int().safe("超过 JavaScript 安全整数范围的 ID 必须以字符串传入。")
+]);
 const payloadSchema = z.record(z.unknown());
 const confirmSchema = z.boolean().optional();
 const versionSchema = z.number().int().nonnegative().optional();
@@ -62,7 +65,7 @@ export const nocodeToolDefinitions = [
     },
     {
         name: "nocode_get_module_schema",
-        description: "一次获取无代码模块字段、表单布局、列表头、页面布局、选项、公式、标签和序列号规则；写入记录前应先调用；只读。",
+        description: "一次获取无代码模块字段、表单布局、列表头、页面布局、选项、公式、标签和序列号规则；写入记录前应先调用，并优先使用 nocode_get_module 返回的实际 version（新建模块通常为 0）；雪花 moduleId 必须以字符串传入，避免 JavaScript 数字精度丢失；只读。",
         schema: z.object({ ...moduleContextShape, includeExtended: z.boolean().optional() }),
         access: "read"
     },
@@ -193,7 +196,7 @@ export const nocodeToolDefinitions = [
     },
     {
         name: "nocode_query_printing",
-        description: "查询无代码打印模板字段、模板列表/详情和打印记录；只读。打印、预览和模板变更请使用 nocode_write_printing。",
+        description: "查询无代码打印模板字段、模板列表/详情和打印记录；只读。records 会先确认当前模块存在打印模板，规避旧后端在空模板集合上生成无效 SQL；打印、预览和模板变更请使用 nocode_write_printing。",
         schema: z.object({
             operation: z.enum(["fields", "templates", "template", "records", "record"]),
             ...extendedContextShape
@@ -243,7 +246,7 @@ export const nocodeToolDefinitions = [
     },
     {
         name: "nocode_write_module",
-        description: "保存、启停、复制、发布、丢弃草稿、删除模块、保存页面布局或维护 BI Dashboard 模块；必须 confirm=true。",
+        description: "保存、启停、复制、发布、丢弃草稿、删除模块、保存页面布局或维护 BI Dashboard 模块；action=save 的 payload 使用旧 CRM ModuleSaveBO（常见普通模块包含 applicationId、name、moduleType=1、icon）；必须 confirm=true。",
         schema: z.object({
             action: z.enum(["save", "status", "copy", "publish", "discardDraft", "delete", "layout", "deleteCancelledCompanyData", "dashboardSave", "dashboardRemove"]),
             moduleId: idSchema.optional(),
@@ -257,14 +260,14 @@ export const nocodeToolDefinitions = [
     },
     {
         name: "nocode_write_field",
-        description: "保存字段，或修改普通/固定模块列表字段排序和样式；必须 confirm=true，否则只返回固定接口和请求预览。",
+        description: "保存字段，或修改普通/固定模块列表字段排序和样式；action=save 的 payload 必须是聚合 ModuleFieldSaveBO，包含 moduleId、实际 version、mainFieldId 或 tempMainFieldId、moduleFieldList，不能直接传单个字段；必须 confirm=true，否则只返回固定接口和请求预览。",
         schema: z.object({ action: z.enum(["save", "sort", "style", "fixedSort", "fixedStyle"]), ...payloadWriteShape }),
         access: "write",
         destructive: true
     },
     {
         name: "nocode_write_record",
-        description: "新增/修改、删除、转移负责人或设置分组；payload 使用对应旧 CRM BO；必须 confirm=true，否则只返回预览。",
+        description: "新增/修改、删除、转移负责人或设置分组；action=save 的 payload 必须是 ModuleFieldDataSaveBO，包含 moduleId、实际 version、fieldDataList；每个字段值应包含 fieldId、fieldName、name、type、value，修改时再带 dataId；必须 confirm=true，否则只返回预览。",
         schema: z.object({ action: z.enum(["save", "delete", "transfer", "setCategory"]), ...payloadWriteShape }),
         access: "write",
         destructive: true
@@ -395,8 +398,8 @@ export const nocodeToolDefinitions = [
         destructive: true
     }
 ];
-export function createNocodeToolHandlers(config = {}) {
-    const client = new CrmClient(config);
+export function createNocodeToolHandlers(config = {}, sharedClient) {
+    const client = sharedClient ?? new CrmClient(config);
     return {
         nocode_list_applications: async () => readonlyResult("/moduleMetadata/customAppList", await client.post("/moduleMetadata/customAppList")),
         nocode_get_application: async (args) => {
@@ -430,10 +433,24 @@ export function createNocodeToolHandlers(config = {}) {
             const moduleId = requiredId(args.moduleId, "moduleId");
             const version = requiredVersion(args.version);
             const query = cleanObject({ moduleId: numericValue(moduleId), version, categoryId: args.categoryId });
-            const [fields, form, listHead, layout, unionModules] = await Promise.all([
+            // 旧后端会直接拆箱 filterHidden；显式传 false 与无代码前端的字段配置请求保持一致，避免空值触发 500。
+            const formQuery = { ...query, filterHidden: false };
+            const [fields, form, listHeadOutcome, layout, unionModules] = await Promise.all([
                 client.post("/moduleField/queryList", query),
-                client.post("/moduleField/formList", query),
-                client.post("/moduleField/queryListHead", query),
+                client.post("/moduleField/formList", formQuery),
+                client.post("/moduleField/queryListHead", query)
+                    .then((data) => ({ data, warning: undefined }))
+                    .catch((error) => {
+                    // 旧端的列表头服务只读取“已发布激活”的模块。新建草稿在字段已经存在时仍会返回 4303，
+                    // 但字段列表和表单结构本身可正常读取；不要让该可预期边界拖垮整个聚合 Schema。
+                    if (isModuleNotFoundError(error)) {
+                        return {
+                            data: [],
+                            warning: "当前模块尚未发布，旧 CRM 不提供列表头；fields/form 仍是有效的草稿 Schema。"
+                        };
+                    }
+                    throw error;
+                }),
                 client.post(`/moduleM/pageLayout/${moduleId}/${version}`),
                 client.post(`/moduleM/unionModules/${moduleId}/${version}`)
             ]);
@@ -451,9 +468,10 @@ export function createNocodeToolHandlers(config = {}) {
                 version,
                 fields,
                 form,
-                listHead,
+                listHead: listHeadOutcome.data,
                 layout,
                 unionModules,
+                ...(listHeadOutcome.warning ? { warnings: [listHeadOutcome.warning] } : {}),
                 ...extended
             };
         },
@@ -511,20 +529,20 @@ export function createNocodeToolHandlers(config = {}) {
         nocode_query_workflow: async (args) => executeNocodeRead(client, queryWorkflowRoute(args)),
         nocode_query_followups: async (args) => executeNocodeRead(client, queryFollowUpRoute(args)),
         nocode_query_configuration: async (args) => executeNocodeRead(client, queryConfigurationRoute(args)),
-        nocode_query_printing: async (args) => executeNocodeRead(client, queryPrintingRoute(args)),
+        nocode_query_printing: async (args) => executePrintingRead(client, args),
         nocode_query_messages: async (args) => executeNocodeRead(client, queryMessageRoute(args)),
         nocode_query_integrations: async (args) => executeNocodeRead(client, queryIntegrationRoute(args)),
         nocode_query_marketplace: async (args) => executeNocodeRead(client, queryMarketplaceRoute(args)),
         nocode_write_application: async (args) => executeApplicationWrite(client, args),
         nocode_write_module: async (args) => executeModuleWrite(client, args),
-        nocode_write_field: async (args) => executePayloadWrite(client, args, {
+        nocode_write_field: async (args) => executeFieldWrite(client, args, {
             save: "/moduleField/save",
             sort: "/moduleField/setFieldSort",
             style: "/moduleField/setFieldStyle",
             fixedSort: "/moduleField/fixed/setFieldSort",
             fixedStyle: "/moduleField/fixed/setFieldStyle"
         }),
-        nocode_write_record: async (args) => executePayloadWrite(client, args, {
+        nocode_write_record: async (args) => executeRecordWrite(client, args, {
             save: "/moduleFieldData/save",
             delete: "/moduleFieldData/delete",
             transfer: "/moduleFieldData/transfer",
@@ -564,6 +582,41 @@ export function createNocodeToolHandlers(config = {}) {
 async function executeNocodeRead(client, route) {
     return readonlyResult(route.targetPath, await client.post(route.targetPath, route.body, route.query), cleanObject({ operation: route.operation, body: route.body, query: route.query }));
 }
+async function executePrintingRead(client, args) {
+    const route = queryPrintingRoute(args);
+    if (route.operation !== "records") {
+        return executeNocodeRead(client, route);
+    }
+    const moduleId = requiredId(args.moduleId, "moduleId");
+    let version;
+    if (args.version !== undefined) {
+        version = requiredVersion(args.version);
+    }
+    else {
+        const moduleDetail = await client.post(`/moduleM/queryById/${moduleId}`, undefined, { isLatest: true });
+        version = requiredVersion(moduleDetail?.version);
+    }
+    // 旧后端 queryPrintRecord 会对空模板 ID 集合直接拼接 IN ()，最终只返回笼统的
+    // “Network Busy”。先用模板列表判断空集，空时按真实业务语义返回无打印记录。
+    const templatePath = `/modulePrintTemplate/list/${moduleId}/${version}`;
+    const templatePage = await client.post(templatePath, { page: 1, limit: 1 });
+    const templateRows = listRows(templatePage);
+    if (templateRows?.length === 0) {
+        return readonlyResult(route.targetPath, [], {
+            operation: route.operation,
+            preflight: { targetPath: templatePath, version, emptyTemplates: true }
+        });
+    }
+    return executeNocodeRead(client, route);
+}
+function listRows(value) {
+    if (Array.isArray(value))
+        return value;
+    if (!value || typeof value !== "object")
+        return undefined;
+    const list = value.list;
+    return Array.isArray(list) ? list : undefined;
+}
 function executeNocodeWrite(client, args, route) {
     return confirmedPost(client, args, route.operation, route.targetPath, route.body, route.query);
 }
@@ -874,11 +927,11 @@ async function executeApplicationWrite(client, args) {
     switch (action) {
         case "create":
             targetPath = "/moduleMetadata/save";
-            body = safePayload(args.payload);
+            body = applicationPayload(args.payload, action);
             break;
         case "update":
             targetPath = "/moduleMetadata/update";
-            body = safePayload(args.payload);
+            body = applicationPayload(args.payload, action);
             break;
         case "status":
             targetPath = `/moduleMetadata/updateStatus/${requiredId(args.applicationId, "applicationId")}`;
@@ -954,6 +1007,20 @@ async function executePayloadWrite(client, args, paths) {
     }
     return confirmedPost(client, args, action, targetPath, safePayload(args.payload));
 }
+async function executeFieldWrite(client, args, paths) {
+    const action = String(args.action);
+    if (action === "save") {
+        validateAggregateSavePayload(args.payload, "ModuleFieldSaveBO", "moduleFieldList");
+    }
+    return executePayloadWrite(client, args, paths);
+}
+async function executeRecordWrite(client, args, paths) {
+    const action = String(args.action);
+    if (action === "save") {
+        validateAggregateSavePayload(args.payload, "ModuleFieldDataSaveBO", "fieldDataList");
+    }
+    return executePayloadWrite(client, args, paths);
+}
 async function executeSceneWrite(client, args) {
     const action = String(args.action);
     const targetPath = action === "delete" || action === "default"
@@ -1026,12 +1093,18 @@ function readonlyResult(targetPath, data, extra = {}) {
     return { readonly: true, targetPath, ...extra, data };
 }
 function requiredId(value, field) {
+    if (typeof value === "number" && !Number.isSafeInteger(value)) {
+        throw new Error(`${field} 超过 JavaScript 安全整数范围，必须以字符串传入。`);
+    }
     const normalized = String(value ?? "").trim();
     if (!/^\d+$/.test(normalized)) {
         throw new Error(`${field} 必须是数字 ID。`);
     }
     return normalized;
 }
+function isModuleNotFoundError(error) {
+    return error instanceof Error && error.message.includes("模块未找到");
+}
 function numericValue(value) {
     const numeric = Number(value);
     return Number.isSafeInteger(numeric) ? numeric : value;
@@ -1075,6 +1148,40 @@ function safePayload(value) {
     }
     return value;
 }
+function applicationPayload(value, action) {
+    const payload = safePayload(value);
+    const name = typeof payload.name === "string" ? payload.name.trim() : "";
+    if (!name) {
+        throw new Error("无代码应用名称不能为空。");
+    }
+    if (Array.from(name).length > 20) {
+        throw new Error("无代码应用名称不能超过 20 个字符。");
+    }
+    const description = payload.description;
+    if (description !== undefined && (typeof description !== "string" || Array.from(description).length > 50)) {
+        throw new Error("无代码应用描述必须是字符串且不能超过 50 个字符。");
+    }
+    const icon = typeof payload.icon === "string" ? payload.icon.trim() : "";
+    if (!icon) {
+        throw new Error("无代码应用图标不能为空。");
+    }
+    // 创建时补齐旧前端提交的非业务默认值；更新仍保留调用方提供的完整应用配置。
+    return action === "create"
+        ? { ...payload, name, icon, description: description ?? "", iconColor: payload.iconColor ?? "#EBECF0", manageUserIds: payload.manageUserIds ?? [] }
+        : { ...payload, name, icon };
+}
+function validateAggregateSavePayload(value, boName, listField) {
+    const payload = safePayload(value);
+    requiredId(payload.moduleId, "payload.moduleId");
+    // 新建模块的有效版本通常为 0；不能用 requiredVersion 的默认值掩盖调用方漏传版本。
+    if (payload.version === undefined) {
+        throw new Error(`${boName} 必须包含实际 version；请先读取模块详情。`);
+    }
+    requiredVersion(payload.version);
+    if (!Array.isArray(payload[listField]) || payload[listField].length === 0) {
+        throw new Error(`${boName} 必须包含非空 ${listField}。`);
+    }
+}
 function cleanObject(input) {
     const output = {};
     for (const [key, value] of Object.entries(input)) {

package/dist/server.js

@@ -1,5 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
+import { CrmClient } from "./client.js";
 import { createNocodeToolHandlers, nocodeToolDefinitions } from "./nocode.js";
 import { createToolHandlers } from "./tools.js";
 export const CRM_READ_SCOPE = "crm.read";
@@ -181,13 +182,14 @@ export function createWukongMcpServer(config = {}) {
     const { oauth, ...crmConfig } = config;
     const server = new McpServer({
         name: "wukong-mcp",
-        version: "0.2.0"
+        version: "0.2.2"
     }, {
         instructions: "先使用只读工具确认模块、记录和字段，再执行写入。所有写入必须显式传 confirm=true；不要尝试任意 URL 请求。"
     });
+    const sharedClient = new CrmClient(crmConfig);
     const handlers = {
-        ...createToolHandlers(crmConfig),
-        ...createNocodeToolHandlers(crmConfig)
+        ...createToolHandlers(crmConfig, sharedClient),
+        ...createNocodeToolHandlers(crmConfig, sharedClient)
     };
     const registeredTools = [
         ...toolDefinitions.map(([name, description, schema]) => ({

package/dist/tools.d.ts

@@ -1,8 +1,8 @@
-import { CrmClientConfig } from "./client.js";
+import { CrmClient, CrmClientConfig } from "./client.js";
 type AnyArgs = Record<string, any>;
 type Handler = (args: AnyArgs) => Promise<any> | any;
 export interface ToolHandlers {
     [name: string]: Handler;
 }
-export declare function createToolHandlers(config?: CrmClientConfig): ToolHandlers;
+export declare function createToolHandlers(config?: CrmClientConfig, sharedClient?: CrmClient): ToolHandlers;
 export {};

package/dist/tools.js

@@ -332,8 +332,8 @@ const WRITE_DOMAINS = {
         allowedPrefixes: ["/finance"]
     }
 };
-export function createToolHandlers(config = {}) {
-    const client = new CrmClient(config);
+export function createToolHandlers(config = {}, sharedClient) {
+    const client = sharedClient ?? new CrmClient(config);
     return {
         crm_auth_status: async () => client.authStatus(),
         crm_list_modules: () => ({

package/package.json

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