nocobase-mcp/docs/LOCAL_DELIVERY.md

本机交付与权限验收

交付模型

每位用户在自己的电脑运行 MCP，并使用绑定本人业务身份的个人 Authorize Key：

本机 AI 客户端 → 本机 TypeScript MCP → 远程 NocoBase API → 本人 ACL

项目不保存共享业务账号，也不需要多人共用的远程 MCP 服务。

Release 发布物

Release workflow 会在带版本 Tag 时执行锁定安装、类型/格式检查、测试、bundle、npm pack 和生产依赖审计，并上传：

• npm tarball；
• SHA256SUMS。

源码仓库保持 Private 时，外部用户必须具有 Release 下载权限，或通过另一个经过身份认证的分发渠道取得相同资产。Private GitHub 链接本身不能成为任意用户可访问的一键安装链接。

用户电脑上的内容

• Node.js 20.11+（唯一系统运行时）；
• 用户应用数据目录中的打包 MCP；
• CRM 映射配置；
• 当前 OS 用户的私有凭证文件；
• MCP 客户端配置和备份。

不需要 Git、Python、uv、nb CLI 或项目源码 checkout。npm 只在隔离前缀安装一个已经 bundle 的包，运行时没有额外 npm 依赖。

权限验收

至少使用两个权限不同的真实测试账号：

1. 分别签发个人 Key，并在隔离的 OS 用户/凭证路径运行 setup。
2. 使用相同参数调用 list_customers、list_contacts、list_followups、list_projects。
3. 确认返回范围与各自在 NocoBase UI 中的 ACL 一致。
4. 无项目写权限账号在 --enable-writes 下调用 create_project，确认 NocoBase 拒绝。
5. 有权限账号创建和更新测试项目，确认审计身份属于该用户。
6. 撤销 Key 后确认 MCP 返回 nocobase_auth_failed，且不会降级使用其他凭证。
7. 检查错误与日志，确认没有 Key、Authorization header 或业务原始行泄漏。

更新与回滚

Agent 下载新的固定 Release tarball并验证 SHA-256，再对同一隔离前缀运行 npm install --prefix ... --omit=dev <tarball>。安装前备份 MCP 客户端配置和非秘密 CRM 配置。

回滚时重新安装上一固定 Release 的已验证 tarball。凭证文件与 CRM 配置位于包目录之外，更新和回滚不应复制、覆盖或删除个人 Key。

常见故障

• nocobase_auth_failed：重新运行 setup，让用户在隐藏提示输入新签发 Key。
• nocobase_request_timeout：检查 NocoBase 可用性或缩小查询。
• nocobase_request_failed / NO_PERMISSIONS：检查该用户 ACL 和字段/行级权限。
• 凭证文件权限错误：POSIX 下修复为 0600，父目录为 0700，不要放宽为共享可读。
• 跨源重定向错误：修正 NocoBase API URL或代理配置；不要关闭同源保护。