mcp-logistics-tracker — 物流追跡MCPラッパー（参照系・最小PoC）

[既定はモック動作 / AfterShip 経由で実接続も可能] 既定では MockAdapter による決定的モック動作です（APIキー不要）。 AFTERSHIP_API_KEY を設定すると AfterShip（追跡アグリゲーター）経由で ヤマト / 佐川 / 日本郵便に実接続します（外部HTTP通信が発生・詳細は下記）。 国内3社は公開追跡REST APIを持たない（法人契約/申請制）ため、アグリゲーター 経由が実接続の現実解です。

配送業者の追跡番号を渡すと配送状況を返す MCP（Model Context Protocol）サーバーです。 Claude Desktop などの AI エージェントから、自然言語で 「この追跡番号どうなってる？」を実行できるようにします。

型1: 参照系ラッパー。 状態照会・履歴取得のみを行い、更新系（再配達依頼等）は 実装しません。保守リスクを最小化するスコープに絞った最小 PoC です。

---

何ができるか（提供ツール）

ツール	説明
list_carriers()	対応配送業者（ヤマト運輸 / 佐川急便 / 日本郵便）の一覧を返す
track_shipment(carrier, tracking_number)	現在の配送状況（最新ステータス）を整形テキストで返す
get_tracking_history(carrier, tracking_number)	配送イベント履歴（発送→輸送中→配達完了）を時系列で返す

戻り値はすべて人間可読の日本語整形テキストです（生 JSON は返しません）。 AI エージェントに生 JSON を渡すと余計なキーや推測ノイズを足すため、 そのまま読み上げられる整形済みテキストに固定しています。

出力例（track_shipment）

【ヤマト運輸】追跡番号 123456789012

現在の状況: 配達完了（配達完了 ✓）
最終更新: 2026/07/06 14:03
場所: 世田谷営業所
詳細: 配達が完了しました

---

動作モード: モック / AfterShip 実接続

本 PoC は CarrierAdapter 抽象境界の内側でアダプタを差し替えて動作します。

モード	有効条件	挙動
モック（既定）	APIキー無し	MockAdapter がリアルな偽データを決定的に返す。ネットワーク非依存で完全動作。
AfterShip 実接続	AFTERSHIP_API_KEY 設定	AfterShipAdapter が AfterShip 経由で JP3社に実接続（外部HTTP通信が発生）。

• 実 API キーは不要。 キーが無くても完全動作します（既定はモック）。
• ヤマト / 佐川 / 日本郵便は公開追跡REST APIを持たない（法人契約/申請制）ため、 実接続は AfterShip（追跡アグリゲーター）経由で行います。AfterShip は APIキーのみで即利用でき、JP3社を含む多数キャリアに対応します。
• 直接キャリアAPIキー（YAMATO_API_KEY 等）用の分岐は残していますが、直接接続 アダプタは未実装です（設定すると NotImplementedError で明示的に失敗し、 AfterShip 経由の利用を促します）。

---

セットアップと実行手順

Python 3.11+ が必要です。以下は uv を使う例です （pip / venv でも同様に可能です）。

cd poc/mcp-logistics-tracker

# 仮想環境を作成
uv venv --python 3.11 .venv

# 依存をインストール（本体 + 開発ツール）
VIRTUAL_ENV=.venv uv pip install -e ".[dev]"

# テスト実行
VIRTUAL_ENV=.venv .venv/bin/python -m pytest --cov=mcp_logistics_tracker

# MCP サーバーを stdio で起動（Claude Desktop 等がこのプロセスを起動する）
VIRTUAL_ENV=.venv .venv/bin/python -m mcp_logistics_tracker.server

pip を使う場合: python3.11 -m venv .venv && .venv/bin/pip install -e ".[dev]"

CLI からの手動確認（任意）

MCP クライアント無しでコアロジックだけ試す例:

PYTHONPATH=src .venv/bin/python -c "
from mcp_logistics_tracker import service
print(service.track_shipment_text('yamato', '123456789012'))
print(service.get_tracking_history_text('sagawa', '998877665544'))
"

---

Claude Desktop への登録方法

Claude Desktop の設定ファイル（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json）に以下を追記します。

※ <ABS_PATH> は本PoCディレクトリの絶対パス（例: /Users/yourname/Dev/ai-secretary）に必ず置換してください。そのまま貼り付けると起動に失敗します。

{
  "mcpServers": {
    "logistics-tracker": {
      "command": "<ABS_PATH>/poc/mcp-logistics-tracker/.venv/bin/python",
      "args": ["-m", "mcp_logistics_tracker.server"],
      "env": {
        "PYTHONPATH": "<ABS_PATH>/poc/mcp-logistics-tracker/src"
      }
    }
  }
}

pip install -e . 済みなら PYTHONPATH は不要で、コンソールスクリプト mcp-logistics-tracker を command に指定することもできます。

登録後に Claude Desktop を再起動し、「yamato の 123456789012 を追跡して」のように 話しかけると track_shipment が呼ばれます。

---

実接続（AfterShip 経由）

AFTERSHIP_API_KEY を設定すると AfterShipAdapter が有効になり、AfterShip Tracking API 経由で JP3社に実接続します。実装は src/mcp_logistics_tracker/adapters.py の AfterShipAdapter、配線は server.py の _build_adapter() にあります。

# .env.example をコピーして値を設定（.env は .gitignore 済み）
cp .env.example .env
# .env の AFTERSHIP_API_KEY に AfterShip のキーを設定
# キー取得: https://organization.automizely.com/api-keys

API キーは必ず環境変数から読みます（os.environ["AFTERSHIP_API_KEY"]）。 ハードコードは禁止です。

環境変数

環境変数名	用途	挙動
AFTERSHIP_API_KEY	AfterShip 経由の実接続（推奨）	設定時に AfterShipAdapter が有効化。JP3社へ実接続（外部HTTP通信が発生）。
YAMATO_API_KEY	直接キャリア接続（未実装）	単独設定時は _build_adapter() が NotImplementedError を送出。
SAGAWA_API_KEY	直接キャリア接続（未実装）	同上。
JAPANPOST_API_KEY	直接キャリア接続（未実装）	同上。

分岐の優先順位: AFTERSHIP_API_KEY あり → AfterShip 実接続 / 無くて直接 キャリアキーあり → NotImplementedError（AfterShip 利用を促す）/ いずれも無し → MockAdapter（既定・モック動作）。

AfterShip API の確認済み仕様

AfterShip 公式ドキュメントで確認した実仕様（2026-07 時点）:

項目	値
ホスト	https://api.aftership.com（HTTPS のみ）
認証	as-api-key ヘッダに API キー
追跡取得	GET /tracking/{version}/trackings/{slug}/{tracking_number}
API バージョン	日付形式（例 2025-07）。constants.AFTERSHIP_API_VERSION でピン留め
レート制限	GET系は 5 req/sec。超過で 429
レスポンス	Body Envelope（meta + data.tracking）
配達完了判定	tracking.tag == "Delivered"（Delivery Statuses enum の9値の1つ）
キャリア slug	ヤマト(国内 TA-Q-BIN)=taqbin-jp / 佐川=sagawa / 日本郵便=japan-post

未確認（防御的実装）: 429 の待機秒ヘッダ名（Retry-After 優先→ x-ratelimit-reset 算出→既定値にフォールバック）、エラー本文の meta.code/meta.message の正確なフィールド名（本実装は HTTP ステータスのみで UpstreamError に変換し本文構造に依存しない）、data のラップキー（tracking 優先・無ければ data 直下）は、公式 SPA ドキュメントで実サンプルまで取得できず、 AfterShip の一般的慣行に基づき防御的にパースしています。ヤマトは総称 slug yamato も併存するため、国内 TA-Q-BIN 前提で taqbin-jp を採用しています。 実キーでの疎通確認は上司判断（本 PoC はHTTPモックでの検証まで）。

レート制限とバックオフ方針

AI エージェントはツールを高頻度で叩くため、上流エラーは構造化して返します。 実アダプタ側では指数バックオフを推奨します:

wait = min(BACKOFF_BASE_SECONDS * 2 ** attempt, cap)   # attempt = 0..BACKOFF_MAX_RETRIES
# RateLimitError.retry_after_seconds が返る場合はそれを優先する

---

保守に関する免責

• 本 PoC はモック動作を前提とした実装であり、実キャリア API への接続・ その API バージョン追従保守は含みません。
• 各社 API の仕様変更（認証方式・エンドポイント・レート制限・レスポンス形式）への 追従は別途保守契約の範囲とします。
• 追跡データの正確性・可用性は各配送業者の提供する API に依存します。

---

動作確認済み環境

項目	値
OS	macOS (darwin, Apple Silicon)
Python	3.11.6
mcp パッケージ	1.28.1（FastMCP デコレータ記法 / mcp.server.fastmcp.FastMCP）
トランスポート	stdio（mcp.run(transport="stdio")）
テスト	pytest 9.1.1 — 31 passed（AfterShipAdapter はrespxでHTTPモック・ネットワーク非依存）
Lint / 型	ruff・mypy strict ともにクリーン

mcp の import パス・ツール登録デコレータ（@mcp.tool()）・起動 API は インストール済みパッケージ（1.28.1）の実ソースで確認済みです。 別バージョンでは API が異なる可能性があります。

---

プロジェクト構成

mcp-logistics-tracker/
├── README.md
├── pyproject.toml          # ruff + mypy + pytest 設定込み
├── .gitignore              # venv / __pycache__ / .env を除外
├── .env.example            # 実APIキーのテンプレート（PoCでは未使用）
├── src/mcp_logistics_tracker/
│   ├── __init__.py
│   ├── constants.py        # 名前付き定数（マジックナンバー排除）
│   ├── models.py           # dataclass モデル + 構造化エラー
│   ├── adapters.py         # CarrierAdapter 抽象境界 + MockAdapter + AfterShipAdapter（実接続）
│   ├── formatting.py       # 整形テキスト生成（人間可読）
│   ├── service.py          # コアロジック（MCP非依存・検証/エラー変換）
│   └── server.py           # FastMCP 配線 + stdio 起動（mcpに依存する唯一の層）
└── tests/
    ├── test_adapters.py
    ├── test_aftership_adapter.py   # AfterShipAdapter（respxでHTTPモック）
    ├── test_formatting.py
    └── test_service.py

コアロジック（adapters / formatting / service / models）は mcp パッケージに 依存しないため、mcp 無しでもテスト可能です。 server.py のみがトランスポート層として mcp に依存します。