mcp-server-weisheng-scrm

微盛企微管家 SCRM 的 MCP Server，基于 MCP 协议 将微盛 SCRM 开放平台的客户管理能力暴露为标准 MCP Tool，供 AI 助手通过自然语言调用。

通过 npx 从 npm 拉取运行，以 stdio 子进程方式与 MCP Client（WorkBuddy）通信。

技术栈

| 组件 | 选型 | |------|------| | 语言 | TypeScript 5.8 | | MCP SDK | @modelcontextprotocol/sdk ^1.12.0 | | 参数校验 | zod ^3.25.0（MCP SDK 内置依赖） | | 运行时 | Node.js >= 18 | | 传输 | stdio（StdioServerTransport） | | 依赖数 | 2 个运行时依赖（零业务依赖） |

关联项目

| 项目 | 说明 | |------|------| | weisheng-scrm-connector | WorkBuddy Connector 配置文件（mcp.json、token-schema.json、skill.md） |

项目结构

src/
├── index.ts              # MCP Server 入口，注册 6 个 Tool + 8 节 instructions
├── config.ts             # 环境变量读取（SCRM_APP_KEY / SCRM_BASE_URL）
├── exceptions.ts         # 异常体系（AuthError / NetworkError / ValidationError / ...）
├── core/
│   ├── cache.ts          # 内存缓存（SimpleCache：通用 KV + 文档已读 Map）
│   ├── json.ts           # safeJsonParse（大整数精度保护）
│   ├── token-manager.ts  # Token 管理（APP_KEY → access_token）
│   ├── http-client.ts    # HTTP 客户端（自动注入 Token / 刷新 / 超时）
│   ├── identity.ts       # 用户身份（角色查询 + 缓存）
│   ├── api-catalog.ts    # 接口目录（全量拉取 + 关键词模糊搜索）
│   ├── doc-fetcher.ts    # 远程文档读取
│   ├── doc-parser.ts     # FIELD_INPUT_SPEC 提取
│   ├── param-splitter.ts # 参数拆分（path / query / body 三段）
│   ├── param-validator.ts# 参数校验（强校验 + 弱校验 + deepEqual）
│   ├── proxy-forwarder.ts# 代理转发（SINGLE + AGGREGATION 轮询）
│   └── file-uploader.ts  # 图片上传（multipart）
└── tools/
    ├── check-identity.ts # Tool: 身份验证
    ├── list-apis.ts      # Tool: 接口搜索
    ├── fetch-api-doc.ts  # Tool: 文档读取
    ├── call-api.ts       # Tool: 接口调用
    ├── upload-image.ts   # Tool: 图片上传
    └── fetch-url.ts      # Tool: 通用 URL 读取

6 个 MCP Tool

| Tool | 功能 | 参数 | |------|------|------| | check-identity | 验证身份，返回用户角色信息 | 无 | | list-apis | 按关键词模糊搜索 SCRM API 目录 | keyword: string | | fetch-api-doc | 获取接口完整文档（参数定义、来源说明） | doc_url: string | | call-api | 调用指定的 SCRM API 接口 | doc_url: string, biz_params: string(JSON) | | upload-image | 上传本地图片，返回公网 URL | file_path: string | | fetch-url | 读取远程 URL 文本内容 | url: string |

环境变量

| 变量 | 必填 | 说明 | |------|:----:|------| | SCRM_APP_KEY | 是 | 用户在 Connector 表单中填入的 APP KEY | | SCRM_BASE_URL | 否 | SCRM 平台地址，默认 https://open.wshoto.com |

上游 API 接口

| 接口 | 方法 | 用途 | |------|------|------| | /openapi/personal_access_token | GET | APP_KEY 换 access_token | | /openapi/auth/check_super_user | POST | 获取用户身份角色 | | /openapi/claw/api/page | POST | 获取接口目录列表 | | /openapi/claw/proxy/forward | POST | 通用代理转发（SINGLE / AGGREGATION） | | /openapi/document/upload/bind | POST multipart | 图片上传 |

内置 instructions

MCP Server 在握手阶段向 AI 下发 8 节全局规则（约 120 行），覆盖：调用流程、用户沟通原则、身份与权限、接口间数据依赖、写操作限制、聚合接口说明、分页数据完整性、错误处理。

缓存设计

| 缓存 | 维度 | TTL | 说明 | |------|------|-----|------| | access_token | 员工级 | expires_in - 300s | 自动刷新 | | api_list | 租户级 | 7200s（2h） | 接口目录 | | identity | 员工级 | 7200s（2h） | 用户角色 | | 文档已读标记 | 员工级 | 7200s（2h） | call-api 调用前校验 |

所有缓存为进程级内存缓存，子进程终止时自然清空。

开发

# 安装依赖
npm install

# 编译
npm run build

# 本地运行
SCRM_APP_KEY="你的APP_KEY" npm start

# 监听模式开发
npm run dev

发布

npm run build
npm publish

本地调试（配合 Connector）

SCRM_APP_KEY="你的APP_KEY" npx mcp-server-weisheng-scrm

启动后通过 stdin 发送 MCP JSON-RPC 请求即可测试。

关键技术决策

| 决策 | 说明 | |------|------| | 大整数精度保护 | Java Long 型 ID（19 位雪花 ID）超出 JS Number.MAX_SAFE_INTEGER，safeJsonParse 在解析前将 16+ 位数字转为字符串 | | 文档已读门控 | 内存 Map（docUrl → expireAt），2 小时 TTL；call-api 调用前检查 doc_url 是否已读 | | const 深度比较 | 参数校验中 object 类型的 const 值使用 deepEqual 递归比较，不依赖 key 顺序 | | 零运行时依赖 | 仅 @modelcontextprotocol/sdk 和 zod，npx 下载体积小 |