安装 NocoBase CRM MCP

这是一份供终端型 AI Agent 执行的通用安装协议，不依赖 Codex、Claude Code、Cursor、OpenCode 或其他特定产品。用户只需要提供本链接、确认一次本机变更，并在隐藏提示中输入自己的 NocoBase API Key。

如果你是安装 Agent，请直接完成下面的流程，不要把命令转交给用户逐条尝试。只有在需要用户确认安装内容、提供 NocoBase 地址或在隐藏提示中粘贴 Key 时才打断用户。

完成目标

安装完成时必须同时满足：

使用固定 Release v0.2.0，不是开发分支；
MCP 在用户本机以 stdio 运行，默认只读；
NocoBase 认证属于当前用户自己的个人 Key 和业务角色；
当前 MCP 客户端已注册 nocobase-crm；
crm_health 返回 ok=true。

不可违反的安全规则

不索取账号密码，不使用共享服务账号或管理员 Key。
不让用户把 Key 发到聊天、命令参数、环境变量或临时文件。
Key 只能由用户粘贴到 nb CLI 的本机隐藏 TTY 提示。
不使用 sudo，不执行 curl | sh / wget | sh。
写 MCP 客户端配置前必须展示目标路径、创建备份并结构化合并，不能覆盖其他 server。
除非用户明确要求且管理员已确认 ACL，否则不启用写入、上传或原始数据。
默认不创建后台服务、不监听端口、不暴露到局域网或公网。

一次安装流程

1. 确认输入和访问权限

从用户或上下文取得：

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

本项目暂时通过 Private GitHub 仓库分发。当前 Agent 必须已经连接一个对 Donaldttt/nocobase-mcp 有只读权限的 GitHub 账号；无权读取时停止，不得退回 master。

2. 一次性说明本机变更

检查 Git、uv、Python 3.12+ 和 NocoBase nb CLI 2.1+。若缺失，向用户一次性说明将安装的工具、官方来源和位置，并取得一次确认后再处理。只有缺少 nb 时才可能额外需要 Node.js/npm；官方 CLI 包为 @nocobase/cli。

用户安装会留下：固定版本仓库副本、项目 .venv、不含 Key 的 config.json、nb CLI 用户登录环境、MCP 客户端配置和配置备份。不会默认创建 systemd 服务或 HTTP Token。

3. 取得固定版本

安全克隆并验证 Release：

git clone --branch v0.2.0 --depth 1 https://github.com/Donaldttt/nocobase-mcp.git <install-dir>
git -C <install-dir> describe --tags --exact-match HEAD

第二条必须精确输出 v0.2.0。目标目录已存在但不是本项目、包含未提交修改或版本不明确时停止覆盖。

4. 只运行一个安装命令

先引导用户在 NocoBase 个人设置中创建一个可撤销、有合理有效期、绑定本人普通业务角色的个人 API Key。不要让用户把 Key 发给你。

然后在用户可直接控制输入的本机终端中运行：

uv run --no-project --python 3.12 python <install-dir>/scripts/agent_install.py \
  --project-root <install-dir> install \
  --api-base-url <nocobase-url> --env-name nb-mcp --json

这个命令会一次完成运行环境准备、隐藏 Key 登录、配置写入、doctor 检查和通用 MCP 客户端配置生成。用户只在 nb 的隐藏提示出现时粘贴 Key；Agent 不读取输入。

若终端不支持用户私密输入，命令会在写入前停止。此时报告缺少安全 TTY，不得让用户改为在聊天中发送 Key。

5. 自动完成客户端注册和验证

读取命令返回的 clientConfig：

展示当前客户端配置文件路径和将新增的 nocobase-crm 条目；
创建可恢复备份；
结构化合并该 server，保留所有其他配置；
按客户端能力重载配置或重启客户端；
调用 crm_health，要求 ok=true。

只有完成以上验证后才能向用户报告成功。最终只报告安装目录、Release、NocoBase 环境名、客户端配置备份位置和启用模式，不显示任何 Token。

默认模式与可选写入

未明确选择时必须保持只读。只有用户明确要求项目创建/更新，且管理员确认该用户角色具有相应 NocoBase ACL 时，才在同一个安装命令末尾加 --enable-writes。这仍不会启用附件上传、删除或原始数据。

故障处理

不要让普通用户手动尝试 nb 或拆分安装子命令。由 Agent 根据结构化错误处理；需要详细恢复、更新或高级 HTTP 部署时，阅读同版本的 docs/LOCAL_DELIVERY.md。Key 过期或撤销时，重新运行同一个 install 命令，让用户在新的隐藏提示中输入新 Key。

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

请按这个协议帮我完成本机安装。默认只读，使用我自己的 NocoBase API Key；只让我在本机隐藏提示中输入 Key，不要让我手动执行安装或 nb 命令。安装完成前必须验证 crm_health：
<固定版本 INSTALL.md 链接>

5.0 KiB Raw Blame History Unescape Escape