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/credentials.ts 固定 https://justconn.top/api、负责隐藏 TTY 输入和用户级私有凭证文件。凭证文件只保存 Key；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 依赖。

身份与网络安全

• 每个请求重新读取当前 OS 用户的凭证文件，NocoBase ACL 是最终权限边界。
• 生产运行时只连接固定 HTTPS API https://justconn.top/api，不接受参数、配置或凭证文件覆盖。
• 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 的版本必须一致。