TracePass

TracePass MCP サーバー

Model Context Protocol サーバーです。 TracePass — EU デジタル製品パスポートのプラットフォームに対応しています。AI アシスタント（Claude、Cursor、IDE エージェント）を使って、製品、デジタル製品パスポート、経済事業者の関係者、GS1 EPCIS 2.0 のサプライチェーンイベントを管理できます。

MCP プロトコルの全機能に対応しています — ツール、リソース、リソーステンプレート、プロンプトです。

2 通りの利用方法

同じサーバーコアを、次の 2 通りの方法で利用できます。

1. ホステッド — MCP クライアントの接続先に https://ai.tracepass.eu/mcp を指定します。 インストール不要で、常に最新です。
2. ローカル（npm） — npx 経由で tracepass-mcp-server を実行します。MCP クライアントがサブプロセスとして起動し、stdio 経由で MCP 通信を行います。

認証

サーバーは、同じ Authorization: Bearer … ヘッダーで TracePass の v1 認証方式 2 種類のどちらかを受け付けます。受信した内容をそのまま 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 を取得してください。多くのホステッドクライアントは、Dynamic Client Registration を使って自動的に自己登録します。

必要なスコープのみをリクエストしてください。例：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 - デジタル製品パスポートを管理します（一覧表示、取得、コンプライアンスチェック、レジストリ登録準備状況の確認、状態フラグの取得／設定、作成、一時停止、アーカイブ、QR の取得、スナップショットの一覧表示、スナップショットの取得）。ID またはシリアル番号で操作します。パスポートは GS1 または追加の 4 つの 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 カテゴリのフィールドスキーマを一覧表示して取得します。各フィールドには、そのフィールドを義務付ける EU の法令が記載されています。
• 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 の範囲内でのみ一意です。そのため、アカウント内の 2 つの GTIN で同じシリアル番号が使われている場合、シリアル番号のみを指定した呼び出しは 409 ambiguous_serial を返します。曖昧さを解消するには、任意の gtin 引数を指定してください（または ID 指定のアクションを使用してください）。同じ gtin による識別は、すべての *_by_serial アクションに適用されます。

tracepass_passports の compliance アクションは、規制の引用を含む検出結果とともに、3 段階のコンプライアンス判定（compliant／compliant_with_warnings／incomplete）を返します。検出結果には、必須フィールドの不足、経済事業者の不足、形式上の問題、カテゴリごとの条件付きルールが含まれます。このアクションは読み取り専用です。パスポートの不足項目を確認し、指摘された不足を修正してから、再度チェックしてください。

compliant の判定は、このパスポートがここで定義されたルールを満たしていることを意味するものであり、この製品を市場に投入できることを意味するものではありません。フィールドの仕様は規制に基づき手作業で作成したもので、EU の公式な成果物ではありません。また、委任法令は現在も策定中です。これは法的助言ではありません。

セカンドライフバッテリー

再利用、再製造、またはリユースされたバッテリーには、元のパスポートに関連付けられた新しいパスポートが必要です（Battery Regulation Art. 77(7)）。tracepass_passports の create に lineage ブロックを渡します。

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

前身のバッテリーは、internalPassportId（自分が発行したパスポートの1つ）または解決可能な identifier で指定します。trigger には、preparation_for_reuse、preparation_for_repurposing、repurposing、remanufacturing のいずれかを指定します。プラットフォームはトリガーから batteryStatus を導出し、ブロックを不変の状態で保存して、自分が発行した元のパスポートを新しいパスポートに関連付けます（successors）。2027年2月18日より前に市場に投入されたバッテリーには元のパスポートがありません。その場合は、noPredecessorReason とともに空のリストを送信します。ルール違反の場合、ルールコードとともに 422 が返されます。

バッテリーの測定値（更新され続ける記録）

capture_measurements は、稼働期間中のデータを自社の設備から公開済みバッテリーパスポートに送信します。対象となるのは、健全性、劣化、サイクル数、動的値、充電状態、マイナスの事象、温度履歴です（Battery Regulation Annex XIII point 4）。測定値はすべて保持されます。各フィールドの最新の値がパスポートの現在値になり、dynamicDataAsOf が設定されます。list_measurements と latest_measurements で測定値を読み戻せます。

測定値は、1日の書き込み上限ではなく、プランの月間測定上限に対してカウントされます。有料プランでは上限を超えても追加料金なしでカウントが続きますが、Free プランでは上限に達すると停止します。パスポートの読み取りには料金が発生しません。

書き込みに関する注意

一部の操作は有料、または取り消し不能です。サーバーのツールの説明で、その旨がモデルに通知されます。

• tracepass_passports の create はドラフトのパスポートを作成します。ドラフトはプランの DPP 枠を消費せず、課金もされません。枠と、プラン上限を超過した場合の超過分は、TracePass ダッシュボードでパスポートを公開した時点で消費されます。create は毎日の書き込み上限に対してカウントされます。
• tracepass_passports の archive は取り消し不能です。公開 QR は恒久的に 404 になります。変更を取り消す可能性がある場合は、可逆的な suspend を使用してください。
• tracepass_epcis — export、capture、query は Free を含むすべてのプランで利用できます。キャプチャしたイベントはプランのイベント上限に対してカウントされ、上限を超えた capture では超過、またはハードブロックのメッセージが返されます。

リソース

会話のコンテキストとして添付できる、読み取り専用のエンティティデータです。

• tracepass://products — 製品カタログ
• tracepass://product/{id} — 1つの製品
• tracepass://passport/{id} — 1つのパスポートの全フィールド詳細
• 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} — 1つのカテゴリの完全なフィールドスキーマ

プロンプト

クライアントがスラッシュコマンドとして表示する、再利用可能な 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> も使用できます。トークンが認証するのは、そのリクエスト 1 件のみです。アカウントも OAuth も必要ありません。すると、アシスタントで次の操作ができるようになります：

ツール	機能
get_request	まずここから始めます。誰がどの製品について何を求めているのか、依頼されたすべての項目の意味、単位、形式、法的根拠、さらに送信済みの回答とレビュー結果を確認できます
validate_answers	ドライランを実行します。保存される内容、依頼されていないキー、適合しない内容を確認できます。書き込みは行いません
get_upload_command	アシスタントがシェルコマンドを実行できる場合に、データシートや証明書を添付する最適な方法です。ディスク上のファイルをアップロードし、引用用の documentId を出力する curl コマンドを返します（PDF、Office、CSV、PNG/JPEG/WebP）
upload_evidence	数キロバイト程度のごく小さなファイルを base64 形式でインライン添付します。get_upload_command の使用を推奨します。または URL や注記を引用してください
submit_answers	値ごとに根拠資料を添えて回答を依頼者の人によるレビューに送信します。レビューが行われるまでは、繰り返し送信できます（回答はマージされます）
get_review_status	依頼者がレビューしたかどうか、結果、承認された項目、リンクの有効期限を確認します

回答は依頼者の人によるレビューに送られます。回答だけで公開されることはありません。

DPP アシスタント：EU パスポートに関する質問

3 つ目のエンドポイントでは、TracePass の無料アカウントを持つすべてのユーザーを対象に、EU デジタル製品パスポートの法規制に関する質問に回答します：

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

カスタムコネクターとして AI アシスタントに追加し（Claude の場合：Customize → Connectors → "+ Add" → "Add custom connector"）、求められたら TracePass アカウントでサインインしてください。OAuth を使用するため、API キーは不要です。回答には出典が記載され、各企業は 1 日あたり約 100 件の回答を得られます。詳しいガイド： tracepass.eu/docs/dpp-assistant。

ツール	機能
scope_check	製品の種類ごとに、EU 法でパスポートが必要か、いつから必要か、各役割にどのような要件があるかを確認します
required_fields	カテゴリーごとにパスポートに必要なデータ、各項目を義務付ける条文、閲覧できるユーザーを確認します
what_changed	指定日以降に、対象カテゴリーの EU パスポート法規制と規格に加えられた変更を確認します。予定されている項目には、まだ法律ではないことが明記されます
registry_guidance	EU 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 を使ってコンテナ化されており、ホストされたエンドポイントは EU 内で稼働します。

Glama に掲載

このサーバーは、公式 MCP レジストリに eu.tracepass/tracepass として公開され、Glamaにも掲載されています。

ライセンス

MIT