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/credentials.ts 管理用户级私有凭证文件与进程内缓存。默认保存 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 文件。Release tarball 没有运行时 npm 依赖。

身份与网络安全

• 凭据在进程内缓存，只有访问令牌临近过期时才进行一次并发合并的刷新；NocoBase ACL 是最终权限边界。
• 生产运行时只连接固定 HTTPS API https://justconn.top/api，不接受参数、配置或凭证文件覆盖。
• OAuth issuer、协议端点和浏览器授权 URL 必须属于固定的 https://justconn.top 来源。
• Device Authorization 请求 api offline_access；密码和浏览器会话不会离开 NocoBase。
• Authorization 只允许在同源重定向中保留，跨源重定向在发送凭证前失败。
• Token 会从 HTTP 错误中替换为 <redacted>。
• stdio 是唯一默认传输，不创建后台服务或监听端口。

兼容规则

• 保持 17 个只读工具名称、参数和主要响应形状稳定。
• 写模式只增加 create_project、update_project，不提供 delete/destroy。
• include_raw 默认在 MCP 边界拒绝。
• 配置继续接受 camelCase 与 snake_case 字段别名。
• Release Tag、package.json 和 install-manifest.json 的版本必须一致。