CLI 与 MCP 接入指南
2026-09-28 更新。CLI 与 MCP 已实现，复用当前 CPQ HTTP 服务。完整操作数量以 operations list 或官网 OpenAPI 目录为准，另有通用请求入口。
安装与启动
在 cpq-app 项目目录运行：
./cpq --help
./cpq operations list --search 界面
./cpq operations describe catalog.draft
CLI 自身只使用 Python 3.11+ 标准库。复制项目后可以直接用 ./cpq；安装到其他 Python 环境：
python3 -m pip install .
cpq --help
需要 MCP 时安装可选依赖（本次验证使用官方 MCP Python SDK 2.2.0）：
python3 -m pip install '.[mcp]'
cpq mcp serve
项目虚拟环境安装命令为 bash scripts/python.sh -m pip install -e '.[mcp]'。 标准输入输出由 MCP 协议占用，正常启动不打印欢迎信息。也可用安装后的 cpq-mcp 命令。 已有 CPQ 本机服务继续使用 8765；Agent 是独立客户端，不需要重启现有业务服务。
本机或独立部署登录
./cpq --base-url http://127.0.0.1:8765 auth login --user 你的登录名
./cpq auth status
./cpq call bootstrap.get
密码由交互提示读取。自动化可用 --password-stdin，由已有凭据管理器传入。 不提供明文 --password 参数。失败不会打印密码、Cookie 或 CSRF。
远程服务使用 HTTPS，例如 --base-url https://cpq.example.com。全局参数放在子命令前。
会话默认保存于 ~/.config/cloudcc-cpq/sessions/，以完整服务源地址的摘要分文件，权限为 0600。 会话失效后重新登录，MCP 下次调用即读取新会话。使用 auth logout 向服务端注销。
| 配置 | 用途 |
|---|---|
| CPQ_BASE_URL / --base-url | 当前 CPQ 地址 |
| CPQ_SESSION_FILE / --session-file | 指定私有会话文件 |
| CPQ_STATE_DIR | 默认会话目录根路径 |
| CPQ_TIMEOUT / --timeout | HTTP 超时秒数，默认 30，最大 600 |
| CPQ_READ_ONLY=1 / --read-only | 只允许已登记的读取、计算、预览 |
| CPQ_SESSION_TOKEN | 可选：由运行环境注入已有会话，优先于文件 |
| CPQ_COOKIE_NAME、CPQ_CSRF | 配合已有会话注入；生产 SaaS Cookie 为 __Host-cpq_session |
注入会话仍遵守服务端到期和撤权机制，不是永不过期的 API Key。不要将真实凭据放到 MCP 配置、Git 或对话中。
SaaS 企业登录
使用集中账号登录平台地址，再进入具体企业：
cpq --base-url https://app.example.com auth login --scope account --user you@example.com
cpq --base-url https://app.example.com call me.tenants.list
cpq --base-url https://app.example.com auth enter \
--tenant-id 从列表取得的企业ID \
--tenant-url https://你的企业.example.com
cpq --base-url https://你的企业.example.com auth status
enter 调用真实登录入口取得 nonce，再使用现有一次性票据换取企业会话。平台 Cookie 不发送到企业地址。 返回 baseUrl、sessionFile，可用于 MCP 配置。企业操作自动携带 CSRF；额度、停用、成员撤权等仍由 SaaS 服务端判断。
平台运营使用 auth login --scope platform；生产环境提供 --code 当前MFA动态码。非生产测试环境若已启用平台密码登录模式，可省略 --code。 建议平台与集中账号各自指定不同 --session-file，以便明确当前身份。
全量 CLI 调用
cpq operations list --limit 500
cpq operations list --search pricing
cpq operations describe quotes.save
cpq call products.list --query '{"page":1,"pageSize":20}'
cpq call quotes.get --path '{"id":"从报价列表取得的ID"}'
cpq call configure.run --body @configuration-input.json
cpq request POST /api/configure --body @configuration-input.json
cpq schema --output cpq-openapi.json
call 操作ID支持目录中的全部操作；request 可调用当前源下新增的 /api/ 路由。 --body 支持 JSON 文本、@文件及 -（标准输入）；--path 和 --query 分别为路径／查询参数。 --headers 可读取 JSON 或 @私有文件，用于已有签名回执、首次设置等接口，不允许覆盖 Host、Cookie、Origin。
主要领域：
| 领域 | 操作前缀／保存机制 |
|---|---|
| 产品、属性、数组、BOM、规则、配置布局、自定义组件、BML 库 | catalog. 完整目录；rules.、bml.、config-tables. |
| 配置、计算与定价 | configure.、calculators.、pricing.、commercial.、price.* |
| 商务流程、权限、审批、报价及多配置 | commerce.、quotes.、users.、product-lines. |
| 报价场景与工作台 | quote-scenarios.、quote-experience. |
| 文档、邮件、报告、文件与后台任务 | document-design.、documents.、email-templates.、reports.、export.、jobs. |
| 资产、订单、门户、集成、AI | business.、portal.、portal-admin.、connections.、integrations.、ai. |
| SaaS 注册、企业和平台管理 | public.、account.、me.、tenant.、platform.* |
| 价目、审批策略、发布及集成管理 | manage.* |
“全量”指当前应用已实现的 HTTP 业务能力，不代表尚未开发的 Oracle 功能或未经联调的外部系统已经可用。 OpenAPI 3.1 文件列出路由、操作、路径参数和主要请求契约；复杂目录对象是开放 JSON，最终由现有服务端领域校验。
产品配置界面定制
读取完整目录并保存为本地文件：
cpq ui configuration get --output configuration-state.json
编辑其中 catalog.configurationLayouts，保留其他型号布局和目录字段。 布局树、引用和自定义组件字段见 界面契约。 保存请求是 {version,catalog}；读取状态文件自身含这两个字段，可直接用作输入：
cpq ui configuration save --body @configuration-state.json --output configuration-saved.json
用保存后的 catalog 和实际 modelId 构建 configuration-preview.json：
{
"catalog": {"这里替换为完整保存后的目录": "..."},
"modelId": "读取到的实际型号ID",
"attributeValues": {}
}
该示例只说明结构，不能以占位目录提交。运行预览：
cpq ui configuration preview --body @configuration-preview.json --output configuration-preview-result.json
检查 errors、layout、规则消息及价格结果。确认需要发布后，以保存返回的新版本发布：
cpq ui configuration publish --body @configuration-saved.json --output configuration-published.json
cpq call configure.run --body '{"modelId":"读取到的实际型号ID"}'
可以定制页签、网格、字段呈现、图片、摘要、按钮，以及既有沙箱 customUI 的 HTML/CSS/JavaScript。 发布单位是完整目录，包含其他已保存草稿；发布前需核对整体内容。服务端拒绝无效引用、丢失必填字段或过期版本。
报价界面定制
cpq ui quote get --output quote-state.json
修改 data.layouts 的组件、页签、匹配范围及 presentation（字段分组、列、动作和汇总位置）。 保留 data.scenarios 和不相关布局。可以复制读取响应中的 standard 布局，换一个非保留 id 后添加。
cpq ui quote save --body @quote-state.json --output quote-saved.json
cpq ui quote preview --body @quote-preview.json --output quote-preview-result.json
cpq ui quote publish --body @quote-saved.json --output quote-published.json
quote-preview.json 必须包含保存后的完整 data，以及真实 quoteId 和 userId；可选 stage、stepId、scenarioId。 预览结果中 quote.quoteLayout 应与预期匹配。发布后读取该报价再次检查。 报价页使用现有组件与呈现元数据，当前不提供整页任意 HTML 替换。界面配置不能提升字段或动作权限。
文件传输
cpq file encode products.xlsx --output upload.json
cpq call table.preview --body @upload.json --output parsed-table.json
cpq call export.download \
--query '{"id":"真实报价ID","kind":"quote","format":"pdf","language":"zh"}' \
--output quote.pdf
file encode 生成 filename 和 base64 content。不同业务接口按契约加入版本、名称等字段；AI 资料上传将文件对象放在 file 字段内。 --output 保存原始文件／JSON并覆盖同名文件；不指定时，文件以含 MIME、文件名、长度的 base64 JSON 返回。 CLI 本地编码文件最多 20 MiB，HTTP 请求最多 30 MiB，响应最多 128 MiB。
Codex 接入
生成当前 Python 环境及会话路径对应的配置：
./cpq mcp config --client codex --output codex-cpq.toml
将文件中的 mcp_servers.cpq 段合并到 Codex MCP 配置。仓库示例需要将 cwd 改为本机路径： Codex TOML。 也可使用官方命令格式，在安装 cpq 的 Python 环境中运行：
codex mcp add cpq --env CPQ_BASE_URL=http://127.0.0.1:8765 -- cpq mcp serve
codex mcp list
如果图形应用 PATH 不包含 cpq，使用生成的 TOML，它绑定虚拟环境 Python 的绝对路径。 配置方式已对照官方 Codex MCP 文档和本机 codex mcp add --help。
WorkBuddy 接入
./cpq mcp config --client workbuddy --output workbuddy-mcp.json
将生成的 mcpServers.cpq 合并到 WorkBuddy 的 MCP 配置： WorkBuddy JSON。 本次提供 stdio、command、args、cwd、env 配置，格式依据WorkBuddy 官方连接器文档。 cwd 字段需 WorkBuddy 4.22.15 或更新版本。如已通过 pip 安装包，也可删去 cwd。 迁移电脑或 Python 环境后重新生成配置；仓库示例中的 cwd 占位路径需要替换。
MCP 工具与资源
| 工具 | 用途 |
|---|---|
| cpq_list_operations | 检索／分页浏览全部已登记操作 |
| cpq_describe_operation | 读取指定操作参数契约 |
| cpq_read | 执行已登记只读操作和预览 |
| cpq_call | 按操作 ID 执行任意当前业务 |
| cpq_request | 通用同源 HTTP 请求 |
| cpq_ui_get | 读取配置页／报价页定义 |
| cpq_ui_save | 保存草稿 |
| cpq_ui_preview | 真实业务预览 |
| cpq_ui_publish | 显式发布 |
资源：cpq://guide、cpq://interfaces、cpq://openapi、cpq://operations/{operation}。 采用官方 Python SDK，支持标准初始化协商；stdio 不混入日志输出。
可向 Agent 下达：
通过 cpq MCP 查找目标型号，读取配置界面，将“参数选择”页签改为“技术参数”，保存草稿并预览，给出校验结果。
读取当前报价界面，将指定销售布局的明细页签提前，保留必需组件和权限，先保存草稿并用指定报价和销售账号预览。
返回与验收边界
CLI 业务成功返回 {ok:true,status,data}，错误返回 {ok:false,status,error,details?}。 操作目录／schema 输出直接为 JSON 对象；mcp config 输出目标原生格式。 退出码：0 成功，2 本地输入／文件错误，3 未登录或无权限，4 HTTP／业务错误，5 网络故障。 MCP 错误同时带 isError=true 和结构化 details。请求超时不自动重试写入；先查询服务端状态。
本轮验证包括真实 CLI 子进程、真实 MCP stdio 子进程、两类界面保存预览发布、历史快照、权限和版本冲突、文件上传下载，以及 SaaS ASGI 身份／企业隔离。 Codex／WorkBuddy 提供可用配置格式，未将当前业务账号凭据写入客户端配置；WorkBuddy 应用内交互未实测。 本次没有修改或发布现有工作库的业务定义，也没有新增公网 MCP 监听端口。