TracePass

TracePass MCP 服务

一个适用于 TracePass 的模型上下文协议服务——这是欧盟数字产品护照平台。它让 AI 助手（Claude、Cursor、IDE Agent）管理产品、数字产品护照、经济运营者各方以及 GS1 EPCIS 2.0 供应链事件。

它支持完整的 MCP 协议——工具、资源、资源模板和提示词。

两种使用方式

同一服务核心提供两种使用方式：

1. 托管式——将 MCP 客户端连接到 https://ai.tracepass.eu/mcp。 无需安装；始终保持最新。
2. 本地（npm）——通过 npx 运行 tracepass-mcp-server。MCP 客户端将其作为子进程启动，并通过 stdio 使用 MCP 通信。

身份验证

该服务接受 TracePass 两种 v1 身份验证方式中的任意一种，均通过相同的 Authorization: Bearer … 标头传递——它会将你发送的内容转发给 API，由 API 决定。请选择适合你连接方式的方法：

	API 密钥	OAuth 2.0
最适用于	单个用户、脚本、服务间通信	代表用户操作的 AI 助手 / 应用
发送内容	作为 Bearer 令牌的静态 tp_… 密钥	通过 OAuth 流程获取的限定范围访问令牌
设置	在 Developer → API Keys 中创建	用户点击 Connect 并批准权限范围
权限范围	全部或无（整个工作区）	仅限用户授予的权限范围；可撤销
适用方式	托管式和本地（npx）	仅限托管端点（需要浏览器授权步骤）

AI 助手应该使用哪种方式？ 如果你的 MCP 客户端支持 OAuth（Claude.ai、ChatGPT 等），优先选择 OAuth——用户只需在 TracePass 授权页面上批准一次连接，你无需处理密钥，且访问权限遵循最小权限原则并可撤销。如果你的客户端只能使用标头 / 令牌，则使用 API 密钥。

OAuth 2.0（推荐用于托管式客户端）

只需将客户端指向托管端点，无需其他配置——系统会自动发现。首次收到未经身份验证的请求时，服务会返回 401，其 WWW-Authenticate 标头包含一个 resource_metadata URL（RFC 9728），指向 /.well-known/oauth-protected-resource，其中列出了 TracePass 授权服务器。客户端会运行标准的带 PKCE 的授权码流程（/api/oauth/authorize → /api/oauth/token），用户批准权限范围，然后客户端存储并刷新令牌。如果你要分发自己的客户端，请在 Developer → OAuth Apps 下注册应用以获取 client_id；许多托管式客户端会通过动态客户端注册自动完成注册。

只请求所需的权限范围，例如 passports:read passports:write offline_access。用户可在 Developer → OAuth Apps → Connected Apps 下管理已连接的应用（并撤销访问权限）。

API 密钥

在 Developer → API Keys 下创建 tp_… 密钥，并将其作为 Bearer 令牌发送。

托管式：

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

本地（npx / stdio）——本地子进程无法执行交互式 OAuth 授权步骤，因此只能通过 TRACEPASS_API_KEY 环境变量使用 API 密钥：

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

可选环境变量：TRACEPASS_BASE_URL（默认为 https://app.tracepass.eu）——将工具指向其他 TracePass 部署。

工具

TracePass v1 API 操作分为 7 个工具。 每个工具都接受一个操作枚举以及该操作专属的参数。工具如下：

• tracepass_products - 管理产品目录（列出、获取、创建、批量创建、更新、归档产品）。
• tracepass_passports - 按 ID 或序列号管理数字产品护照（列出、获取、合规性检查、注册准备情况检查、获取/设置状况标志、创建、暂停、归档、获取二维码、列出快照、获取快照）。护照通过 GS1 或另外四种 EN 18219 方案（iso15459、iec61406、did、doi）识别；电池护照仅接受 gs1 和 iso15459（第 77 条第（3）款）。状况标志是经批准的“是/否”事实（例如，电池的 hasBMS、rechargeable、externalStorageOnly、isStationaryBess），用于决定是否适用附带条件的法定义务——设置经批准的标志可能会使其他字段成为必填项，并在这些字段为空时阻止发布。
• tracepass_passport_fields - 按 ID 或序列号更新护照的类别专属数据字段。
• tracepass_passport_parties - 设置或移除护照的经济运营者相关方（制造商、进口商等）。
• tracepass_epcis - 导出、采集和查询护照的 GS1 EPCIS 2.0 供应链事件。
• tracepass_templates - 列出并获取 DPP 类别字段架构，每个字段均注明其强制规定所依据的欧盟法规。
• tracepass_scope - 检查产品类型是否需要数字产品护照（check），读取公司的全目录范围报告（catalogue_report），并触发或轮询目录刷新任务（catalogue_run、catalogue_run_status）。

各工具的完整操作集：

工具	操作
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
tracepass_scope	check、catalogue_report、catalogue_run、catalogue_run_status

*_by_serial 操作使用客户自己的序列号而非 TracePass ID 来指定护照。序列号仅在 同一个 GTIN 内 唯一，因此，如果您的账户中两个 GTIN 下存在相同序列号，仅使用序列号的调用会返回 409 ambiguous_serial——请传入可选的 gtin 参数以消除歧义（或使用按 ID 调用的操作）。相同的 gtin 消歧参数适用于所有 *_by_serial 操作。

tracepass_passports 的 compliance 操作会返回三级合规性判定（compliant / compliant_with_warnings / incomplete），并提供引用法规的检查结果——缺少必填字段、缺少经济运营者相关方、格式问题以及各类别的附加条件规则。此操作为只读；可用它检查护照的差距、修复所引用的问题，然后重新检查。

compliant 判定表示此护照符合此处编码的规则，并不表示此产品可以投放市场。字段规范根据法规由人工编写，并非欧盟官方文件，授权法案仍在陆续出台。本文不构成法律建议。

二次利用电池

经过改造、再制造或再利用的电池需要一个与原始护照关联的新护照（《电池法规》第 77(7) 条）。向 tracepass_passports create 传入 lineage 块：

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

前序护照通过 internalPassportId（你自己的护照之一）或可解析的 identifier 指定。trigger 可以是 preparation_for_reuse、preparation_for_repurposing、repurposing 或 remanufacturing。平台会根据触发项推导 batteryStatus，以不可变方式存储该块，并将你自己的原始护照反向链接到新护照（successors）。在 2027 年 2 月 18 日之前投放市场的电池没有原始护照：请发送空列表并附上 noPredecessorReason。违反规则时会返回状态码为 422 的响应，并附带规则代码。

电池测量数据（持续更新的记录）

capture_measurements 会将你自己的设备采集的电池全生命周期数据写入已发布的电池护照：健康状态、衰减、循环次数、动态值、电量状态、负面事件、温度历史记录（《电池法规》附件 XIII 第 4 点）。每条测量数据都会保留；每个字段中最新的数据会成为护照的当前值，并设置 dynamicDataAsOf。可通过 list_measurements 和 latest_measurements 读取这些数据。

这些数据会计入套餐的每月测量额度，而不是每日写入额度。付费套餐超过额度后仍会继续计数，但不收费；Free 套餐达到额度后会停止。读取护照不会计量收费。

关于写入的说明

有些操作会产生费用或不可逆——服务器的工具描述会告知模型：

• tracepass_passports create 会创建草稿护照。草稿不会占用套餐的 DPP 名额，也不会计费；发布护照时才会占用名额，超出套餐上限的部分也会在此时计费。每次 create 都会计入每日写入额度。
• tracepass_passports archive 不可逆——公开二维码将永久返回 404。如果更改可能需要撤销，请使用可逆的 suspend。
• tracepass_epcis — export、capture 和 query 适用于所有套餐，包括 Free；采集的事件会计入套餐的事件额度，超过额度时，capture 会返回超额提示或硬性阻止提示。

资源

只读实体数据，可作为对话上下文附加：

• tracepass://products — 产品目录
• tracepass://product/{id} — 单个产品
• tracepass://passport/{id} — 单个护照的完整字段详情
• tracepass://passport/{id}/epcis — 某个护照的 EPCIS 2.0 事件
• tracepass://passport/{id}/compliance — 某个护照的合规判定
• tracepass://passport/{id}/registry-readiness — 参照欧盟 DPP 注册库正式准入门槛进行的机械式提交前检查：必填字段是否存在、格式是否正确、公开链接是否可解析、是否达到单件级粒度（不检查商品编码：电池护照的注册标识符不会填写在海关申报单中）。这不是实质性合规判定，也不预测实际注册库的响应——其注册 API 尚无公开规范。仅适用于电池。
• tracepass://passport/{id}/snapshots — 护照的快照历史记录（最新的在前）：发布时以及每次修改非草稿护照后都会生成快照；每条记录包含版本、原因（例如 published、field_edit、status_change、baseline）、操作者、snapshotAt、contentHash、hashValid（读取时重新验证）、restorable 标记和字段数量。
• tracepass://templates — 全部 13 种 DPP 类别的字段架构
• tracepass://template/{category} — 某一类别的完整字段架构

提示词

客户端以斜杠命令形式提供的可复用 DPP 工作流：

• 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 <token>。该令牌仅授权这一次请求；无需账户，也不使用 OAuth。之后，助手可以使用以下工具：

工具	功能
get_request	从这里开始：谁在请求、针对哪种产品、请求的每个字段及其含义、单位、格式和法律依据；还包括已提交的答复和审核结果
validate_answers	试运行：将存储哪些内容、哪些键未被请求，以及哪些内容不符合要求。不会写入任何内容
get_upload_command	当助手可以运行 shell 命令时，附加数据表或证书的最佳方式：返回一条 curl 命令，从磁盘上传文件并打印可供引用的 documentId（支持 PDF、Office、CSV、PNG/JPEG/WebP）
upload_evidence	将很小的文件（几 KB）以 base64 格式内联附加；优先使用 get_upload_command，或引用 URL 或备注
submit_answers	将每项答复及其证据发送给请求方进行人工审核；审核前可以重复提交（答复会合并）
get_review_status	请求方是否已审核、审核结果、已接受的字段，以及链接何时过期

答复会提交给请求方进行人工审核；不会自行发布任何内容。

DPP 助手：欧盟护照相关问题

第三个端点面向所有拥有免费 TracePass 账户的用户，回答有关欧盟数字产品护照法规的问题：

https://ai.tracepass.eu/compliance/mcp

将其添加为 AI 助手的自定义连接器（在 Claude 中：Customize → Connectors → "+ Add" → "Add custom connector"），然后按提示使用 TracePass 账户登录。该服务使用 OAuth；无需 API 密钥。答复会注明来源，每家公司每天大约可获得 100 条答复。完整指南： tracepass.eu/docs/dpp-assistant。

工具	功能
scope_check	欧盟法律是否要求某类产品提供护照、从何时开始，以及对各个角色有哪些要求
required_fields	某类产品的护照必须包含的数据、要求每个字段的条款，以及哪些人可以查看这些数据
what_changed	自某个日期以来，适用于你所在类别的欧盟护照法规和标准的变化；计划中的事项会标明尚未成为法律
registry_guidance	欧盟 DPP 注册处及技术相关内容：注册、标识符、数据载体、格式和标准
create_draft_passport	在你自己的账户中创建一份草稿护照；发布仍由你在 TracePass 中完成
report_answer	举报你认为有误或不清楚的答复，以供审核
get_profile、update_profile、delete_profile	助手会在不同问题之间记住的公司信息，避免你重复提供

开发

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

托管服务是一个纯 Node HTTP 服务器（dist/http.js），采用无状态设计——每个请求都携带自己的 API 密钥，并创建一个全新的 MCP 会话。服务通过 Dockerfile 容器化；托管端点运行在欧盟境内。

已在 Glama 上架

此服务已发布于官方 MCP 注册表， 名称为 eu.tracepass/tracepass，并已在 Glama 上架：

许可证

MIT