nocobase-mcp/INSTALL.md

安装 NocoBase CRM MCP

这是一份供终端型 AI Agent 执行的通用安装协议，不依赖任何特定 Agent 或 MCP 客户端。用户只需要提供本链接、确认本机变更，并在隐藏提示中输入自己的 NocoBase Authorize Key。

如果你是安装 Agent，请直接执行流程，不要让用户逐条尝试命令。只有在确认系统工具变更、取得 NocoBase URL、要求用户创建 Key，或让用户在隐藏提示中粘贴 Key 时才中断用户。

完成标准

• 下载本文件所在的同一固定 Release，不使用默认分支；
• 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。
• 默认不启用写入、原始数据、后台服务或网络监听。

安装流程

1. 确认输入与 Release 权限

取得：

• NocoBase 应用 URL，例如 https://nocobase.example；
• 当前 Agent/MCP 客户端及其配置路径；
• 普通用户应用数据目录。

从本文件 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

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

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。

在用户可直接控制的本机终端运行：

<installed-command> setup --api-base-url <nocobase-url> --json

安装程序会先验证安全 TTY，再显示隐藏 Key 提示；没有安全 TTY 时会在写文件前停止。Key 通过 roles:check 验证成功后才保存，并立即执行 crm_health。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 的最短指令

请按这个固定 Release 的协议帮我完成本机安装。默认只读，使用我自己的 NocoBase Authorize Key；只让我在本机隐藏提示中输入 Key，不要静默安装系统工具。完成前必须验证 crm_health：
<固定 Release 的 INSTALL.md 链接>