Import Sourcing Advisor

Un agente de datos específico de dominio para el análisis de aprovisionamiento de importaciones a nivel macro para Ucrania. Pregúntale de qué países debería obtenerse un grupo de productos, y procesa la pregunta a través de datos comerciales abiertos: qué orígenes lo suministran realmente, cuán concentrada está esa oferta, cuánto costaría cada candidato puesto en destino y cómo se clasifican los candidatos entre sí.

El agente se amplía mediante dos conexiones MCP:

Todo se ejecuta con datos públicos sin entradas confidenciales, y el servidor personalizado no necesita credenciales de API de ningún tipo.

Lo que se ve primero

Una lista de trabajo, no una caja de chat. Seis líneas de importación rastreadas, una fila cada una, ordenadas por banda de riesgo y luego por importe: proveedor principal, su participación, cuánto vale esa participación, cuántos orígenes efectivos hay detrás y un estado de una palabra. Abrir una fila expande su detalle de orígenes en el mismo lugar; la ejecución del agente es una acción deliberada a partir de ahí.

Sobre la lista, una franja de agregados. En la ventana actual: 554 millones de USD importados, 346 millones de ellos concentrados en un único origen por línea (62 %), y Türkiye liderando 3 de las 6 líneas: 183 millones de la exposición. Esa última cifra es la que ningún informe por producto puede mostrar: líneas que fallarían a la vez.

La lista se calcula, no se razona. web/portfolio.py abre una sesión MCP stdio con el mismo servidor personalizado que usa el agente y llama a las herramientas directamente, sin ningún modelo en el bucle. La primera pantalla que carga un visitante no debería esperar a un agente ni costar nada.

Moneda. La serie comercial anual se retrasa unos dos años, por lo que la lista se basa en una ventana móvil de doce meses construida a partir de informes mensuales, que termina en el mes que la fuente haya publicado realmente: actualmente Oct 2024 to Sep 2025, aproximadamente once meses por delante del último año anual completo. Eso no es cosmético: con los datos anuales de 2024, los tomates frescos mostraban un 71,8 % de origen turco y llevaban la marca de origen único; con la ventana muestran un 64,6 % y no la llevan.

Related MCP server: supply-chain-mcp-server

Requisitos previos

No se necesita ninguna clave, token ni cuenta para ninguna de las tres API de datos.

Instalación

git clone <repository-url> logistics_mcp
cd logistics_mcp

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt

Instala una vez el servidor de navegador y una compilación de Chromium (Node 18+ en el PATH):

npm install
npx -y playwright install chromium

npm install fija @playwright/mcp, y el agente lo inicia después como node node_modules/@playwright/mcp/cli.js. No pasa por npx: no hay ningún ejecutable llamado npx en Windows, y Node se niega a lanzar npx.cmd sin un shell, por lo que iniciar el servidor con ese nombre fallaba silenciosamente: la ejecución continuaba y el modelo informaba de que no tenía herramienta de navegador. Sin npm install, el agente recurre a npx -y @playwright/mcp@latest, que funciona donde un shell POSIX lo resuelve.

Configuración

cp .env.example .env

.env está ignorado por git. Nada de lo que contiene es necesario para el servidor MCP personalizado; los valores solo afectan al agente y al modo de transporte de datos.

Ejecutar las piezas de forma independiente

El servidor MCP personalizado es un proceso separado y se inicia por su cuenta. Nada de él depende del agente.

1. Servidor MCP personalizado

python -m mcp_server.server

Sirve MCP a través de stdio e imprime su transporte y modo de datos en stderr al arrancar. Para inspeccionar los contratos que publica sin ningún agente:

python scripts/inspect_tools.py           # summary of all five tool contracts
python scripts/inspect_tools.py --json    # full input and output JSON schemas

O condúcelo con el inspector oficial:

npx -y @modelcontextprotocol/inspector python -m mcp_server.server

2. Servidor MCP de Playwright

El agente lo lanza él mismo; ejecútalo manualmente solo para inspeccionarlo.

node node_modules/@playwright/mcp/cli.js --headless --isolated

3. Agente y aplicación web

python -m web.app          # serves http://127.0.0.1:8000

La aplicación web lanza ambas conexiones MCP como procesos hijo y muestra qué herramientas expuso cada una.

Verificar la instalación

python -m pytest tests -q        # 47 unit tests, no network, ~2s
python scripts/smoke_tools.py    # calls every tool end to end against the live APIs
REPLAY=1 python scripts/smoke_tools.py   # the same run, offline, from fixtures
python scripts/run_e2e.py        # the whole agent flow, both MCP servers, live
python scripts/run_failure_demo.py       # the same flow with the browser server broken

run_e2e.py es la comprobación en la que se apoya la demo. Hace fallar la ejecución a menos que ambos servidores se hayan conectado y que las cinco herramientas personalizadas se hayan llamado realmente: una ejecución en la que el servidor personalizado no llegó a arrancar sigue produciendo una respuesta fluida, porque el modelo simplemente informa de que no tiene herramientas. Cada evento se escribe en scripts/last_e2e_trace.jsonl para que la ejecución pueda inspeccionarse después en lugar de aceptarse sin más. Una ejecución completa dura aproximadamente 10 minutos, 20 turnos y unos $0.55. Un error de navegación en una URL de actualidad de respaldo se tolera una vez que otra página de la cadena ha cargado — la cadena está ordenada y el agente se detiene en la primera página que responde —, pero una cadena en la que no cargó nada, y cualquier error del servidor personalizado, siguen haciendo fallar la ejecución.

run_failure_demo.py es la otra mitad: apunta el navegador a un host irresoluble sin respaldos y solo pasa si la navegación se notifica como error, no falla nada más y aun así sale una recomendación con la comprobación fallida mencionada en ella. El requisito no es que nada falle, sino que un fallo sea distinguible de una respuesta vacía.

Modo sin conexión / reproducción

El servidor personalizado llama a tres API de red, por lo que las respuestas reales se registran en fixtures/ y pueden reproducirse sin acceso a la red:

# Offline
SOURCING_MODE=replay python -m mcp_server.server

# Re-record after changing a query
SOURCING_MODE=record python scripts/smoke_tools.py

La sustitución ocurre en el límite de transporte (mcp_server/sources/http.py): la reproducción devuelve el mismo JSON bruto que devolvió la red, y todos los analizadores, pasos de deduplicación y cálculos posteriores se ejecutan sin cambios. Ninguna ruta de código devuelve una respuesta preparada.

Cada fixture es un sobre que registra la URL exacta, la marca de tiempo de recuperación y el cuerpo de respuesta literal.

Lo que cubre el modo sin conexión. La cartera, la clasificación de cada producto tal como la muestra la pantalla de inicio, y el flujo del agente. Verificado ejecutando la clasificación de un producto en vivo y en reproducción y comparando cada campo: idénticos hasta el último decimal. Esa comprobación merece la pena conservarla: así se encontró el error de arancel mencionado más abajo, y antes de que se registraran los fixtures de clasificación, así se encontraron también las puntuaciones fuera de línea colapsadas.

Lo que no cubre. Solo se registra una ventana de referencia (Oct 2024 – Sep 2025), por lo que una solicitud de cualquier otra ventana móvil falla sin conexión en lugar de recurrir a un respaldo. Dos productos tienen un candidato que no puede valorarse en ninguno de los dos modos: USA y NLD para las almendras, y AZE para el kiwi, no notifican peso, por lo que no existe un valor unitario del que derivar. Esas filas se marcan como incompletas en pantalla y se mencionan en una advertencia; son una laguna de la fuente, no del registro.

Fuentes de datos

El comportamiento verificado de los endpoints, los límites de tasa y las peculiaridades están documentados en docs/01-data-sources-verified.md.

Estructura del repositorio

mcp_server/          Custom MCP server (separate process)
  server.py          Five tool registrations, stdio entry point
  models.py          Pydantic input/output contracts
  sources/           http (rate limit, cache, fixtures), comtrade, worldbank, wits, reference
  domain/            costing and analysis calculations
agent/               Claude Agent SDK wiring, two model tiers, trace events
web/                 FastAPI application, portfolio over MCP, single-page UI
  app.py             Endpoints: portfolio, commodity detail, agent run, chat
  portfolio.py       The tracked lines, queried over an MCP stdio session
  index.html         Portfolio screen, line detail, MCP trace, chat panel
data/reference/      Vendored HS2022 and country reference data
fixtures/            Recorded genuine API responses for replay mode
scripts/             inspect_tools, smoke_tools, run_e2e
tests/               Unit tests
docs/                Requirements digest, verified sources, contracts, rationale, demo script

Documentación

Limitaciones conocidas

Declaradas de antemano en lugar de enterradas:

• El costo de flete está modelado, no cotizado. Ninguna fuente abierta publica tarifas de flete. Cada cifra modelada está etiquetada como estimated en la salida de la herramienta.

• El arancel es la tasa NMF. WITS devuelve HTTP 404 para tasas preferenciales, por lo que acuerdos como el DCFTA de la UE se marcan como posibles pero no se aplican.

• La serie anual se retrasa unos dos años. En agosto de 2026, Ucrania había reportado 2024 pero no 2025. La serie mensual llega hasta septiembre de 2025, que es lo que utiliza la lista de trabajo. Las herramientas de costo aterrizado y clasificación aún se ejecutan sobre la base anual, y el arancel proviene nuevamente de una observación más antigua — cada resultado nombra la base que utilizó.

• Los valores unitarios no son precios. Un valor unitario de Comtrade es el valor total sobre el peso total, no una cotización.

• El Índice de Desempeño Logístico no es una serie anual. 2022 es la observación más reciente.

• La página de aduanas bloquea a los clientes automatizados. customs.gov.ua responde HTTP 403 en su borde Akamai a cualquier cosa que no sea un navegador humano, mientras que se abre normalmente para una persona. Por lo tanto, el paso de actualidad recurre a la página del sector externo del Banco Nacional, y el agente nombra qué página leyó realmente. Eso confirma la versión de la publicación pero no una cifra de facturación, por lo que la verificación de actualidad es parcial por diseño y no por accidente.

• La cartera es de seis líneas, elegidas por señal. Las manzanas (HS 080810, $0.5M) y las nueces con cáscara (HS 080231, cerca de cero) se eliminaron: Ucrania cultiva y exporta ambas, por lo que sus líneas de importación son ruido.

• Esta es una herramienta de selección. Reduce una lista de países que vale la pena investigar; no reemplaza una licitación.