37 lines
2.4 KiB
Markdown
37 lines
2.4 KiB
Markdown
# 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/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` 的版本必须一致。
|