tariff-resolver

MCP-сервер, который превращает ваш AI-ассистент в инструмент исследования импортных пошлин США — построен на официальных данных Harmonized Tariff Schedule от USITC (общественное достояние правительства США, более 35 000 тарифных позиций).

🔍 Кандидаты кодов HTS по обычному текстовому описанию товара, со ссылками на решения CBP CROSS
🧮 Компоненты landed cost: базовые ставки MFN/FTA + дополнительные пошлины Chapter 99 (IEEPA / Section 301 / 232) + сборы MPF/HMF
📡 Отслеживание изменений тарифов: добавляйте свои коды HTS в watchlist и сравнивайте ставки между редакциями HTS
🤖 Оптимизирован под AI, устойчив к галлюцинациям: возвращает реальный текст правил Chapter 99 с разобранными ставками, чтобы ваш LLM рассуждал на основе настоящих цепочек исключений, а не выдумывал цифры образца 2024 года

Почему сейчас: после отмены льготы de minimis (29 августа 2025 года) каждая отправка в США требует кода HTS и уплаты пошлины — а ставки 2025–26 годов продолжают меняться указами президента.

Проект не аффилирован с государственными органами. Результаты — кандидаты/оценки для предварительного скрининга до привлечения брокера, а не таможенные, юридические или налоговые консультации. В оценки не входят пошлины AD/CVD.

Установка

Требуется Node.js ≥ 18.

claude mcp add tariff-resolver -- npx -y tariff-resolver

Или в конфигурации любого MCP-клиента:

{ "mcpServers": { "tariff-resolver": { "command": "npx", "args": ["-y", "tariff-resolver"] } } }

Claude Desktop (в один клик): скачайте tariff-resolver-.mcpb со страницы релизов и дважды кликните по нему — терминал не нужен.

💡 Попробуйте эти запросы

Простой поиск: «Найди код HTS для мужской футболки из 100% хлопка».
Полный сценарий: «Рассчитай тарифный сценарий для HTS 6109.10.00, происхождение — Китай, таможенная стоимость $5 000, морской фрахт».
Выбор поставщика: «Я импортирую термосы из нержавеющей стали на $10 000. Сравни landed cost при закупке в Китае и во Вьетнаме».
Будь в курсе: «Отслеживай изменения тарифов по моему каталогу: 6109.10.00, 8507.60.00, 9617.00.10».

Инструменты

Инструмент	Что делает
`search_hs_candidates`	Описание товара → лучшие кандидаты HTS со ставками и ссылками на решения CBP CROSS
`calculate_tariff_scenario`	Код HTS + происхождение + стоимость (+ вес) → структурированный JSON: базовая ставка MFN/FTA, слои-кандидаты Chapter 99 с match/confidence по каждому слою, блок possibly_expired с источниками, MPF/HMF
`watch_tariff_changes`	Регистрирует коды HTS в локальном watchlist
`check_tariff_updates`	Сравнивает текущую и предыдущую редакции HTS — видно, какие именно ставки изменились
`dataset_info`	Дата редакции данных, число строк, источник, лицензия

Принцип работы

Сервер выполняет поиск данных, а рассуждения остаются за вашим LLM. Правила Chapter 99 возвращаются дословно (с разобранным adder_pct, где применимо), чтобы модель читала реальные цепочки исключений, а не доверяла расчёту «чёрного ящика». Ставки для 10-значных статистических суффиксов наследуются от родительской строки ставки. Позиции, которые тариф помечает как недействующие — прекращённые, приостановленные, истёкшие, — отфильтровываются и подсчитываются, а собственная пометка USITC compiler_note передаётся вместе с каждым правилом, в котором она есть.

Переопределения статусов. Файл data/status_overrides.json — это небольшой список позиций Chapter 99 с указанием источников, взимание по которым прекратилось, истекло или приостановлено, хотя тариф по-прежнему их печатает. Слой, совпавший с такой записью, возвращается в блоке possibly_expired с полями status, reason, URL источника source и датой as_of, а не в layers. Каждая запись опирается на источник CBP, Federal Register или USITC; в pull request'ах, добавляющих новые записи, такой источник обязателен.

Чего данные не скажут. Опубликованный тариф в каждый момент времени ошибается в обе стороны, поэтому каждый результат содержит stacking_warning и дату снимка данных. Положения, взимание по которым уже прекратилось, продолжают печататься без даты окончания — чаще всего это позиции IEEPA и Section 122, — а недавно провозглашённые меры появляются в тарифе лишь через несколько дней после вступления в силу. Если просуммировать все слои, которые печатает тариф, получится ставка, которую в действительности никому не начисляют. Относитесь к слоям как к кандидатам и сверяйте статус взимания с сообщениями CBP CSMS, прежде чем полагаться на стек.

Одно ядро, две точки входа. Вся логика пошлин находится в tariff-resolver/core (чистый TypeScript, без обращений к файловой системе и сети): resolveDuty(dataset, { hts, origin, value_usd?, ocean? }) — origin принимает код ISO-3166 alpha-2 или название страны на английском — возвращает базовую строку, отдельные MPF/HMF, каждый слой-кандидат Chapter 99 с match и confidence, блок possibly_expired с указанием источников и дату снимка данных. MCP-инструмент вызывает её; то же доступно любому Node- или edge-runtime. Нераспознанное название страны возвращает ошибку ORIGIN_UNKNOWN, а не частичное совпадение, поэтому опечатка в стране происхождения никогда не приведёт незаметно к урезанному стеку слоёв.

Данные

Поставляется с полным снимком HTS, загруженным из официального JSON API USITC (общественное достояние правительства США). Обновить можно в любой момент:

python3 scripts/fetch_hts.py   # ~2 min, fails hard rather than write a partial dataset

dataset_info сообщает дату редакции, относительно которой выполняются ваши запросы.

Политика конфиденциальности

tariff-resolver полностью работает на вашей машине и ничего не собирает:

Сбор данных: отсутствует. Запросы, телеметрия, аналитика и данные об использовании не собираются и не передаются.
Использование и хранение: ваш watchlist хранится в локальном JSON-файле на вашей машине; все запросы выполняются по встроенному локальному набору данных.
Передача третьим сторонам: отсутствует. Сервер не выполняет сетевых запросов во время работы. (Опциональный скрипт обновления scripts/fetch_hts.py обращается только к официальному API USITC.)
Хранение данных: хранить нечего — локальный файл watchlist можно удалить в любой момент.
Контакты: tom@opsloft.dev

Полный текст политики: https://opsloft.dev/privacy

Лицензия

MIT. Тарифные данные — произведение правительства США (общественное достояние).