load-planner-mcp

一个确定性的装载规划求解器，外加一个将其暴露为两个工具的 MCP stdio 服务器。该求解器为一组订单决定运输方式——全空运、海运拼箱（LCL）或整箱——为每个选项定价，并附带风险评估（ETA 百分位数、错过截止日期的概率、延误尾部 CVaR）。

包含内容

这两个子问题采用分层而非合并的方式处理。在 MILP 内部求解真正的 3D 放置会导致组合爆炸，因此装箱器先运行，将装载率和可行性标志交给 CP-SAT。

Related MCP server: freight-pulse

双工具契约

solve(problem) 运行求解器并原样返回其输出——不重新格式化、不四舍五入、不汇总——同时附带一个 result_id 和结果的 SHA-256 content_hash。结果保存在进程内存储中。

explain(result_id) 返回基于固定模板构建的叙述，模板中的槽位由该存储结果填充。

这种拆分就是设计本身。调用此服务器的语言模型选择要解决的问题，并将答案组织成文字；它不产生任何数字。三个属性使这一点是结构性的而非一厢情愿：

1. explain 只接受一个不透明的 id，其他什么都不接受。 它的输入结构只有一个属性。它不可能被传入费率、重量或截止日期，因此也不可能复述这些值。

2. 存储记录只持有求解器结果。 求解器运行完毕后，solve 会丢弃问题负载。存储记录上没有任何字段能携带输入值。

3. explain 路径上没有算术运算。 值按键查找并渲染为字符串。选择推荐方案卡只是读取求解器已设置的标志；它不进行比较或计算。

verify_narration(narration, stored) 将这一声明变成一项检查。它扫描文本中的数字串，并拒绝任何不在存储结果中的词元，因此，将 11480.0 四舍五入为"11500"、将 0.1246 转换为"12.46%"或将两个存储成本相加的叙述都会失败——这些数字都不是求解器产生的。主机可以在显示前对任何叙述应用此检查，包括模型用自己的话写的、而非 explain 返回的叙述。explain 在返回前会对自己的输出运行该检查。

该防护刻意放行的内容（以免被误认为是更强的声明）：存储字符串和字典键中的数字被视为存在，因为叙述可能逐字引用这些字符串。"ortools-cpsat+py3dbp" 放行 3，字段名 eta_p90_days 放行 90。这是对数字词元的词法检查，而非语义正确性的证明：将正确数字附到错误标签上的叙述仍然通过。

安装

Python 3.10 或更新版本。

python -m venv .venv
./.venv/bin/pip install ortools py3dbp pytest

或者安装包本身，它会引入两个运行时依赖：

pip install -e .

ortools 是 CP-SAT 引擎；py3dbp 是 3D 装箱器，采用 MIT 许可证。MCP 服务器在标准库之外没有添加任何东西——stdio 协议面足够小，可以直接实现，从而让依赖列表保持可审计。

运行

服务器在 stdin/stdout 上使用换行分隔的 JSON-RPC 2.0：

python -m solver_mcp

求解器也可以在无 MCP 的情况下使用，既可以作为库，也可以作为子进程：

from load_planner import generate_scenarios
result = generate_scenarios(problem)

cat fixtures/cohort_urgent.json | python -m load_planner.cli

接入 MCP 客户端

任何启动 stdio 服务器的客户端都接受一个命令和参数。对于使用常见 mcpServers 配置形态的客户端：

{
  "mcpServers": {
    "load-planner": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "solver_mcp"],
      "env": { "PYTHONPATH": "/absolute/path/to/load-planner-mcp" }
    }
  }
}

只有当包尚未安装到解释器环境中时才需要 PYTHONPATH；执行 pip install -e . 之后，env 块就可以去掉了。

握手是标准的：先 initialize，然后发送 notifications/initialized 通知，再执行 tools/list。服务器报告协议版本 2025-06-18，并接受 2025-03-26 和 2024-11-05；如果客户端请求的是其中之一，服务器会回显该版本。

测试

python -m pytest tests/ -q

三个测试套件：求解器针对 fixture 的自身测试；MCP 握手和两个工具，在进程内以及真实 stdio 子进程上进行了测试；以及篡改套件，它断言包含存储结果中不存在值的叙述会被拒绝。

限制

• 单机、单进程。 结果存储位于内存中，生命周期与服务器进程相同。一个进程中的 result_id 能在另一个进程中解析出来，只是因为 id 是内容寻址的且求解器是确定性的——重新求解同一问题会重现相同的 id。没有共享存储、没有驱逐策略，也没有对保留结果数量的限制。

• 求解器运行时间。 CP-SAT 在每个枚举的模式组合上调用一次，每次 solve 最多三次，模型只有一个整数变量和两个约束；它在毫秒级返回。随规模增长的成本来自 3D 装箱器，它为每个托盘放置一个物品——几百个托盘没问题，几万个就不行了。solve 同步运行且没有内部超时，因此主机应自行设置超时。

• 仅支持整单分配。 将一个订单拆分到两种模式（基础加应急策略）不在模型范围内；每个订单被完整分配给一种模式。

• 种子风险输入。 risk.py 中的延误分布是已发布的承运商可靠性种子数据，而非来自您自己航线历史的测量值。在调用者替换它们之前，它们形态正确但精度不对。

• 防护是词法层面的。 参见上文说明：verify_narration 检查叙述中的每个数字是否都出现在结果中。它不检查该数字是否被用于表达正确的含义。