--- title: MCP сървър description: MCP сървър — AI асистенти (Claude, Cursor, IDE) управляват продукти, паспорти, EPCIS събития. Хостван endpoint или локален npm пакет. canonical: "https://www.tracepass.eu/bg/docs/mcp" locale: bg source: "https://www.tracepass.eu/bg/docs/mcp" --- # MCP сървър > MCP сървър — AI асистенти (Claude, Cursor, IDE) управляват продукти, паспорти, EPCIS събития. Хостван endpoint или локален npm пакет. MCP сървърът на TracePass позволява на един AI асистент да управлява платформата TracePass директно — да изброява и създава продукти, да изгражда и одитира цифрови продуктови паспорти, да задава икономически оператори и да чете или заснема GS1 EPCIS събития във веригата на доставки. Той говори целия Model Context Protocol: tools, resources и prompts. Свържете хостван `endpoint` или го пуснете локално чрез `npx` — и двата начина се удостоверяват със същите `tp_` API ключове като v1 API. Изходен код в [GitHub](https://github.com/malinoto/tracepass-mcp-server), публикуван като [tracepass-mcp-server](https://www.npmjs.com/package/tracepass-mcp-server) в npm. Включен в официалния [регистър MCP](https://registry.modelcontextprotocol.io) като `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, updateОперации с каталога — преглеждане, четене и създаване или актуализиране на продукти. | | tracepass\_passports | list, get, get\_by\_serial, compliance, create, suspend, suspend\_by\_serial, archive, archive\_by\_serial, get\_qrЖизненият цикъл на паспорта — изброяване и четене на паспорти, търсене по сериен номер, създаване, спиране, архивиране и извличане на QR кода. | | 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 — какво трябва да съдържа един паспорт в съответствие с изискванията и кой Регламент стои зад всяко задължително поле. Позволява на асистента да съветва за изискванията, преди да създадете каквото и да е. | **Някои действия за запис струват пари или са необратими.** Описанията на tools на сървъра казват това на модела, но трябва да го знаете и вие: `tracepass_passports` с действие `create` заема платен DPP слот от вашия план — създаването извън квотата води до такса за overage на паспорт и продължава само след като потребителят се съгласи чрез `confirmOverage`. Действието `archive` е необратимо; използвайте `suspend`, когато може да ви потрябва паспортът отново. Действията на `tracepass_epcis` (`capture`, `query`, `export`) са включени във всеки платен план и се таксуват по брой събития на месец според таблицата с планове. ## 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://templates` * `tracepass://template/{category}` ## Prompts Prompts са повтаряеми DPP работни процеси, които MCP клиентът показва на потребителя, обикновено като slash-команди. Всеки засява разговора така, че асистентът да изпълни задачата по начина, по който TracePass предвижда — например винаги да потвърждава, преди да създаде платен паспорт: * `audit_passport` * `onboard_product` * `review_epcis_events` * `explain_dpp_requirements` * `compliance_gap_check` ## 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 has 94 required fields. By access level: • Public (consumer-facing): manufacturer identity, battery category, weight, capacity, expected lifetime, recycled-content shares (Co, Pb, Li, Ni). — Art. 77, Annex VI • Restricted (authorised parties): full material composition, hazardous-substance breakdown, dismantling info. • Authority-only: conformity test reports, due-diligence data. 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 schema, SN-2026-00042 is NOT publishable yet: ✗ carbonFootprintDeclaration — empty (required, Art. 7) ✗ recycledContentCobalt — empty (required, Annex VI) ✗ recycler party — not set ⚠ stateOfHealth — present but pending review Everything else is approved. Fix the two empty required fields and add the recycler party, and it's ready. Most important first: the carbon-footprint declaration — it blocks publishing and takes the longest to obtain. ``` **Tip —** Примерен сценарий. Отговорите на асистента идват от живата схема на категорията и от вашите собствени данни за паспорта чрез горните tools — точната формулировка зависи от модела и клиента.