Supply Chain Decision Intelligence MCP

Un proyecto de investigación MCP local y determinista para el análisis de cadenas de suministro de hardware de alta fiabilidad. Demuestra cómo un LLM puede plantear preguntas sobre la cadena de suministro en lenguaje natural, mientras que las herramientas SQL/Python —no el modelo— son las dueñas de la respuesta cuantitativa.

El problema que este proyecto demuestra resolver: las decisiones de cadena de suministro y de escalada de fabricación (qué proveedor cualificar, si una pieza se agotará antes de que llegue el reaprovisionamiento, o si la opción de precio más bajo primero o de doble fuente merece el sobreprecio) requieren unir datos de proveedores, inventario, órdenes de compra y calidad, y ejecutar cálculos coherentes y auditables, no la mejor suposición de un LLM. Este proyecto muestra ese patrón de extremo a extremo sobre un conjunto de datos sintéticos: el LLM solo elige qué cálculo gobernado ejecutar y narra el resultado.

Solo datos sintéticos. Este repositorio no contiene datos reales de Zipline de proveedores, producción, demanda, clientes ni operaciones. Es una demostración metodológica inspirada en patrones públicos de problemas de cadena de suministro: rendimiento de proveedores, previsión de escalada, riesgo de escasez en MRP, concentración de fuentes, coste de aterrizaje, análisis de capacidad de flota, reposición médica y capacidad plurianual de suministro.

Por qué este diseño

flowchart LR
  Q["Natural-language research question"] --> L["LLM chooses a tool"]
  L --> M["MCP typed interface"]
  subgraph D["Deterministic analytics boundary"]
    M --> A["Governed SQL / Python"]
    A --> C["Checked-in synthetic CSVs"]
    A --> R["Structured result + trust block"]
  end
  R --> L2["LLM interprets the result"]

El modelo elige cuál cálculo gobernado invocar y explica el resultado. El modelo no reproduce de memoria los cálculos de MAPE, OTD, semanas de cobertura, cosmética, aterrizaje, expresión o capacidad.

Consultaa docs/ARCHITECTURE.md para la versión totalmente etiquetada de este diagrama (que distingue explícitamente la capa proprobabilística del LLM de la capa determinística gobernada), un mapa MCP completo de herramientas (los 13 herramientas -> los conjuntos de datos que lee cada una) y un flujo de decisión ejemplo. Vel docs/DATA_MODEL.md para el diagrama entidad-relación.

Related MCP server: Fabric MCP Agent

Superficie de herramientas

También hay un recurso MCP research://catalog, y los prompts supply_chain_investigation y supply_chain_question_generator.

Local primero: la ruta exacta que evitó fallos previos de configuración de MCP

Este proyecto usa intencionadamente una patrón de ejecución que ha resultado sólido en creaciones MCP locales anteriores:

• no se crea ningún archivo de base de datos durante el inicio

• no se distribuye .venv

• no se incluye .mcp.json

• cada ruta de se bases de datos deriva de server.pyvíafile`

• DuckDB crea vistas nuevas en memoria sobre los CSV del repositorio

• uv run --with ... hace que el lanzamiento de desarrollo/stdio sea independiente de los metadatos de instalación editable.

1. Verificación previa

cd <where-you-cloned-this-repo>
uv sync --extra dev
uv run python scripts/preflight.py

Espera ver PREFLIGHT PASSED.

2. Lanzar en MCP Inspector

./scripts/run_mcp_dev.sh

Acepta la instalación de dependencias si uv lo pide. MCP Inspector debería abrirse con 13 herramientas.

Primeras llamadas recomendadas:

1. supplier_scorecard con limit=5

2. forecast_accuracy

3. parts_at_risk con limit=10

4. dual_source_risk

5. compare_landed_costs

6. dock_capacity

7. stockout_reduction

8. capacity_ramp

9. projected_shortage_risk con horizon_weeks=8

10. quality_gate_risk

11. quality_rush_signal

12. quality_trend

3. Probar los análisis sin Claude

uv run python scripts/smoke_test.py

Aplicación web ejecutiva

Aplicación web local y estática que usa estas mismas herramientas: "Production Ramp Intelligence", con panoramas de preparación de rampa, riesgo de piezas críticas, concentración de productos y una vista de decisión de capacidad/cualificación, cada una conectada con la llamada de herramienta MCP que la respalda:

uv run python scripts/generate_executive_dataset.py
uv run python scripts/serve_executive_site.py

Luego abre http://127.0.0.1:8765/. Consulta docs/EXECUTIVE_APP.md para ver más.

Ejecutar las pruebas

uv sync --extra dev
uv run pytest -q

Esto ejecuta comprobaciones de integridad de datos, aserciones sobre el comportamiento de las herramientas, controles de contrato en tiempo de ejecución y la suite de regresión de seguridad/empaquetado/verificación JSON — ver docs/CODE_WALKTHROUGH.md ("Quemas: comprobar que cada archivo realmente prueba") para saber qué verifica.

4. Registrarte con Claude Code solo después de que inspector funcione

./scripts/register_claude.sh
claude

En Claude Code ejecuta /mcp. Deberías ver zipline-supply-chain conectado con 13 tools.

Luego usa un para ver cómo:

Actúa como analista de cadena de suministro. Empieza con list_research_questions. Usa solo las herramientas MCP zipline-supply-chain para las pruebas cuantitativas. Léame qué riesgos de proveedor/pieza son más relevantes para la rampa de fabricación, qué dicen los pr вых and computational limitations on the sample data. No inspecciones los CSV en crudo ni recalcules las métricas vosotros.

able resolver

Véase está separando dos cadenas de suministro entrelazadas:

Fabricación: rendimiento de proveedores, sesgo de título, escasez MRP, concentración por fuente única, coste de aterrizaje y capacidad plurianual.

Logística operativa: capacidad de la flota en el dock y reducción de roturas de stock médicas.

Esa separación está incorporada en las herramientas y en la disciplina de los prompts.

Ver DEMO_QUESTIONS.md y PROMPTS.md.

Documentation map

Arboltrento de archivos completo: docs/REPOSITORY_GUIDE.md.

What he does not claim

No es un ERP/MRP funcional, un optimizador de rutas, un sistema de calificación aeroespacial, una investigación causal no de resultados reales de una empresa. El objetivo es que el LLM mantiene fronteras analíticas gobadas tomado como apoyo de decisiones.

Integrity / reproducibility checks

Ejecuxe Integrity... + Field not recognized.>

El modelo relacional sintético garantiza: los hechos de recepción y calidad llevan claves válidas (part_id, supplier_id), las compuertas de calificación usan identificadores reales del maestro de proveedores, cada pedido de compra utiliza un mapeo válido pieza-proveedor y el inventario tiene exactamente una fila por pieza. Ver data/MANIFEST.json/DATASET_VERSION para la versión vigente del conjunto de datos.

Ejecutar antes del MCP (también cubierto por scripts/preflight.py):

uv run python scripts/audit_data_relationships.py
uv run python scripts/generate_synthetic_facts.py --check

El primero comprueba claves foráneas, relaciones compuestas, unicidad y anclas de referencia importantes (valores fijos que este conjunto de datos está diseñado para reproducir). El segundo regenera las tablas de hechos estocásticas/enriquecidas a partir de semillas fijas y datos maestros, y las compara byte a byte con las salidas incorporadas al repositorio.

El propio servidor no contiene aleatoriedad en tiempo de ejecución. Dados los CSV incluidos, los resultados de las herramientas son deterministas. Se trata de datos sintéticos de investigación reproducibles, no una afirmación de que las distribuciones sintéticas sean estadísticamente representativas de Zipline.

Escala del conjunto de datos

El demand.csv de 12 semanas es el caso exacto de rampa gobernada que respalda las anclas de referencia; annual_demand.csv añade 52 observaciones semanales deterministas para un análisis más largo de error móvil, expuesto a través de forecast_accuracy(series="annual_52w"), de modo que no cambia silenciosamente el ejemplo práctico de 12 semanas.

El universo sintético de piezas abarca 60 piezas distribuidas en 14 familias de productos, intencionadamente a escala de demostración: suficientes observaciones para clasificaciones significativas de inventario y oportunidades de aprovisionamiento, pero lo bastante pequeño para inspeccionarlo y explicarlo en vivo.