Supply Chain Decision Intelligence MCP

Локальный, детерминированный исследовательский проекта MCP для аналитики цепочек поставок в областях с высокими требованиями к надёжности. Он демонстрирует, как LLM может задавать вопросы по цепочке поставок на естественном языке, в то время как права количественного ответа принадлежит SQL/Python-инструментам, а не модели.

Демонстрируемая здесь проблема: решения по цепочке поставок и наращиванию производства (какого поставщика допустить к продукции, кончится ли деталь раньше, чем придёт пополнение; оправдана ли более дорогая стратегия «сначала самый дешёвый» или двухуровневое снабжение) требуют объединения данных о поставщиках, запасах, закупочных заказах и качестве и выполнения это непротиворечивых, проверяемых расчётов — а не «лучшего предположения» LLM. Данный проект показывает эту схему полностью на синтетическом наборе данных: LLM лишь выбирает, какой управляемый расчёт выполнить, и комментирует результат.

Только синтетические данные. Этот репозиторий не содержит реальных данных Zipline о поставщиках, производстве, спросе, клиентах или об операционных показателях. Это демонстрация методологии, вдохновлённая типовыми задачами цепочки поставок: результативность поставщика, прогнозирование рампы, дефицит MRP, концентрация источников снабжения, стоимость доставки (landed cost), проверка вместимости парка, медицинское возобновление запасов и многолетняя мощность поставщиков.

Почему такая архитектура

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"]

Модель выбирает, какой управляемый расчёт вызвать, и объясняет результат. Модель не воссоздаёт по памяти расчёты MAPE, OTD, «недель покрытия», landed cost или мощностей.

См. docs/ARCHITECTURE.md — полностью размеченную версию этой диаграммы (с явным разделением вероятностного LLM-слоя и детерминированного управляющего слоя), полную карту инструментов MCP (все 13 инструментов -> какие данные читает каждый) и разобранный пример принятия решения. См. docs/DATA_MODEL.md — диаграмму связей сущностей.

Related MCP server: Fabric MCP Agent

Управляемые инструменты

Также есть MCP-ресурс research://catalog и промпты supply_chain_investigation и supply_chain_question_generator.

Локально прежде всего: единственный путь, избавивший от прежних сбоев настройки MCP

Этот проект намеренно использует интерпретацию времени выполнения, которая хорошо показала себя в ранних локальных сборках MCP:

• Файл базы данных не создаётся при старте

• .venv не поставляется

• .mcp.json не поставляется

• каждый путь к данным определяется из server.py через __file__

• DuckDB создаёт новые представления в памяти по включённым в репозиторий CSV-файлам

• вызов uv run --with ... позволяет запустить dev/stdio без зависимости от метаданных editable-установки

1. Предловые проверки

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

Вы должны получить PREFLIGHT PASSED.

2. Запуск в MCP Inspector

./scripts/run_mcp_dev.sh

Если uv запросит, подтвердите установку зависимостей. MCP Inspector должен открыться с 13 инструментами.

Рекомендуемые первые вызовы:

1. supplier_scorecard с limit=5

2. forecast_accuracy

3. parts_at_risk с limit=10

4. dual_source_risk

5. compare_landed_costs

6. dock_capacity

7. stockout_reduction

8. capacity_ramp

9. projected_shortage_risk с horizon_weeks=8

10. quality_gate_risk

11. quality_rush_signal

12. quality_trend

3. Дымовая проверка аналитики без Claude

uv run python scripts/smoke_test.py

Исполнительское веб-приложение

Локальное статичное веб-приложение «Production Ramp Intelligence», построенное на тех же управляемых инструментах, — готовность к наращиванию производства, риски критичных деталей, концентрация источников и панель решений о мощностях и квалификации, при этом каждый экран сопоставим с соответствующим вызовом MCP-инструмента:

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

Затем откройте http://127.0.0.1:8765/. См. docs/EXECUTIVE_APP.md.

Запуск тестов

uv sync --extra dev
uv run pytest -q

Здесь выполняются проверки целостности данных, тесты поведения инструментов, проверки условий соглашения времени выполнения и регрессионный набор JSON-безопасности / упаковки / preflight — см. docs/CODE_WALKTHROUGH.md («Tests: what each file actually proves»), чтобы понять, что именно проверяет каждый тестовый файл.

4. Регистрация в Claude Code — только после того, как работает Inspector

./scripts/register_claude.sh
claude

Внутри Claude Code выполните /mcp. Вы должны увидеть подключённый zipline-supply-chain с 13 инструментами.

Затем используйте, например, такой промпт:

Действуйте как аналитик цепочки поставок. Начните с list_research_questions. Используйте для количественных аргументов только MCP-инструменты zipline-supply-chain. Объясните, какие риски по поставщику/части критичны для выхода производства на мощность, что об этом говорят данные, что является вашей версией, а чего синтетические данные установить не могут. Не открывайте исходные CSV-файлы и не пересчитывайте метрики самостоятельно.

Примеры исследовательских вопросов

В этом наборе данных разделены две взаимосвязанные цепочки поставок:

Производственная: работа поставщиков, систематическая ошибка прогноза, нехватка MRP, концентрация моногодистрибьютора, затраты на полную стоимость (landed cost) и многолетняя мощность поставщиков.

Операционная логистика: вместимость флота на доке в час скопления и сокращение дефицита медицинских запасов.

Это разделение встроено в инструменты и в предъявленную систему промптов.

См. DEMO_QUESTIONS.md и PROMPTS.md.

Карта документации

Полное дерево файлов: docs/REPOSITORY_GUIDE.md.

Что данный проект не заявляет

Это не боевой ERP/MRP, не оптимизатор маршрутов, не система сертификации авиационной техники, не каузальное исследование эффектов и не реальные данные компании. Смысл — обуздание годания аналитических границ для поддержки решений с участием LLM.

Проверки целостности / воспрообразимости

Синтетическая реляционная модель гарантирует: факты поступлений и качества несут корректные ключи (part_id, supplier_id), этапы квалификации используют настоящие идентификаторы из мастер-данных поставщиков, каждый PO-заказ применяет корректную связку «деталь-поставщик», а в inventory ровно одна строка на каждую деталь. Текущую версию датасета см.: data/MANIFEST.json/DATASET_VERSION.

Запускать перед MCP (также охвачено scripts/preflight.py):

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

Первая проверка проверяет внешние ключи, составные связи, уникальность и важные референсные якоря (фиксированные значения, которые должен воспроизвести этот датасет). Вторая перегенерирует стохастические/обогащённые таблицы фактов из фиксированных сидов и мастер-фикстур и побайтово сравнивает их с включёнными в репозиторий результатами.

Сам сервер не содержит случайности во время выполнения. При зафиксированных в репозитории CSV-файлах выводы инструментов детерминированы. Это воспроизводимые синтетические исследовательские данные, а не утверждение о том, что синтетические распределения статистически репрезентативны для Zipline.

Масштаб датасета

12-недельный demand.csv — это точный управляемый сценарий наращивания, лежащий в основе референсных якорей; annual_demand.csv добавляет 52 детерминированных недельных наблюдения для более длительного анализа скользящей ошибки и доступен через forecast_accuracy(series="annual_52w"), поэтому он не изменяет незаметно 12-недельный рабочий пример.

Синтетическая вселенная деталей охватывает 60 компонентов в 14 товарных группах — намеренно демонстрационного масштаба: достаточно наблюдений для значимых рейтингов по запасам и источникам поставок, но при этом достаточно мала, чтобы можно было разобрать и объяснить её вживую.