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 です。

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

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

出力例（track_shipment）

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

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

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

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

• 実 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 実接続 / 無くて直接 キャリアキーあり → NotImplementedError（AfterShip 利用を促す）/ いずれも無し → MockAdapter（既定・モック動作）。

AfterShip API の確認済み仕様

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

未確認（防御的実装）: 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 に依存します。

動作確認済み環境

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 に依存します。