load-planner-mcp

決定論的な積載計画ソルバーと、それを2つのツールとして公開するMCP stdioサーバーです。ソルバーは注文群の貨物モード（オールエアー、海上LCL混載、フルコンテナ）を決定し、各オプションの価格を算出して、リスク評価（ETAパーセンタイル、納期超過確率、遅延テールのCVaR）を付加します。

このリポジトリの内容

2つの部分問題は、マージされるのではなくレイヤー化されています。MILP内で真の3D配置を解くと組み合わせ爆発が起きるため、パッカーが先に実行され、充填率と実行可能性フラグがCP-SATに渡されます。

Related MCP server: freight-pulse

2つのツールの契約

solve(problem) はソルバーを実行し、その出力をそのまま（再フォーマットも丸めも要約もせずに）、result_id と結果のSHA-256 content_hash とともに返します。結果はプロセス内ストアに保持されます。

explain(result_id) は、保存された結果でスロットを埋めた固定テンプレートから生成したナレーションを返します。

この分割こそが設計です。このサーバーを呼び出す言語モデルは、解くものを選び、答えを言葉にします。数値を独自に生み出すことはありません。次の3つの性質が、これを理念ではなく構造的なものにしています。

1. explain は不透明なIDを1つだけ受け取る。 入力スキーマは単一プロパティのみです。レート、重量、納期を渡しようがないため、それらを言い直すこともできません。

2. 保存レコードはソルバー結果のみを保持する。 solve はソルバー実行後に問題ペイロードを破棄します。保存レコードには入力値を保持しうるフィールドがありません。

3. explain の経路には算術が存在しない。 値はキーで参照して文字列として描画します。推奨カードの選択はソルバーが既に設定したフラグを読むだけであり、比較も計算も行いません。

verify_narration(narration, stored) はこの主張を検査に変換します。テキストを走査して数字の連なりを探し、保存結果に存在しないトークンを拒否します。したがって、11480.0 を「11500」に丸めたり、0.1246 を「12.46%」に変換したり、保存された費用を2つ足し合わせたりするナレーションは失敗します——いずれもソルバーが生成したことのない数値だからです。ホストは表示前に任意のナレーションにこれを適用できます。explain が返したものではなく、モデルが独自の言葉で書いたナレーションでも構いません。explain は返却前に自身の出力にもこれを実行します。

ガードが意図的に許容するもの（より強い主張と誤解されないため）: 保存された文字列や辞書キーの中の数字は、存在するものとみなされます。ナレーションがそれらの文字列を逐語的に引用することがあり得るためです。"ortools-cpsat+py3dbp" は 3 を認め、フィールド名 eta_p90_days は 90 を認めます。これは数値トークンに対する語彙的な検査であり、意味的な正しさの証明ではありません。正しい数値を誤ったラベルに付けたナレーションも通過します。

インストール

Python 3.10以降。

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

または、パッケージ自体をインストールする方法もあります。この場合は2つの実行時依存関係が導入されます:

pip install -e .

ortools はCP-SATエンジン、py3dbp はMITライセンスの3Dパッカーです。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

3つのスイートがあります: フィクスチャに対するソルバー自身のテスト、MCPハンドシェイクと両ツールをプロセス内および実際のstdioサブプロセス越しに実行するテスト、そして保存結果に存在しない値を含むナレーションが拒否されることを検証する改ざんスイートです。

制限事項

• 単一マシン、単一プロセス。 結果ストアはインメモリで、サーバープロセスの生存期間と同じだけ存在します。あるプロセスの result_id が別のプロセスで解決できるのは、IDがコンテンツアドレス方式であり、ソルバーが決定論的であるからです——同じ問題を再解決すれば同じIDが再現されます。共有ストアも退避も、保持結果数の上限もありません。

• ソルバーの実行時間。 CP-SATは、列挙されたモードパターンごとに1回、solve ごとに最大3回、1つの整数変数と2つの制約を持つモデルに対して呼び出され、ミリ秒単位で結果を返します。スケールするコストは3Dパッカーで、これはアイテムを1つずつパレットに配置していきます——数百パレットなら問題ありませんが、数万パレットは対応できません。solve は同期的に実行され、内部タイムアウトを持たないため、ホスト側で独自のタイムアウトを設定すべきです。

• 注文全体への割当のみ。 1つの注文を2つのモードに分割する（ベース＋サージ方式）ことはモデル化されていません。各注文は完全に1つのモードに割り当てられます。

• シードされたリスク入力。 risk.py の遅延分布は、公開されたキャリア信頼性シードであり、自社のレーン履歴から得た測定値ではありません。呼び出し側が置き換えるまでは、形は正しいものの、精度は正しくありません。

• ガードは語彙的な検査です。 上記の注記を参照してください: verify_narration は、ナレーション内のすべての数値が結果に現れることを検査します。数値が正しい意味で使用されているかどうかは検査しません。