TracePass MCP Server

Сервер Model Context Protocol для

TracePass — платформы цифровых паспортов

продукции ЕС. Он позволяет AI-ассистентам (Claude, Cursor, IDE-агентам)

управлять продуктами, цифровыми паспортами продукции, экономическими

операторами и событиями цепочки поставок GS1 EPCIS 2.0.

Сервер поддерживает полный протокол MCP: инструменты, ресурсы,

шаблоны ресурсов и промпты.

Два способа использования

Один и тот же сервер доступен в двух вариантах:

Хостинг — укажите в MCP-клиенте адрес https://ai.tracepass.eu/mcp.

Устанавливать ничего не нужно; сервер всегда обновлён.

Локальный запуск (npm) — запустите tracepass-mcp-server через npx. MCP-клиент запускает сервер как дочерний процесс и обменивается с ним данными по MCP через stdio.

Аутентификация

Сервер принимает любой из двух методов аутентификации TracePass v1 в одном и том же заголовке Authorization: Bearer …. Он передаёт полученные данные в API, а тот определяет способ аутентификации. Выберите подходящий для вашего сценария:

	API key	OAuth 2.0
Лучше всего подходит для	Одного пользователя, скриптов, взаимодействия между серверами	AI-ассистентов и приложений, действующих от имени пользователя
Что передавать	Статический ключ `tp_…` в качестве Bearer-токена	Токен доступа с заданными областями действия, полученный через OAuth
Настройка	Создайте ключ в разделе Developer → API Keys	Пользователь нажимает Connect и подтверждает запрошенные области действия
Область доступа	Без ограничений по отдельным разрешениям — весь рабочий кабинет	Только разрешения, предоставленные пользователем; доступ можно отозвать
Поддерживаемые варианты	Хостинг и локальный запуск (npx)	Только хостинг — требуется подтверждение через браузер

Что выбрать для AI-ассистента? Если ваш MCP-клиент поддерживает OAuth

(Claude.ai, ChatGPT и другие), предпочтителен OAuth: пользователь один раз

подтверждает подключение на странице TracePass, вам не нужно работать с секретом,

а доступ предоставляется по принципу наименьших привилегий и может быть отозван. Если

клиент принимает только заголовок или токен, используйте API key.

OAuth 2.0 (рекомендуется для клиентов с хостингом)

Дополнительная настройка не требуется: достаточно указать адрес сервера с хостингом —

обнаружение выполняется автоматически. При первом запросе без аутентификации сервер

возвращает 401. В заголовке WWW-Authenticate передаётся URL

resource_metadata (RFC 9728), указывающий на /.well-known/oauth-protected-resource,

где указан сервер авторизации TracePass. Затем клиент выполняет стандартный

поток авторизации по коду с PKCE (/api/oauth/authorize →

/api/oauth/token), пользователь подтверждает запрошенные разрешения, а клиент сохраняет

и обновляет токен. Если вы распространяете собственный клиент, зарегистрируйте приложение

в разделе Developer → OAuth Apps, чтобы получить client_id. Многие клиенты с хостингом

автоматически регистрируются самостоятельно через Dynamic Client Registration.

Запрашивайте только необходимые разрешения, например: passports:read passports:write offline_access. Пользователи могут управлять подключёнными приложениями и отзывать доступ в разделе

Developer → OAuth Apps → Connected Apps.

API key

Создайте ключ tp_… в разделе Developer → API Keys и передавайте его как Bearer-

токен.

Хостинг:

{
  "mcpServers": {
    "tracepass": {
      "url": "https://ai.tracepass.eu/mcp",
      "headers": { "Authorization": "Bearer tp_YOUR_KEY" }
    }
  }
}

Локальный запуск (npx / stdio) — локальный дочерний процесс не может выполнить

интерактивное подтверждение OAuth, поэтому здесь поддерживается только API key через

переменную окружения TRACEPASS_API_KEY:

{
  "mcpServers": {
    "tracepass": {
      "command": "npx",
      "args": ["-y", "tracepass-mcp-server"],
      "env": {
        "TRACEPASS_API_KEY": "tp_YOUR_KEY"
      }
    }
  }
}

Необязательная переменная окружения: TRACEPASS_BASE_URL (по умолчанию —

https://app.tracepass.eu). С её помощью можно направить инструменты на другой

экземпляр TracePass.

Инструменты

Операции API TracePass v1 объединены в 6 инструментов.

Каждый инструмент принимает перечисление действий и соответствующие аргументы. Список инструментов:

tracepass_products — управление каталогом продуктов: просмотр списка, получение данных, создание, пакетное создание, обновление и архивирование продуктов.
tracepass_passports — управление цифровыми паспортами продукции: просмотр списка и получение данных, проверка соответствия требованиям и готовности к регистрации, получение и установка флагов состояния, создание, приостановка и архивирование, получение QR-кода, просмотр списка снимков и получение снимка. Доступ возможен по идентификатору или серийному номеру. Для идентификации паспортов используются GS1 или одна из четырёх дополнительных схем EN 18219 (iso15459, iec61406, did, doi); для паспортов батарей допустимы только gs1 и iso15459 (ст. 77(3)). Флаги состояния — это утверждённые факты с ответом «да» или «нет» (например, для батареи: hasBMS, rechargeable, externalStorageOnly, isStationaryBess), от которых зависят отдельные юридические требования. Установка утверждённого флага может сделать обязательным заполнение дополнительных полей; публикация будет заблокирована, если они не заполнены.
tracepass_passport_fields — обновление полей данных паспорта, специфичных для категории, по идентификатору или серийному номеру.
tracepass_passport_parties — добавление или удаление экономических операторов, связанных с паспортом (производителя, импортёра и других).
tracepass_epcis — экспорт, регистрация и поиск событий цепочки поставок GS1 EPCIS 2.0 для паспорта.
tracepass_templates — просмотр списка и получение схем полей для категорий цифровых паспортов продукции. Для каждого поля указан нормативный акт ЕС, устанавливающий соответствующее требование.

Полный список действий для каждого инструмента:

Tool	Actions
`tracepass_products`	`list`, `get`, `create`, `create_batch`, `update`, `archive`
`tracepass_passports`	`list`, `get`, `get_by_serial`, `compliance`, `registry_readiness`, `get_condition_flags`, `get_condition_flags_by_serial`, `set_condition_flags`, `set_condition_flags_by_serial`, `capture_measurements`, `capture_measurements_by_serial`, `list_measurements`, `list_measurements_by_serial`, `latest_measurements`, `latest_measurements_by_serial`, `create`, `suspend`, `suspend_by_serial`, `archive`, `archive_by_serial`, `get_qr`, `get_qr_by_serial`, `list_snapshots`, `get_snapshot`
`tracepass_passport_fields`	`update`, `update_by_serial`
`tracepass_passport_parties`	`set`, `remove`
`tracepass_epcis`	`export`, `export_by_serial`, `capture`, `capture_job`, `query`
`tracepass_templates`	`list`, `get`

Действия *_by_serial позволяют обращаться к паспорту по серийному номеру,

назначенному самим клиентом, а не по идентификатору TracePass. Серийный номер уникален только в пределах GTIN, поэтому

если в вашем аккаунте один и тот же номер указан для двух GTIN, запрос только по серийному номеру

вернёт 409 ambiguous_serial. Чтобы устранить неоднозначность, передайте необязательный аргумент gtin

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

действиям *_by_serial.

Действие compliance инструмента tracepass_passports возвращает

один из трёх результатов проверки соответствия требованиям (compliant / compliant_with_warnings /

incomplete) и замечания со ссылками на нормативные акты. Проверяются отсутствующие обязательные поля,

отсутствующие сведения об экономических операторах, ошибки формата и условные требования для конкретной категории.

Проверка выполняется только для чтения. Используйте её, чтобы выявить пробелы в данных паспорта, устранить

указанные недочёты и выполнить проверку повторно.

Результат compliant означает, что паспорт соответствует правилам, реализованным здесь,

но не подтверждает, что этот продукт разрешено размещать на рынке. Спецификации полей

составлены вручную на основе нормативных актов и не являются официальным документом ЕС; кроме того,

делегированные акты продолжают публиковаться. Эта информация не является юридической консультацией.

Батареи, используемые повторно

Для батареи, прошедшей переоборудование, переработку или повторное использование, требуется новый

паспорт, связанный с исходным паспортом или паспортами (Регламент о батареях, ст. 77(7)). Передайте блок

lineage в действие create инструмента tracepass_passports:

{ "predecessors": [ { "internalPassportId": "<your original passport id>", "trigger": "repurposing" } ] }

Исходный паспорт можно указать с помощью internalPassportId (идентификатора одного из ваших паспортов)

или доступного для разрешения identifier. Для trigger допускаются значения

preparation_for_reuse, preparation_for_repurposing, repurposing и

remanufacturing. Платформа определяет batteryStatus на основе

указанных причин, сохраняет блок без возможности изменения и связывает ваши исходные паспорта

с новым паспортом, добавляя их в successors. Для батареи, размещённой на рынке до

18 Feb 2027, исходного паспорта нет: передайте пустой список и укажите

noPredecessorReason. При нарушении правил возвращается ошибка 422 с кодом правила.

Измерения батареи (актуальная запись)

Действие capture_measurements передаёт в опубликованный паспорт батареи данные о её эксплуатации,

полученные с вашего оборудования: состояние работоспособности, снижение характеристик, число циклов,

динамические значения, уровень заряда, негативные события и историю температуры (Регламент о батареях,

приложение XIII, пункт 4). Сохраняется каждое измерение; последнее значение для каждого поля становится

текущим значением паспорта и задаёт dynamicDataAsOf.

Действия list_measurements и latest_measurements позволяют получать эти данные.

Измерения учитываются в месячном лимите тарифа, а не в дневном лимите записей. На платных тарифах

учёт продолжается после достижения лимита без дополнительной платы; тариф Free прекращает приём данных

после исчерпания лимита. Чтение паспорта не тарифицируется.

Примечание об операциях записи

Некоторые действия платные или необратимые — об этом предупреждают описания инструментов сервера:

tracepass_passports create расходует платные слоты DPP.

За создание сверх лимита взимается дополнительная плата за каждый паспорт. Инструмент выводит сообщение в стиле 402 и продолжает работу только при args.confirmOverage: true — после согласия пользователя.

tracepass_passports archive — необратимое действие: публичный QR-код навсегда перестаёт открываться и возвращает 404. Если изменение может потребоваться отменить, используйте обратимую операцию suspend.
Для tracepass_epcis capture / query требуется платное дополнение EPCIS; export входит в тарифы Starter и выше.

Ресурсы

Доступные только для чтения данные о сущностях, которые можно добавить в контекст беседы:

tracepass://products — каталог товаров
tracepass://product/{id} — сведения об одном товаре
tracepass://passport/{id} — полный набор полей одного паспорта
tracepass://passport/{id}/epcis — события EPCIS 2.0 для паспорта
tracepass://passport/{id}/compliance — заключение о соответствии паспорта требованиям
tracepass://passport/{id}/registry-readiness — техническая предварительная проверка перед подачей, построенная по формальным критериям EU DPP Registry: наличие обязательных полей, корректность формата, доступность публичной ссылки и детализация на уровне товара (проверка кода товара не выполняется: регистрационный идентификатор паспорта батареи не указывается в таможенной декларации). Это не заключение о соответствии требованиям по существу и не прогноз ответа реестра: спецификация его API регистрации не опубликована. Только для батарей.
tracepass://passport/{id}/snapshots — история снимков паспорта, от новых к старым. Снимок создаётся при публикации и после каждого изменения паспорта, не находящегося в статусе черновика. Для каждой записи указаны версия, причина (например, published, field_edit, status_change, baseline), субъект, время создания снимка (snapshotAt), хеш содержимого (contentHash), результат повторной проверки хеша при чтении (hashValid), возможность восстановления (restorable) и количество полей.
tracepass://templates — схемы полей для всех 13 категорий DPP
tracepass://template/{category} — полная схема полей для одной категории

Промпты

Повторно используемые сценарии работы с DPP, доступные в клиенте как slash-команды:

audit_passport — проверить полноту паспорта и готовность к подтверждению соответствия требованиям
onboard_product — создать товар и первый паспорт для него
explain_dpp_requirements — объяснить, что должен содержать соответствующий требованиям DPP для выбранной категории, и указать нормативный акт для каждого поля
compliance_gap_check — составить приоритизированный список препятствий для публикации паспорта в соответствии с требованиями со ссылками на нормативные акты
review_epcis_events — обобщить историю движения паспорта по цепочке поставок

Для поставщиков: ответ на запрос данных

Для поставщиков, получивших запрос данных от TracePass, доступна отдельная конечная точка. Она не относится к перечисленным выше инструментам. В письме с запросом указан персональный адрес:

https://ai.tracepass.eu/supplier/mcp/<token>

Добавьте его в AI-ассистент как пользовательский коннектор. Если клиент позволяет настраивать заголовки, можно использовать и адрес https://ai.tracepass.eu/supplier/mcp с заголовком Authorization: Bearer . Токен даёт доступ только к одному запросу; учётная запись и OAuth не требуются. После этого ассистенту будут доступны следующие инструменты:

Инструмент	Назначение
`get_request`	Начните с этого инструмента: он укажет, кто отправил запрос, к какому товару он относится и какие поля нужно заполнить, а также приведёт описание, единицу измерения, формат и правовое основание для каждого поля. Кроме того, он покажет уже отправленные ответы и результат их проверки
`validate_answers`	Предварительная проверка: показывает, какие данные будут сохранены, какие ключи не запрашивались и какие значения не соответствуют требованиям. Ничего не записывает
`get_upload_command`	Рекомендуемый способ приложить паспорт изделия или сертификат, если ассистент может выполнять команды оболочки: возвращает команду `curl`, которая загружает файл с диска и выводит `documentId` для ссылки на него (поддерживаются PDF, Office, CSV, PNG/JPEG/WebP)
`upload_evidence`	Прикрепить небольшой файл (несколько килобайт) в формате base64. Предпочтительно использовать `get_upload_command` либо указать URL или примечание
`submit_answers`	Отправить ответы с подтверждающими материалами для каждого значения на проверку человеком со стороны запрашивающей организации. Отправку можно повторять до завершения проверки — ответы будут объединяться
`get_review_status`	Узнать, проверила ли запрашивающая организация ответы, каков результат проверки, какие поля приняты и когда истекает срок действия ссылки

Ответы поступают на проверку человеку со стороны запрашивающей организации; сами по себе они ничего не публикуют.

Разработка

dist/ npm run typecheck npm test # vitest npm run lint npm start # run the hosted HTTP service locally (:8080) npm run start:stdio # run the stdio server locally">

npm install
npm run build        # tsc -> dist/
npm run typecheck
npm test             # vitest
npm run lint
npm start            # run the hosted HTTP service locally (:8080)
npm run start:stdio  # run the stdio server locally

Размещённый сервис — это простой HTTP-сервер Node (dist/http.js) без сохранения состояния: каждый запрос содержит собственный API key и создаёт новую сессию MCP. Сервис упакован в контейнер с помощью Dockerfile и развёрнут на Hetzner; см. tracepass-environment/docker-mcp.yml.

В каталоге Glama

Сервер опубликован в официальном реестре MCP под именем eu.tracepass/tracepass и представлен на Glama:

Лицензия

MIT