gitea-admin/nocobase-mcp

Fork 0

Files

T

nac 7cc521938f feat: add MCP-guided browser login

2026-08-20 04:09:07 +00:00

12 KiB

Raw Blame History

安装 NocoBase CRM MCP

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

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

完成标准

从 Gitea main 解析安装开始时的最新完整 Commit SHA，并将本次安装的文档、源码和构建全部固定到该 Commit；
只连接固定的 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、包管理器或其他系统工具。
解析 main 后只使用带完整 Commit SHA 的不可变 URL；一次安装中不得再次读取移动中的 main 文件。
最新 Commit 无法下载、检查、测试或构建时必须停止，不得静默退回旧 Release、旧 Commit 或其他来源。
修改 MCP 客户端配置前展示目标文件与新增项，创建备份，并结构化合并；不得覆盖其他 server。
默认不启用写入、原始数据、后台服务或网络监听。
不询问或接受其他 NocoBase URL，也不允许通过参数、配置或凭证文件覆盖固定 API 地址。

安装流程

1. 解析并固定最新 Commit

确定当前 Agent/MCP 客户端及其配置路径，以及普通用户应用数据目录。NocoBase API 已固定为 https://justconn.top/api，不需要向用户询问地址。

安装源固定为：

仓库：https://git.justconn.top/gitea-admin/nocobase-mcp
分支：main
分支 API：https://git.justconn.top/api/v1/repos/gitea-admin/nocobase-mcp/branches/main

通过当前用户已经授权的 Gitea API/连接读取分支 API，只解析一次 commit.id，并验证它是 40 位十六进制完整 SHA。记录为 <commit-sha> 后，本次安装即使发现 main 又有新提交，也继续完成这个已固定快照；下一次安装才重新解析最新提交。

立即从以下不可变地址重新读取安装协议，后续不再依赖最初的 main 页面内容：

https://git.justconn.top/gitea-admin/nocobase-mcp/raw/commit/<commit-sha>/INSTALL.md

仓库访问受限时必须使用当前用户已有的授权连接；无权访问时停止，不得索取或接收用户在聊天中发送的 Gitea 访问令牌。

2. 一次性说明本机变更

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

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

正常安装只会留下：

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

源码快照、构建期 node_modules 和本地 tarball 只放在新建的临时目录，安装完成后不作为持久文件保留。不会安装 Git、Python、uv、nb CLI、后台服务或本机监听端口。

3. 下载、验证并构建固定 Commit

在新建的临时目录中下载 <commit-sha> 的源码归档，不下载 Release 资产，也不从移动的 main URL 下载源码。Windows 使用 .zip，macOS/Linux 使用 .tar.gz；两种归档都必须包含同一个已解析的完整 Commit SHA：

Windows:     https://git.justconn.top/gitea-admin/nocobase-mcp/archive/<commit-sha>.zip
macOS/Linux: https://git.justconn.top/gitea-admin/nocobase-mcp/archive/<commit-sha>.tar.gz

不要让用户选择版本，也不要因为操作系统不同而改用 Release。每次新的安装任务都重新解析当时 main 的最新 Commit，随后只下载并使用该 SHA。

下载后记录归档 SHA-256。解包前拒绝绝对路径、.. 路径穿越或逃出临时目录的链接；源码根目录必须包含 package.json、package-lock.json、install-manifest.json、INSTALL.md 和 src/。

确认归档中的 install-manifest.json 声明 distribution.branch 为 main、distribution.strategy 为 resolve-latest-commit-then-pin。随后只在这个临时源码目录运行：

npm ci
npm run check
npm test
npm run build
npm pack --pack-destination <temporary-output-directory>

任何一步失败都停止并报告 <commit-sha> 与失败步骤，不得改装旧 Release。记录本地生成 npm tarball 的 SHA-256；安装结束时只报告哈希，不发送或上传 tarball。

选择用户级安装前缀，例如：

Windows：%LOCALAPPDATA%\nocobase-crm-mcp\app
macOS：~/Library/Application Support/nocobase-crm-mcp/app
Linux：${XDG_DATA_HOME:-~/.local/share}/nocobase-crm-mcp/app

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

npm install --prefix <install-prefix> --omit=dev <locally-built-commit.tgz>

定位安装后的命令：POSIX 为 <install-prefix>/node_modules/.bin/nocobase-crm-mcp，Windows 为相同目录下的 nocobase-crm-mcp.cmd。运行 --version 和 --help，确认版本等于源码 package.json，并且帮助中包含本 Commit 安装协议使用的 setup --no-browser 选项；不一致时停止，不得继续注册旧二进制。

4. 在登录前注册 MCP

先运行：

<installed-command> client-config --json

该命令会在需要时从包内模板准备默认 config.json，不要求凭据，也不会发起 OAuth。读取返回的 clientConfig：

展示客户端配置路径和新增的 nocobase-crm 条目；
创建可恢复备份；
结构化合并该 server，保留所有其他配置；
重载或重启 MCP 客户端，并在客户端要求时让用户信任该连接器。

没有凭据时 stdio MCP 仍应正常启动并响应 tools/list。此时业务工具会返回结构化的 nocobase_auth_failed，而不是导致整个 MCP 进程退出。

5. 通过 MCP 把登录链接交给用户

注册完成后调用：

nocobase_login({})

该工具通过 NocoBase OAuth 发现接口动态注册本机公共客户端，请求 api offline_access，并立即返回：

login_url：只指向 https://justconn.top 的完整授权链接；
user_code：供用户在页面核对的确认码；
expires_in_seconds：剩余有效时间；
browser_opened：桌面浏览器是否已成功自动打开。

无论 browser_opened 是真是假，都应立即把 login_url、user_code 和有效期发给用户。用户只在 NocoBase 网页输入账号信息、核对确认码并点击授权。随后调用 nocobase_login_status({})；授权仍在等待时它会安全地重复同一链接，成功时返回 status=authenticated。不要高频轮询；可在用户确认完成后或按合理间隔查询。

取得 authenticated 后调用 crm_health，要求 ok=true。如果已有凭据但 crm_health 明确返回认证失败，调用 nocobase_login({"force": true}) 创建新的授权，不得换用共享高权限 Token 或 Key。

这一流程同时适用于桌面 GUI、Hermes Agent、OpenClaw 和远程无界面服务器：桌面环境会尝试自动打开浏览器；远程环境直接把同一个 HTTPS 链接经当前 Messenger 或聊天通道交给用户。后台轮询、凭据验证和保存都由 MCP 进程完成，Agent 只能看到安全的链接、确认码和状态，看不到 OAuth Token 或设备码。一个 MCP 进程只能服务一个受信任的用户身份；多用户必须使用相互隔离的 Agent/MCP 实例和凭据路径。

设备授权约十分钟后失效。密码和浏览器会话始终留在 NocoBase，程序不会读取浏览器 Cookie。访问令牌临近过期时会自动使用刷新令牌续期。POSIX 凭证目录使用 0700，凭证文件使用 0600；Windows 使用当前用户应用数据目录。凭证文件不保存或接受 API 地址，Token 不会出现在工具返回、命令参数、MCP 配置或日志中。

如果某个 MCP 客户端在登录前完全无法加载自定义连接器，才使用 CLI 备用入口：

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

本机桌面终端也可省略 --no-browser 以尝试自动打开网页。CLI 会先验证或准备配置，再开始 OAuth，避免用户完成网页授权后才因配置路径不存在而丢失结果。Agent 必须持续读取该进程的输出、把链接和确认码发给用户，并让进程继续轮询。

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

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

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

最终只报告完整 Commit SHA、源码版本、本地构建 tarball 的 SHA-256、安装目录、配置备份位置、认证方式和只读/写入模式，不显示任何 Token 或 Key。

可选写入

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

故障处理

浏览器未打开：把 nocobase_login 返回的 login_url 和 user_code 发给用户手动打开；不需要重启 MCP。
授权超时或被取消：再次调用 nocobase_login 生成新链接并重新核对确认码。
nocobase_auth_failed：调用 nocobase_login({"force": true}) 重新授权；不要换用共享高权限 Token 或 Key。
nocobase_request_failed / NO_PERMISSIONS：检查用户角色、字段权限、行级权限与 config.json 映射，不得换用共享高权限身份。
Node.js 缺失：报告前置条件并请求用户授权正规安装，不退回 Python/uv/nb CLI 方案。
main 或 Commit 归档无权访问：报告 Gitea 权限问题，不索取聊天中的访问令牌，也不退回旧 Release。
最新 Commit 的依赖安装、检查、测试或构建失败：报告 SHA 和原始失败步骤后停止；不得以“先装可用版本”为由降级。
安装过程中 main 更新：不影响当前任务，继续完成开始时固定的 SHA；下次安装再取得新 SHA。

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

请按这个 INSTALL.md 帮我完成安装。每次先解析当前 Gitea 仓库 main 分支的最新完整 Commit SHA，并把本次安装固定在该 Commit；不要退回旧 Release。默认只读；请先注册 MCP，再调用 nocobase_login，把登录链接和确认码发给我，让我只在 NocoBase 官方网页登录并确认授权。不要向我索要密码、Token 或 Authorize Key，也不要静默安装系统工具。完成前必须验证 crm_health：
https://git.justconn.top/gitea-admin/nocobase-mcp/raw/branch/main/INSTALL.md

12 KiB Raw Blame History Unescape Escape