命令与工具参考

本文面向集成者和维护者。普通用户请从仓库根目录的 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 授权链接和确认码；搭配 --json 时还会在 stderr 输出 authorization_required 结构化事件。
--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、标准别名 verification_uri_complete、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 查询结果。它们属于 OAuth Device Flow 的短期用户验证信息，不是密码、Key、Bearer Token 或内部 device_code。待授权状态以短期私有文件保存，因此桌面、远程或无界面环境都不需要回调端口或服务器远程桌面，stdio 进程重启后也能恢复同一个授权。已有凭据被 NocoBase 拒绝时，使用 nocobase_login({"force": true}) 重新授权。CLI 的 setup --no-browser 保留为客户端无法在登录前加载连接器时的持续等待备用入口；运行期间不得关闭该 CLI 进程。

发现地址：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.7 KiB Raw Permalink Blame History