30 lines
2.1 KiB
Markdown
30 lines
2.1 KiB
Markdown
# Internal architecture
|
|
|
|
The default data path is:
|
|
|
|
```text
|
|
MCP client -> server facade -> CRM domain mixins -> NbClient -> local nb CLI -> NocoBase
|
|
```
|
|
|
|
The local `nb` environment is the identity boundary. The MCP does not keep a shared NocoBase account, and NocoBase ACL remains authoritative.
|
|
|
|
## Package boundaries
|
|
|
|
- `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
|
|
|
|
- `scripts/agent_install.py` is a compatibility entrypoint. Its standard-library-only implementation lives in `scripts/agent_installer/`, so `inspect` and secure Key connection can run before project dependencies are synchronized.
|
|
- `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.
|