77 lines
3.4 KiB
Markdown
77 lines
3.4 KiB
Markdown
# 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 能认证访问的下载地址。
|
||
|
||
## 安装
|
||
|
||
把对应 Release Tag 下的不可变 [`INSTALL.md`](INSTALL.md) 链接交给安装 Agent。该协议不依赖 Codex、Claude Code、Cursor、OpenCode 或其他特定客户端。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`，不提供删除或任意资源工具。
|
||
|
||
## 本地开发
|
||
|
||
```bash
|
||
npm ci
|
||
npm run check
|
||
npm test
|
||
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)。
|