@wukongcrm/mcp-server 0.1.3

package/README.md

@@ -0,0 +1,219 @@
+# @wukongcrm/mcp-server
+
+WukongCRM MCP Server，用于给支持 Model Context Protocol 的本地 AI 客户端提供 CRM 查询和受控写入能力。
+
+默认代理 `https://www.72crm.com/api-11/` 下的固定白名单接口，不提供任意 URL 透传。
+
+## 特点
+
+- 通过 `CRM_API_KEY` 登录，MCP 进程内部调用 `/login` 换取 `adminToken`。
+- 业务请求按 72CRM 要求发送 `Admin-Token` 请求头，token 只缓存在本地进程内存中。
+- API Key 登录使用独立端类型 `type=4`，避免占用 PC 端 `type=1` 登录态。
+- 不读取 OpenAPI，不调用 `/v3/api-docs`。
+- 不支持附件上传、删除、下载流代理。
+- 查询能力覆盖线索、客户、联系人、商机、产品、合同、回款、发票、跟进记录等模块。
+- 写入只开放线索、客户、联系人、商机、跟进记录，并且必须传 `confirm=true`。
+
+## 通用 MCP 配置
+
+推荐直接通过 `npx` 启动，无需提前全局安装：
+
+```json
+{
+  "mcpServers": {
+    "wukongcrm": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@wukongcrm/mcp-server"],
+      "env": {
+        "CRM_BASE_URL": "https://www.72crm.com/api-11/",
+        "CRM_API_KEY": "你的 72CRM API Key"
+      }
+    }
+  }
+}
+```
+
+如果你的 MCP 客户端不支持 `type` 字段，可以去掉它：
+
+```json
+{
+  "mcpServers": {
+    "wukongcrm": {
+      "command": "npx",
+      "args": ["-y", "@wukongcrm/mcp-server"],
+      "env": {
+        "CRM_BASE_URL": "https://www.72crm.com/api-11/",
+        "CRM_API_KEY": "你的 72CRM API Key"
+      }
+    }
+  }
+}
+```
+
+## pnpm 使用
+
+不要求必须使用 npm。支持通过 `pnpm dlx` 启动：
+
+```json
+{
+  "mcpServers": {
+    "wukongcrm": {
+      "type": "stdio",
+      "command": "pnpm",
+      "args": ["dlx", "@wukongcrm/mcp-server"],
+      "env": {
+        "CRM_BASE_URL": "https://www.72crm.com/api-11/",
+        "CRM_API_KEY": "你的 72CRM API Key"
+      }
+    }
+  }
+}
+```
+
+## 全局安装
+
+```bash
+npm install -g @wukongcrm/mcp-server
+```
+
+安装后可以直接启动：
+
+```bash
+CRM_API_KEY="你的 72CRM API Key" \
+CRM_BASE_URL="https://www.72crm.com/api-11/" \
+wukongcrm-mcp
+```
+
+对应 MCP 配置：
+
+```json
+{
+  "mcpServers": {
+    "wukongcrm": {
+      "type": "stdio",
+      "command": "wukongcrm-mcp",
+      "env": {
+        "CRM_BASE_URL": "https://www.72crm.com/api-11/",
+        "CRM_API_KEY": "你的 72CRM API Key"
+      }
+    }
+  }
+}
+```
+
+## API Key 配置
+
+`CRM_API_KEY` 是运行时环境变量，不应在 `npm install` 阶段传入。
+
+README 中示例里的 `CRM_API_KEY` 对应 72CRM 个人中心生成的 MCP Token。获取地址：
+
+```text
+https://www.72crm.com/cloud/#/person/index?selectedIndex=1
+```
+
+MCP 客户端启动 server 时必须能把 `CRM_API_KEY` 注入到 `@wukongcrm/mcp-server` 进程环境中。常见方式是写在 MCP 客户端配置的 `env` 字段里，或由启动脚本/系统环境变量注入。
+
+## 开发运行
+
+```bash
+npm install
+CRM_API_KEY="你的 72CRM API Key" \
+CRM_BASE_URL="https://www.72crm.com/api-11/" \
+npm run build
+node dist/index.js
+```
+
+## 发布
+
+发布前验证：
+
+```bash
+npm test
+npm run build
+npm pack --dry-run
+```
+
+首次公开发布 scoped 包：
+
+```bash
+npm publish
+```
+
+`package.json` 已配置 `publishConfig.access=public`，因此不需要额外追加 `--access public`。
+
+## 支持工具
+
+- `crm_auth_status`
+- `crm_list_modules`
+- `crm_list_customer_pools`
+- `crm_get_module_schema`
+- `crm_validate_field`
+- `crm_search_records`
+- `crm_get_record`
+- `crm_get_record_information`
+- `crm_get_related_records`
+- `crm_get_record_timeline`
+- `crm_get_action_records`
+- `crm_list_files`
+- `crm_list_users`
+- `crm_find_user_id`
+- `crm_list_departments`
+- `crm_find_dept_id`
+- `crm_preview_write`
+- `crm_create_record`
+- `crm_update_customer`
+- `crm_update_record_fields`
+- `crm_add_followup`
+- `crm_update_followup`
+
+### `crm_search_records` 语义搜索
+
+`crm_search_records` 支持直接传入明显带搜索语义的参数，并自动转换为 72CRM 高级筛选 `searchList`：
+
+```json
+{
+  "module": "customer",
+  "keyword": "18581241105",
+  "page": 1,
+  "limit": 15
+}
+```
+
+客户模块会转换为“客户名称 / 手机 / 电话”三个高级筛选条件，使用 `type=3`（包含）和不同 `groupId` 做 OR 查询。也支持 `query`、`q`、`phone`、`mobile`、`name` 等字段。
+
+### 客户更新
+
+推荐优先使用 `crm_update_customer` 修改客户字段。它支持直接传客户 ID，也支持通过手机号、客户名或关键字唯一匹配客户；正式写入前会读取客户字段结构，自动补齐 `fieldId`、`fieldType`、`type`、`formType`，避免下拉字段或自定义字段写错结构。
+
+```json
+{
+  "phone": "18581241105",
+  "updates": {
+    "mobile": "16333022010",
+    "客户级别": "B"
+  },
+  "confirm": true
+}
+```
+
+实际写入仍然调用固定接口 `/crmCustomer/updateInformation`，请求体为：
+
+```json
+{
+  "id": "客户ID",
+  "label": 2,
+  "list": [
+    {
+      "fieldName": "mobile",
+      "value": "16333022010"
+    }
+  ]
+}
+```
+
+写入成功后默认会再次读取 `/crmCustomer/information/{id}` 做字段级校验；如只想写入不校验，可传 `verify=false`。
+
+## 安全边界
+
+以下操作前期全部拒绝：删除、转移负责人、公海流转、导入导出、审批/状态流转、字段配置修改、附件上传。

package/dist/client.d.ts

@@ -0,0 +1,31 @@
+export interface CrmClientConfig {
+    baseUrl?: string;
+    apiKey?: string;
+    fetchImpl?: typeof fetch;
+}
+export interface CrmResult<T = unknown> {
+    code: number;
+    msg?: string;
+    data?: T;
+}
+export interface AuthStatusResult {
+    ok: boolean;
+    authMode?: "apiKey";
+    data?: unknown;
+    message?: string;
+}
+export declare class CrmClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private adminToken;
+    constructor(config?: CrmClientConfig);
+    authStatus(): Promise<AuthStatusResult>;
+    call<T = unknown>(method: "GET" | "POST", path: string, body?: unknown, query?: Record<string, unknown>): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown, query?: Record<string, unknown>): Promise<T>;
+    private ensureToken;
+    private loginWithApiKey;
+    private requestOnce;
+    private buildUrl;
+    private buildHeaders;
+}

package/dist/client.js

@@ -0,0 +1,155 @@
+const API_KEY_REQUIRED_MESSAGE = "请先配置 CRM_API_KEY，然后重新启动本地 MCP。";
+const AUTH_FAILURE_MESSAGE = "MCP 鉴权失败，请检查 CRM_API_KEY 是否正确或是否已被重置。";
+export class CrmClient {
+    baseUrl;
+    apiKey;
+    fetchImpl;
+    adminToken = "";
+    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 ?? "";
+        this.fetchImpl = config.fetchImpl ?? fetch;
+    }
+    async authStatus() {
+        try {
+            const data = await this.call("POST", "/adminUser/queryLoginUser");
+            return { ok: true, authMode: "apiKey", data };
+        }
+        catch (error) {
+            return { ok: false, authMode: "apiKey", message: errorMessage(error) };
+        }
+    }
+    async call(method, path, body, query) {
+        assertFixedPath(path);
+        await this.ensureToken();
+        try {
+            return await this.requestOnce(method, path, body, query);
+        }
+        catch (error) {
+            if (!(error instanceof CrmUnauthenticatedError)) {
+                throw error;
+            }
+        }
+        await this.ensureToken(true);
+        try {
+            return await this.requestOnce(method, path, body, query);
+        }
+        catch (error) {
+            if (error instanceof CrmUnauthenticatedError) {
+                throw new CrmAuthenticationError();
+            }
+            throw error;
+        }
+    }
+    async post(path, body, query) {
+        return this.call("POST", path, body, query);
+    }
+    async ensureToken(force = false) {
+        if (!this.apiKey.trim()) {
+            throw new Error(API_KEY_REQUIRED_MESSAGE);
+        }
+        if (!force && this.adminToken.trim()) {
+            return;
+        }
+        this.adminToken = await this.loginWithApiKey();
+    }
+    async loginWithApiKey() {
+        try {
+            const response = await this.fetchImpl(this.buildUrl("/login"), {
+                method: "POST",
+                headers: this.buildHeaders(true),
+                body: JSON.stringify({
+                    loginType: 12,
+                    authorization: this.apiKey,
+                    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 CrmAuthenticationError();
+        }
+    }
+    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)
+        });
+        if (response.status === 401 || response.status === 403) {
+            throw new CrmUnauthenticatedError();
+        }
+        const result = await parseJsonResult(response);
+        if (result.code === 302) {
+            throw new CrmUnauthenticatedError();
+        }
+        if (result.code !== 0) {
+            throw new Error(result.msg || `72CRM 接口返回异常，code=${result.code}`);
+        }
+        return result.data;
+    }
+    buildUrl(path, query) {
+        assertFixedPath(path);
+        const url = new URL(path.slice(1), this.baseUrl);
+        for (const [key, value] of Object.entries(query ?? {})) {
+            if (value !== undefined && value !== null && value !== "") {
+                url.searchParams.set(key, String(value));
+            }
+        }
+        return url.toString();
+    }
+    buildHeaders(hasJsonBody, adminToken) {
+        const headers = new Headers();
+        if (adminToken) {
+            headers.set("Admin-Token", adminToken);
+        }
+        if (hasJsonBody) {
+            headers.set("Content-Type", "application/json;charset=UTF-8");
+        }
+        return headers;
+    }
+}
+class CrmUnauthenticatedError extends Error {
+    constructor() {
+        super("72CRM 当前登录态已失效。");
+    }
+}
+class CrmAuthenticationError extends Error {
+    constructor() {
+        super(AUTH_FAILURE_MESSAGE);
+    }
+}
+async function parseJsonResult(response) {
+    const text = await response.text();
+    if (!text) {
+        return { code: response.ok ? 0 : response.status, msg: response.statusText, data: undefined };
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error("72CRM 接口返回了非 JSON 内容，当前 MCP 不代理文件流或下载响应。");
+    }
+}
+function normalizeBaseUrl(baseUrl) {
+    return baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function assertFixedPath(path) {
+    if (!path.startsWith("/")) {
+        throw new Error("MCP 仅允许调用固定白名单接口，不允许任意 URL 透传。");
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createWukongMcpServer } from "./server.js";
+const server = createWukongMcpServer();
+await server.connect(new StdioServerTransport());

package/dist/modules.d.ts

@@ -0,0 +1,17 @@
+export type ModuleKey = "leads" | "customer" | "contacts" | "product" | "business" | "contract" | "receivables" | "receivablesPlan" | "invoice" | "activity" | "quotation" | "returnVisit" | "visitPlan" | "customerPool" | "leadsPool";
+export interface CrmModuleDefinition {
+    key: ModuleKey;
+    name: string;
+    label: number;
+    basePath: string;
+    primaryKey: string;
+    aliases: string[];
+    supportedOperations: string[];
+    unsupportedOperations: string[];
+    writable: boolean;
+}
+export declare const CRM_MODULES: CrmModuleDefinition[];
+export declare const WRITE_MODULES: Set<ModuleKey>;
+export declare function getModuleByKey(module: string | number): CrmModuleDefinition;
+export declare function ensureWritableModule(module: CrmModuleDefinition): void;
+export declare function unsupportedOperationMessage(operation: string): string;

package/dist/modules.js

@@ -0,0 +1,193 @@
+const COMMON_READ = ["搜索", "详情", "字段", "详情页信息", "附件"];
+const UNSUPPORTED_HIGH_RISK = ["删除", "负责人转移", "导入导出", "审批/状态流转"];
+export const CRM_MODULES = [
+    {
+        key: "leads",
+        name: "线索",
+        label: 1,
+        basePath: "/crmLeads",
+        primaryKey: "leadsId",
+        aliases: ["线索", "crmLeads", "1"],
+        supportedOperations: [...COMMON_READ, "简要实体", "新增", "更新", "跟进"],
+        unsupportedOperations: ["删除", "转移", "锁定", "分配/领取", "公海", "导入导出", "团队成员", "合并", "共享"],
+        writable: true
+    },
+    {
+        key: "customer",
+        name: "客户",
+        label: 2,
+        basePath: "/crmCustomer",
+        primaryKey: "customerId",
+        aliases: ["客户", "crmCustomer", "2"],
+        supportedOperations: [...COMMON_READ, "客户名/ID 查询", "新增", "更新", "跟进"],
+        unsupportedOperations: ["删除", "成交状态", "锁定", "负责人转移", "公海", "地址写入", "上下级客户", "客户产品", "合并", "导入导出"],
+        writable: true
+    },
+    {
+        key: "contacts",
+        name: "联系人",
+        label: 3,
+        basePath: "/crmContacts",
+        primaryKey: "contactsId",
+        aliases: ["联系人", "crmContacts", "3"],
+        supportedOperations: [...COMMON_READ, "关联商机只读", "新增", "更新", "跟进"],
+        unsupportedOperations: ["删除", "关联/取消关联商机写入", "负责人转移", "团队成员", "合并", "导入导出"],
+        writable: true
+    },
+    {
+        key: "product",
+        name: "产品",
+        label: 4,
+        basePath: "/crmProduct",
+        primaryKey: "productId",
+        aliases: ["产品", "crmProduct", "4"],
+        supportedOperations: [...COMMON_READ, "简要实体", "销售产品列表"],
+        unsupportedOperations: ["新增", "更新", "删除", "上下架", "负责人转移", "导入导出"],
+        writable: false
+    },
+    {
+        key: "business",
+        name: "商机",
+        label: 5,
+        basePath: "/crmBusiness",
+        primaryKey: "businessId",
+        aliases: ["商机", "crmBusiness", "5"],
+        supportedOperations: [...COMMON_READ, "关联产品/联系人只读", "新增", "更新", "跟进"],
+        unsupportedOperations: ["删除", "赢单/输单状态", "负责人转移", "关联联系人写入", "团队成员", "合并", "导入导出"],
+        writable: true
+    },
+    {
+        key: "contract",
+        name: "合同",
+        label: 6,
+        basePath: "/crmContract",
+        primaryKey: "contractId",
+        aliases: ["合同", "crmContract", "6"],
+        supportedOperations: [...COMMON_READ, "合同产品", "回款计划", "简要实体"],
+        unsupportedOperations: ["新增", "更新", "作废", "状态更新", "负责人转移", "审批相关", "导入导出"],
+        writable: false
+    },
+    {
+        key: "receivables",
+        name: "回款",
+        label: 7,
+        basePath: "/crmReceivables",
+        primaryKey: "receivablesId",
+        aliases: ["回款", "crmReceivables", "7"],
+        supportedOperations: [...COMMON_READ, "产品明细", "简要实体"],
+        unsupportedOperations: ["新增", "更新", "删除", "负责人转移", "审批/财务状态", "导入导出"],
+        writable: false
+    },
+    {
+        key: "receivablesPlan",
+        name: "回款计划",
+        label: 8,
+        basePath: "/crmReceivablesPlan",
+        primaryKey: "receivablesPlanId",
+        aliases: ["回款计划", "crmReceivablesPlan", "8"],
+        supportedOperations: [...COMMON_READ, "按合同/客户查询"],
+        unsupportedOperations: ["新增", "批量保存", "更新", "删除", "负责人转移", "导入导出"],
+        writable: false
+    },
+    {
+        key: "invoice",
+        name: "发票",
+        label: 18,
+        basePath: "/crmInvoice",
+        primaryKey: "invoiceId",
+        aliases: ["发票", "crmInvoice", "18"],
+        supportedOperations: [...COMMON_READ, "发票类型"],
+        unsupportedOperations: ["新增", "更新", "开票/重置状态", "发票明细写入", "删除", "导入导出"],
+        writable: false
+    },
+    {
+        key: "activity",
+        name: "跟进记录",
+        label: 19,
+        basePath: "/crmActivity",
+        primaryKey: "activityId",
+        aliases: ["跟进记录", "跟进", "crmActivity", "19"],
+        supportedOperations: [...COMMON_READ, "新增", "更新", "评论数"],
+        unsupportedOperations: ["删除", "有效性标记", "外勤签到", "邮箱活动", "导入导出"],
+        writable: false
+    },
+    {
+        key: "quotation",
+        name: "报价单",
+        label: 26,
+        basePath: "/crmQuotation",
+        primaryKey: "quotationId",
+        aliases: ["报价单", "crmQuotation", "26"],
+        supportedOperations: [...COMMON_READ, "产品明细", "简要实体"],
+        unsupportedOperations: ["新增", "更新", "状态更新", "负责人转移", "团队成员", "导入导出"],
+        writable: false
+    },
+    {
+        key: "returnVisit",
+        name: "回访",
+        label: 17,
+        basePath: "/crmReturnVisit",
+        primaryKey: "visitId",
+        aliases: ["回访", "crmReturnVisit", "17"],
+        supportedOperations: [...COMMON_READ, "简要实体"],
+        unsupportedOperations: ["新增", "更新", "删除", "提醒配置", "团队成员", "导入导出"],
+        writable: false
+    },
+    {
+        key: "visitPlan",
+        name: "拜访计划",
+        label: 25,
+        basePath: "/crmVisit",
+        primaryKey: "visitPlanId",
+        aliases: ["拜访计划", "crmVisit", "25"],
+        supportedOperations: [...COMMON_READ],
+        unsupportedOperations: ["新增", "更新", "删除", "状态类操作"],
+        writable: false
+    },
+    {
+        key: "customerPool",
+        name: "客户公海",
+        label: 9,
+        basePath: "/crmCustomerPool",
+        primaryKey: "customerId",
+        aliases: ["客户公海", "crmCustomerPool", "9"],
+        supportedOperations: ["列表查询只读"],
+        unsupportedOperations: ["领取", "分配", "退回", "转移", "公海规则配置"],
+        writable: false
+    },
+    {
+        key: "leadsPool",
+        name: "线索池",
+        label: 21,
+        basePath: "/crmLeadsPool",
+        primaryKey: "leadsId",
+        aliases: ["线索池", "crmLeadsPool", "21"],
+        supportedOperations: ["列表查询只读"],
+        unsupportedOperations: ["领取", "分配", "退回", "转移", "公海规则配置"],
+        writable: false
+    }
+];
+export const WRITE_MODULES = new Set(["leads", "customer", "contacts", "business"]);
+const MODULE_LOOKUP = new Map();
+for (const moduleDefinition of CRM_MODULES) {
+    MODULE_LOOKUP.set(moduleDefinition.key.toLowerCase(), moduleDefinition);
+    for (const alias of moduleDefinition.aliases) {
+        MODULE_LOOKUP.set(alias.toLowerCase(), moduleDefinition);
+    }
+}
+export function getModuleByKey(module) {
+    const key = String(module).trim().toLowerCase();
+    const definition = MODULE_LOOKUP.get(key);
+    if (!definition) {
+        throw new Error(`不支持的 CRM 模块：${module}。请先调用 crm_list_modules 查看白名单。`);
+    }
+    return definition;
+}
+export function ensureWritableModule(module) {
+    if (!WRITE_MODULES.has(module.key)) {
+        throw new Error(`当前 MCP 前期不支持对“${module.name}”执行写入操作。`);
+    }
+}
+export function unsupportedOperationMessage(operation) {
+    return `当前 MCP 前期不支持${operation}。已禁用：${UNSUPPORTED_HIGH_RISK.join("、")}、附件上传。`;
+}

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CrmClientConfig } from "./client.js";
+export declare function createWukongMcpServer(config?: CrmClientConfig): McpServer;