feat: migrate MCP runtime to TypeScript
This commit is contained in:
+21
-18
@@ -1,29 +1,32 @@
|
||||
# Internal architecture
|
||||
|
||||
The default data path is:
|
||||
默认数据路径:
|
||||
|
||||
```text
|
||||
MCP client -> server facade -> CRM domain mixins -> NbClient -> local nb CLI -> NocoBase
|
||||
MCP client → TypeScript tool boundary → CRM domain service → NocoBaseClient → NocoBase HTTP API
|
||||
```
|
||||
|
||||
The local `nb` environment is the identity boundary. The MCP does not keep a shared NocoBase account, and NocoBase ACL remains authoritative.
|
||||
## 模块边界
|
||||
|
||||
## Package boundaries
|
||||
- `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 依赖。
|
||||
|
||||
- `crm.py` is the stable `CrmService` facade. Metadata discovery, directory resolution, record queries, presentation, analytics, and reporting live in separate `crm_*` modules.
|
||||
- `server.py` owns dependency assembly and the public command entrypoint. The four `server_tools_*` modules register the existing MCP contracts; `server_runtime.py` owns HTTP authentication and ASGI assembly; `tool_errors.py` owns structured error mapping.
|
||||
- `config.py` keeps the public frozen configuration dataclasses and uses one data-driven section loader for camelCase and snake_case JSON aliases.
|
||||
- `nb_client.py` is the only read/query adapter to the local `nb` CLI. `nocobase_http.py` is limited to HTTP operations the CLI does not expose cleanly, such as multipart upload and attachment relations.
|
||||
## 身份与网络安全
|
||||
|
||||
## Bootstrap and advanced deployment
|
||||
- 每个请求重新读取当前 OS 用户的凭证文件,NocoBase ACL 是最终权限边界。
|
||||
- 非回环 HTTP URL 被拒绝;远程 Key 只能发往 HTTPS。
|
||||
- Authorization 只允许在同源重定向中保留,跨源重定向在发送凭证前失败。
|
||||
- Token 会从 HTTP 错误中替换为 `<redacted>`。
|
||||
- stdio 是唯一默认传输,不创建后台服务或监听端口。
|
||||
|
||||
- `scripts/agent_install.py` is a compatibility entrypoint. Its standard-library-only implementation lives in `scripts/agent_installer/`; `flow.py` composes the public one-command `install` journey, while the lower-level inspect, prepare, authentication, diagnostics, and client-config functions remain independently testable recovery primitives.
|
||||
- `scripts/manage_mcp_service.py` is the compatibility entrypoint for optional Linux loopback HTTP mode. Configuration serialization, runtime operations, and CLI parsing live in separate `mcp_service_*` modules.
|
||||
## 兼容规则
|
||||
|
||||
Default installation remains stdio, read-only, without a background service, listener port, uploads, raw rows, or shared credentials.
|
||||
|
||||
## Compatibility rules
|
||||
|
||||
- Keep the `nocobase-crm-mcp` console entrypoint and `CrmService` import stable.
|
||||
- Treat MCP tool names, input schemas, response shapes, configuration aliases, installer commands, and service-manager commands as public contracts.
|
||||
- Personal API Keys may only enter the `nb` CLI private TTY prompt. Never move them through Agent chat, argv, environment variables, logs, or temporary files.
|
||||
- 保持 17 个只读工具名称、参数和主要响应形状稳定。
|
||||
- 写模式只增加 `create_project`、`update_project`,不提供 delete/destroy。
|
||||
- `include_raw` 默认在 MCP 边界拒绝。
|
||||
- 配置继续接受 camelCase 与 snake_case 字段别名。
|
||||
- Release Tag、`package.json` 和 `install-manifest.json` 的版本必须一致。
|
||||
|
||||
Reference in New Issue
Block a user