NocoBase CRM MCP

本项目是在用户电脑本机运行的 NocoBase CRM MCP。每位用户使用自己的个人 Authorize Key，所有查询和写入继续由 NocoBase ACL、字段权限和行级权限裁决；不需要共享账号或远程 MCP 服务。

用户侧依赖

正式 Release 是一个已打包的 npm tarball，内部包含 MCP SDK 和运行代码。用户电脑只需要：

• Node.js 20.11 或更高版本（npm 随 Node.js 一起提供）；
• 能访问目标 NocoBase；
• 用户自己的个人 Authorize Key。

用户不再需要 Git、Python、uv、Python 包或 nb CLI。安装也不会全局安装本项目，而是放到用户自己的应用数据目录。

Private GitHub 仓库的 Release 只能由已经获得仓库或分发渠道权限的用户下载。若要实现面向任意用户的“一条链接安装”，需要另行提供用户 Agent 能认证访问的下载地址。

安装

把对应 Release Tag 下的不可变 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，不提供删除或任意资源工具。

本地开发

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

开发时初始化个人配置：

node dist/index.js setup --api-base-url https://nocobase.example --json

Authorize Key 只能输入到隐藏提示。不要把 Key 放进参数、环境变量、聊天、config.json、MCP 客户端配置或日志。

可用命令：

nocobase-crm-mcp setup --api-base-url <url> [--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。

权限边界

AI 客户端 → 本机 TypeScript MCP → HTTPS NocoBase API → 当前用户 Key 对应的 ACL

MCP 不缓存共享身份。每个请求都会从当前操作系统用户的私有凭证文件读取 Key，因此撤销或替换 Key 后无需重新生成 MCP 客户端配置。远程地址必须使用 HTTPS（回环地址除外），跨域重定向会在转发 Authorization 前被拒绝，错误内容会脱敏。

内部结构见 docs/ARCHITECTURE.md，运维与权限验收见 docs/LOCAL_DELIVERY.md。