命令与工具参考

本文面向集成者和维护者。普通用户请从仓库根目录的 README 开始；安装 Agent 应从 main 的 INSTALL.md 进入，先解析最新完整 Commit SHA，再固定该快照完成安装。

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：准备默认 CRM 配置并输出可合并到 MCP 客户端的配置片段；不要求登录，也不包含任何 Token 或 Key。
--enable-writes：显式增加受控项目写入工具；默认不启用。
--no-browser：不自动启动浏览器，只显示 NocoBase 授权链接和确认码。
--manual-key：仅在 OAuth 不可用时，通过安全 TTY 隐藏输入个人 Authorize Key。

默认工具

默认提供 2 个登录工具和 17 个 CRM 只读工具。

登录：nocobase_login、nocobase_login_status
健康、配置和总览：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_login 会启动用户确认的 OAuth 授权，并在成功后写入本机私有凭据文件，因此不会被标记为只读；它不会修改任何 CRM 业务数据。该工具只返回可交给用户的 login_url、user_code、有效期和状态，不返回 Token 或设备码。

可选工具

设置 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 登录

推荐在 MCP 注册后调用 nocobase_login，把返回的链接和确认码发给用户，再用 nocobase_login_status 查询结果。桌面环境会尝试自动打开浏览器；远程或无界面环境使用相同链接，不需要回调端口。已有凭据被 NocoBase 拒绝时，使用 nocobase_login({"force": true}) 重新授权。CLI 的 setup --no-browser 保留为客户端无法在登录前加载连接器时的备用入口。

发现地址：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

启动后凭据缓存在进程内存中；MCP 登录成功时会主动刷新这份缓存，不需要重启连接器。
只有访问令牌临近过期时才刷新，并把轮换后的凭据写回私有文件。
默认不创建后台服务，不监听本机或公网端口。
NocoBase ACL、字段权限和行级权限是最终权限边界。
认证失败、超时和上游请求错误会以结构化错误返回。

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

5.0 KiB Raw Blame History