# 客徕徕 SCRM MCP Server

**让 AI 助手通过标准 MCP 协议查询客户、理解会话、准备运营内容，并在确认后执行已有业务操作。**

本项目将客徕徕 SCRM 的业务 API 封装为 **42 个公开 MCP 工具**，配套 **17 个业务 Skills**，提供 HTTP / stdio 接入、自动生成的工具手册、参数校验、写操作确认、预演和调用统计。

它是 AI 客户端与业务后端之间的接入服务，不是独立聊天机器人，也不包含业务数据库、模型服务或工作手机端。核心工具主要对接 **wei-kefu-be** 的接口契约；企业微信 `wework-server` 是相关项目，不能只替换 URL 就假定全部工具兼容。

**微信（WeChat）：`Linglanhuakaiyue`（技术支持 / 合作）**

[联系我们](https://kelailai.chat/contact-us.html) · [快速开始](#快速开始) · [客户端接入](#客户端接入) · [工具清单](#工具清单) · [业务-skills](#业务-skills) · [关联仓库](#关联仓库)

## MCP 在整个项目中的作用

传统工作台由人点击页面、查询数据和提交任务；MCP 把相同业务能力转换为 AI 客户端可发现、可调用的工具。Agent 可以先读业务数据，再组织分析和建议，经确认后调用后端完成操作。

```mermaid
flowchart LR
    Human[客服 / 运营人员] --> AI[支持 MCP 的 AI 客户端]
    AI <-->|HTTP 或 stdio| MCP[kelailai-mcp-server]
    MCP --> Tools[42 个工具 / 参数校验 / 确认与预演]
    AI --> Skills[17 个业务 Skills]
    Tools --> Backend[兼容业务 API 的后端]
    Backend --> DB[(业务数据库)]
    Backend <-->|任务与回执| Device[工作手机 / 设备端]
    Web[Web / 桌面工作台] <--> Backend
```

### 可以帮助完成的工作

- **客服准备**：查好友和历史消息，整理客户画像、需求、跟进建议和公共话术。
- **会话处理**：查私聊/群聊消息，定位会话，准备回复；获确认后调用消息发送工具。
- **朋友圈运营**：准备与创建朋友圈任务、查看动态和评论、回复评论、查询好友动态并执行单条点赞操作。
- **群发与跟进**：创建好友或群群发任务，查看明细与失败原因，按业务接口重试失败目标。
- **客户管理**：查询分组、系统标签与微信原生标签，维护上下文记忆、号码组和自动加好友任务。
- **内容复用**：上传文件、查询或收藏素材、维护公共话术及关键词回复。
- **运营分析**：查询消息、好友、朋友圈和账号操作统计，结合 Skills 形成简报或复盘。
- **知识辅助**：检索企业知识库，辅助形成有业务依据的回复。

分析与文案由接入的模型完成，数据查询和执行结果由后端提供。模型质量、账号权限、设备状态和接口版本共同影响实际效果。

## 项目优势

| 优势 | 实现方式 |
| --- | --- |
| 统一接入 | 一个 MCP Server 暴露业务工具，兼容支持 Streamable HTTP 或 stdio 的客户端 |
| 工具与业务流程结合 | Tools 提供执行能力，Skills 描述准备、确认、执行和结果检查步骤 |
| 工具手册与代码同步 | `/onboard.json?full=1` 从工具注册表生成清单、参数与返回值说明，README 也有同源测试 |
| 减少重复 Schema | 合并工具族通过 action 选择分支，支持按组发现和 slim 展示；具体节省取决于客户端和场景 |
| 参数校验 | Zod 定义参数并生成 JSON Schema，错误返回结构化失败码和建议动作 |
| 写操作有明确边界 | 统一处理 `confirm=true`、`dry_run=true`、设备资格与读写限流；确认标记本身不替代宿主的人机确认 |
| 凭据传递分层 | HTTP 服务访问密钥与业务 JWT / API Key 分开；业务权限仍由后端执行 |
| 可观察 | 可选工具调用统计、耗时与失败分类，日志和统计参数提供凭据脱敏 |
| 独立自建 | 后端与上传地址通过环境变量配置，公开版默认使用本机地址，不附生产凭据和数据 |
| 开源可扩展 | TypeScript 单模块结构，可沿既有注册表、Schema、工具族和测试添加业务能力 |

工具清单过滤只影响 `tools/list`，**不是权限隔离**，不会禁止调用清单之外的工具。权限、授权和执行结果必须以服务端校验为准。

## 快速开始

### 1. 安装与构建

需要 **Node.js 22.14+**，推荐 **Node.js 24 LTS**。

```bash
git clone https://github.com/lwang998/kelailai-mcp-server.git
cd kelailai-mcp-server
npm ci --ignore-scripts --no-audit --no-fund
npm run build
```

核心 HTTP / stdio 服务不需要 Electron 或 SQLite 原生模块，因此使用 `--ignore-scripts` 安装即可进行服务构建与单元测试。`src/electron/` 保留历史桌面集成代码，本次不将其视为完成验收的桌面产品。

### 2. 配置自己的环境

```bash
cp .env.example .env
node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"
```

PowerShell 可用 `Copy-Item .env.example .env`。将生成的随机值填入 `.env` 的 `MCP_API_TOKEN`，再按自己的环境修改后端地址。不要提交 `.env`。

```dotenv
KEFU_BASE_URL=http://127.0.0.1:13086
UPLOAD_URL=http://127.0.0.1:18081/fileUpload
MCP_TRANSPORT=http
MCP_HOST=127.0.0.1
MCP_PORT=3010
MCP_PUBLIC_BASE_URL=http://127.0.0.1:3010
MCP_API_TOKEN=填入自己生成的随机值
MCP_AUTH_DISABLED=false
MCP_BUSINESS_AUTH_DISABLED=false
MCP_STATS_ENABLED=false
```

`.env` 通过 dotenv 从启动工作目录读取。没有 `MCP_API_TOKEN` 且未显式关闭访问鉴权时，HTTP 服务拒绝启动；公开示例默认只监听本机。

### 3. 启动与查看手册

```bash
npm start
```

- 健康检查：`http://127.0.0.1:3010/health`
- 接入页面：`http://127.0.0.1:3010/onboard`
- 精简接入信息：`http://127.0.0.1:3010/onboard.json`
- 完整工具文档：`http://127.0.0.1:3010/onboard.json?full=1`
- MCP 协议地址：`http://127.0.0.1:3010/mcp`

健康检查和接入手册可以在没有真实后端的情况下打开。业务工具需要自己的兼容后端与业务凭据；HTTP 200 的接入页面并不表示已完成业务认证。

## 客户端接入

### HTTP：服务密钥与业务凭据分开

服务访问使用 `x-mcp-token`，业务凭据使用 `token`，避免占用同一个 Authorization 头。

```json
{
  "mcpServers": {
    "kelailai": {
      "url": "http://127.0.0.1:3010/mcp?tools=core&schema=slim",
      "headers": {
        "x-mcp-token": "YOUR_MCP_API_TOKEN",
        "token": "YOUR_BUSINESS_TOKEN"
      }
    }
  }
}
```

这是通用配置形状，具体字段和环境变量引用语法以客户端为准。已有业务 API Key / JWT 时填入自己的凭据；没有业务 token 时，可以先仅配置服务密钥，调用 `auth_login`，再把返回的 token 配到业务头中。

`initialize`、`tools/list`、`ping` 和登录引导工具不要求已存在的业务 JWT，但仍受启用的 HTTP 服务访问鉴权控制。其他业务调用默认校验业务凭据。公开接入手册只输出密钥占位引用，不回传服务端实际密钥。

### stdio：由客户端启动本地进程

```json
{
  "mcpServers": {
    "kelailai": {
      "command": "node",
      "args": ["/absolute/path/kelailai-mcp-server/dist/index.js"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "KEFU_BASE_URL": "http://127.0.0.1:13086",
        "KEFU_TOKEN": "YOUR_BUSINESS_TOKEN",
        "UPLOAD_URL": "http://127.0.0.1:18081/fileUpload",
        "MCP_STATS_ENABLED": "false"
      }
    }
  }
}
```

替换为自己的绝对路径。stdio 不使用 HTTP 层的服务密钥，应由启动它的客户端隔离进程与凭据；工具请求仍需要被后端接受。stdio 保持统计关闭，以免历史统计的标准输出污染 MCP 通信。

更详细的 HTTP 调用和鉴权说明见 [docs/USAGE.md](docs/USAGE.md)。

## 工具清单

写操作需在用户明确确认后传入 `confirm=true`；`dry_run=true` 用于预演工具将构造的后端调用，不代表业务已经执行。预演不会调用真实 BackendClient，但 URL 文件上传的准备过程可能抓取 `source_url`，无网络预演应使用 base64 文件输入。

### 可用工具（42 个，与注册表一致）

| 分类 | 工具 | 用途 |
| --- | --- | --- |
| 登录与引导 | `auth_login`, `auth_session_guide` | 登录业务系统、获取标准凭据检查指引 |
| 账号与文件 | `wechat_list`, `device_group_list`, `file_upload` | 查询微信账号/设备分组、上传文件 |
| 好友与分组 | `friend_list`, `friend_detail`, `friend_group` | 查询好友及资料、读取或移动分组 |
| 群聊 | `chatroom_list`, `chatroom_member_list` | 查询群与群成员 |
| 会话与消息 | `session`, `message_search`, `message_list`, `chat_history`, `chatroom_message_search`, `message_send`, `chatroom_message_send` | 查会话与历史、私聊或群消息发送 |
| 朋友圈与评论 | `circle_create`, `circle_list`, `circle_detail`, `circle_delete`, `circle_comment_list`, `circle_comment_reply`, `circle_comment_delete`, `circle_friend_list`, `circle_like` | 朋友圈任务、动态、评论、好友动态与单条点赞 |
| 群发与定时任务 | `mass_create`, `timed_task` | 好友/群群发、任务明细、目标和失败记录、重试与状态管理 |
| 好友自动化 | `sop_friend_add_task`, `group_member_auto_add`, `phone_group`, `phone_number` | 加好友任务、群成员自动添加、号码组与号码导入 |
| 标签 | `system_label`, `wechat_label` | 系统标签与微信原生标签；原生批量打标返回任务进度 |
| 关键词与素材 | `keyword`, `material` | 关键词/敏感词管理、触发记录、素材查询/收藏/维护 |
| 公共话术 | `common_term`, `common_term_group`, `common_term_order` | 公共话术、分类和排序 |
| 客户上下文 | `contact_context` | 客户资料、上下文记忆查询与维护 |
| 知识库 | `search_ai_knowledge` | 企业知识检索 |
| 运营统计 | `ops_query` | 总览、消息、好友、朋友圈、操作日志和限流状态等只读统计 |

完整 action、参数、返回字段以自身服务的 `/onboard.json?full=1` 和 `tools/list` 为准。旧工具名通过 aliases 保留兼容，但不计入公开工具数量。

## 业务 Skills

Skills 是随仓提供的 Markdown 工作流说明，由 Agent 阅读和执行；它们不等同于后台自动开启的定时任务。

| 场景 | Skill |
| --- | --- |
| 统一入口与启动检查 | `scrm-using`、`scrm-bootstrap` |
| 朋友圈内容、效果与互动 | `scrm-circle`、`scrm-circle-effect`、`scrm-moments-like` |
| 客户理解 | `scrm-contact-portrait`、`scrm-chat-insight`、`scrm-vip-signal` |
| 沟通与转化准备 | `scrm-talk-prep`、`scrm-first-touch`、`scrm-deal-blocker`、`scrm-deal-review` |
| 日常与运营报告 | `scrm-daily-brief`、`scrm-ops-report` |
| 群发 | `scrm-mass-friend`、`scrm-mass-chatroom` |
| 实时消息与自动回复 | `scrm-auto-reply` |

源码在 [skills/](skills/)。服务支持 `/skills/<id>.md` 及对应 references 路径，默认需要业务鉴权。不要将 Skills 中的示例域名当成可用服务地址。

## 实时消息盒子

普通工具查询和发送不要求安装盒子。持续收消息与后台自动回复需要额外部署 `scrm-auto-reply` 对应的本机组件、兼容后端推送协议和模型/Agent 驱动。

- 当前工作流使用本机 **39202** 端口的消息盒子，提供 wait / peek / ack 等 HTTP 接口。
- 盒子与驱动源码保存在该 Skill 的 references Markdown 中；[scripts/build-box-exe.mjs](scripts/build-box-exe.mjs) 可用 Bun 构建分发程序。
- 仓库不附可执行程序。`/dl/*` 在没有自行构建并配置产物时会返回 404。
- 历史 Bridge **39200** 不是当前接入主路径；远程 MCP 不提供收件箱工具。
- 可选 `/box-ws` 中继默认关闭。不要把公开 MCP 服务启动成功理解为实时盒子已经部署。

## 配置、权限与边界

| 配置 | 说明 |
| --- | --- |
| `KEFU_BASE_URL` | 兼容业务后端根地址，默认本机 13086 |
| `KEFU_TOKEN` | 可选进程默认业务凭据；多用户 HTTP 场景优先使用请求级凭据 |
| `UPLOAD_URL` | 文件服务上传地址 |
| `MCP_TRANSPORT` | http / stdio；默认 http |
| `MCP_HOST` / `MCP_PORT` / `MCP_PATH` | HTTP 监听；`.env.example` 使用本机 3010 与 /mcp |
| `MCP_PUBLIC_BASE_URL` | 生成接入链接时使用的外部可达地址 |
| `MCP_API_TOKEN` | HTTP 服务访问密钥，不是业务 token |
| `MCP_AUTH_DISABLED` / `MCP_BUSINESS_AUTH_DISABLED` | 分别控制服务访问与业务鉴权；公开示例均为 false |
| `MCP_RATE_READ_PER_MINUTE` / `MCP_RATE_WRITE_PER_MINUTE` | 读写限流默认 60 / 10 |
| `MCP_RATE_MEDIA_WRITE_PER_MINUTE` | 媒体写入限流默认 2 |
| `MCP_TIMEOUT_MS` | 后端请求超时默认 10000 毫秒 |
| `MCP_STATS_ENABLED` | 可选统计；示例默认关闭 |
| `MCP_STATS_DB_PATH` | 统计数据目录，不是文件名；不要提交生成的数据 |
| `BOX_WS_ENABLED` | 可选盒子中继开关，默认关闭 |

工具曝光策略定义于 [EXPOSURE_POLICY](src/tools/exposure.ts)：账号权限、密钥计费、内部运维、发布与设备授权等接口不直接作为业务工具开放。工具写入还会调用后端的设备资格检查，并按后端权限与业务规则执行。

这不是“AI 无限制接管系统”。实际操作应先查询目标、展示拟执行内容并获用户确认，之后调用工具、检查返回码和任务回执；接口受理不等于手机已执行成功。

## 测试与开发

```bash
npm run build
npm test
npm run check:confirm
```

测试覆盖工具注册表、Schema、合并工具族、确认与预演、错误分类、鉴权、token 续期、日志脱敏、HTTP 接入、Skills 和 README 一致性。材料类型测试使用仓库内协议枚举快照，无需私有兄弟仓库。

公开版本修复了接入页回显服务密钥的问题，并增加回归测试；入口会加载 `.env`，生成的默认接入指令区分服务密钥和业务凭据。构建会复制统计页到 dist，避免源码有页面而构建产物缺失。

当前验证基线：**335 个测试通过**，**53 个写入口的确认门禁与预演检查通过**；真实 MCP SDK 的 HTTP / stdio 握手、42 个工具发现和本地引导调用通过。测试与协议握手通过不等于已完成真实账号、设备发送、第三方模型或跨平台盒子的联调验收。

## 关联仓库

| 仓库 | 作用 |
| --- | --- |
| [kelailai-mcp-server](https://github.com/lwang998/kelailai-mcp-server) | MCP 工具、Agent 接入手册和业务 Skills（本仓库） |
| [wei-kefu-be](https://github.com/icodingany/wei-kefu-be) | MCP 核心工具主要适配的业务 API 后端 |
| [kelailaichatpc](https://github.com/icodingany/kelailaichatpc) | 关联微信私域管理前端 |
| [wework-server](https://github.com/icodingany/wework-server) | 企业微信业务后端；接入 MCP 前需逐项核对 API 契约 |
| [workchat](https://github.com/icodingany/workchat) | 企业微信前端与桌面工程 |

各仓库状态以实际发布内容为准。文件服务、设备端、授权/资格数据和模型能力需要根据部署场景另行配置。

## 在线体验与联系方式

整体产品测试站：**https://test.kelailai.chat/**

| 公开测试账号 | 密码 |
| --- | --- |
| `test7` | `t123456` |

这是维护者授权公开的网页体验账号，不是本仓库初始化账号，也不保证具备 MCP 写入权限。请使用模拟数据；测试环境功能以账号权限和设备状态为准。公开版不自动连接测试站。

- **微信（WeChat）：`Linglanhuakaiyue`（技术支持 / 合作）**
- **联系页面：https://kelailai.chat/contact-us.html**
- 问题与建议：[GitHub Issues](https://github.com/lwang998/kelailai-mcp-server/issues)
- 可交流：MCP 接入、私有化部署、Agent 工作流、业务系统集成与二次开发。

## 许可证

项目自有代码采用 [MIT License](LICENSE)。npm 依赖保留其各自许可证，参见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。公开仓库不包含生产配置、真实业务数据、私钥、登录态、运行日志或已构建的客户端程序。