nocobase-mcp/INSTALL.md

安装 NocoBase CRM MCP

这是一份供终端型 AI Agent 执行的通用安装协议，不依赖任何特定 Agent 或 MCP 客户端。用户只需要提供本链接、确认本机变更，并在浏览器中登录自己的 NocoBase 账号完成授权。

如果你是安装 Agent，请直接执行流程，不要让用户逐条尝试命令。只有在确认系统工具变更或等待用户在 NocoBase 网页登录授权时才中断用户。

完成标准

• 下载本文件所在的同一固定 Release，不使用默认分支；
• 只连接固定的 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、包管理器或其他系统工具。
• 修改 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。

仓库访问受限时，必须使用当前用户已经授权的代码托管平台连接读取 Release；无权访问时停止，不得退回默认分支、源码 clone 或索取用户的访问令牌到聊天。

2. 一次性说明本机变更

检查 node --version 和 npm --version。要求 Node.js >=20.11。

如果 Node.js 缺失或版本过低，向用户说明需要安装或升级 Node.js、官方来源、目标位置和影响，取得明确同意后再使用操作系统的正规安装方式。不能因为 npm 不存在就直接尝试全局安装。

正常安装只会留下：

• 应用数据目录中的 npm 包；
• 不含凭据的 CRM config.json；
• 权限受限的本机凭证文件；
• MCP 客户端配置及其备份。

不会安装 Git、Python、uv、nb CLI、后台服务或本机监听端口。

3. 下载并验证固定发布物

通过当前 Gitea 实例或经批准分发渠道的已授权 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

执行隔离安装，不使用全局目录：

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. 浏览器登录 NocoBase

运行：

<installed-command> setup --json

安装程序通过 NocoBase 的 OAuth 发现接口动态注册本机公共客户端，请求 api offline_access 权限，并自动打开带确认码的 NocoBase 设备授权页。用户在网页中登录、核对确认码并点击授权；程序随后取得短期访问令牌和可撤销的刷新令牌，通过 https://justconn.top/api/roles:check 验证成功后保存，并立即执行 crm_health。

浏览器没有自动打开时，安装程序会继续显示完整授权链接和确认码。可重新运行：

<installed-command> setup --no-browser --json

然后由用户手动打开链接。设备授权约十分钟后失效；密码和浏览器会话始终留在 NocoBase，安装程序不会读取浏览器 Cookie。访问令牌临近过期时会自动使用刷新令牌续期，不影响日常 MCP 调用。

POSIX 凭证目录使用 0700，凭证文件使用 0600。Windows 使用当前用户应用数据目录。凭证文件不保存或接受 API 地址，Token 不会出现在返回 JSON、命令参数、MCP 配置或日志中。不要复制其他用户的凭证文件；每个操作系统用户都必须单独登录。

只有在 OAuth 暂时不可用、管理员明确要求且用户拥有个人 Authorize Key 时，才使用：

<installed-command> setup --manual-key --json

该备用模式必须在用户可直接控制的安全 TTY 中隐藏输入 Key；仍不得让用户把 Key 发给 Agent。

5. 注册并验证 MCP

读取 setup 返回的 clientConfig：

1. 展示客户端配置路径和新增的 nocobase-crm 条目；
2. 创建可恢复备份；
3. 结构化合并该 server，保留所有其他配置；
4. 重载或重启 MCP 客户端；
5. 调用 crm_health，要求 ok=true。

最终只报告 Release、安装目录、配置备份位置、认证方式和只读/写入模式，不显示任何 Token 或 Key。

可选写入

未明确选择时保持只读。只有用户明确要求项目创建/更新，并且管理员确认该用户角色具有对应 NocoBase ACL 时，才在 setup 以及生成的启动参数中加入 --enable-writes。这只增加 create_project 和 update_project；不增加删除、任意集合访问或附件文件上传接口。

故障处理

• 浏览器未打开：使用 setup --no-browser，让用户手动打开终端显示的 justconn.top 授权链接。
• 授权超时或被取消：重新运行 setup，再次核对确认码并授权。
• nocobase_auth_failed：重新运行 setup 完成浏览器登录；不要换用共享高权限 Token 或 Key。
• nocobase_request_failed / NO_PERMISSIONS：检查用户角色、字段权限、行级权限与 config.json 映射，不得换用共享高权限身份。
• Node.js 缺失：报告前置条件并请求用户授权正规安装，不退回 Python/uv/nb CLI 方案。
• 受限 Release 无权访问：报告 Gitea 或分发渠道的权限问题，不退回 clone 默认分支。

用户可发送给 Agent 的最短指令

请按这个固定 Release 的协议帮我完成本机安装。默认只读；请运行 setup，让我只在 NocoBase 官方网页登录并确认授权。不要向我索要密码、Token 或 Authorize Key，也不要静默安装系统工具。完成前必须验证 crm_health：
<固定 Release 的 INSTALL.md 链接>