load-planner-mcp

Детерминированный решатель задач планирования загрузки, а также MCP-сервер stdio, который предоставляет его в виде двух инструментов. Решатель определяет вид транспорта для группы заказов — полностью авиа, консолидированный морской LCL или полный контейнер, — рассчитывает стоимость каждого варианта и прилагает оценку риска (процентили ETA, вероятность срыва срока, CVaR хвоста задержки).

Что здесь находится

Две подзадачи выстроены слоями, а не объединены. Решение настоящего 3D-размещения внутри MILP комбинаторно взрывается, поэтому упаковщик запускается первым и передаёт CP-SAT коэффициент заполнения и флаг допустимости.

Related MCP server: freight-pulse

Контракт двух инструментов

solve(problem) запускает решатель и возвращает его вывод дословно — без переформатирования, округления или обобщения — вместе с result_id и SHA-256 content_hash результата. Результат хранится во внутрипроцессном хранилище.

explain(result_id) возвращает повествование, построенное по фиксированному шаблону, слоты которого заполняются из сохранённого результата.

Такое разделение — это и есть замысел. Языковая модель, вызывающая этот сервер, выбирает, что решать, и облекает ответ в слова; она не порождает ни одной цифры. Три свойства делают это структурным, а не декларативным:

1. explain принимает один непрозрачный идентификатор и ничего больше. Его входная схема имеет единственное свойство. Ему нельзя передать тариф, вес или срок, поэтому он не может их пересказать.

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 достаточно мала, чтобы реализовать её напрямую, что делает список зависимостей проверяемым.

Запуск

Сервер общается через построчно разделённый JSON-RPC 2.0 на stdin/stdout:

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

Три набора: собственные тесты решателя на фикстуре; рукопожатие MCP и оба инструмента, проверенные как в процессе, так и через реальный дочерний процесс stdio; и набор проверок на подделку, который утверждает, что повествование, содержащее значение, отсутствующее в сохранённом результате, отклоняется.

Ограничения

• Одна машина, один процесс. Хранилище результатов находится в памяти и живёт столько же, сколько процесс сервера. result_id из одного процесса разрешается в другом только потому, что идентификаторы адресуются по содержимому, а решатель детерминирован — повторное решение той же задачи воспроизводит идентификатор. Нет общего хранилища, нет вытеснения и нет ограничения на количество сохраняемых результатов.

• Время работы решателя. CP-SAT вызывается один раз на каждый перечисленный шаблон режима, максимум три раза за solve, на модели с одной целочисленной переменной и двумя ограничениями; он возвращается за миллисекунды. Затраты, которые масштабируются, — это 3D-упаковщик, размещающий один предмет на паллет — несколько сотен паллет — это нормально, десятки тысяч — нет. solve выполняется синхронно и не имеет внутреннего тайм-аута, поэтому хост должен установить свой собственный.

• Только назначение всего заказа. Разделение одного заказа на два режима (политика «база плюс пик») не моделируется; каждый заказ назначается целиком одному режиму.

• Заданные входные данные риска. Распределения задержек в risk.py — это опубликованные показатели надёжности перевозчиков, а не измерения из вашей собственной истории маршрутов. Они имеют правильную форму и неправильную точность, пока вызывающий код не заменит их.

• Защита лексическая. См. примечание выше: verify_narration проверяет, что каждое число в повествовании присутствует в результате. Он не проверяет, что число использовано для обозначения правильной вещи.