Logistics

Servidor de Model Context Protocol (MCP) diseñado para transformar una base de datos logística en un activo estratégico. Este servidor permite que agentes de IA (como VS Code Cline o Claude Desktop) realicen consultas analíticas, detecten cuellos de botella y generen predicciones de demanda directamente sobre PostgreSQL.

Arquitectura del Proyecto

El proyecto sigue los principios de Clean Architecture, asegurando que la lógica de negocio sea independiente de los detalles técnicos.

• model: Modelos de datos puros utilizando SQLAlchemy 2.0 (Declarative Mapping).
• application: Servicios de orquestación, lógica de analítica y cálculos predictivos (Regresiones, promedios históricos).
• infrastructure: Gestión de persistencia con SQLAlchemy Async Engine y pooling de conexiones mediante asyncpg.
• main.py: Adaptador de entrada que implementa el protocolo MCP y expone las herramientas al agente.

Stack Tecnológico

• Lenguaje: Python 3.10+
• Protocolo: MCP (Model Context Protocol)
• Base de Datos: PostgreSQL
• ORM: SQLAlchemy 2.0 (Async)
• Driver DB: asyncpg
• Analítica: SQL Estadístico (REGR_SLOPE, AVG, CASE)

Creación tabla en Base de Datos

Se puede encontrar el script de la tabla shipments en el directorio scripts en la raíz del proyecto, y dentro el archivo shipments.sql, para crear la tabla bastará con abrir una ventana de query dando clic derecho sobre la base de datos y dar clic en la opción Query Tool, luego copiar las instrucciones del script y ejecutar

Datos de prueba

Se puede encontrar un set de datos utilizados para las pruebas en el directorio data en la raíz del proyecto, y dentro el archivo envios_logistica_prueba.csv, para importarlo bastará con seleccionar la tabla en pgAdmin, clic derecho y dar clic en la opción Import/Export Data

Herramientas disponibles

• get_shipment_info: Obtiene detalles de un envío específico por su ID de rastreo.
• analyze_logistics_health: Obtiene estadísticas de paquetes retrasados y volumen total.
• get_route_efficiency: Analiza qué rutas o ciudades tienen mayores retrasos promedio.
• get_operational_bottlenecks: Identifica puntos críticos en la cadena de suministro y da recomendaciones.
• get_volume_trends: Muestra la tendencia de carga de los últimos 14 días para predicción de demanda.
• predict_delivery_delay: Predice si un paquete sufrirá retrasos basándose en el histórico de la ruta.
• forecast_workload: Predice la carga de trabajo y necesidad de personal para los próximos N días.

Environment

• DB_HOST: Host del servidor de base de datos, o del contenedor en Docker, por ejemplo: postgresql
• DB_PORT: Puerto del servidor de base de datos, para PostgreSQL el puerto por defecto es 5432
• DB_NAME: Nombre de la base de datos
• DB_USER: Usuario del servidor de base de datos
• DB_PASSWORD: Contraseña del usuario del servidor de base de datos

Instalar dependencias

pip install -r requirements.txt

Configuración de MCP en VSCode

En VSCode ir a View -> Command Palette -> MCP: Open User Configuration y modificar el archivo JSON mcp.json, agregando el nuevo servidor MCP:

{
	"servers": {
		"logistics-server": {
		"command": "python",
		"args": ["/Users/Yeisson/Desktop/logistics_mcp/main.py"]
		}
	}
}

En args se colocará la ruta absoluta hacia el archivo python del proyecto, una vez guardado VSCode lo reconocerá:

Además de que al visualizar las herramientas disponibles por el agente se visualizará la que se acaba de agregar:

Ejemplo de Uso

¿Cómo va la operación hoy? ¿Hay muchos retrasos?

Dame más detalles de los envios de Barranquilla

¿Deberíamos contratar más transportistas para la ruta de Bogotá?

Analiza todos los paquetes que salieron hoy de la bodega Medellín. ¿Cuáles tienen más del 80% de probabilidad de llegar tarde?

¿Cuándo se estima que llegará el paquete TRK20260005?