107 lines
7.4 KiB
Markdown
107 lines
7.4 KiB
Markdown
# NocoBase CRM MCP
|
||
|
||
在你的电脑上，让 AI 客户端安全地查询 NocoBase CRM。首次需要认证时通过浏览器登录 NocoBase；每位用户使用自己的身份，看到的数据范围与本人在 NocoBase 中的权限一致。
|
||
|
||
## 安装或更新
|
||
|
||
推荐把首次安装和后续更新都交给支持终端操作的 AI Agent 完成。同一段提示可以重复使用：Agent 会先检查本机状态，未安装时完成首次安装，已安装时保留个人配置和登录状态并更新到最新 Commit。你不需要克隆源码，也不需要逐条执行命令。
|
||
|
||
### 安装前准备
|
||
|
||
- Node.js 20.11 或更高版本；
|
||
- 能访问 `https://justconn.top`；
|
||
- 你自己的 NocoBase 账号；
|
||
- 能读取当前 Gitea 仓库 `main` 分支，并能访问 npm 软件源。
|
||
|
||
如果 Node.js 尚未安装，Agent 会先说明需要进行的系统变更，并在获得你确认后再继续。
|
||
|
||
支持 Windows、macOS 和 Linux，三个平台都会使用任务开始时 `main` 的最新 Commit。
|
||
|
||
不需要提前创建或复制 Authorize Key。MCP 注册或重载后，Agent 会先检查现有登录；只有确实需要认证时才调用登录工具并把 NocoBase 官方网页链接发给你。桌面环境通常也会自动打开该页面，你确认授权后 Agent 会自动继续验收。
|
||
|
||
### 最快方式
|
||
|
||
无论是第一次安装还是以后更新，都把下面整段直接复制给 Agent：
|
||
|
||
```text
|
||
请按以下 INSTALL.md 帮我安装或更新 NocoBase CRM MCP。自动判断首次安装、更新、修复或已是最新，使用 main 当前最新 Commit，并严格执行文档中的安全与验收规则；已有安装时保留配置、凭据和读写模式。只有确实需要登录时，才把 NocoBase 官方网页链接和确认码发给我。无界面或远程环境也要发到当前私聊；它们不是密码、Token、Key 或 device_code，不要要求远程桌面。安装系统工具前先征得我同意。完成前确认 crm_health 返回 ok=true。
|
||
https://git.justconn.top/gitea-admin/nocobase-mcp/raw/branch/main/INSTALL.md
|
||
```
|
||
|
||
Agent 会固定任务开始时的最新 Commit，按本机状态执行安装、更新、修复或直接验收；已有安装会保留个人状态，相同 Commit 不会重复构建。注册后先检查 `crm_health`，只有认证确实缺失或失效时才发起登录。桌面环境通常自动打开浏览器；远程 Agent 会把同一授权链接发到当前对话，MCP 重启后也能继续该授权。
|
||
|
||
完整的安装、更新和验收规则见 [INSTALL.md](INSTALL.md)。该 `main` 链接是统一入口；Agent 必须先解析一次最新 Commit，然后重新读取该 Commit 中不可变的同一文件，不能在一次任务中混用不同提交。
|
||
|
||
## 重要注意事项
|
||
|
||
- **只在 NocoBase 网页登录：** 安装程序不会读取浏览器 Cookie，也不会接触你的密码；OAuth 令牌只保存到权限受限的个人凭据文件，不会进入聊天、命令参数、环境变量、CRM 配置、MCP 客户端配置或日志。
|
||
- **默认只读：** 安装后默认只能查询 CRM，不会创建、更新或删除业务数据。
|
||
- **权限跟随本人：** MCP 不会绕过 NocoBase 的角色、字段权限和行级权限，也不会使用共享管理员账号。
|
||
- **远程登录不需要远程桌面：** Hermes Agent、OpenClaw 或无界面服务器会把短期 OAuth Device Flow 验证链接和确认码发到发起用户的当前私聊；它们不能发到群聊、公开频道或第三方，但不是密码、Token、Key 或内部 `device_code`。
|
||
- **只连接公司环境：** 程序固定连接 `https://justconn.top/api`，不会要求你填写其他 NocoBase 地址。
|
||
- **始终使用最新提交：** 每次安装或更新只解析一次 `main` 的最新 Commit SHA，随后固定该快照完成任务；不会因为旧 Release 可用而安装旧代码。
|
||
- **更新保留个人状态：** 更新不会覆盖 CRM `config.json`、OAuth 凭据或现有只读/写入模式；已有登录有效时不会要求重新授权。
|
||
- **安装在用户目录：** 不使用 `sudo`，不会全局安装本项目，也不需要 Git、Python、uv 或 `nb CLI`。源码和构建依赖只存在于临时目录，安装后仅保留打包运行文件。
|
||
- **受限仓库需要授权：** 如果 Agent 无法读取 Gitea `main` 或对应 Commit 快照，请联系仓库管理员开通权限，不要把访问令牌发到聊天中。
|
||
|
||
## 安装后可以做什么
|
||
|
||
你可以直接让 AI：
|
||
|
||
- 查询客户、联系人和跟进记录；
|
||
- 按负责人、团队、状态或时间范围筛选 CRM 数据；
|
||
- 查看 CRM 总览、团队贡献和长期未跟进客户；
|
||
- 查看项目详情和项目跟进时间线。
|
||
|
||
例如：
|
||
|
||
```text
|
||
列出我负责的、最近 30 天没有有效跟进的客户。
|
||
```
|
||
|
||
```text
|
||
查看“华东团队”本月的客户、跟进和在途项目概况。
|
||
```
|
||
|
||
## 可选写入
|
||
|
||
只有在你明确需要创建或更新项目，并且管理员已经确认你的 NocoBase 权限时，才应启用写入模式。
|
||
|
||
写入模式只增加固定字段的项目创建和更新能力，不提供删除操作，也不开放任意集合或任意字段写入。不要为了绕过权限错误而换用共享高权限 Key。
|
||
|
||
## 遇到问题
|
||
|
||
- 尚未登录：让 Agent 调用 `nocobase_login`，把返回的 `login_url` 和 `user_code` 发给你；授权后调用 `nocobase_login_status`。
|
||
- 只想检查更新：仍发送上面的统一提示；如果本机已经是 `main` 当前最新 Commit，Agent 会直接验证并报告“已是最新”，不重复构建或登录。
|
||
- 登录失效：让 Agent 调用 `nocobase_login` 并设置 `force=true`，重新在浏览器授权；正常情况下访问令牌会在后台自动刷新。
|
||
- 浏览器没有打开：让 Agent 把 `nocobase_login` 返回的 `justconn.top` 链接和确认码发到当前私聊，然后在你的手机或电脑浏览器打开；不需要服务器远程桌面。若当前是群聊，请先转到与 Agent 的一对一私聊。
|
||
- MCP 客户端暂时无法调用登录工具：可在本人终端运行安装程序的 `setup --no-browser`，这是备用入口。
|
||
- 仅在 OAuth 暂时不可用且管理员明确要求时，才使用 `setup --manual-key` 的隐藏输入备用模式；不要把 Key 发到聊天中。
|
||
- 返回 `NO_PERMISSIONS`：请检查本人 NocoBase 角色和数据权限。
|
||
- 请求超时：确认可以访问 `https://justconn.top`，或缩小查询范围。
|
||
- 最新 Commit 无法解析或构建失败：停止本次任务并报告 Commit SHA 和失败步骤，不要退回旧 Release。
|
||
- 源码快照无法下载：确认当前账号或 Agent 已获得 Gitea 仓库的读取权限。
|
||
|
||
更多故障处理和更新、回滚说明见 [本机交付与权限验收](docs/LOCAL_DELIVERY.md)。
|
||
|
||
## 更多文档
|
||
|
||
- [完整安装/更新协议](INSTALL.md)：供 Agent 识别本机状态、固定最新 Commit、构建、安装或更新并验收。
|
||
- [命令与工具参考](docs/REFERENCE.md)：CLI 命令、MCP 工具和可选运行开关。
|
||
- [内部架构](docs/ARCHITECTURE.md)：模块边界、身份与网络安全设计。
|
||
- [本机交付与权限验收](docs/LOCAL_DELIVERY.md)：运维、权限验收、更新和回滚。
|
||
|
||
## 本地开发
|
||
|
||
开发者可从源码运行以下检查：
|
||
|
||
```bash
|
||
npm ci
|
||
npm run check
|
||
npm test
|
||
npm run build
|
||
node dist/index.js --help
|
||
```
|
||
|
||
本项目要求 Node.js 20.11 或更高版本。需要安装或更新时，Agent 会在临时目录从锁定依赖构建最新 Commit；最终运行包不含额外 npm 运行时依赖，用户不需要长期保留源码开发环境。
|