nocobase-mcp/docs/ARCHITECTURE.md

Internal architecture

默认数据路径：

MCP client → TypeScript tool boundary → CRM domain service → NocoBaseClient → NocoBase HTTP API

模块边界

• src/index.ts 是单一可执行入口；src/cli.ts 管理 setup、doctor、客户端配置和 stdio 生命周期。
• src/nocobase-endpoints.ts 集中固定 API、OAuth issuer、发现地址和 resource identifier。
• src/oauth.ts 实现 OAuth 发现、动态公共客户端注册、设备授权、浏览器启动、轮询和刷新；不读取浏览器 Cookie，也不监听本机端口。
• src/auth-service.ts 把设备授权包装成 MCP 可调用的开始/状态会话；先返回安全的网页链接，再跨 stdio 进程恢复、验证和保存授权结果。
• src/authorization-store.ts 管理短期待授权文件、跨进程独占锁、崩溃恢复和锁所有权；src/credentials.ts 管理用户级私有凭证及进程内缓存；两者共用 src/private-json.ts 的私有目录检查和原子 JSON 写入。默认保存 OAuth 访问/刷新令牌，兼容旧版个人 Key；任何凭据都不进入 argv、环境变量、CRM 配置或 MCP 配置。
• src/nocobase-client.ts 是唯一远程适配器，直接实现 NocoBase resource action 协议、data-modeling 读取、项目附件关系和 ACL 检查。
• src/crm-service.ts 负责 CRM 查询、解析、分页、聚合和可读输出；src/crm-helpers.ts 与 src/filters.ts 保存纯函数。
• src/project-service.ts 只允许固定项目字段的 create/update；src/tools.ts 是稳定 MCP 契约和错误/原始数据策略边界。
• scripts/build.mjs 用 esbuild 将 MCP SDK、Zod 和所有运行代码打成一个 ESM 文件。按 Commit 构建的安装 tarball 和正式 Release tarball 都没有运行时 npm 依赖。

身份与网络安全

• 凭据在进程内缓存，只有访问令牌临近过期时才进行一次并发合并的刷新；NocoBase ACL 是最终权限边界。
• 生产运行时只连接固定 HTTPS API https://justconn.top/api，不接受参数、配置或凭证文件覆盖。
• OAuth issuer、协议端点和浏览器授权 URL 必须属于固定的 https://justconn.top 来源。
• Device Authorization 请求 api offline_access；密码和浏览器会话不会离开 NocoBase。
• MCP 可以在无配置、无凭据状态下准备默认配置并启动；只有业务请求需要身份。nocobase_login 返回应交给发起用户当前私聊的 OAuth Device Flow 网页链接、确认码和机器可读交付边界；链接不是 Bearer 凭据，无界面服务器不需要远程桌面。内部设备码只进入短期 0600 文件；nocobase_login_status 可在新进程中继续兑换，完成的 Token 不经过 Agent。
• Authorization 只允许在同源重定向中保留，跨源重定向在发送凭证前失败。
• Token 会从 HTTP 错误中替换为 <redacted>。
• stdio 是唯一默认传输，不创建后台服务或监听端口。

兼容规则

• 保持 17 个 CRM 只读工具名称、参数和主要响应形状稳定，并固定提供 nocobase_login、nocobase_login_status 两个身份工具。
• 写模式只增加 create_project、update_project，不提供 delete/destroy。
• include_raw 默认在 MCP 边界拒绝。
• 配置继续接受 camelCase 与 snake_case 字段别名。
• 默认安装先解析 Gitea main 的最新完整 Commit SHA，再在同一快照中读取协议、检查、测试、构建和打包；失败时不回退旧 Release。
• 正式 Release 仍要求 Tag、package.json 和 install-manifest.json 的版本一致，但 Release 不再是默认安装前提。