feat: add NocoBase browser OAuth login
This commit is contained in:
nac
@@ -1,34 +1,95 @@
|
||||
# NocoBase CRM MCP
|
||||
|
||||
本项目是在用户电脑本机运行的 NocoBase CRM MCP。每位用户使用自己的个人 Authorize Key，所有查询和写入继续由 NocoBase ACL、字段权限和行级权限裁决；不需要共享账号或远程 MCP 服务。
|
||||
|
||||
## 用户侧依赖
|
||||
|
||||
正式 Release 是一个已打包的 npm tarball，内部包含 MCP SDK 和运行代码。用户电脑只需要：
|
||||
|
||||
- Node.js 20.11 或更高版本（npm 随 Node.js 一起提供）；
|
||||
- 能访问固定的 NocoBase 环境 `https://justconn.top`；
|
||||
- 用户自己的个人 Authorize Key。
|
||||
|
||||
用户不再需要 Git、Python、uv、Python 包或 `nb CLI`。安装也不会全局安装本项目，而是放到用户自己的应用数据目录。
|
||||
|
||||
Private GitHub 仓库的 Release 只能由已经获得仓库或分发渠道权限的用户下载。若要实现面向任意用户的“一条链接安装”，需要另行提供用户 Agent 能认证访问的下载地址。
|
||||
在你的电脑上，让 AI 客户端安全地查询 NocoBase CRM。安装时通过浏览器登录 NocoBase；每位用户使用自己的身份，看到的数据范围与本人在 NocoBase 中的权限一致。
|
||||
|
||||
## 安装
|
||||
|
||||
把对应 Release Tag 下的不可变 [`INSTALL.md`](INSTALL.md) 链接交给安装 Agent。该协议不依赖 Codex、Claude Code、Cursor、OpenCode 或其他特定客户端。Agent 会：
|
||||
推荐把安装交给支持终端操作的 AI Agent 完成。你不需要克隆源码，也不需要逐条执行安装命令。
|
||||
|
||||
1. 检查 Node.js，而不会静默安装系统工具；
|
||||
2. 下载并校验固定 Release 的 npm tarball；
|
||||
3. 安装到用户应用数据目录；
|
||||
4. 引导用户在本机隐藏提示中输入自己的 Authorize Key；
|
||||
5. 备份并结构化合并 MCP 客户端配置；
|
||||
6. 调用 `crm_health` 验证完成。
|
||||
### 安装前准备
|
||||
|
||||
默认 stdio、只读、不监听端口。只有用户明确要求且管理员确认 ACL 时，才给启动参数增加 `--enable-writes`，这只增加固定字段的 `create_project` 和 `update_project`，不提供删除或任意资源工具。
|
||||
- Node.js 20.11 或更高版本；
|
||||
- 能访问 `https://justconn.top`；
|
||||
- 你自己的 NocoBase 账号；
|
||||
- 能读取当前 Gitea 仓库对应 Release 的权限。
|
||||
|
||||
如果 Node.js 尚未安装，安装 Agent 会先说明需要进行的系统变更，并在获得你确认后再继续。
|
||||
|
||||
不需要提前创建或复制 Authorize Key。安装程序会打开 NocoBase 官方网页；你在网页中登录并确认授权后，本机安装会自动继续。
|
||||
|
||||
### 最快安装方式
|
||||
|
||||
1. 打开当前 Gitea 仓库的 **Releases（版本发布）** 页面，选择要安装的固定版本。
|
||||
2. 确认该版本包含 npm 安装包和 `SHA256SUMS`，然后打开同一版本下的 `INSTALL.md`。不要使用默认分支中的安装说明代替固定版本。
|
||||
3. 把这个固定版本的 `INSTALL.md` 链接和下面的文字一起发给安装 Agent：
|
||||
|
||||
```text
|
||||
请按这个固定版本的安装协议帮我完成 NocoBase CRM MCP 本机安装。
|
||||
默认只读；请运行 setup，让我只在 NocoBase 官方网页完成登录和授权。
|
||||
不要向我索要密码、Token 或 Authorize Key，也不要静默安装系统工具。完成前请验证 crm_health 返回 ok=true。
|
||||
```
|
||||
|
||||
4. 浏览器打开后，在 `justconn.top` 登录并核对页面与终端显示的确认码，然后点击授权。浏览器没有自动打开时，复制终端显示的授权链接手动打开。
|
||||
5. 安装完成后，确认 Agent 报告 `crm_health` 返回 `ok=true`。
|
||||
|
||||
完整的安装和验收规则见 [INSTALL.md](INSTALL.md)。实际安装时应使用所选 Release Tag 中的同一文件。
|
||||
|
||||
## 重要注意事项
|
||||
|
||||
- **只在 NocoBase 网页登录：** 安装程序不会读取浏览器 Cookie，也不会接触你的密码；OAuth 令牌只保存到权限受限的个人凭据文件，不会进入聊天、命令参数、环境变量、CRM 配置、MCP 客户端配置或日志。
|
||||
- **默认只读：** 安装后默认只能查询 CRM，不会创建、更新或删除业务数据。
|
||||
- **权限跟随本人：** MCP 不会绕过 NocoBase 的角色、字段权限和行级权限，也不会使用共享管理员账号。
|
||||
- **只连接公司环境：** 程序固定连接 `https://justconn.top/api`，不会要求你填写其他 NocoBase 地址。
|
||||
- **安装在用户目录：** 不使用 `sudo`，不会全局安装本项目，也不需要 Git、Python、uv 或 `nb CLI`。
|
||||
- **受限仓库需要授权：** 如果 Agent 无法读取 Gitea Release，请联系仓库管理员开通权限，不要把访问令牌发到聊天中。
|
||||
|
||||
## 安装后可以做什么
|
||||
|
||||
你可以直接让 AI：
|
||||
|
||||
- 查询客户、联系人和跟进记录；
|
||||
- 按负责人、团队、状态或时间范围筛选 CRM 数据；
|
||||
- 查看 CRM 总览、团队贡献和长期未跟进客户；
|
||||
- 查看项目详情和项目跟进时间线。
|
||||
|
||||
例如：
|
||||
|
||||
```text
|
||||
列出我负责的、最近 30 天没有有效跟进的客户。
|
||||
```
|
||||
|
||||
```text
|
||||
查看“华东团队”本月的客户、跟进和在途项目概况。
|
||||
```
|
||||
|
||||
## 可选写入
|
||||
|
||||
只有在你明确需要创建或更新项目，并且管理员已经确认你的 NocoBase 权限时，才应启用写入模式。
|
||||
|
||||
写入模式只增加固定字段的项目创建和更新能力，不提供删除操作，也不开放任意集合或任意字段写入。不要为了绕过权限错误而换用共享高权限 Key。
|
||||
|
||||
## 遇到问题
|
||||
|
||||
- 登录失效：重新运行安装程序的 `setup`，在浏览器中再次授权；正常情况下访问令牌会在后台自动刷新。
|
||||
- 浏览器没有打开：重新运行 `setup --no-browser`，然后手动打开终端显示的授权链接。
|
||||
- 仅在 OAuth 暂时不可用且管理员明确要求时，才使用 `setup --manual-key` 的隐藏输入备用模式；不要把 Key 发到聊天中。
|
||||
- 返回 `NO_PERMISSIONS`：请检查本人 NocoBase 角色和数据权限。
|
||||
- 请求超时：确认可以访问 `https://justconn.top`，或缩小查询范围。
|
||||
- Release 无法下载：确认当前账号或 Agent 已获得 Gitea 仓库和 Release 的读取权限。
|
||||
|
||||
更多故障处理和更新、回滚说明见 [本机交付与权限验收](docs/LOCAL_DELIVERY.md)。
|
||||
|
||||
## 更多文档
|
||||
|
||||
- [完整安装协议](INSTALL.md)：供安装 Agent 执行的固定版本安装与验收流程。
|
||||
- [命令与工具参考](docs/REFERENCE.md)：CLI 命令、MCP 工具和可选运行开关。
|
||||
- [内部架构](docs/ARCHITECTURE.md)：模块边界、身份与网络安全设计。
|
||||
- [本机交付与权限验收](docs/LOCAL_DELIVERY.md)：运维、权限验收、更新和回滚。
|
||||
|
||||
## 本地开发
|
||||
|
||||
开发者可从源码运行以下检查：
|
||||
|
||||
```bash
|
||||
npm ci
|
||||
npm run check
|
||||
@@ -37,40 +98,4 @@ npm run build
|
||||
node dist/index.js --help
|
||||
```
|
||||
|
||||
开发时初始化个人配置：
|
||||
|
||||
```bash
|
||||
node dist/index.js setup --json
|
||||
```
|
||||
|
||||
Authorize Key 只能输入到隐藏提示。不要把 Key 放进参数、环境变量、聊天、`config.json`、MCP 客户端配置或日志。
|
||||
|
||||
可用命令：
|
||||
|
||||
```text
|
||||
nocobase-crm-mcp setup [--config <path>] [--json]
|
||||
nocobase-crm-mcp [serve] [--config <path>] [--enable-writes]
|
||||
nocobase-crm-mcp doctor [--config <path>] [--json]
|
||||
nocobase-crm-mcp client-config [--config <path>] [--enable-writes] [--json]
|
||||
```
|
||||
|
||||
## 工具
|
||||
|
||||
默认提供 17 个只读工具：
|
||||
|
||||
- `crm_health`, `crm_schema`, `crm_overview`, `crm_filter_options`
|
||||
- `resolve_owner`, `list_teams`, `resolve_team`, `get_team`, `team_crm_overview`
|
||||
- `list_customers`, `get_customer`, `list_contacts`, `list_followups`
|
||||
- `list_projects`, `get_project`, `get_project_timeline`, `list_stale_customers`
|
||||
|
||||
`NOCOBASE_MCP_ENABLE_CONFIG_TOOLS=1` 可临时增加 `crm_config_template`。`include_raw=true` 默认被拒绝；管理员审核后才可设置 `NOCOBASE_MCP_ENABLE_RAW_DATA=1`。
|
||||
|
||||
## 权限边界
|
||||
|
||||
```text
|
||||
AI 客户端 → 本机 TypeScript MCP → HTTPS NocoBase API → 当前用户 Key 对应的 ACL
|
||||
```
|
||||
|
||||
MCP 不缓存共享身份。每个请求都会从当前操作系统用户的私有凭证文件读取 Key，因此撤销或替换 Key 后无需重新生成 MCP 客户端配置。API 地址固定为 `https://justconn.top/api`，不接受安装参数或凭证文件覆盖；跨域重定向会在转发 Authorization 前被拒绝，错误内容会脱敏。
|
||||
|
||||
内部结构见 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)，运维与权限验收见 [`docs/LOCAL_DELIVERY.md`](docs/LOCAL_DELIVERY.md)。
|
||||
本项目要求 Node.js 20.11 或更高版本。正式 Release 已将运行代码和依赖打包，最终用户不需要源码开发环境。
|
||||
|
||||
Reference in New Issue
Block a user