MCP сървър — свържете AI асистенти към DPP данни

MCP сървърът на TracePass позволява на един AI асистент да управлява платформата TracePass директно — да изброява и създава продукти, да изгражда и одитира цифрови продуктови паспорти, да задава икономически оператори и да чете или заснема GS1 EPCIS събития във веригата на доставки. Той говори целия Model Context Protocol: tools, resources и prompts. Свържете хостван endpoint или го пуснете локално чрез npx — и двата начина се удостоверяват с tp_ API ключ или OAuth 2.0 токен за достъп. Изходен код в GitHub, публикуван като tracepass-mcp-server в npm. Включен в официалния регистър MCP като eu.tracepass/tracepass.

Какво представлява

MCP е отворен протокол, който позволява на AI асистент да извиква външни tools и да чете външни данни през един стандартен интерфейс. MCP сървърът на TracePass е тънък adapter без състояние пред v1 API на TracePass — той няма собствена база данни; всяко извикване на tool и всяко четене на resource минават директно през същото API, което използват и другите ви интеграции, така че удостоверяване, ограничения по план и лимити на честотата се държат по идентичен начин. Има два начина да го свържете. Хостваният сървър работи на https://ai.tracepass.eu/mcp през HTTP — няма какво да се инсталира, винаги е актуален. Локалният сървър е npm пакетът tracepass-mcp-server, пуснат като подпроцес от вашия MCP клиент и говорещ MCP през stdio.

Свързване (хостван)

Насочете вашия MCP клиент към хоствания endpoint и подайте вашия API ключ като Bearer token. Генерирайте ключ в таблото от Developer → API Keys — това е същият tp_ ключ, който използва v1 API. Добавете този блок към MCP конфигурацията на вашия клиент:

json

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

Свързване (локално / npx)

За локална настройка вашият MCP клиент пуска npm пакета като подпроцес и говори с него през stdio. Няма нужда от предварителна инсталация — npx изтегля tracepass-mcp-server при първото пускане. API ключът се подава през променливата на средата TRACEPASS_API_KEY вместо през header:

json

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

Tools

Операциите на v1 API на TracePass са групирани в осем tools. Всеки приема action плюс специфични за действието args, така че асистентът избира tool по област, а операцията — по action:

Tool	Действия
`tracepass_products`	`list, get, create, create_batch, update` — Операции с каталога — преглеждане, четене и създаване или актуализиране на продукти.
`tracepass_passports`	`list, get, get_by_serial, compliance, registry_readiness, prepare_registry_upi, prepare_registry_upload_file, record_acceptance_test, get_condition_flags, get_condition_flags_by_serial, set_condition_flags, set_condition_flags_by_serial, create, get_qr, get_qr_by_serial, list_snapshots, get_snapshot, capture_measurements, capture_measurements_by_serial, list_measurements, list_measurements_by_serial, latest_measurements, latest_measurements_by_serial` — Жизненият цикъл на паспорта — изброяване и четене на паспорти, търсене по сериен номер, създаване, извличане на QR кода или на Data Matrix и четене на историята от моментни снимки, включително версията, валидна към дадена дата.
`tracepass_passport_fields`	`update, update_by_serial` — Актуализиране на отделни полета на шаблон в паспорт.
`tracepass_passport_parties`	`set, remove` — Задаване или премахване на икономически оператори (производител, вносител, рециклатор и т.н.) в паспорт.
`tracepass_epcis`	`export, export_by_serial, capture, capture_job, query` — Четене и запис на GS1 EPCIS 2.0 събития във веригата на доставки — експорт на историята на събитията на паспорт, заснемане на нови събития, изпълнение на capture задача и заявки към хранилището на събития.
`tracepass_templates`	`list, get` — Четене на регулаторната схема за всяка категория DPP — какво трябва да съдържа един паспорт в съответствие с изискванията и кой Регламент стои зад всяко задължително поле. Позволява на асистента да съветва за изискванията, преди да създадете каквото и да е.
`tracepass_scope`	`check, catalogue_report, catalogue_run, catalogue_run_status` — Проверка дали даден продуктов тип изисква цифров продуктов паспорт, от кога и по кой акт и член; четене на отчета за обхвата на каталога; стартиране и проследяване на проверката на каталога.
`tracepass_passport_lifecycle`	`record_registration, undo_registration, place_on_market, suspend, suspend_by_serial, archive, archive_by_serial, archive_product` — Необратими и публично видими действия, отделени, за да не ги обхваща разрешението „винаги позволявай“ за четене: записване на регистрацията на паспорт на батерия в регистъра на ЕС за DPP (операторът я извършва на уебсайта на регистъра) или изпращането му към API на регистър по EN 18222, спиране или архивиране на паспорт и архивиране на продукт. Асистентът трябва да потвърждава всяко извикване с вас.

Някои действия за запис струват пари или са необратими. Описанията на tools на сървъра казват това на модела, но трябва да го знаете и вие: tracepass_passports с действие create създава чернова на паспорт. Черновата не заема място от плана и не се таксува; лимитът на плана и евентуалната такса за паспорт над него се прилагат, когато паспортът се публикува от таблото. Архивирането, спирането и пускането на пазара са в отделен tool, tracepass_passport_lifecycle, за да не ги обхваща разрешението „винаги позволявай“ за четене; действието му archive е необратимо, затова използвайте suspend, когато може да ви потрябва паспортът отново. Действията на tracepass_epcis (capture, query, export) са включени във всеки план, включително Free, и се таксуват по брой събития на месец според таблицата с планове.

Кой е записал дадена стойност, остава в историята. Актуализация чрез tracepass_passport_fields се записва с правата на този, който е свързал асистента: API ключ или администратор я записва като одобрена, а свързано приложение, действащо от името на редактор, я изпраща за преглед, както би направило таблото. Когато асистентът сам е намерил или извел стойността (проучване в интернет, четене на документ), вместо да му е била съобщена, той подава source: "ai_suggested" и стойността чака в опашката за преглед в таблото, докато човек я одобри. Полета, които може да декларира само икономическият оператор или които трябва да бъдат измерени, отказват такава стойност. Всяка промяна се записва в историята на паспорта с идентификационните данни и канала. Публикуването не е достъпно за асистента; то остава в таблото.

Resources

Resources са данни само за четене, които потребителят прикача като контекст на разговора, адресирани чрез tracepass:// URI. Два са статични resources, останалите са resource templates, които клиентът допълва с id:

tracepass://products
tracepass://product/{id}
tracepass://passport/{id}
tracepass://passport/{id}/epcis
tracepass://passport/{id}/compliance
tracepass://passport/{id}/registry-readiness
tracepass://passport/{id}/snapshots
tracepass://templates
tracepass://template/{category}

Prompts

Prompts са повтаряеми DPP работни процеси, които MCP клиентът показва на потребителя, обикновено като slash-команди. Всеки засява разговора така, че асистентът да изпълни задачата по начина, по който TracePass предвижда — например винаги да потвърждава, преди да създаде паспорт:

audit_passport
onboard_product
review_epcis_events
explain_dpp_requirements
compliance_gap_check
register_battery_passport

Copilot за съответствие в действие

Заедно tool-ът за шаблони и промптовете превръщат асистента в copilot за съответствие на DPP — той знае какво изисква Регламентът за всяка категория, а не само как да въвежда данни. Ето примерна сесия за производител на батерии:

text

You  ▸  What does a compliant battery passport need, and which fields will be hardest to source?

TracePass copilot  ▸  Calling tracepass_templates(get, battery)…

  A battery DPP is governed by the EU Battery Regulation (EU) 2023/1542,
  mandatory from 18 Feb 2027. The template covers the Annex XIII field set. By
  access level:

    • Public (consumer-facing): manufacturer identity, battery
      category, weight, capacity, hazardous substances, recycled-
      content shares (Co, Pb, Li, Ni), carbon footprint, due-
      diligence report. — Art. 77, Annex XIII
    • Restricted (legitimate interest): cell materials (cathode,
      anode, electrolyte), dismantling and removal info, state of
      health, expected lifetime.
    • Authority-only: test reports, third-party audit results,
      recycled-content documentation.

  Hardest to source up front: the recycled-content shares and the
  carbon-footprint declaration — those usually live with your cell
  supplier. Want me to draft a supplier request for them?

You  ▸  Yes — and gap-check passport SN-2026-00042 before I publish it.

TracePass copilot  ▸  Running the compliance_gap_check prompt…

  Against the battery template, SN-2026-00042 has gaps to close
  before you publish:

    ✗ hazardousSubstances — empty (required, Annex XIII 1(a))
    ✗ extinguishingAgent — empty (required, Annex XIII 1(a))
    ⚠ recycler party — not set (flagged; does not block publishing)
    ⚠ stateOfHealth — present but pending review

  Everything else is approved. Fill the two empty required fields
  before you publish. Most important first: the hazardous-substances
  list — it usually needs a declaration from the cell supplier.

За регулаторни въпроси — какво казва законодателството на ЕС за даден тип продукт, с цитиран член — вижте DPP Асистента. Той използва отделен набор от регулаторни инструменти и отделен MCP endpoint на https://ai.tracepass.eu/compliance/mcp.