mcpField
T
track17

track17

github.com/tristanmanchesterその他3102 回インストール7 週間前に更新
リポジトリ

track17 について

付属の Python コマンドラインツールで17TRACKを利用するスキルです。ポーリング、荷物管理、認証済みWebhookを扱い、ローカル保存やリモート変更の明示的な制御も説明します。

主な機能

  1. 01追跡番号と配送業者による荷物管理
  2. 02追跡状況とクォータのポーリング
  3. 03署名検証済みWebhookの受信
  4. 04追跡更新の保存と重複排除
  5. 05イベント時刻と更新時刻の区別

活用シーン

  1. 01複数の配送業者の荷物状況確認
  2. 02認証済み17TRACKプッシュの処理
  3. 03同期未完了時に更新なしと誤認せず確認

MCP 対応

入力ではスキルとコマンドラインの手順が説明されていますが、MCP連携についての記載はありません。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/tristanmanchester/agent-skills --skill track17

インストール後、Claude Code で/track17を入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

README.md
scripts/
track17.py
tests/
test_review_regressions.py
test_track17.py

詳細

17TRACK で荷物を追跡

SKILL_DIR をこのスキルのインストールディレクトリに解決します。ストレージや署名の処理を再実装せず、同梱の CLI を使用してください。コマンドは JSON を返します。終了ステータスがゼロ以外の場合は、失敗または同期が未完了であることを意味します。

セットアップ

ホストのシークレットストアまたは環境変数を通じて TRACK17_TOKEN を設定し、決して表示しないでください。TRACK17_DATA_DIR には、リポジトリ外のプライベートな絶対パスを設定します。その後、次を実行します。

python3 "$SKILL_DIR/scripts/track17.py" init
python3 "$SKILL_DIR/scripts/track17.py" --help

このリビジョンでは新しいローカルスキーマを使用します。packages を含む古いデータベースは変更されずに拒否されます。新しいデータディレクトリを選び、古いレコードをローカルで確認またはエクスポートして、ユーザーが引き続き追跡を希望する荷物だけを登録してください。古いデータベースを削除したり、すべてを自動的に再登録したりしないでください。プロバイダーの利用枠を消費する可能性があります。

通常のワークフロー

プッシュ配信が必要でない限り、ポーリングを優先してください。追加や削除を行う前に、現在の荷物リストを読み取ります。荷物は、推測したローカル ID ではなく、追跡番号と配送業者コードの組み合わせで特定してください。

python3 "$SKILL_DIR/scripts/track17.py" list
python3 "$SKILL_DIR/scripts/track17.py" carriers-search DHL
python3 "$SKILL_DIR/scripts/track17.py" add RR123456789CN --label "Headphones"
python3 "$SKILL_DIR/scripts/track17.py" sync
python3 "$SKILL_DIR/scripts/track17.py" status RR123456789CN --carrier 3011 --refresh
python3 "$SKILL_DIR/scripts/track17.py" quota

上記の配送業者番号は例であり、汎用の既定値ではありません。自動検出で配送業者を特定できない場合は --carrier を使用してください。--param は、その配送業者が追加情報を必要とする場合にのみ使用してください。登録が成功しても、追跡イベントがすでに取得可能とは限りません。

stop、retrack、remove には、追跡番号と --carrier が必要です。--delete-remote を明示的に指定しない限り、remove はローカルのみで実行されます。リモートでの削除を実行する前に、ユーザーに確認してください。ネットワーク障害が発生し、結果が不明な場合は、変更を再試行する前にプロバイダーの状態を照合してください。このクライアントは書き込み操作を自動的に再実行しません。

認証済み Webhook

17TRACK は、元のボディのバイト列の後に / と API セキュリティキーを連結し、SHA-256 で署名します。署名は sign ヘッダーで送られます。このヘルパーは TRACK17_TOKEN をそのキーとして使用します。無関係な別の Webhook シークレットを作成したり、プロバイダーのアルゴリズムを HMAC に置き換えたりしないでください。

キャプチャ済みの配信データを扱う場合は、ボディを変更せずに保持し、実際の署名を指定してください。

python3 "$SKILL_DIR/scripts/track17.py" ingest-webhook --file delivery.json --signature "$DELIVERY_SIGN"

プッシュ配信の場合：

python3 "$SKILL_DIR/scripts/track17.py" webhook-server --port 8789

受信側はループバックにバインドされます。意図的に設定した TLS リバースプロキシを前段に配置し、sign と生のボディをそのまま保持してください。開発用サーバーを不用意に公開しないでください。認証ヘッダーが欠落している場合、無効な場合、または重複している場合は失敗します。データベーストランザクションのコミット後にのみ、受信が承認されます。ストレージ障害時には、プロバイダーが再試行できるよう失敗レスポンスを返します。署名なしでのインポート経路や、後で処理する受信トレイプロセッサーはありません。

同一の配信データは冪等に処理されます。日付の古い更新が、より新しい日付のスナップショットを上書きすることはありません。ただし、順序があらゆる場合に保証されるわけではありません。タイムスタンプでは、同時刻の訂正を解決できず、日付のない更新が最新であることも証明できません。イベント時刻とローカルでの受信時刻は分けて報告してください。

報告

配達完了、配達中、集荷、配達失敗、例外を優先してください。配送業者、イベント時刻、最後に成功した更新を含め、新しいプロバイダーレスポンスと保存済みの状態を区別してください。部分的な同期やイベントの欠落は、不完全な証拠として扱い、「変更なし」とみなさないでください。無関係な荷物や古いスナップショットから配達日を推測しないでください。

情報源と確認

17TRACK API ドキュメント（2026-09-13 確認）には、署名方式が記載され、v2.2 が引き続きオンラインで提供されることが明記されています。このヘルパーは、意図的にそのサポート対象のレスポンス仕様を維持しています。v2.4 は、追加の登録フィールドが異なるため、バージョン文字列を変更するだけでは置き換えられません。

オフラインおよびループバック HTTP の回帰テストを実行します。

python3 -m unittest discover -s "$SKILL_DIR/tests" -v

updated_at はスナップショットの変更時刻を記録し、last_refreshed_at はスナップショットに変更がない場合も含め、最後に受け入れられたポーリングレスポンスの時刻を記録します。どちらも配送業者のイベント時刻ではありません。Webhook の受信や重複排除は、ポーリングの成功としてカウントされません。

コメント

Markdown 対応