# Internal architecture

默认数据路径：

```text
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 不再是默认安装前提。