load-planner-mcp

A deterministic load-planning solver, plus an MCP stdio server that exposes it as two tools. The solver decides freight mode for a cohort of orders — all-air, consolidated sea-LCL, or full container — prices each option, and attaches a risk read (ETA percentiles, deadline-miss probability, CVaR of the delay tail).

What is in here

Path	Contents
load_planner/geometry.py	3D bin-packing (py3dbp): do the pallets fit a 20GP/40GP/40HC, and at what fill rate
load_planner/solver.py	Fixed-charge MILP over OR-Tools CP-SAT: cheapest feasible assignment per enumerated mode-pattern
load_planner/risk.py	Delay-distribution convolution: p50/p90 ETA, deadline-miss probability, CVaR(alpha)
load_planner/scenarios.py	Enumerates the cards, scores them on one identical vector, ranks them, picks a recommendation
load_planner/cli.py	A plain stdin/stdout JSON boundary, for hosts that prefer a child process to an import
solver_mcp/server.py	The MCP stdio server: JSON-RPC 2.0, two tools, and verify_narration()
fixtures/cohort_urgent.json	A synthetic 20-pallet cohort with a synthetic rate card, used by the tests

The two sub-problems are layered rather than merged. Solving true 3D placement inside the MILP explodes combinatorially, so the packer runs first and hands CP-SAT a fill rate and a feasibility flag.

The two-tool contract

solve(problem) runs the solver and returns its output verbatim — not reformatted, not rounded, not summarised — together with a result_id and a SHA-256 content_hash of the result. The result is kept in an in-process store.

explain(result_id) returns a narration built from a fixed template whose slots are filled from that stored result.

The split is the design. A language model calling this server chooses what to solve and puts the answer into words; it does not originate any figure. Three properties make that structural rather than aspirational:

1. explain takes one opaque id and nothing else. Its input schema has a single property. It cannot be handed a rate, a weight or a deadline, so it cannot restate one.
2. The stored record holds the solver result only. solve discards the problem payload once the solver has run. There is no field on the stored record that could carry an input value.
3. There is no arithmetic on the explain path. Values are looked up by key and rendered as strings. Selecting the recommended card reads a flag the solver already set; it does not compare or compute.

verify_narration(narration, stored) turns the claim into a check. It scans the text for digit runs and rejects any token absent from the stored result, so a narration that rounds 11480.0 to "11500", converts 0.1246 to "12.46%", or adds two stored costs together fails — each of those is a number the solver never produced. A host can apply it to any narration before display, including one the model wrote in its own words rather than one explain returned. explain runs it on its own output before returning.

What the guard deliberately allows, so it is not mistaken for a stronger claim: digits inside stored strings and dict keys count as present, because a narration may quote those strings verbatim. "ortools-cpsat+py3dbp" admits 3, and the field name eta_p90_days admits 90. It is a lexical check on numeric tokens, not a proof of semantic correctness: a narration that attaches the right number to the wrong label still passes.

Install

Python 3.10 or newer.

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

Or install the package itself, which pulls the two runtime dependencies:

pip install -e .

ortools is the CP-SAT engine; py3dbp is the 3D packer, MIT-licensed. The MCP server adds nothing beyond the standard library — the stdio protocol surface is small enough to implement directly, which keeps the dependency list auditable.

Run

The server speaks newline-delimited JSON-RPC 2.0 on stdin/stdout:

python -m solver_mcp

The solver is also usable without MCP, as a library or as a child process:

from load_planner import generate_scenarios
result = generate_scenarios(problem)

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

Wiring into an MCP client

Any client that launches stdio servers takes a command and arguments. For a client using the common mcpServers configuration shape:

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

PYTHONPATH is only needed when the package has not been installed into the interpreter's environment; after pip install -e . the env block can go.

The handshake is the standard one: initialize, then the notifications/initialized notification, then tools/list. The server reports protocol version 2025-06-18 and accepts 2025-03-26 and 2024-11-05, echoing back whichever the client asked for if it is one of those.

Tests

python -m pytest tests/ -q

Three suites: the solver's own tests against the fixture; the MCP handshake and both tools, exercised in process and over a real stdio subprocess; and the tamper suite, which asserts that a narration containing a value absent from the stored result is rejected.

Limits

• Single machine, single process. The result store is in memory and lives for the life of the server process. A result_id from one process resolves in another only because ids are content-addressed and the solver is deterministic — re-solving the same problem reproduces the id. There is no shared store, no eviction, and no bound on the number of retained results.
• Solver runtimes. CP-SAT is called once per enumerated mode-pattern, at most three times per solve, on a model with one integer variable and two constraints; it returns in milliseconds. The cost that scales is the 3D packer, which places one item per pallet — a few hundred pallets is fine, tens of thousands is not. solve runs synchronously and has no internal timeout, so a host should impose its own.
• Whole-order assignment only. Splitting one order across two modes (a base-plus-surge policy) is not modelled; each order is assigned entirely to one mode.
• Seeded risk inputs. The delay distributions in risk.py are published carrier-reliability seeds, not measurements from your own lane history. They are the right shape and the wrong precision until a caller replaces them.
• The guard is lexical. See the note above: verify_narration checks that every number in a narration appears in the result. It does not check that the number was used to mean the right thing.