gitea-admin/nocobase-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
8fe148ea8e36e6a6bfbebca7c6b7caab0e3d435d
nocobase-mcp/INSTALL.md
T

9.2 KiB
Raw Blame History

Agent 安装入口：NocoBase CRM MCP

这是一份供任意终端型 Agent 执行、也供用户审阅的安装协议。它不依赖 Codex、Claude Code、Cursor、OpenCode 或其他单一产品的插件格式。MCP 是可移植的功能层；Agent 只需把最后生成的 stdio 启动配置转换成自己客户端支持的格式。

如果你是收到本链接的 Agent：请完整阅读本文后再执行命令，按顺序持续工作到“完成条件”全部满足。不要把本文当成需要原样转发给用户的普通说明；你应根据操作系统、Shell、已有软件和当前 Agent 客户端自适应执行，并向用户报告关键检查点。

不可变安全规则

  1. 只安装 install-manifest.json 指定的仓库和 releaseRef，不得默认安装 master、main、开发分支或其他未固定版本。
  2. 不使用 curl | sh、wget | sh 或同类远程脚本管道。缺少全局依赖时，先说明来源、版本、影响范围并取得用户同意，再采用该工具的官方安装方式。
  3. 不使用 sudo，不删除或覆盖未知目录，不丢弃已有 Git 改动。目标目录已存在时先识别它；不是本项目或工作区不干净时停止覆盖并向用户说明。
  4. 认证默认使用用户自己的个人 API Key（Authorize Key），不使用账号密码。Agent 可以引导用户在 NocoBase 页面创建 Key，但不得要求用户把 Key 发到聊天；Key 只能由用户粘贴到本机、用户可控、隐藏回显的安全输入提示中。
  5. 默认只读。除非用户明确要求且管理员已确认 NocoBase ACL，否则不得启用 --enable-writes、附件上传或原始数据输出。
  6. 写入 Agent/MCP 客户端配置前，显示目标文件和将新增的 server 名称，创建可恢复备份，并只合并 nocobase-crm 条目；不得覆盖其他 MCP 配置。
  7. 不把本机 MCP 端口暴露到局域网或公网。通用安装默认使用 stdio，不创建后台服务，也不生成共享业务凭证。

安装输入

从用户或当前上下文确定以下内容；已有明确答案时不要重复提问：

  • NocoBase 应用 URL，例如 https://nocobase.example。安装器会规范化为以 /api 结尾；远程环境必须使用 HTTPS。
  • 安装目录。使用该操作系统的普通用户应用/数据目录作为默认值，并在写入前告知用户；不要默认放在系统目录。
  • 当前 Agent/MCP 客户端的名称及其本机 MCP 配置位置。
  • 功能模式。未明确选择时必须使用“只读”。

不要要求用户在 Agent 对话中提供 NocoBase Key、密码、Token、Cookie 或 ~/.nocobase 目录。Key 只进入 nb CLI 自己的本机隐藏提示。

执行协议

1. 读取并锁定发布版本

读取同版本的 install-manifest.json。本版本的预期来源是：

repository: https://github.com/Donaldttt/nocobase-mcp.git
releaseRef: v0.2.0

若 v0.2.0 尚不存在，或 Agent 无权读取私有仓库，停止安装并清楚报告“发布物/访问权限尚未就绪”，不得退回开发分支。面向普通外部用户发布时，安装方必须能匿名读取本页和发布物；私有分发则需要用户已连接有权访问该仓库的 GitHub 账号。

首次安装使用等效于以下语义的 Git 命令，并根据当前 Shell 正确转义路径：

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。已有安装的更新不得直接 git pull 开发分支；先保存当前版本和 config.json，确认工作区干净，再获取并切换到用户指定的新 Release Tag。

2. 环境检查与确定性准备

需要：Git、uv、Python 3.12+、NocoBase nb CLI 2.1+。先运行只读检查：

uv run --no-project --python 3.12 python <install-dir>/scripts/agent_install.py --project-root <install-dir> inspect --json

若 uv 或 nb 不存在，先取得用户同意再安装。NocoBase CLI 当前官方包入口是 npm install -g @nocobase/cli；安装后必须重新运行检查，不要通过修改 PATH 输出伪造成功。

然后运行幂等准备步骤：

uv run --no-project --python 3.12 python <install-dir>/scripts/agent_install.py --project-root <install-dir> prepare --json

该脚本只会校验项目文件、在缺失时从示例创建 config.json，并执行锁定依赖同步。已有 config.json 会被保留，依赖必须来自 uv.lock。

3. 连接用户自己的 NocoBase 账号

先引导用户在目标 NocoBase 网页中打开头像或个人设置，寻找当前版本中名为 API Keys、Access Tokens、访问令牌 或类似名称的入口。让用户创建一个：

  • 绑定用户本人，而不是共享服务账号；
  • 只使用其正常业务角色，不选择管理员/root 角色；
  • 有合理过期时间、可单独撤销；
  • 仅用于这台电脑上的 MCP。

如果用户看不到个人 Key 功能，Agent 应提示联系 NocoBase 管理员开通或代为签发绑定该用户普通业务角色的 Key；不得改用账号密码或共享管理员 Key。

取得 Key 后，Agent 必须在用户能直接控制输入的本机终端中启动以下流程，而不是把命令交给用户手动尝试：

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

安装器会自动：

  1. 规范化并验证 HTTPS URL；
  2. 脱敏检查已有环境，拒绝覆盖指向其他服务器的同名环境；
  3. 调用 nb env add/auth --auth-type token，但故意不传 --access-token，让 nb 在 TTY 内隐藏提示；
  4. 由用户本人把 Key 粘贴到这个本机提示中，Agent 不读取输入；
  5. 自动执行环境读回、把选定环境写入 config.json，并在修改前保存 config.json.pre-agent-install.bak。

若环境名冲突，安装器会给出新名称建议；Agent 使用建议名称重启同一流程，不覆盖旧环境。若当前 Agent 无法提供用户可直接输入的本机 TTY，必须停止并报告“缺少安全 Key 输入通道”；不得要求用户把 Key 粘到聊天、命令参数、环境变量或临时文件中，也不得把 nb 命令交给用户反复尝试。

Key 过期或撤销后，Agent 重新启动 connect-key，用户在新的隐私提示中输入新 Key。不得退回共享凭证。

4. 注册到当前 Agent/MCP 客户端

生成不含 NocoBase Token 的通用配置：

uv run --no-project --python 3.12 python <install-dir>/scripts/agent_install.py --project-root <install-dir> client-config

输出采用常见的 mcpServers JSON 形状，包含绝对的项目、uv 和 nb 路径。Agent 应查明自己客户端当前版本支持的 MCP 配置格式，将其中的 command、args、env 等价映射过去。

写入前：

  1. 向用户显示目标客户端配置文件路径和新增的 nocobase-crm 条目。
  2. 备份原文件；解析后做结构化合并，不能用字符串替换或整文件覆盖。
  3. 保留所有其他 server、设置和注释（客户端格式允许时）。
  4. 按客户端要求重载 MCP 配置或提醒用户重启客户端。

只有用户明确要求项目创建/更新，且其管理员确认对应角色 ACL 后，才可重新生成含写工具的配置：

uv run --no-project --python 3.12 python <install-dir>/scripts/agent_install.py --project-root <install-dir> client-config --enable-writes

这仍不启用上传、删除或原始数据。附件上传属于单独的 Linux 本机 HTTP 高级部署，不是通用安装流程的一部分。

5. 验证

先检查本机安装，不读取 NocoBase 秘密：

uv run --no-project --python 3.12 python <install-dir>/scripts/agent_install.py --project-root <install-dir> doctor --json

然后通过已注册的 MCP 调用 crm_health。只有同时满足以下条件才可向用户报告安装完成：

  • doctor 返回 ok: true；
  • connect-key 返回 ok: true、authType: token，且目标 URL 正确；
  • 客户端已发现 nocobase-crm；
  • crm_health 返回 ok: true，不是 nb_auth_failed、NO_PERMISSIONS 或其他结构化错误；
  • 默认状态仍是只读、uploads disabled、raw data disabled。

最后报告安装目录、Release Tag、NocoBase 环境名、客户端配置备份位置、启用的能力以及一条最小使用示例。不要报告或回显任何 Token。

给用户的最短用法

普通情况下，用户只需把当前不可变 Release 版本的 INSTALL.md 链接发给具备本机终端和文件权限的 Agent，并说：

请完整阅读这个安装协议，根据我的系统和当前 Agent 客户端自适应安装。默认只读；认证使用我本人的个人 API Key，不使用账号密码。请引导我在 NocoBase 获取 Key，并只让我在本机隐藏提示中粘贴；不要让我把 Key 发到聊天，也不要让我手动尝试 nb 命令。安装后必须通过 doctor 和 crm_health：
<version-pinned INSTALL.md URL>

如果 Agent 只能聊天、不能执行本机命令或写 MCP 配置，它应说明能力限制并按本文生成逐步人工安装指令，而不能声称已经安装。

Reference in New Issue View Git Blame Copy Permalink