load-planner-mcp

Ein deterministischer Ladungsplanungs-Solver, plus ein MCP-stdio-Server, der ihn als zwei Werkzeuge bereitstellt. Der Solver entscheidet den Frachtmodus für eine Kohorte von Aufträgen – reine Luftfracht, konsolidierte See-LCL oder voller Container –, bepreist jede Option und fügt eine Risikoeinschätzung hinzu (ETA-Perzentile, Wahrscheinlichkeit der Fristverfehlung, CVaR des Verzögerungsendes).

Was ist hier enthalten

Die beiden Teilprobleme sind geschichtet statt zusammengeführt. Das Lösen echter 3D-Platzierung innerhalb des MILP explodiert kombinatorisch, daher läuft der Packer zuerst und übergibt CP-SAT einen Füllgrad und ein Machbarkeitsflag.

Related MCP server: freight-pulse

Der Zwei-Werkzeuge-Vertrag

solve(problem) führt den Solver aus und gibt seine Ausgabe unverändert zurück – nicht umformatiert, nicht gerundet, nicht zusammengefasst – zusammen mit einer result_id und einem SHA-256-content_hash des Ergebnisses. Das Ergebnis wird in einem prozessinternen Speicher gehalten.

explain(result_id) gibt eine Erzählung zurück, die aus einer festen Vorlage aufgebaut ist, deren Platzhalter aus diesem gespeicherten Ergebnis gefüllt werden.

Die Trennung ist das Design. Ein Sprachmodell, das diesen Server aufruft, wählt, was gelöst werden soll, und formuliert die Antwort in Worte; es erzeugt keine Zahl. Drei Eigenschaften machen das strukturell, nicht nur wünschenswert:

1. explain nimmt eine opake ID und sonst nichts. Sein Eingabeschema hat eine einzige Eigenschaft. Es kann keine Rate, kein Gewicht und keine Frist erhalten, also kann es keine wiederholen.

2. Der gespeicherte Datensatz enthält nur das Solver-Ergebnis. solve verwirft die Problem-Payload, sobald der Solver gelaufen ist. Es gibt kein Feld auf dem gespeicherten Datensatz, das einen Eingabewert tragen könnte.

3. Auf dem explain-Pfad gibt es keine Arithmetik. Werte werden per Schlüssel nachgeschlagen und als Text gerendert. Die Auswahl der empfohlenen Karte liest ein Flag, das der Solver bereits gesetzt hat; es vergleicht oder berechnet nicht.

verify_narration(narration, stored) macht aus der Behauptung eine Prüfung. Es durchsucht den Text nach Ziffernfolgen und lehnt jedes Token ab, das nicht im gespeicherten Ergebnis vorkommt. So schlägt eine Erzählung fehl, die 11480.0 auf „11500“ rundet, 0.1246 in „12.46%“ umwandelt oder zwei gespeicherte Kosten addiert – jede dieser Zahlen hat der Solver nie erzeugt. Ein Host kann es auf jede Erzählung anwenden, bevor sie angezeigt wird, auch auf eine, die das Modell in eigenen Worten geschrieben hat, statt auf eine, die explain zurückgegeben hat. explain führt es auf seiner eigenen Ausgabe aus, bevor es zurückgibt.

Was die Absicherung bewusst zulässt, damit sie nicht als stärkere Behauptung verstanden wird: Ziffern in gespeicherten Zeichenketten und Dict-Keys gelten als vorhanden, weil eine Erzählung diese Zeichenketten wörtlich zitieren kann. "ortools-cpsat+py3dbp" lässt 3 zu, und der Feldname eta_p90_days lässt 90 zu. Es ist eine lexikalische Prüfung auf numerische Token, kein Beweis semantischer Korrektheit: Eine Erzählung, die die richtige Zahl an das falsche Label hängt, besteht weiterhin.

Installation

Python 3.10 oder neuer.

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

Oder installieren Sie das Paket selbst, das die beiden Laufzeitabhängigkeiten zieht:

pip install -e .

ortools ist die CP-SAT-Engine; py3dbp ist der 3D-Packer, MIT-lizenziert. Der MCP-Server fügt nichts über die Standardbibliothek hinaus hinzu – die stdio-Protokolloberfläche ist klein genug, um sie direkt zu implementieren, was die Abhängigkeitsliste überprüfbar hält.

Ausführen

Der Server spricht zeilengetrenntes JSON-RPC 2.0 auf stdin/stdout:

python -m solver_mcp

Der Solver ist auch ohne MCP nutzbar, als Bibliothek oder als Kindprozess:

from load_planner import generate_scenarios
result = generate_scenarios(problem)

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

Einbindung in einen MCP-Client

Jeder Client, der stdio-Server startet, nimmt einen Befehl und Argumente entgegen. Für einen Client, der die übliche mcpServers-Konfigurationsform verwendet:

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

PYTHONPATH wird nur benötigt, wenn das Paket nicht in die Umgebung des Interpreters installiert wurde; nach pip install -e . kann der env-Block entfallen.

Der Handshake ist der Standard: initialize, dann die notifications/initialized-Benachrichtigung, dann tools/list. Der Server meldet Protokollversion 2025-06-18 und akzeptiert 2025-03-26 und 2024-11-05, wobei er diejenige zurückgibt, die der Client angefordert hat, wenn sie eine dieser ist.

Tests

python -m pytest tests/ -q

Drei Test-Suiten: die eigenen Tests des Solvers gegen die Fixture; der MCP-Handshake und beide Werkzeuge, in Prozess und über einen echten stdio-Subprozess getestet; und die Manipulations-Suite, die bestätigt, dass eine Erzählung, die einen Wert enthält, der nicht im gespeicherten Ergebnis vorkommt, abgelehnt wird.

Einschränkungen

• Einzelne Maschine, einzelner Prozess. Der Ergebnisspeicher ist im Speicher und lebt für die Lebensdauer des Serverprozesses. Eine result_id aus einem Prozess wird in einem anderen aufgelöst, weil IDs inhaltsadressiert sind und der Solver deterministisch ist – das erneute Lösen desselben Problems reproduziert die ID. Es gibt keinen gemeinsamen Speicher, keine Verdrängung und keine Begrenzung für die Anzahl aufbewahrter Ergebnisse.

• Solver-Laufzeiten. CP-SAT wird einmal pro aufgezähltem Modusmuster aufgerufen, höchstens dreimal pro solve, auf einem Modell mit einer ganzzahligen Variable und zwei Nebenbedingungen; es antwortet in Millisekunden. Die Kosten, die skalieren, sind der 3D-Packer, der ein Element pro Palette platziert – ein paar hundert Paletten sind in Ordnung, Zehntausende nicht. solve läuft synchron und hat kein internes Timeout, daher sollte ein Host ein eigenes setzen.

• Nur Zuordnung ganzer Aufträge. Die Aufteilung eines Auftrags auf zwei Modi (eine Basis-plus-Spitze-Politik) wird nicht modelliert; jeder Auftrag wird vollständig einem Modus zugeordnet.

• Gesetzte Risiko-Eingaben. Die Verzögerungsverteilungen in risk.py sind veröffentlichte Träger-Zuverlässigkeits-Seeds, keine Messungen aus Ihrer eigenen Streckenhistorie. Sie haben die richtige Form und die falsche Genauigkeit, bis ein Aufrufer sie ersetzt.

• Die Absicherung ist lexikalisch. Siehe die obige Anmerkung: verify_narration prüft, dass jede Zahl in einer Erzählung im Ergebnis vorkommt. Es prüft nicht, dass die Zahl verwendet wurde, um das Richtige zu bedeuten.