资源中心文档版本 1.0.0 · 2026-09-28

MCP 工具与资源

云动 CPQ 使用标准 stdio MCP，由客户端启动本地进程。工具将调用转交给配置的 CPQ HTTP 服务，不直接访问业务数据库。

安装、登录与连接

在 cpq-app 项目目录中运行：

python3 -m pip install '.[mcp]'
cpq --base-url http://127.0.0.1:8765 auth login --user 你的登录名
cpq mcp config --client codex --output codex-cpq.toml
cpq mcp config --client workbuddy --output workbuddy-mcp.json

把生成的对应配置段加入 Agent 的 MCP 配置，重新连接服务。启动命令为 cpq mcp serve，也可使用安装后的 cpq-mcp；stdio 不输出欢迎信息。

Codex 配置模板与 WorkBuddy 配置模板可直接下载。模板未包含凭据，Python 路径和 cwd 需适配本机；命令生成的配置使用实际解释器与私有会话文件。详细 SaaS 换票流程见接入指南。

调用方式

先发现操作，再查看契约，最后执行读取或写入。每个 MCP 工具参数是 JSON 对象；HTTP 请求体放在 body 中，路径参数放在 path 中。

{"operation":"quotes.get","path":{"id":"从报价列表取得的真实ID"}}

以上参数用于 cpq_read。MCP 请求和响应封装由 Agent 客户端完成，不需要手写协议报文。

产品配置与报价界面采用 cpq_ui_get → cpq_ui_save → cpq_ui_preview → cpq_ui_publish。surface 的值为 configuration 或 quote。草稿、预览和正式发布是不同操作；使用最近一次返回的 version。

返回与错误

业务调用成功返回 {ok:true,status,data}；文件返回 {ok:true,status,file:{mimeType,filename,encoding:"base64",content,bytes}}。操作列表、单项契约等发现工具直接返回其结构化对象。

错误设置 MCP isError=true，并返回 {ok:false,status,error,details?}。401 后通过 CLI 重新登录，下一次 MCP 调用会重新读取会话。403 表示权限不足；400/409 可能表示版本冲突，须重新读取再合并修改。

工具不会自动重试写请求。超时后先查询服务端对象、任务或审计状态。设置 CPQ_READ_ONLY=1 可限制此 MCP 进程执行已登记的读取、试算和预览。

资源目录

URI MIME 类型 内容
cpq://guide text/markdown 认证、发现、调用、文件与错误处理
cpq://interfaces text/markdown 两类界面的布局和组件约束
cpq://openapi application/json 与本网站下载一致的 OpenAPI 契约
cpq://operations/{operation} application/json 指定操作的输入契约和版本约束

工具参数参考

以下参数和说明直接从当前 MCP 服务的工具注册表生成。完整原始结构也可下载为 MCP JSON。

cpq_list_operations

检索全部 CPQ / SaaS 操作的 ID、HTTP 路径、说明和只读属性；支持分页。

参数类型 / 取值要求说明
searchstring可选默认：
offsetinteger可选默认：0
limitinteger可选默认：50
完整工具参数 Schema
{
  "properties": {
    "search": {
      "default": "",
      "title": "Search",
      "type": "string"
    },
    "offset": {
      "default": 0,
      "title": "Offset",
      "type": "integer"
    },
    "limit": {
      "default": 50,
      "title": "Limit",
      "type": "integer"
    }
  },
  "title": "cpq_list_operationsArguments",
  "type": "object"
}

cpq_describe_operation

返回操作的 inputSchema、必填参数及版本约束；调用前先读取。

参数类型 / 取值要求说明
operationstring必需—
完整工具参数 Schema
{
  "properties": {
    "operation": {
      "title": "Operation",
      "type": "string"
    }
  },
  "required": [
    "operation"
  ],
  "title": "cpq_describe_operationArguments",
  "type": "object"
}

cpq_read

调用已登记的只读操作，包括配置试算和预览；写操作会被拒绝。

参数类型 / 取值要求说明
operationstring必需—
pathobject / null可选默认：None
queryobject / null可选默认：None
bodyobject / null可选默认：None
完整工具参数 Schema
{
  "properties": {
    "operation": {
      "title": "Operation",
      "type": "string"
    },
    "path": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Path"
    },
    "query": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Query"
    },
    "body": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Body"
    }
  },
  "required": [
    "operation"
  ],
  "title": "cpq_readArguments",
  "type": "object"
}

cpq_call

执行目录中任意业务操作。保存、发布、审批、发信、停用等立即执行；写入不自动重试。

参数类型 / 取值要求说明
operationstring必需—
pathobject / null可选默认：None
queryobject / null可选默认：None
bodyobject / null可选默认：None
headersobject / null可选默认：None
完整工具参数 Schema
{
  "properties": {
    "operation": {
      "title": "Operation",
      "type": "string"
    },
    "path": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Path"
    },
    "query": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Query"
    },
    "body": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Body"
    },
    "headers": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Headers"
    }
  },
  "required": [
    "operation"
  ],
  "title": "cpq_callArguments",
  "type": "object"
}

cpq_request

通用同源 /api/ 请求，覆盖新增接口；保留 HTTP 错误，下载返回 MIME 与 base64。

参数类型 / 取值要求说明
methodstring · GET / POST必需—
pathstring必需—
bodyobject / null可选默认：None
queryobject / null可选默认：None
headersobject / null可选默认：None
完整工具参数 Schema
{
  "properties": {
    "method": {
      "enum": [
        "GET",
        "POST"
      ],
      "title": "Method",
      "type": "string"
    },
    "path": {
      "title": "Path",
      "type": "string"
    },
    "body": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Body"
    },
    "query": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Query"
    },
    "headers": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Headers"
    }
  },
  "required": [
    "method",
    "path"
  ],
  "title": "cpq_requestArguments",
  "type": "object"
}

cpq_ui_get

读取配置页或报价页完整定义、草稿版本及参考对象。编辑后保留其他对象。

参数类型 / 取值要求说明
surfacestring · configuration / quote必需—
完整工具参数 Schema
{
  "properties": {
    "surface": {
      "enum": [
        "configuration",
        "quote"
      ],
      "title": "Surface",
      "type": "string"
    }
  },
  "required": [
    "surface"
  ],
  "title": "cpq_ui_getArguments",
  "type": "object"
}

cpq_ui_save

保存界面草稿：configuration 用 {version,catalog}，quote 用 {version,data}。不发布。

参数类型 / 取值要求说明
surfacestring · configuration / quote必需—
bodyobject必需—
完整工具参数 Schema
{
  "properties": {
    "surface": {
      "enum": [
        "configuration",
        "quote"
      ],
      "title": "Surface",
      "type": "string"
    },
    "body": {
      "additionalProperties": true,
      "title": "Body",
      "type": "object"
    }
  },
  "required": [
    "surface",
    "body"
  ],
  "title": "cpq_ui_saveArguments",
  "type": "object"
}

cpq_ui_preview

配置页用 {catalog,modelId,...选配输入}；报价页用 {data,quoteId,userId,...}。返回真实业务预览。

参数类型 / 取值要求说明
surfacestring · configuration / quote必需—
bodyobject必需—
完整工具参数 Schema
{
  "properties": {
    "surface": {
      "enum": [
        "configuration",
        "quote"
      ],
      "title": "Surface",
      "type": "string"
    },
    "body": {
      "additionalProperties": true,
      "title": "Body",
      "type": "object"
    }
  },
  "required": [
    "surface",
    "body"
  ],
  "title": "cpq_ui_previewArguments",
  "type": "object"
}

cpq_ui_publish

显式发布界面定义。使用最近一次保存返回的版本；configuration 发布完整目录。

参数类型 / 取值要求说明
surfacestring · configuration / quote必需—
bodyobject必需—
完整工具参数 Schema
{
  "properties": {
    "surface": {
      "enum": [
        "configuration",
        "quote"
      ],
      "title": "Surface",
      "type": "string"
    },
    "body": {
      "additionalProperties": true,
      "title": "Body",
      "type": "object"
    }
  },
  "required": [
    "surface",
    "body"
  ],
  "title": "cpq_ui_publishArguments",
  "type": "object"
}