GJP ERP AI 销售开单 MCP

基于 AgentScope 2.0.5 的完整销售单 MCP 服务，服务名为 erp-billing。

AI 平台 / SaaS 对话页
  │ Authorization: Bearer <ERP JWT / OAuth2 token>
  ▼
ERP 开单 MCP
  ├─ McpIdentityResolver：解析身份与 billing scopes
  ├─ McpToolSetResolver：按 tenant/account/session 隔离会话
  ├─ BillingToolSet：资料追问、商品匹配、预览和提交
  └─ BillingApiPort
       └─ Adapter：固定 ERP URL + 按会话注入 Bearer

ERP URL 不是租户动态参数，由部署环境唯一配置：

ERP_BILLING_BASE_URL=https://test-ai.yuncyb.com/aicyberp-api

URL 不进入 InvocationContext 或 Tool Schema。生产环境由 MCP 客户端直接携带 ERP JWT / OAuth2 Bearer，服务端只从 payload 解析无凭据身份，并在调用 ERP API 时 按当前请求注入原 Bearer；账号、密码、验证码、Cookie 和 Token 都不进入模型可见 工具参数。

销售单流程

业务必填项：

• 客户

• 出库仓库

• 经手人

• 录单日期（YYYY-MM-DD）

• 商品明细

备注可选，最多 200 字。接口必填的 id=0 与 saveType 由工具内部管理：草稿 0、预收 1、正式 2。

MCP 发布十个工具：

实际调用接口：

GET  /product/page
GET  /customer/page
GET  /warehouse/page
GET  /staff/page
POST /sales/orders
GET  /sales/orders/page
GET  /sales/orders/{id}
PUT  /sales/orders/{id}
PUT  /sales/orders/{id}/void

只有 previewSalesOrder 返回 ready_to_submit=true 且 required_actions=["confirm_submit"]，用户明确确认当前预览，并且调用身份具有 billing:write 时，才允许提交。submitSalesOrder 还要求唯一 idempotency_key；当前实现提供会话内防重，生产多副本应接入共享幂等存储。

提示词只保留两个入口：ERP_BILLING_MCP_INSTRUCTIONS 由 MCP initialize 自动下发， ERP_BILLING_SYSTEM_PROMPT 供 AI 平台装配 Agent。两者职责不同，不需要对接方再 拼接第三份响应契约。

Related MCP server: SAP RFC MCP Server

开发

uv sync --extra dev
uv run pytest -q
uv run ruff check src tests

代码结构：

src/
├── erp_billing/  # 销售单领域、ToolSet、Port、Adapter、Prompt 和 MCP
└── gjp_common/   # 身份、固定端点、凭据、MCP、配置和日志

主要文档：

• 工具、API 与商品匹配

• 业务数据流

• AI 平台对接

• 部署说明

• 当前工具与提示词契约 ADR

• 历史云开单边界 ADR