内容
# TracePass MCP 服务器
[](https://glama.ai/mcp/servers/malinoto/tracepass-mcp-server)
[](https://smithery.ai/servers/malinoto/tracepass-mcp-server)
一个 <a href="https://modelcontextprotocol.io">模型上下文协议（MCP）</a> 服务器，用于 **<a href="https://www.tracepass.eu">TracePass</a>** —— 欧盟数字产品护照平台。它允许 AI 助手（Claude、Cursor、IDE 代理）管理产品、数字产品护照、经济运营方和 GS1 EPCIS 2.0 供应链事件。
它支持完整的 MCP 协议 —— **工具**、**资源**、**资源模板** 和 **提示**。
## 使用方式
同一个服务器核心提供了两种使用方式：
1. **托管服务** —— 将您的 MCP 客户端指向 `https://ai.tracepass.eu/mcp`。无需安装；始终保持最新。
2. **本地（npm）** —— 通过 `npx` 运行 `tracepass-mcp-server`。MCP 客户端将其作为子进程启动，并通过标准输入输出进行 MCP 通信。
## 身份验证
服务器接受 TracePass 的两种 v1 身份验证方法，均使用相同的 `Authorization: Bearer …` 头部 —— 它将您发送的内容转发到 API，由 API 决定。请选择适合您的连接方式：
| | **API 密钥** | **OAuth 2.0** |
|---|---|---|
| 适合 | 单个用户、脚本、服务器到服务器 | AI 助手 / 应用 **代表用户** |
| 您发送的内容 | 作为 Bearer 令牌的静态 `tp_…` 密钥 | 通过 OAuth 流程获得的限定访问令牌 |
| 设置 | 在 **开发者 → API 密钥** 中生成 | 用户点击 **连接** 并批准权限 |
| 权限范围 | 全部或 nothing（整个工作区） | 用户授予的权限范围；可撤销 |
| 适用场景 | 托管 **和** 本地（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`，该 URL 指向 TracePass 授权服务器。 客户端运行标准 **authorization-code flow with PKCE**（`/api/oauth/authorize` → `/api/oauth/token`），用户批准权限范围，客户端存储并刷新令牌。 如果您分发自己的客户端，请在 **开发者 → OAuth 应用** 下注册一个应用以获取 `client_id`；许多托管客户端通过动态客户端注册自动注册。
仅请求您需要的权限范围，例如 `passports:read passports:write offline_access`。 用户在 **开发者 → OAuth 应用 → 已连接的应用** 下管理已连接的应用（并撤销权限）。
### API 密钥
在 **开发者 → API 密钥** 下生成一个 `tp_…` 密钥，并将其作为 Bearer 令牌发送。
**托管服务：**
```json
{
"mcpServers": {
"tracepass": {
"url": "https://ai.tracepass.eu/mcp",
"headers": { "Authorization": "Bearer tp_YOUR_KEY" }
}
}
}
```
**本地（npx / stdio）** —— 本地子进程无法执行交互式 OAuth 同意步骤，因此仅限使用 API 密钥，通过 `TRACEPASS_API_KEY` 环境变量：
```json
{
"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 操作分为 **6 种工具**。每种工具都接受一个操作枚举和操作特定的参数。工具有：
- `tracepass_products` - 管理产品目录（列出、获取、创建、更新产品）。
- `tracepass_passports` - 管理数字产品护照（列出、获取、合规性检查、创建、暂停、存档、获取二维码），按 ID 或序列号。
- `tracepass_passport_fields` - 更新护照的类别特定数据字段，按 ID 或序列号。
- `tracepass_passport_parties` - 设置或删除护照的经济运营方（制造商、进口商等）。
- `tracepass_epcis` - 导出、捕获和查询护照的 GS1 EPCIS 2.0 供应链事件。
- `tracepass_templates` - 列出和获取 DPP 类别监管字段模式。
每种工具的完整操作集：
| 工具 | 操作 |
|------|---------|
| `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` |
| `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 ID 来寻址护照。序列号在 **一个 GTIN 内唯一**，因此如果同一个序列号存在于您的帐户中的两个 GTIN 下，则仅返回序列号的调用 **409 `ambiguous_serial`** —— 传递可选的 `gtin` 参数来消除歧义（或使用按 ID 的操作）。 同样的 `gtin` 消歧器适用于每个 `*_by_serial` 操作。
**`tracepass_passports` `compliance`** 操作返回一个三层合规性判决（`compliant` / `compliant_with_warnings` / `incomplete`），并附有法规引用的发现结果 —— 缺少必填字段、缺少经济运营方、格式问题和每个类别的条件规则。 只读；使用它来检查护照的差距，修复引用的差距，然后重新检查。
### 关于写入的说明
某些操作 **需要付费或不可逆转** —— 服务器的工具描述会告知模型：
- **`tracepass_passports` `create`** 消耗帐户计划中的一个可计费 DPP 插槽。 超出配额的创建会产生每个护照的超额费用；工具会显示类似 402 的消息，只有在用户同意后才继续执行 `args.confirmOverage: true`。
- **`tracepass_passports` `archive`** 是不可逆转的 —— 公共二维码永久 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://templates` —— 所有 12 个 DPP 类别的监管模式
- `tracepass://template/{category}` —— 一个类别的完整字段模式
## 提示
客户端作为斜杠命令显示的可重用 DPP 工作流程：
- `audit_passport` —— 审查护照的完整性和合规性准备情况
- `onboard_product` —— 创建产品及其第一个护照
- `explain_dpp_requirements` —— 解释一个类别的合规 DPP 必须包含的内容，以及每个字段背后的法规
- `compliance_gap_check` —— 生成一个按优先级排序的、法规引用的列表，列出阻止护照发布的内容
- `review_epcis_events` —— 总结护照的供应链轨迹
## 开发
```bash
npm install
npm run build # tsc -> dist/
npm run typecheck
npm test # vitest
npm run lint
npm start # 在本地运行托管的 HTTP 服务（:8080）
npm run start:stdio # 在本地运行 stdio 服务器
```
托管服务是一个普通的 Node HTTP 服务器（`dist/http.js`），无状态 —— 每个请求都携带自己的 API 密钥并建立一个新的 MCP 会话。 它通过 `Dockerfile` 进行容器化并部署到 Hetzner；参见 `tracepass-environment/docker-mcp.yml`。
## 已在 Glama 上列出
该服务器已在 <a href="https://registry.modelcontextprotocol.io">官方 MCP 注册表</a> 中发布为 `eu.tracepass/tracepass`，并在 <a href="https://glama.ai/mcp/servers/malinoto/tracepass-mcp-server">Glama</a> 上列出：
[](https://glama.ai/mcp/servers/malinoto/tracepass-mcp-server)
## 许可证
MIT
