load-planner-mcp

Un solucionador determinista de planificación de carga, más un servidor MCP stdio que lo expone como dos herramientas. El solucionador decide el modo de transporte para un conjunto de pedidos — todo por aire, mar consolidado (LCL) o contenedor completo —, calcula el precio de cada opción y adjunta una lectura de riesgo (percentiles de ETA, probabilidad de incumplir el plazo, CVaR de la cola de retraso).

Qué contiene

Los dos subproblemas están en capas en lugar de fusionados. Resolver la colocación 3D real dentro del MILP explota combinatoriamente, por lo que el empaquetador se ejecuta primero y entrega a CP-SAT una tasa de llenado y un indicador de viabilidad.

Related MCP server: freight-pulse

El contrato de dos herramientas

solve(problem) ejecuta el solucionador y devuelve su salida tal cual — sin reformatear, sin redondear, sin resumir — junto con un result_id y un content_hash SHA-256 del resultado. El resultado se guarda en un almacén dentro del proceso.

explain(result_id) devuelve una narración construida a partir de una plantilla fija cuyos espacios se rellenan con ese resultado almacenado.

La división es el diseño. Un modelo de lenguaje que llama a este servidor elige qué resolver y pone la respuesta en palabras; no origina ninguna cifra. Tres propiedades hacen que esto sea estructural en lugar de aspiracional:

1. explain toma un único id opaco y nada más. Su esquema de entrada tiene una única propiedad. No se le puede pasar una tarifa, un peso o un plazo, por lo que no puede repetir uno.

2. El registro almacenado contiene solo el resultado del solucionador. solve descarta la carga del problema una vez que el solucionador ha terminado. No hay ningún campo en el registro almacenado que pueda contener un valor de entrada.

3. No hay aritmética en la ruta de explain. Los valores se buscan por clave y se representan como cadenas. Seleccionar la tarjeta recomendada lee un indicador que el solucionador ya estableció; no compara ni calcula.

verify_narration(narration, stored) convierte la afirmación en una comprobación. Escanea el texto en busca de secuencias de dígitos y rechaza cualquier token que no esté en el resultado almacenado, por lo que una narración que redondea 11480.0 a "11500", convierte 0.1246 a "12.46%" o suma dos costes almacenados falla — cada uno de esos es un número que el solucionador nunca produjo. Un host puede aplicarlo a cualquier narración antes de mostrarla, incluida una que el modelo escribió con sus propias palabras en lugar de una que explain devolvió. explain lo ejecuta sobre su propia salida antes de devolverla.

Lo que la protección permite deliberadamente, para que no se confunda con una afirmación más fuerte: los dígitos dentro de cadenas almacenadas y claves de diccionario cuentan como presentes, porque una narración puede citar esas cadenas textualmente. "ortools-cpsat+py3dbp" admite 3, y el nombre de campo eta_p90_days admite 90. Es una comprobación léxica de tokens numéricos, no una prueba de corrección semántica: una narración que asocia el número correcto a la etiqueta incorrecta sigue pasando.

Instalación

Python 3.10 o superior.

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

O instala el paquete en sí, que trae las dos dependencias de ejecución:

pip install -e .

ortools es el motor CP-SAT; py3dbp es el empaquetador 3D, con licencia MIT. El servidor MCP no añade nada más allá de la biblioteca estándar — la superficie del protocolo stdio es lo suficientemente pequeña como para implementarla directamente, lo que mantiene la lista de dependencias auditable.

Ejecución

El servidor habla JSON-RPC 2.0 delimitado por nuevas líneas en stdin/stdout:

python -m solver_mcp

El solucionador también se puede usar sin MCP, como biblioteca o como proceso hijo:

from load_planner import generate_scenarios
result = generate_scenarios(problem)

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

Conexión con un cliente MCP

Cualquier cliente que lance servidores stdio toma un comando y argumentos. Para un cliente que use la forma de configuración común mcpServers:

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

PYTHONPATH solo es necesario cuando el paquete no se ha instalado en el entorno del intérprete; después de pip install -e . el bloque env se puede eliminar.

El protocolo de inicio es el estándar: initialize, luego la notificación notifications/initialized, y después tools/list. El servidor informa la versión de protocolo 2025-06-18 y acepta 2025-03-26 y 2024-11-05, devolviendo la que el cliente haya solicitado si es una de esas.

Pruebas

python -m pytest tests/ -q

Tres suites: las pruebas propias del solucionador contra el fixture; el protocolo de inicio de MCP y ambas herramientas, ejercitadas en proceso y sobre un subproceso stdio real; y la suite de manipulación, que verifica que una narración que contenga un valor ausente del resultado almacenado sea rechazada.

Limitaciones

• Una sola máquina, un solo proceso. El almacén de resultados está en memoria y vive durante la vida del proceso del servidor. Un result_id de un proceso se resuelve en otro solo porque los ids están direccionados por contenido y el solucionador es determinista — volver a resolver el mismo problema reproduce el id. No hay almacén compartido, ni desalojo, ni límite en el número de resultados retenidos.

• Tiempos de ejecución del solucionador. CP-SAT se llama una vez por patrón de modo enumerado, como máximo tres veces por solve, en un modelo con una variable entera y dos restricciones; devuelve en milisegundos. El coste que escala es el empaquetador 3D, que coloca un artículo por palé — unos cientos de palés está bien, decenas de miles no. solve se ejecuta de forma síncrona y no tiene tiempo de espera interno, por lo que un host debería imponer el suyo propio.

• Solo asignación de pedido completo. Dividir un pedido entre dos modos (una política de base más suplemento) no está modelado; cada pedido se asigna por completo a un modo.

• Entradas de riesgo con semilla. Las distribuciones de retraso en risk.py son semillas publicadas de fiabilidad de transportistas, no mediciones de tu propio historial de rutas. Tienen la forma correcta y la precisión incorrecta hasta que un llamador las reemplace.

• La protección es léxica. Véase la nota anterior: verify_narration comprueba que cada número en una narración aparece en el resultado. No comprueba que el número se haya utilizado para significar lo correcto.