gitea-admin/nocobase-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
67d7ff66082206e3cc2869a1388dbe0dfcb11726
nocobase-mcp/INSTALL.md
T
nac e00391f5f6 ci: run checks on master
2026-08-14 15:19:10 +00:00

8.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. 用户必须亲自在浏览器完成 NocoBase OAuth 登录。不得索取、复制、打印或保存用户的 Access Token、Refresh Token、Cookie、密码或 ~/.nocobase 目录；不得执行带 --show-secrets 的命令。
  5. 默认只读。除非用户明确要求且管理员已确认 NocoBase ACL，否则不得启用 --enable-writes、附件上传或原始数据输出。
  6. 写入 Agent/MCP 客户端配置前，显示目标文件和将新增的 server 名称，创建可恢复备份，并只合并 nocobase-crm 条目；不得覆盖其他 MCP 配置。
  7. 不把本机 MCP 端口暴露到局域网或公网。通用安装默认使用 stdio，不创建后台服务，也不生成共享业务凭证。

安装输入

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

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

不要要求用户提供 NocoBase Token。OAuth 登录之外没有必填秘密输入。

执行协议

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 账号

先直接执行：

nb env list

如果 nb-mcp 不存在，为规范化后的目标 URL 创建 OAuth 环境，并在写操作后读回列表：

nb env add nb-mcp --api-base-url <normalized-url-ending-in-/api> --auth-type oauth
nb env list

如果 nb-mcp 已存在，先用不显示秘密的 nb env info nb-mcp 核对 URL。URL 相同则复用；URL 不同则不要覆盖，选择清楚且未占用的新名称（例如 nb-mcp-example），创建后同步更新项目配置：

uv run --no-project --python 3.12 python <install-dir>/scripts/agent_install.py --project-root <install-dir> set-env <new-env-name> --json

此命令修改前会保留 config.json.pre-agent-install.bak。然后启动登录：

nb env auth <configured-env>

让用户亲自在浏览器完成登录；Agent 只负责保持命令运行、提示用户返回以及继续读取 CLI 的成功或错误信息。最后执行 nb env info <configured-env> 验证，不得附加 --show-secrets。如果登录失败或过期，重新运行同一个 nb env auth，不得换用共享 Token。

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；
  • nb env info <configured-env> 成功且目标 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 客户端自适应安装。默认只读；不要索取或显示任何 Token；需要全局安装依赖、写客户端配置或启用写功能前先告诉我。安装后必须通过 doctor 和 crm_health：
<version-pinned INSTALL.md URL>

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

Reference in New Issue View Git Blame Copy Permalink