Советник по импортному сорсингу

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

Агент расширяется с помощью двух MCP-подключений:

Всё работает на публичных данных без конфиденциальных входных данных, и пользовательскому серверу не нужны никакие учётные данные API.

Что вы видите первым делом

Список задач, а не окно чата. Шесть отслеживаемых импортных позиций, по одной строке на каждую, упорядоченных по уровню риска, а затем по сумме: ведущий поставщик, его доля, сколько стоит эта доля, сколько эффективных стран происхождения за ней стоит, и статус из одного слова. Открытие строки разворачивает детализацию по странам происхождения на месте; запуск агента — это осознанное действие уже оттуда.

Над списком — полоса агрегированных показателей. На текущем окне: импортировано 554 млн долл. США, из них 346 млн сосредоточено в одном источнике по каждой позиции (62%), и Турция лидирует в 3 из 6 позиций — 183 млн подверженности риску. Последняя цифра — та, которую не может показать ни один отчёт по отдельному продукту: позиции, которые отказали бы одновременно.

Список вычисляется, а не создаётся рассуждением. web/portfolio.py открывает одну MCP-сессию stdio к тому же пользовательскому серверу, который использует агент, и вызывает инструменты напрямую, без модели в цикле. Первый экран, который загружает посетитель, не должен ждать агента или что-то стоить.

Актуальность. Годовые ряды торговой статистики отстают примерно на два года, поэтому список работает на скользящем двенадцатимесячном окне, построенном из месячных отчётов и заканчивающемся тем месяцем, до которого источник реально опубликовал данные, — сейчас это октябрь 2024 — сентябрь 2025, примерно на одиннадцать месяцев впереди последнего полного годового периода. Это не косметика: по годовым данным 2024 года свежие томаты читались как на 71,8 процента турецкие и имели флаг единственного источника; по окну они читаются как 64,6 процента и флага не имеют.

Related MCP server: supply-chain-mcp-server

Предварительные требования

Ни для одного из трёх API данных не нужны ключ, токен или учётная запись.

Установка

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

Установите браузерный сервер и сборку Chromium один раз (Node 18+ в PATH):

npm install
npx -y playwright install chromium

npm install фиксирует @playwright/mcp, и агент затем запускает его как node node_modules/@playwright/mcp/cli.js. Он не идёт через npx: в Windows нет исполняемого файла с именем npx, а Node отказывается запускать npx.cmd без оболочки, поэтому запуск сервера под этим именем молча завершался неудачей — выполнение продолжалось, и модель сообщала, что у неё нет браузерного инструмента. Без npm install агент откатывается к npx -y @playwright/mcp@latest, что работает там, где POSIX-оболочка его находит.

Конфигурация

cp .env.example .env

.env игнорируется git. Ничего в нём не требуется для пользовательского MCP-сервера; значения влияют только на агента и режим транспортировки данных.

Запуск компонентов по отдельности

Пользовательский MCP-сервер — это отдельный процесс, и он запускается сам по себе. Ничто в нём не зависит от агента.

1. Пользовательский MCP-сервер

python -m mcp_server.server

Он обслуживает MCP через stdio и при запуске выводит в stderr свой транспорт и режим данных. Чтобы просмотреть публикуемые им контракты вообще без агента:

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

Или управляйте им с помощью официального инспектора:

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

2. Playwright MCP-сервер

Агент запускает его сам; вручную его запускают только для проверки.

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

3. Агент и веб-приложение

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

Веб-приложение запускает оба MCP-подключения как дочерние процессы и показывает, какие инструменты раскрыло каждое из них.

Проверка установки

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 — это проверка, на которой держится демо. Он завершает прогон ошибкой, если оба сервера не подключились и все пять пользовательских инструментов не были реально вызваны — прогон, в котором пользовательский сервер не смог запуститься, всё равно даёт связный ответ, потому что модель просто сообщает, что у неё нет инструментов. Каждое событие записывается в scripts/last_e2e_trace.jsonl, чтобы прогон можно было изучить задним числом, а не принимать на веру. Полный прогон занимает примерно 10 минут, 20 ходов и около $0,55. Неудачная навигация по запасному URL проверки актуальности допускается, если загрузилась другая страница в цепочке — цепочка упорядочена, и агент останавливается на первой странице, которая дала ответ, — но цепочка, в которой ничего не загрузилось, и любая ошибка пользовательского сервера по-прежнему завершают прогон ошибкой.

run_failure_demo.py — вторая половина: он направляет браузер на неразрешаемый хост без запасных вариантов и проходит только в том случае, если навигация сообщается как ошибка, больше ничего не ошибается, и рекомендация всё равно выходит с указанием в ней неудачной проверки. Требование не в том, чтобы ничего не падало, — а в том, чтобы сбой можно было отличить от пустого ответа.

Офлайн / режим воспроизведения

Пользовательский сервер вызывает три сетевых API, поэтому настоящие ответы записываются в fixtures/ и могут быть воспроизведены без доступа к сети:

# Offline
SOURCING_MODE=replay python -m mcp_server.server

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

Подстановка происходит на границе транспорта (mcp_server/sources/http.py): воспроизведение возвращает тот же сырой JSON, который вернула сеть, а каждый парсер, шаг дедупликации и расчёт выше него выполняются без изменений. Ни один путь кода не возвращает заранее подготовленный ответ.

Каждая фикстура — это конверт, фиксирующий точный URL, время получения и дословное тело ответа.

Что покрывает офлайн-режим. Портфель, ранжирование каждого продукта в том виде, в каком его показывает стартовый экран, и поток агента. Проверено прогоном ранжирования одного продукта вживую и в режиме воспроизведения и сравнением каждого поля: идентично до последнего десятичного знака. Эту проверку стоит сохранить — именно так была найдена описанная ниже ошибка с пошлиной, а до записи фикстур ранжирования так же были найдены схлопнувшиеся офлайн-оценки.

Чего он не покрывает. Записан только один эталонный период (окт. 2024 — сент. 2025), поэтому запрос любого другого скользящего окна в офлайне завершается ошибкой, а не откатом. У двух продуктов есть кандидат, который невозможно оценить ни в одном режиме: для миндаля USA и NLD, а для киви AZE не сообщают вес, поэтому не из чего вывести удельную стоимость. Эти строки помечены на экране как неполные и названы в оговорке; это пробел в источнике, а не в записи.

Источники данных

Проверенное поведение конечных точек, лимиты запросов и особенности задокументированы в docs/01-data-sources-verified.md.

Структура репозитория

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

Документация

Известные ограничения

Заявлены заранее, а не спрятаны:

• Стоимость фрахта смоделирована, а не котируется. Ни один открытый источник не публикует ставки фрахта. Каждая смоделированная цифра помечена как estimated в выводе инструмента.

• Пошлина — это ставка РНБ. WITS возвращает HTTP 404 для преференциальных ставок, поэтому такие соглашения, как EU DCFTA, помечаются как возможные, но не применяются.

• Годовой ряд отстаёт примерно на два года. В августе 2026 года Украина отчиталась за 2024-й, но не за 2025-й. Месячный ряд доходит до сентября 2025 года, что и используется в рабочем списке. Инструменты расчёта стоимости с доставкой и ранжирования по-прежнему работают на годовой основе, а пошлина снова берётся из более старого наблюдения — каждый результат указывает, какая основа использовалась.

• Стоимость единицы — это не цена. Единичная стоимость Comtrade — это общая стоимость, делённая на общий вес, а не котировка.

• Индекс эффективности логистики — это не годовой ряд. 2022 год — последнее наблюдение.

• Страница таможни блокирует автоматизированных клиентов. customs.gov.ua отвечает HTTP 403 на своём крае Akamai на всё, что не является браузером человека, хотя для человека открывается нормально. Поэтому шаг проверки актуальности переходит на страницу внешнего сектора Национального банка, и агент называет, какую страницу он фактически прочитал. Это подтверждает дату публикации, но не цифру оборота, так что проверка актуальности частична по замыслу, а не случайно.

• Портфель состоит из шести позиций, выбранных по значимости. Яблоки (HS 080810, $0,5 млн) и грецкие орехи в скорлупе (HS 080231, почти ноль) были исключены: Украина выращивает и экспортирует и то, и другое, поэтому их импортные позиции — это шум.

• Это инструмент первичного отбора. Он сужает список стран, которые стоит исследовать; он не заменяет тендер.