96 lines
5.7 KiB
Markdown
96 lines
5.7 KiB
Markdown
# 命令与工具参考
|
|
|
|
本文面向集成者和维护者。普通用户请从仓库根目录的 [README](../README.md) 开始；安装 Agent 应从 `main` 的 [INSTALL.md](../INSTALL.md) 进入，先解析最新完整 Commit SHA，再固定该快照完成安装。
|
|
|
|
## CLI 命令
|
|
|
|
```text
|
|
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` 默认会被拒绝。只有经过管理员审核并显式设置以下变量后才允许返回原始行：
|
|
|
|
```text
|
|
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` 来源
|
|
|
|
## 默认运行边界
|
|
|
|
```text
|
|
AI 客户端 → 本机 stdio MCP → HTTPS NocoBase API → 当前用户 ACL
|
|
```
|
|
|
|
- 启动后凭据缓存在进程内存中；MCP 登录成功时会主动刷新这份缓存，不需要重启连接器。
|
|
- 只有访问令牌临近过期时才刷新，并把轮换后的凭据写回私有文件。
|
|
- 默认不创建后台服务，不监听本机或公网端口。
|
|
- NocoBase ACL、字段权限和行级权限是最终权限边界。
|
|
- 认证失败、超时和上游请求错误会以结构化错误返回。
|
|
|
|
实现细节见 [内部架构](ARCHITECTURE.md)，运维和真实权限验收见 [本机交付与权限验收](LOCAL_DELIVERY.md)。
|