116 lines
5.9 KiB
Markdown
116 lines
5.9 KiB
Markdown
# 安装 NocoBase CRM MCP
|
||
|
||
这是一份供终端型 AI Agent 执行的通用安装协议，不依赖任何特定 Agent 或 MCP 客户端。用户只需要提供本链接、确认本机变更，并在隐藏提示中输入自己的 NocoBase Authorize Key。
|
||
|
||
如果你是安装 Agent，请直接执行流程，不要让用户逐条尝试命令。只有在确认系统工具变更、要求用户创建 Key，或让用户在隐藏提示中粘贴 Key 时才中断用户。
|
||
|
||
## 完成标准
|
||
|
||
- 下载本文件所在的同一固定 Release，不使用默认分支；
|
||
- 只连接固定的 NocoBase API `https://justconn.top/api`；
|
||
- MCP 在用户本机以 stdio 运行，默认只读；
|
||
- 认证属于当前用户自己的个人 Authorize Key 和业务角色；
|
||
- 当前 MCP 客户端已注册 `nocobase-crm`；
|
||
- `crm_health` 返回 `ok=true`。
|
||
|
||
## 安全规则
|
||
|
||
- 不索取账号密码，不使用共享服务账号或管理员 Key。
|
||
- 不让用户把 Key 发到聊天、命令参数、环境变量、剪贴板日志或 MCP 配置。
|
||
- Key 只能由用户输入到安装程序的本机隐藏 TTY 提示。
|
||
- 不使用 `sudo`，不执行 `curl | sh` 或 `wget | sh`。
|
||
- 不静默安装 Git、Node.js、包管理器或其他系统工具。
|
||
- 修改 MCP 客户端配置前展示目标文件与新增项，创建备份，并结构化合并；不得覆盖其他 server。
|
||
- 默认不启用写入、原始数据、后台服务或网络监听。
|
||
- 不询问或接受其他 NocoBase URL，也不允许通过参数、配置或凭证文件覆盖固定 API 地址。
|
||
|
||
## 安装流程
|
||
|
||
### 1. 确认本机位置与 Release 权限
|
||
|
||
确定当前 Agent/MCP 客户端及其配置路径，以及普通用户应用数据目录。NocoBase API 已固定为 `https://justconn.top/api`，不需要向用户询问地址。
|
||
|
||
从本文件 URL 解析固定 Release Tag。读取同一 Release 的资产列表，只接受：
|
||
|
||
- `donaldttt-nocobase-crm-mcp-<version>.tgz`；
|
||
- `SHA256SUMS`。
|
||
|
||
仓库为 Private 时，必须使用当前用户已经授权的 GitHub 连接读取 Release；无权访问时停止，不得退回默认分支、源码 clone 或索取用户 GitHub Token 到聊天。
|
||
|
||
### 2. 一次性说明本机变更
|
||
|
||
检查 `node --version` 和 `npm --version`。要求 Node.js `>=20.11`。
|
||
|
||
如果 Node.js 缺失或版本过低，向用户说明需要安装或升级 Node.js、官方来源、目标位置和影响，取得明确同意后再使用操作系统的正规安装方式。不能因为 npm 不存在就直接尝试全局安装。
|
||
|
||
正常安装只会留下：
|
||
|
||
- 应用数据目录中的 npm 包；
|
||
- 不含 Key 的 CRM `config.json`；
|
||
- 权限受限的本机凭证文件；
|
||
- MCP 客户端配置及其备份。
|
||
|
||
不会安装 Git、Python、uv、`nb CLI`、后台服务或本机监听端口。
|
||
|
||
### 3. 下载并验证固定发布物
|
||
|
||
通过已授权的 GitHub API/连接下载两个 Release 资产到新建的临时目录。验证 tarball 的 SHA-256 与 `SHA256SUMS` 完全一致；不一致立即停止并删除未使用的下载文件。
|
||
|
||
选择用户级安装前缀，例如：
|
||
|
||
- Windows：`%LOCALAPPDATA%\NocoBaseMCP\app`
|
||
- macOS：`~/Library/Application Support/NocoBaseMCP/app`
|
||
- Linux：`${XDG_DATA_HOME:-~/.local/share}/nocobase-crm-mcp/app`
|
||
|
||
执行隔离安装，不使用全局目录：
|
||
|
||
```bash
|
||
npm install --prefix <install-prefix> --omit=dev <verified-release.tgz>
|
||
```
|
||
|
||
定位安装后的命令：POSIX 为 `<install-prefix>/node_modules/.bin/nocobase-crm-mcp`，Windows 为相同目录下的 `nocobase-crm-mcp.cmd`。
|
||
|
||
### 4. 个人 Key 设置
|
||
|
||
先引导用户在 NocoBase 个人设置中创建可撤销、有合理有效期、绑定本人普通业务角色的个人 Authorize Key。不要让用户把 Key 发给 Agent。
|
||
|
||
在用户可直接控制的本机终端运行：
|
||
|
||
```bash
|
||
<installed-command> setup --json
|
||
```
|
||
|
||
安装程序会先验证安全 TTY，再显示固定 API 地址和隐藏 Key 提示；没有安全 TTY 时会在写文件前停止。Key 通过 `https://justconn.top/api/roles:check` 验证成功后才保存，并立即执行 `crm_health`。凭证文件只保存 Key，不保存或接受 API 地址。Key 不会出现在返回 JSON、命令参数、MCP 配置或日志中。
|
||
|
||
POSIX 凭证目录使用 `0700`，凭证文件使用 `0600`。Windows 使用当前用户应用数据目录。不要复制其他用户的凭证文件；每个操作系统用户都必须单独设置自己的 Key。
|
||
|
||
### 5. 注册并验证 MCP
|
||
|
||
读取 setup 返回的 `clientConfig`：
|
||
|
||
1. 展示客户端配置路径和新增的 `nocobase-crm` 条目；
|
||
2. 创建可恢复备份；
|
||
3. 结构化合并该 server，保留所有其他配置；
|
||
4. 重载或重启 MCP 客户端；
|
||
5. 调用 `crm_health`，要求 `ok=true`。
|
||
|
||
最终只报告 Release、安装目录、配置备份位置和只读/写入模式，不显示任何 Key。
|
||
|
||
## 可选写入
|
||
|
||
未明确选择时保持只读。只有用户明确要求项目创建/更新，并且管理员确认该用户角色具有对应 NocoBase ACL 时，才在 setup 以及生成的启动参数中加入 `--enable-writes`。这只增加 `create_project` 和 `update_project`；不增加删除、任意集合访问或附件文件上传接口。
|
||
|
||
## 故障处理
|
||
|
||
- `nocobase_auth_failed`：让用户撤销失效 Key，重新运行同一个 setup 命令并在隐藏提示输入新 Key。
|
||
- `nocobase_request_failed` / `NO_PERMISSIONS`：检查用户角色、字段权限、行级权限与 `config.json` 映射，不得换用共享高权限 Key。
|
||
- Node.js 缺失：报告前置条件并请求用户授权正规安装，不退回 Python/uv/nb CLI 方案。
|
||
- Private Release 无权访问：报告分发权限问题，不退回 clone 默认分支。
|
||
|
||
## 用户可发送给 Agent 的最短指令
|
||
|
||
```text
|
||
请按这个固定 Release 的协议帮我完成本机安装。默认只读，使用我自己的 NocoBase Authorize Key；只让我在本机隐藏提示中输入 Key，不要静默安装系统工具。完成前必须验证 crm_health：
|
||
<固定 Release 的 INSTALL.md 链接>
|
||
```
|