命令与工具参考

本文面向集成者和维护者。普通用户请从仓库根目录的 README 开始，安装 Agent 请使用固定 Release Tag 中的 INSTALL.md。

CLI 命令

nocobase-crm-mcp setup [--config <path>] [--no-browser] [--manual-key] [--json]
nocobase-crm-mcp [serve] [--config <path>] [--enable-writes]
nocobase-crm-mcp doctor [--config <path>] [--json]
nocobase-crm-mcp client-config [--config <path>] [--enable-writes] [--json]

setup：通过 NocoBase OAuth 浏览器授权登录、准备 CRM 配置并输出 MCP 客户端配置。
serve：通过 stdio 启动 MCP；省略子命令时也是此模式。
doctor：验证凭据和 CRM 映射是否可用。
client-config：输出可合并到 MCP 客户端的配置片段，不包含任何 Token 或 Key。
--enable-writes：显式增加受控项目写入工具；默认不启用。
--no-browser：不自动启动浏览器，只显示 NocoBase 授权链接和确认码。
--manual-key：仅在 OAuth 不可用时，通过安全 TTY 隐藏输入个人 Authorize Key。

默认只读工具

默认稳定提供 17 个只读工具：

健康、配置和总览：crm_health、crm_schema、crm_overview、crm_filter_options
用户与团队：resolve_owner、list_teams、resolve_team、get_team、team_crm_overview
客户与联系人：list_customers、get_customer、list_contacts
跟进与项目：list_followups、list_projects、get_project、get_project_timeline
客户维护：list_stale_customers

查询结果默认返回经过整理的紧凑字段，而不是完整 NocoBase 原始记录。

可选工具

设置 NOCOBASE_MCP_ENABLE_CONFIG_TOOLS=1 时，会临时增加 crm_config_template，用于生成带字段元数据的配置参考。

使用 --enable-writes 启动时，只增加：

create_project
update_project

写入仅允许配置中定义的项目字段和附件关系，不提供删除、任意集合访问或任意字段写入。

原始数据策略

工具参数中的 include_raw=true 默认会被拒绝。只有经过管理员审核并显式设置以下变量后才允许返回原始行：

NOCOBASE_MCP_ENABLE_RAW_DATA=1

不应把该变量作为普通用户的默认配置。

运行环境变量

NOCOBASE_MCP_CONFIG：覆盖 CRM 映射配置文件路径。
NOCOBASE_MCP_CREDENTIALS：覆盖当前操作系统用户的凭据文件路径。
NOCOBASE_MCP_DATA_SOURCE：覆盖 NocoBase data source 名称。
NOCOBASE_MCP_TIMEZONE：覆盖结果显示时区。
NOCOBASE_MCP_ENABLE_CONFIG_TOOLS=1：启用配置模板工具。
NOCOBASE_MCP_ENABLE_RAW_DATA=1：经审核后允许请求原始数据。

OAuth Token 和 Authorize Key 都不支持也不允许通过环境变量传入。API 地址固定为 https://justconn.top/api，不能通过配置或环境变量覆盖。

OAuth 登录

发现地址：https://justconn.top/api/.well-known/openid-configuration
授权模式：OAuth 2.1 Device Authorization
客户端类型：动态注册的 native public client，不保存 client secret
请求权限：api offline_access
浏览器只访问 https://justconn.top；程序不读取 Cookie 或浏览器存储
访问令牌临近过期时自动刷新；并发请求只触发一次刷新
OAuth 端点、浏览器 URL 和 issuer 都必须匹配固定的 justconn.top 来源

默认运行边界

AI 客户端 → 本机 stdio MCP → HTTPS NocoBase API → 当前用户 ACL

启动后凭据缓存在进程内存中；日常请求不重复读取文件，也不增加 OAuth 网络请求。
只有访问令牌临近过期时才刷新，并把轮换后的凭据写回私有文件。
默认不创建后台服务，不监听本机或公网端口。
NocoBase ACL、字段权限和行级权限是最终权限边界。
认证失败、超时和上游请求错误会以结构化错误返回。

实现细节见内部架构，运维和真实权限验收见本机交付与权限验收。

4.0 KiB Raw Blame History