# 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/credentials.ts` 负责 URL 安全校验、隐藏 TTY 输入和用户级私有凭证文件。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 是最终权限边界。
- 非回环 HTTP URL 被拒绝；远程 Key 只能发往 HTTPS。
- 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` 的版本必须一致。