Internal architecture

The default data path is:

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.

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.

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.