Skip to main content
Glama
Sign In
deenesjakoruzh
Load Planner MCP

Load Planner MCP

by bayraak
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

load-planner-mcp

CI

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

このリポジトリの内容

パス

内容

load_planner/geometry.py

3Dビンパッキング（py3dbp）: パレットが20GP/40GP/40HCに収まるかどうか、および充填率

load_planner/solver.py

OR-Tools CP-SATによる固定費MILP: 列挙されたモードパターンごとの最安実行可能割当

load_planner/risk.py

遅延分布の畳み込み: p50/p90 ETA、納期超過確率、CVaR(alpha)

load_planner/scenarios.py

カードを列挙し、それらを同一のベクトルでスコアリングし、ランク付けして推奨を選択する

load_planner/cli.py

importではなく子プロセスを好むホスト向けの、素のstdin/stdout JSON境界

solver_mcp/server.py

MCP stdioサーバー: JSON-RPC 2.0、2つのツール、verify_narration()

fixtures/cohort_urgent.json

テストで使用する、合成レートカード付きの合成20パレットコホート

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 は、ナレーション内のすべての数値が結果に現れることを検査します。数値が正しい意味で使用されているかどうかは検査しません。

Available Tools

2 tools
explainNarrate a stored solver resultA

Return a narration template populated only from a stored solver result. Takes a result_id and nothing else: it has no access to the problem inputs and performs no arithmetic, so it cannot state a number the solver did not produce.

NameRequiredDescriptionDefault
result_idYesA result_id returned by solve.

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the transparency burden. It explicitly discloses key behavioral constraints: no access to problem inputs, no arithmetic, and inability to state numbers the solver did not produce. It does not cover failure modes or detailed return structure, but the core limitation is clearly communicated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the primary action and followed by a concise constraint. Every sentence earns its place, and there is no repetition of schema fields or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with no output schema, the description explains the input source, what the tool returns, and its limitations. It could specify the narration template's structure, but the tool's simplicity and clear boundaries make it adequately complete for selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single parameter is already described as 'A result_id returned by solve.' The description adds value by emphasizing that it takes 'a result_id and nothing else' and by clarifying the tool's isolation from problem inputs, reinforcing the parameter's purpose beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Return a narration template populated only from a stored solver result,' which is a specific verb and object. It clearly distinguishes this tool from the sibling solve by emphasizing that it consumes a stored result rather than producing one.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use after solve by stating it takes a result_id and nothing else, and the schema's parameter description says the result_id is 'returned by solve.' It also provides a clear exclusion: it has no access to problem inputs and performs no arithmetic, so it should not be used to derive or verify numbers.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

solveSolve a load planA

Run the CP-SAT load-planning solver on a problem and return its numeric result verbatim, with a result_id and a content hash. This is the only tool that produces numbers.

NameRequiredDescriptionDefault
problemYesThe load-planning problem.

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses that it runs a solver and returns the numeric result verbatim with result_id and content hash, which is useful. However, it does not mention side effects, performance implications, error behavior, or prerequisites, leaving a moderate gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the action, and contains no redundant or irrelevant information. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich schema for the input and no output schema, the description adequately describes the output format (numeric result, result_id, content hash) and provides context (only numeric tool). However, it omits details like failure handling or solver constraints, which could be important. Overall it is fairly complete for a simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the schema itself defines the problem structure thoroughly. The tool description adds no specific parameter guidance beyond 'run on a problem', so it meets the baseline of 3 but does not elevate it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (run the CP-SAT load-planning solver) and resource (a problem), and specifically notes 'This is the only tool that produces numbers', which differentiates it from the sibling 'explain'. This meets the standard of a specific verb+resource that distinguishes from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides clear guidance on when to use this tool (when numeric results are needed) by stating it is the only tool that produces numbers. However, it does not explicitly mention when not to use it or alternative usage scenarios beyond that differentiation, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedexplain
    • First observedsolve
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored across 2 tools

Disambiguation5/5

solve and explain have clearly separated responsibilities: solve is the only numeric-producing tool, while explain only consumes a stored result_id and never touches inputs or arithmetic. There is no overlap or plausible misselection.

Naming Consistency5/5

Both tool names are bare imperative verbs following the same style: solve and explain. Although the pattern is not verb_noun, it is entirely consistent across the server.

Tool Count3/5

With only two tools, the server is minimal and borderline thin. Each tool has a distinct role, but the surface feels light for a load-planning MCP.

Completeness4/5

The core solve-then-explain workflow is covered, and solve returns a result_id for later explanation. Gaps appear around stored result management, such as listing or retrieving prior results independently.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • @kubova/mcp

    @kubova/mcpofficial

    Kubova-com
    A
    license
    A
    quality
    D
    maintenance
    Lets AI agents pack shipping containers using the Kubova calculator, with tools for container loading and API key verification.
    4
    15 npm
    MIT

  • freight-pulse

    Baneado98
    A
    license
    A
    quality
    D
    maintenance
    Ocean and multimodal freight intelligence suite providing cross-validated rates, total landed cost, transit reliability, customs, risk, emissions, and unified ship decisions through 47 tools.
    47
    10 npm
    MIT

  • hansatic-mcp

    1aleksa
    A
    license
    A
    quality
    D
    maintenance
    Enables AI agents to pack trucks and shipping containers by generating validated 3D load plans with metrics like LDM, linear feet, and pallet positions through the Hansatic packing API.
    3
    7 npm
    MIT

  • logistics-mcp

    Azzaraell
    A
    license
    A
    quality
    B
    maintenance
    Enables AI assistants to query and manage logistics shipment data, supporting operations like tracking, quoting, and performance analysis via nine tools backed by a demo dataset or a REST API.
    9
    253 npm
    MIT