# NocoBase CRM MCP

在你的电脑上，让 AI 客户端安全地查询 NocoBase CRM。安装时通过浏览器登录 NocoBase；每位用户使用自己的身份，看到的数据范围与本人在 NocoBase 中的权限一致。

## 安装

推荐把安装交给支持终端操作的 AI Agent 完成。你不需要克隆源码，也不需要逐条执行安装命令。

### 安装前准备

- Node.js 20.11 或更高版本；
- 能访问 `https://justconn.top`；
- 你自己的 NocoBase 账号；
- 能读取当前 Gitea 仓库 `main` 分支，并能访问 npm 软件源。

如果 Node.js 尚未安装，安装 Agent 会先说明需要进行的系统变更，并在获得你确认后再继续。

支持 Windows、macOS 和 Linux。三个平台都会安装 `main` 在任务开始时的最新 Commit；Windows 下载该 Commit 的 `.zip`，macOS/Linux 下载同一 Commit 的 `.tar.gz`。

不需要提前创建或复制 Authorize Key。MCP 注册后，Agent 会调用登录工具并把 NocoBase 官方网页链接发给你；桌面环境通常也会自动打开该页面。你在网页中确认授权后，Agent 会自动继续验收。

### 最快安装方式

把下面整段直接复制给安装 Agent：

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

安装协议：
https://git.justconn.top/gitea-admin/nocobase-mcp/raw/branch/main/INSTALL.md
```

1. Agent 会读取 Gitea `main` 的最新 Commit，把源码快照、安装协议和构建过程固定到同一个 SHA，再在临时目录完成检查和打包。
2. Agent 会先注册 MCP，再调用 `nocobase_login`。桌面环境通常自动打开浏览器；无界面或远程 Agent 会把同一个授权链接和确认码发到当前对话。
3. 你在 `justconn.top` 登录、核对确认码并授权后，Agent 会轮询 `nocobase_login_status`，最后确认 `crm_health` 返回 `ok=true`。

完整的安装和验收规则见 [INSTALL.md](INSTALL.md)。该 `main` 链接是安装入口；Agent 必须先解析一次最新 Commit，然后重新读取该 Commit 中不可变的同一文件，不能在一次安装中混用不同提交。

## 重要注意事项

- **只在 NocoBase 网页登录：** 安装程序不会读取浏览器 Cookie，也不会接触你的密码；OAuth 令牌只保存到权限受限的个人凭据文件，不会进入聊天、命令参数、环境变量、CRM 配置、MCP 客户端配置或日志。
- **默认只读：** 安装后默认只能查询 CRM，不会创建、更新或删除业务数据。
- **权限跟随本人：** MCP 不会绕过 NocoBase 的角色、字段权限和行级权限，也不会使用共享管理员账号。
- **只连接公司环境：** 程序固定连接 `https://justconn.top/api`，不会要求你填写其他 NocoBase 地址。
- **始终安装最新提交：** 每次安装只解析一次 `main` 的最新 Commit SHA，随后固定该快照完成构建；不会因为旧 Release 可用而安装旧代码。
- **安装在用户目录：** 不使用 `sudo`，不会全局安装本项目，也不需要 Git、Python、uv 或 `nb CLI`。源码和构建依赖只存在于临时目录，安装后仅保留打包运行文件。
- **受限仓库需要授权：** 如果 Agent 无法读取 Gitea `main` 或对应 Commit 快照，请联系仓库管理员开通权限，不要把访问令牌发到聊天中。

## 安装后可以做什么

你可以直接让 AI：

- 查询客户、联系人和跟进记录；
- 按负责人、团队、状态或时间范围筛选 CRM 数据；
- 查看 CRM 总览、团队贡献和长期未跟进客户；
- 查看项目详情和项目跟进时间线。

例如：

```text
列出我负责的、最近 30 天没有有效跟进的客户。
```

```text
查看“华东团队”本月的客户、跟进和在途项目概况。
```

## 可选写入

只有在你明确需要创建或更新项目，并且管理员已经确认你的 NocoBase 权限时，才应启用写入模式。

写入模式只增加固定字段的项目创建和更新能力，不提供删除操作，也不开放任意集合或任意字段写入。不要为了绕过权限错误而换用共享高权限 Key。

## 遇到问题

- 尚未登录：让 Agent 调用 `nocobase_login`，把返回的 `login_url` 和 `user_code` 发给你；授权后调用 `nocobase_login_status`。
- 登录失效：让 Agent 调用 `nocobase_login` 并设置 `force=true`，重新在浏览器授权；正常情况下访问令牌会在后台自动刷新。
- 浏览器没有打开：直接打开 `nocobase_login` 返回的 `justconn.top` 链接。即使桌面自动打开失败，该链接仍会返回给 Agent。
- MCP 客户端暂时无法调用登录工具：可在本人终端运行安装程序的 `setup --no-browser`，这是备用入口。
- 仅在 OAuth 暂时不可用且管理员明确要求时，才使用 `setup --manual-key` 的隐藏输入备用模式；不要把 Key 发到聊天中。
- 返回 `NO_PERMISSIONS`：请检查本人 NocoBase 角色和数据权限。
- 请求超时：确认可以访问 `https://justconn.top`，或缩小查询范围。
- 最新 Commit 无法解析或构建失败：停止安装并报告 Commit SHA 和失败步骤，不要退回旧 Release。
- 源码快照无法下载：确认当前账号或 Agent 已获得 Gitea 仓库的读取权限。

更多故障处理和更新、回滚说明见 [本机交付与权限验收](docs/LOCAL_DELIVERY.md)。

## 更多文档

- [完整安装协议](INSTALL.md)：供安装 Agent 解析并固定最新 Commit、构建、安装和验收。
- [命令与工具参考](docs/REFERENCE.md)：CLI 命令、MCP 工具和可选运行开关。
- [内部架构](docs/ARCHITECTURE.md)：模块边界、身份与网络安全设计。
- [本机交付与权限验收](docs/LOCAL_DELIVERY.md)：运维、权限验收、更新和回滚。

## 本地开发

开发者可从源码运行以下检查：

```bash
npm ci
npm run check
npm test
npm run build
node dist/index.js --help
```

本项目要求 Node.js 20.11 或更高版本。安装 Agent 会在临时目录从锁定依赖构建最新 Commit；最终运行包不含额外 npm 运行时依赖，用户不需要长期保留源码开发环境。