184 lines
12 KiB
Markdown
184 lines
12 KiB
Markdown
# 安装 NocoBase CRM MCP
|
||
|
||
这是一份供终端型 AI Agent 执行的通用安装协议，不依赖任何特定 Agent 或 MCP 客户端。用户只需要提供本链接、确认本机变更，并在浏览器中登录自己的 NocoBase 账号完成授权。
|
||
|
||
如果你是安装 Agent，请直接执行流程，不要让用户逐条尝试命令。只有在确认系统工具变更或等待用户在 NocoBase 网页登录授权时才中断用户。
|
||
|
||
## 完成标准
|
||
|
||
- 从 Gitea `main` 解析安装开始时的最新完整 Commit SHA，并将本次安装的文档、源码和构建全部固定到该 Commit；
|
||
- 只连接固定的 NocoBase API `https://justconn.top/api`；
|
||
- MCP 在用户本机以 stdio 运行，默认只读；
|
||
- 通过 NocoBase 原生 OAuth 2.1 认证当前用户，权限仍跟随本人的业务角色；
|
||
- 当前 MCP 客户端已注册 `nocobase-crm`；
|
||
- `crm_health` 返回 `ok=true`。
|
||
|
||
## 安全规则
|
||
|
||
- 不索取账号密码、OAuth Token 或 Authorize Key，不使用共享服务账号或管理员身份。
|
||
- 用户只能在 `https://justconn.top` 的 NocoBase 页面输入账号信息并确认授权。
|
||
- OAuth Token 不得进入聊天、命令参数、环境变量、CRM 配置、剪贴板日志或 MCP 客户端配置。
|
||
- 不使用 `sudo`，不执行 `curl | sh` 或 `wget | sh`。
|
||
- 不静默安装 Git、Node.js、包管理器或其他系统工具。
|
||
- 解析 `main` 后只使用带完整 Commit SHA 的不可变 URL；一次安装中不得再次读取移动中的 `main` 文件。
|
||
- 最新 Commit 无法下载、检查、测试或构建时必须停止，不得静默退回旧 Release、旧 Commit 或其他来源。
|
||
- 修改 MCP 客户端配置前展示目标文件与新增项，创建备份，并结构化合并；不得覆盖其他 server。
|
||
- 默认不启用写入、原始数据、后台服务或网络监听。
|
||
- 不询问或接受其他 NocoBase URL，也不允许通过参数、配置或凭证文件覆盖固定 API 地址。
|
||
|
||
## 安装流程
|
||
|
||
### 1. 解析并固定最新 Commit
|
||
|
||
确定当前 Agent/MCP 客户端及其配置路径，以及普通用户应用数据目录。NocoBase API 已固定为 `https://justconn.top/api`，不需要向用户询问地址。
|
||
|
||
安装源固定为：
|
||
|
||
- 仓库：`https://git.justconn.top/gitea-admin/nocobase-mcp`
|
||
- 分支：`main`
|
||
- 分支 API：`https://git.justconn.top/api/v1/repos/gitea-admin/nocobase-mcp/branches/main`
|
||
|
||
通过当前用户已经授权的 Gitea API/连接读取分支 API，只解析一次 `commit.id`，并验证它是 40 位十六进制完整 SHA。记录为 `<commit-sha>` 后，本次安装即使发现 `main` 又有新提交，也继续完成这个已固定快照；下一次安装才重新解析最新提交。
|
||
|
||
立即从以下不可变地址重新读取安装协议，后续不再依赖最初的 `main` 页面内容：
|
||
|
||
```text
|
||
https://git.justconn.top/gitea-admin/nocobase-mcp/raw/commit/<commit-sha>/INSTALL.md
|
||
```
|
||
|
||
仓库访问受限时必须使用当前用户已有的授权连接；无权访问时停止，不得索取或接收用户在聊天中发送的 Gitea 访问令牌。
|
||
|
||
### 2. 一次性说明本机变更
|
||
|
||
检查 `node --version` 和 `npm --version`。要求 Node.js `>=20.11`。
|
||
|
||
如果 Node.js 缺失或版本过低，向用户说明需要安装或升级 Node.js、官方来源、目标位置和影响，取得明确同意后再使用操作系统的正规安装方式。不能因为 npm 不存在就直接尝试全局安装。还需确认 npm 能读取锁定依赖；不得改用未锁定的依赖版本。
|
||
|
||
正常安装只会留下：
|
||
|
||
- 应用数据目录中的 npm 包；
|
||
- 不含凭据的 CRM `config.json`；
|
||
- 权限受限的本机凭证文件；
|
||
- MCP 客户端配置及其备份。
|
||
|
||
源码快照、构建期 `node_modules` 和本地 tarball 只放在新建的临时目录，安装完成后不作为持久文件保留。不会安装 Git、Python、uv、`nb CLI`、后台服务或本机监听端口。
|
||
|
||
### 3. 下载、验证并构建固定 Commit
|
||
|
||
在新建的临时目录中下载 `<commit-sha>` 的源码归档，不下载 Release 资产，也不从移动的 `main` URL 下载源码。Windows 使用 `.zip`，macOS/Linux 使用 `.tar.gz`；两种归档都必须包含同一个已解析的完整 Commit SHA：
|
||
|
||
```text
|
||
Windows: https://git.justconn.top/gitea-admin/nocobase-mcp/archive/<commit-sha>.zip
|
||
macOS/Linux: https://git.justconn.top/gitea-admin/nocobase-mcp/archive/<commit-sha>.tar.gz
|
||
```
|
||
|
||
不要让用户选择版本，也不要因为操作系统不同而改用 Release。每次新的安装任务都重新解析当时 `main` 的最新 Commit，随后只下载并使用该 SHA。
|
||
|
||
下载后记录归档 SHA-256。解包前拒绝绝对路径、`..` 路径穿越或逃出临时目录的链接；源码根目录必须包含 `package.json`、`package-lock.json`、`install-manifest.json`、`INSTALL.md` 和 `src/`。
|
||
|
||
确认归档中的 `install-manifest.json` 声明 `distribution.branch` 为 `main`、`distribution.strategy` 为 `resolve-latest-commit-then-pin`。随后只在这个临时源码目录运行：
|
||
|
||
```bash
|
||
npm ci
|
||
npm run check
|
||
npm test
|
||
npm run build
|
||
npm pack --pack-destination <temporary-output-directory>
|
||
```
|
||
|
||
任何一步失败都停止并报告 `<commit-sha>` 与失败步骤，不得改装旧 Release。记录本地生成 npm tarball 的 SHA-256；安装结束时只报告哈希，不发送或上传 tarball。
|
||
|
||
选择用户级安装前缀，例如：
|
||
|
||
- Windows：`%LOCALAPPDATA%\nocobase-crm-mcp\app`
|
||
- macOS：`~/Library/Application Support/nocobase-crm-mcp/app`
|
||
- Linux：`${XDG_DATA_HOME:-~/.local/share}/nocobase-crm-mcp/app`
|
||
|
||
执行隔离安装，不使用全局目录：
|
||
|
||
```bash
|
||
npm install --prefix <install-prefix> --omit=dev <locally-built-commit.tgz>
|
||
```
|
||
|
||
定位安装后的命令：POSIX 为 `<install-prefix>/node_modules/.bin/nocobase-crm-mcp`，Windows 为相同目录下的 `nocobase-crm-mcp.cmd`。运行 `--version` 和 `--help`，确认版本等于源码 `package.json`，并且帮助中包含本 Commit 安装协议使用的 `setup --no-browser` 选项；不一致时停止，不得继续注册旧二进制。
|
||
|
||
### 4. 在登录前注册 MCP
|
||
|
||
先运行：
|
||
|
||
```bash
|
||
<installed-command> client-config --json
|
||
```
|
||
|
||
该命令会在需要时从包内模板准备默认 `config.json`，不要求凭据，也不会发起 OAuth。读取返回的 `clientConfig`：
|
||
|
||
1. 展示客户端配置路径和新增的 `nocobase-crm` 条目；
|
||
2. 创建可恢复备份；
|
||
3. 结构化合并该 server，保留所有其他配置；
|
||
4. 重载或重启 MCP 客户端，并在客户端要求时让用户信任该连接器。
|
||
|
||
没有凭据时 stdio MCP 仍应正常启动并响应 `tools/list`。此时业务工具会返回结构化的 `nocobase_auth_failed`，而不是导致整个 MCP 进程退出。
|
||
|
||
### 5. 通过 MCP 把登录链接交给用户
|
||
|
||
注册完成后调用：
|
||
|
||
```text
|
||
nocobase_login({})
|
||
```
|
||
|
||
该工具通过 NocoBase OAuth 发现接口动态注册本机公共客户端，请求 `api offline_access`，并立即返回：
|
||
|
||
- `login_url`：只指向 `https://justconn.top` 的完整授权链接；
|
||
- `user_code`：供用户在页面核对的确认码；
|
||
- `expires_in_seconds`：剩余有效时间；
|
||
- `browser_opened`：桌面浏览器是否已成功自动打开。
|
||
|
||
无论 `browser_opened` 是真是假，都应立即把 `login_url`、`user_code` 和有效期发给用户。用户只在 NocoBase 网页输入账号信息、核对确认码并点击授权。随后调用 `nocobase_login_status({})`；授权仍在等待时它会安全地重复同一链接，成功时返回 `status=authenticated`。不要高频轮询；可在用户确认完成后或按合理间隔查询。
|
||
|
||
取得 `authenticated` 后调用 `crm_health`，要求 `ok=true`。如果已有凭据但 `crm_health` 明确返回认证失败，调用 `nocobase_login({"force": true})` 创建新的授权，不得换用共享高权限 Token 或 Key。
|
||
|
||
这一流程同时适用于桌面 GUI、Hermes Agent、OpenClaw 和远程无界面服务器：桌面环境会尝试自动打开浏览器；远程环境直接把同一个 HTTPS 链接经当前 Messenger 或聊天通道交给用户。后台轮询、凭据验证和保存都由 MCP 进程完成，Agent 只能看到安全的链接、确认码和状态，看不到 OAuth Token 或设备码。一个 MCP 进程只能服务一个受信任的用户身份；多用户必须使用相互隔离的 Agent/MCP 实例和凭据路径。
|
||
|
||
设备授权约十分钟后失效。密码和浏览器会话始终留在 NocoBase，程序不会读取浏览器 Cookie。访问令牌临近过期时会自动使用刷新令牌续期。POSIX 凭证目录使用 `0700`，凭证文件使用 `0600`；Windows 使用当前用户应用数据目录。凭证文件不保存或接受 API 地址，Token 不会出现在工具返回、命令参数、MCP 配置或日志中。
|
||
|
||
如果某个 MCP 客户端在登录前完全无法加载自定义连接器，才使用 CLI 备用入口：
|
||
|
||
```bash
|
||
<installed-command> setup --no-browser --json
|
||
```
|
||
|
||
本机桌面终端也可省略 `--no-browser` 以尝试自动打开网页。CLI 会先验证或准备配置，再开始 OAuth，避免用户完成网页授权后才因配置路径不存在而丢失结果。Agent 必须持续读取该进程的输出、把链接和确认码发给用户，并让进程继续轮询。
|
||
|
||
只有在 OAuth 暂时不可用、管理员明确要求且用户拥有个人 Authorize Key 时，才使用：
|
||
|
||
```bash
|
||
<installed-command> setup --manual-key --json
|
||
```
|
||
|
||
该备用模式必须在用户可直接控制的安全 TTY 中隐藏输入 Key；仍不得让用户把 Key 发给 Agent。
|
||
|
||
最终只报告完整 Commit SHA、源码版本、本地构建 tarball 的 SHA-256、安装目录、配置备份位置、认证方式和只读/写入模式，不显示任何 Token 或 Key。
|
||
|
||
## 可选写入
|
||
|
||
未明确选择时保持只读。只有用户明确要求项目创建/更新，并且管理员确认该用户角色具有对应 NocoBase ACL 时，才在 `client-config`（或 CLI 备用 `setup`）以及生成的启动参数中加入 `--enable-writes`。这只增加 `create_project` 和 `update_project`；不增加删除、任意集合访问或附件文件上传接口。
|
||
|
||
## 故障处理
|
||
|
||
- 浏览器未打开：把 `nocobase_login` 返回的 `login_url` 和 `user_code` 发给用户手动打开；不需要重启 MCP。
|
||
- 授权超时或被取消：再次调用 `nocobase_login` 生成新链接并重新核对确认码。
|
||
- `nocobase_auth_failed`：调用 `nocobase_login({"force": true})` 重新授权；不要换用共享高权限 Token 或 Key。
|
||
- `nocobase_request_failed` / `NO_PERMISSIONS`：检查用户角色、字段权限、行级权限与 `config.json` 映射，不得换用共享高权限身份。
|
||
- Node.js 缺失：报告前置条件并请求用户授权正规安装，不退回 Python/uv/nb CLI 方案。
|
||
- `main` 或 Commit 归档无权访问：报告 Gitea 权限问题，不索取聊天中的访问令牌，也不退回旧 Release。
|
||
- 最新 Commit 的依赖安装、检查、测试或构建失败：报告 SHA 和原始失败步骤后停止；不得以“先装可用版本”为由降级。
|
||
- 安装过程中 `main` 更新：不影响当前任务，继续完成开始时固定的 SHA；下次安装再取得新 SHA。
|
||
|
||
## 用户可发送给 Agent 的最短指令
|
||
|
||
```text
|
||
请按这个 INSTALL.md 帮我完成安装。每次先解析当前 Gitea 仓库 main 分支的最新完整 Commit SHA，并把本次安装固定在该 Commit；不要退回旧 Release。默认只读；请先注册 MCP，再调用 nocobase_login，把登录链接和确认码发给我，让我只在 NocoBase 官方网页登录并确认授权。不要向我索要密码、Token 或 Authorize Key，也不要静默安装系统工具。完成前必须验证 crm_health：
|
||
https://git.justconn.top/gitea-admin/nocobase-mcp/raw/branch/main/INSTALL.md
|
||
```
|