dongsk/mcp-server-demo

Fork 0

Files

T

dongsk 71c3d86ccf 初始提交：MCP Server Demo（ERP/CRM/Bexell 三模组，动态 Bearer Token 鉴权）

2026-09-02 17:08:10 +08:00

14 KiB

Raw Blame History

MCP for ERP — 工具说明文档

服务对象：汽车零部件（小型阀体外壳）智能报价智能体服务定位：ERP 侧核价基础数据与成本计算引擎（只读 + 计算，不写库）版本：v1.1（2026-08-09）

1 服务概览

项	值
服务名	`mcp-for-erp-auto`
框架	MCPServer（mcp 2.0.0 内置高级框架），`@app.tool()` 装饰器注册
传输协议	Streamable HTTP（JSON-RPC 2.0）
远程端点	`https://erp-data.dongsk.top/mcp`
本地端点	`http://0.0.0.0:8001/mcp`（`cd src && python3 server.py`）
数据库	PostgreSQL 15+，库 `smart_quotation_auto`（仅服务层内部经 `db.py` 连接池访问）
工具数	5 个（全部只读/计算）

工具一览

#	工具	功能	报价环节
1	`query_material_master`	查询物料主数据（体积/密度/吨位/后处理）	基础数据
2	`match_material_grade`	客户牌号 → 内部等效牌号对照	材质确认
3	`get_die_casting_params`	压铸参数：铝水重量、节拍、铸造成本	压铸成本
4	`get_machining_estimate`	机加工工时估算（固化工装节拍）	机加工成本
5	`calculate_part_cost`	汇总核价，输出最终单价	最终报价

2 调用约定

2.1 客户端注册（mcpServers）

{
  "mcpServers": {
    "erp": { "url": "https://erp-data.dongsk.top/mcp" }
  }
}

2.2 JSON-RPC 调用流程

initialize（握手，获取 Mcp-Session-Id）
notifications/initialized（通知，无响应体）
tools/list（可选，列出工具）
tools/call（调用工具，params: {name, arguments}）

2.3 兜底命令行客户端（纯标准库）

python3 scripts/mcp_http_client.py erp <工具名> '<JSON参数>'
# 示例
python3 scripts/mcp_http_client.py erp calculate_part_cost '{"material_code":"VHB-AT-001","annual_qty":300000}'

2.4 返回通用约定

所有工具返回 JSON 字符串（ensure_ascii=False，中文不转义）。
查询类工具返回 {"total": N, "<集合名>": [...]}；操作/计算类工具返回 {"success": true|false, ...}。
失败统一形态：{"success": false, "message": "<原因>"}（查询类失败以 total: 0 空集表达）。
金额/重量：浮点数，成本保留 2 位小数，重量保留 3 位小数；日期 YYYY-MM-DD，月份 YYYY-MM。

3 工具详解

3.1 query_material_master — 查询物料主数据

功能：按物料编码精确查询，或按零件类别、材质牌号、压铸吨位组合过滤。返回物料档案（含体积、密度、净重、吨位、表面处理），是核价的起点数据。

入参（全部可选；全部不传 = 返回全表）：

参数	类型	必填	默认	说明
`material_code`	string	否	—	物料编码，精确匹配，如 `VHB-AT-001`
`part_category`	string	否	—	零件类别，精确匹配，如 `阀体外壳`
`material_grade`	string	否	—	客户材质牌号，精确匹配，如 `ADC12`
`die_casting_ton`	int	否	—	压铸机吨位，精确匹配，如 `400`

返回字段：

字段	类型	说明
`total`	int	命中条数
`materials[]`	array	物料行列表
`materials[].material_code`	string	物料编码（内部主键）
`materials[].part_name`	string	零件名称
`materials[].part_category`	string	零件类别
`materials[].material_grade`	string	客户材质牌号
`materials[].density`	decimal	密度 g/cm³（JSON 中为字符串）
`materials[].volume_cc`	decimal	零件体积 cm³（算铝水重量的依据）
`materials[].net_weight_kg`	decimal	净重 kg（算后处理成本的依据）
`materials[].die_casting_ton`	int	压铸机吨位
`materials[].surface_treatment`	string	表面处理（阳极氧化/钝化/无等）
`materials[].unit`	string	计量单位
`materials[].created_at`	string	建档时间

返回示例：

{
  "total": 1,
  "materials": [
    {
      "material_code": "VHB-AT-001",
      "part_name": "变速箱阀体外壳",
      "part_category": "阀体外壳",
      "material_grade": "ADC12",
      "density": "2.700",
      "volume_cc": "444.44",
      "net_weight_kg": "1.200",
      "die_casting_ton": 400,
      "surface_treatment": "阳极氧化",
      "unit": "件",
      "created_at": "2026-08-07 12:18:51.484993"
    }
  ]
}

3.2 match_material_grade — 材质牌号对照

功能：把客户指定牌号（GB/ASTM/JIS/EN/ISO 任一体系或内部码）对照为企业内部等效牌号，返回密度与铝锭参考价。支持模糊匹配与热处理后缀自动剥离（如 A356-T6 → A356，最多剥 2 段）。

入参：

参数	类型	必填	默认	说明
`customer_grade`	string	是	—	客户牌号，大小写不敏感，模糊匹配六大码系
`standard`	string	否	—	标准体系提示（当前实现未参与过滤，保留参数）

返回字段（命中时）：

字段	类型	说明
`matched`	bool	是否命中
`customer_grade`	string	原客户牌号
`internal_code`	string	内部等效牌号，如 `AL-ADC12`
`density`	float	密度 g/cm³
`price_per_kg`	float	铝锭参考价 ¥/kg（兜底价，核价优先取月度价）
`all_mappings[]`	array	全部命中行（含 gb/astm/jis/en/iso/internal 六码、grade_group 材质族）

未命中返回：

{ "matched": false, "message": "未找到材质 AD12" }

返回示例（ADC12）：

{
  "matched": true,
  "customer_grade": "ADC12",
  "internal_code": "AL-ADC12",
  "density": 2.7,
  "price_per_kg": 18.5,
  "all_mappings": [
    {
      "grade_group": "铝合金",
      "gb_code": "ZAlSi10Cu(ADC12)",
      "astm_code": "A380",
      "jis_code": "ADC12",
      "en_code": "EN AC-4600",
      "iso_code": "AlSi9Cu3",
      "internal_code": "AL-ADC12",
      "density": "2.700",
      "price_per_kg": "18.50"
    }
  ]
}

业务规则：未命中时 Skill 层应回退默认铝价并产生 warning（TC-06 场景），不应中断报价。

3.3 get_die_casting_params — 获取压铸参数

功能：按物料编码取压铸参数。核心输出：铝水重量（体积×密度×1.05 损耗）、压铸机吨位、模次节拍、单件压铸成本。体现 MVP 原则「靠体积算铝水重量、压铸机吨位固定工时」。

入参：

参数	类型	必填	默认	说明
`material_code`	string	是	—	物料编码
`volume_cc`	float	否	物料档案体积	覆盖体积（图纸实测体积优先于档案默认值）

返回字段：

字段	类型	说明
`success`	bool	成功标记
`material_code`	string	物料编码
`volume_cc`	float	采用体积 cm³
`density`	float	密度 g/cm³
`aluminum_weight_kg`	float	铝水重量 = 体积×密度/1000×1.05，3 位小数
`die_casting_ton`	int	压铸机吨位
`cycle_time_sec`	float	模次节拍（秒/模，按吨位固化）
`machine_rate`	float	机台费率 ¥/小时
`mold_cavities`	int	模穴数
`casting_cost_per_part`	float	单件压铸成本 = (节拍/3600)×费率/模穴数，2 位小数

失败返回：{"success": false, "message": "未找到物料 XXX"} 或 {"success": false, "message": "未找到 400T 压铸机参数"}

返回示例（VHB-AT-001，444.44cc，400T）：

{
  "success": true,
  "material_code": "VHB-AT-001",
  "volume_cc": 444.44,
  "density": 2.7,
  "aluminum_weight_kg": 1.26,
  "die_casting_ton": 400,
  "cycle_time_sec": 30.0,
  "machine_rate": 260.0,
  "mold_cavities": 1,
  "casting_cost_per_part": 2.17
}

3.4 get_machining_estimate — 机加工工时估算

功能：按孔清单（钻孔/攻丝/铰孔）与铣面数量估算机加工总工时与刀具成本。所有规格节拍来自固化表 machining_cycle（工装节拍），逐项累加。

入参：

参数	类型	必填	默认	说明
`material_code`	string	是	—	物料编码（回显用）
`drill_holes`	array[object]	否	[]	钻孔清单，元素 `{"spec": "Φ6", "count": 2}`
`tap_holes`	array[object]	否	[]	攻丝清单，元素 `{"spec": "M6×1.0", "count": 2}`
`ream_holes`	array[object]	否	[]	铰孔清单，元素 `{"spec": "Φ8H7", "count": 1}`
`mill_faces`	int	否	0	铣面数量

孔元素字段：spec（规格字符串，缺省 Φ8 / M8×1.25 / Φ8H7）、count（数量，缺省 1）。

返回字段：

字段	类型	说明
`success`	bool	成功标记
`material_code`	string	物料编码
`total_time_sec`	float	总工时（秒），2 位小数
`total_time_hours`	float	总工时（小时），4 位小数
`total_tool_cost`	float	刀具成本合计 ¥
`details[]`	array	逐项明细：`operation`（drill/tap/ream/mill）、`spec`、`count`、`total_time_sec`

返回示例（钻 Φ6×2 + 攻 M6×1.0×2 + 铣面×1）：

{
  "success": true,
  "material_code": "VHB-AT-001",
  "total_time_sec": 26.0,
  "total_time_hours": 0.0072,
  "total_tool_cost": 1.5,
  "details": [
    { "operation": "drill", "spec": "Φ6", "count": 2, "total_time_sec": 6.0 },
    { "operation": "tap", "spec": "M6×1.0", "count": 2, "total_time_sec": 8.0 },
    { "operation": "mill", "spec": "face", "count": 1, "total_time_sec": 12.0 }
  ]
}

注意：固化表中不存在的规格静默跳过（不计工时也不报错）；毛坯件（无孔无面）返回总工时 0，Skill 层应产生 warning（TC-07 场景）。

3.5 calculate_part_cost — 汇总核价（最终单价）

功能：一站式核价。材料成本（铝水重量×当月铝价）+ 压铸成本 + 机加工成本 + 后处理成本 → 小计 × (1+管理费率) × (1+利润率) = 最终单价。铝价优先取 material_price_history 最新月度价并留痕月份；机加工费率按材质族（铝合金 60 / 灰铁 75 / 球铁 80 ¥/h）取 machining_rate。

入参：

参数	类型	必填	默认	说明
`material_code`	string	是	—	物料编码
`annual_qty`	int	是	—	年用量（件/年）
`drill_holes`	array[object]	否	[]	同 3.4
`tap_holes`	array[object]	否	[]	同 3.4
`ream_holes`	array[object]	否	[]	同 3.4
`mill_faces`	int	否	0	铣面数量
`overhead_rate`	float	否	0.12	管理费率
`profit_rate`	float	否	0.15	利润率

返回字段：

字段	类型	说明
`success`	bool	成功标记
`material_code` / `part_name`	string	物料编码 / 零件名称
`cost_breakdown.material_cost`	float	材料成本 = 铝水重量×铝价
`cost_breakdown.aluminum_weight_kg`	float	铝水重量（含 1.05 损耗）
`cost_breakdown.aluminum_price_per_kg`	float	采用铝价 ¥/kg
`cost_breakdown.price_basis_month`	string	铝价月份 `YYYY-MM`（留痕；无月度价时为 null）
`cost_breakdown.internal_code`	string	内部牌号
`cost_breakdown.grade_group`	string	材质族（决定机加工费率）
`cost_breakdown.casting_cost`	float	单件压铸成本
`cost_breakdown.die_casting_ton`	int	压铸机吨位
`cost_breakdown.machining_cost`	float	机加工成本 = 工时×费率
`cost_breakdown.machining_hours`	float	机加工总工时（小时）
`cost_breakdown.machining_rate_per_hour`	float	机加工费率 ¥/h
`cost_breakdown.post_process_cost`	float	后处理成本 = 净重×工艺费率
`cost_breakdown.surface_treatment`	string	表面处理工艺
`total_cost`	float	四项成本小计
`overhead_rate` / `overhead`	float	管理费率 / 管理费额
`profit_rate`	float	利润率
`unit_price`	float	最终单价 = (total_cost+overhead)×(1+profit_rate)
`currency`	string	固定 `CNY`

返回示例（VHB-AT-001，30 万件/年，钻 Φ6×2/攻 M6×1.0×2/铰 Φ8H7×1/铣面×1）：

{
  "success": true,
  "material_code": "VHB-AT-001",
  "part_name": "变速箱阀体外壳",
  "cost_breakdown": {
    "material_cost": 23.31,
    "aluminum_weight_kg": 1.26,
    "aluminum_price_per_kg": 18.5,
    "price_basis_month": "2026-08",
    "internal_code": "AL-ADC12",
    "grade_group": "铝合金",
    "casting_cost": 2.17,
    "die_casting_ton": 400,
    "machining_cost": 0.53,
    "machining_hours": 0.0089,
    "machining_rate_per_hour": 60.0,
    "post_process_cost": 6.0,
    "surface_treatment": "阳极氧化"
  },
  "total_cost": 32.01,
  "overhead_rate": 0.12,
  "overhead": 3.84,
  "profit_rate": 0.15,
  "unit_price": 41.23,
  "currency": "CNY"
}

失败返回：{"success": false, "message": "未找到物料 XXX"}

4 附录

4.1 核心公式

铝水重量(kg)   = 体积(cm³) × 密度(g/cm³) / 1000 × 1.05(损耗系数)
材料成本       = 铝水重量 × 铝锭单价(当月月度价，缺省 18.5)
压铸成本       = (节拍秒 / 3600) × 机台费率 / 模穴数          ← 吨位固化节拍
机加工成本     = Σ(工序固化节拍×数量) / 3600 × 材质族费率
后处理成本     = 净重(kg) × 表面处理费率
单价           = (四项成本小计 × (1+管理费率)) × (1+利润率)

4.2 依赖数据表

表	用途
`material_master`	物料主数据（体积/密度/吨位/后处理）
`material_grade_mapping`	五标准体系牌号对照 + 材质族 + 参考铝价
`material_price_history`	月度铝价留痕（核价取最新月）
`die_casting_params`	吨位 → 节拍/费率/模穴数
`machining_cycle`	工序规格固化节拍与刀具费率
`machining_rate`	材质族机加工费率（60/75/80 ¥/h）
`post_process_rate`	表面处理费率（¥/kg）

4.3 与 CRM 服务的协作

ERP 服务只读不写。报价存档链路（create_inquiry → save_quotation → update_opportunity）由 mcp-for-crm 承担，见《MCP for CRM — 工具说明文档》。

14 KiB Raw Blame History Unescape Escape

MCP for ERP — 工具说明文档

1 服务概览

工具一览

2 调用约定

2.1 客户端注册（mcpServers）

2.2 JSON-RPC 调用流程

2.3 兜底命令行客户端（纯标准库）

2.4 返回通用约定

3 工具详解

3.1 query_material_master — 查询物料主数据

3.2 match_material_grade — 材质牌号对照

3.3 get_die_casting_params — 获取压铸参数

3.4 get_machining_estimate — 机加工工时估算

3.5 calculate_part_cost — 汇总核价（最终单价）

4 附录

4.1 核心公式

4.2 依赖数据表

4.3 与 CRM 服务的协作

14 KiB

Raw Blame History