# 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)。