Import Sourcing Advisor

ウクライナ向けのマクロレベルの輸入調達スクリーニングのためのドメイン特化型データエージェントです。 どの国から製品グループを調達すべきかを尋ねると、オープンな貿易データを通じてその質問を処理します。つまり、どの原産地が実際に供給しているか、その供給がどの程度集中しているか、各候補の陸揚げコスト、そして候補同士のランキングを提示します。

エージェントは2つのMCP接続によって拡張されています：

すべては機密情報を含まない公開データで動作し、カスタムサーバーはどのようなAPI認証情報も必要としません。

最初に表示されるもの

チャットボックスではなく、ワークリストです。追跡対象の輸入ラインが6件あり、それぞれ1行で、リスク帯と金額の順に並んでいます。主要サプライヤー、そのシェア、そのシェアの価値、背後にある実効的な原産地の数、そして一言のステータスが表示されます。行を開くと、その場で原産地の詳細が展開されます。エージェントの実行はそこから意図的に行うアクションです。

リストの上には集計の帯があります。現在のウィンドウでは、554m USDが輸入され、そのうち346mがラインごとに単一の原産地に集中しており（62%）、6ラインのうち3ラインでトルコが首位 — 露出額は183mです。最後の数字は、どの製品別レポートにも表示できないものです。つまり、一緒に失敗するラインを示しています。

リストは推論ではなく計算されています。web/portfolio.py は、エージェントが使用するのと同じカスタムサーバーへのMCP stdioセッションを1つ開き、モデルを介さずにツールを直接呼び出します。訪問者が最初に読み込む画面は、エージェントを待つ必要も、コストがかかることもありません。

通貨。 年間貿易系列は約2年遅れるため、リストは月次レポートから構築された直近12か月のローリングウィンドウで動作し、ソースが実際に公開した月で終了します — 現在は2024年10月から2025年9月で、最新の完全な年間年より約11か月先行しています。これは見た目だけの問題ではありません。2024年の年間データでは、生トマトは71.8%がトルコ産で単一ソースフラグが付きましたが、ウィンドウでは64.6%となり、フラグは付きません。

Related MCP server: supply-chain-mcp-server

前提条件

3つのデータAPIのいずれにもキー、トークン、アカウントは不要です。

インストール

git clone <repository-url> logistics_mcp
cd logistics_mcp

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt

ブラウザサーバーとChromiumビルドを一度インストールします（PATHにNode 18+が必要）：

npm install
npx -y playwright install chromium

npm install は @playwright/mcp を固定し、エージェントはそれを node node_modules/@playwright/mcp/cli.js として起動します。npx は使用しません。Windowsには npx という実行可能ファイルが存在せず、Nodeはシェルなしで npx.cmd を起動することを拒否するため、その名前でサーバーを起動すると静かに失敗しました — 実行は続行され、モデルはブラウザツールがないと報告しました。npm install がない場合、エージェントは npx -y @playwright/mcp@latest にフォールバックします。これはPOSIXシェルが解決できる環境で動作します。

設定

cp .env.example .env

.env はgit無視されます。カスタムMCPサーバーにはその中の何も必要ありません。値はエージェントとデータ転送モードにのみ影響します。

各コンポーネントを個別に実行する

カスタムMCPサーバーは独立したプロセスであり、単独で起動されます。エージェントに依存するものは何もありません。

1. カスタムMCPサーバー

python -m mcp_server.server

stdioでMCPを提供し、起動時にトランスポートとデータモードをstderrに出力します。エージェントなしで公開される契約を検査するには：

python scripts/inspect_tools.py           # summary of all five tool contracts
python scripts/inspect_tools.py --json    # full input and output JSON schemas

または公式インスペクタで操作します：

npx -y @modelcontextprotocol/inspector python -m mcp_server.server

2. Playwright MCPサーバー

エージェントがこれを自ら起動します。検査のためだけに手動で実行します。

node node_modules/@playwright/mcp/cli.js --headless --isolated

3. エージェントとウェブアプリケーション

python -m web.app          # serves http://127.0.0.1:8000

ウェブアプリは両方のMCP接続を子プロセスとして起動し、それぞれが公開したツールを表示します。

インストールの検証

python -m pytest tests -q        # 47 unit tests, no network, ~2s
python scripts/smoke_tools.py    # calls every tool end to end against the live APIs
REPLAY=1 python scripts/smoke_tools.py   # the same run, offline, from fixtures
python scripts/run_e2e.py        # the whole agent flow, both MCP servers, live
python scripts/run_failure_demo.py       # the same flow with the browser server broken

run_e2e.py はデモが依存するチェックです。両方のサーバーが接続され、5つすべてのカスタムツールが実際に呼び出されない限り、実行を失敗させます。カスタムサーバーが起動に失敗した場合でも、モデルがツールがないと報告するだけで、流暢な回答が生成されます。すべてのイベントは scripts/last_e2e_trace.jsonl に書き込まれるため、実行を信頼するのではなく後で検査できます。完全な実行は約10分、20ターン、約$0.55です。フォールバックの再帰URLでのナビゲーション失敗は、チェーン内の別のページが読み込まれた場合に許容されます — チェーンは順序付けられており、エージェントは最初に応答したページで停止します — しかし、何も読み込まれなかったチェーン、およびカスタムサーバーからのすべてのエラーは、実行を失敗させます。

run_failure_demo.py はもう半分です。ブラウザをフォールバックなしの解決不可能なホストに向け、ナビゲーションがエラーとして報告され、他にエラーがなく、失敗したチェックが名前付きで推奨事項がまだ出てくる場合にのみ合格します。要件は何も失敗しないことではなく、失敗が空の回答と区別できることです。

オフライン / リプレイモード

カスタムサーバーは3つのネットワークAPIを呼び出すため、実際のレスポンスは fixtures/ の下に記録され、ネットワークアクセスなしでリプレイできます：

# Offline
SOURCING_MODE=replay python -m mcp_server.server

# Re-record after changing a query
SOURCING_MODE=record python scripts/smoke_tools.py

置換はトランスポート境界（mcp_server/sources/http.py）で行われます。リプレイはネットワークが返したのと同じ生のJSONを返し、その上のすべてのパーサー、重複排除ステップ、計算は変更されずに実行されます。準備された回答を返すコードパスはありません。

各フィクスチャは、正確なURL、取得タイムスタンプ、逐語的なレスポンスボディを記録したエンベロープです。

オフラインでカバーされるもの。 ポートフォリオ、ランディング画面に表示される各製品のランキング、およびエージェントフロー。1つの製品のランキングをライブとリプレイで実行し、すべてのフィールドを比較して検証済み：最後の小数まで同一です。このチェックは維持する価値があります — これが以下の関税バグを発見した方法であり、ランキングフィクスチャが記録される前は、オフラインスコアの崩壊もこれで発見されました。

カバーされないもの。 参照ウィンドウは1つだけ記録されています（2024年10月 – 2025年9月）。そのため、他の任意のトレーリングウィンドウのリクエストは、フォールバックではなくオフラインで失敗します。2つの製品には、どちらのモードでも価格設定できない候補があります — アーモンドのUSAとNLD、キウイフルーツのAZEは重量を報告しないため、導出する単位価値が存在しません。これらの行は画面上で不完全とマークされ、注意書きに名前が挙げられています。これはソースのギャップであり、記録のギャップではありません。

データソース

検証済みのエンドポイントの動作、レート制限、癖は docs/01-data-sources-verified.md に文書化されています。

リポジトリ構成

mcp_server/          Custom MCP server (separate process)
  server.py          Five tool registrations, stdio entry point
  models.py          Pydantic input/output contracts
  sources/           http (rate limit, cache, fixtures), comtrade, worldbank, wits, reference
  domain/            costing and analysis calculations
agent/               Claude Agent SDK wiring, two model tiers, trace events
web/                 FastAPI application, portfolio over MCP, single-page UI
  app.py             Endpoints: portfolio, commodity detail, agent run, chat
  portfolio.py       The tracked lines, queried over an MCP stdio session
  index.html         Portfolio screen, line detail, MCP trace, chat panel
data/reference/      Vendored HS2022 and country reference data
fixtures/            Recorded genuine API responses for replay mode
scripts/             inspect_tools, smoke_tools, run_e2e
tests/               Unit tests
docs/                Requirements digest, verified sources, contracts, rationale, demo script

ドキュメント

既知の制限事項

後段に埋もれさせるのではなく、最初に明記する:

• 運送費はモデル計算による値であり、引用値ではない。 運送料金を公開しているオープンソースは存在しない。モデル化されたすべての数値は、ツール出力ではestimatedとラベル付けされる。

• 関税はMFN税率である。 WITSは特恵税率に対してHTTP 404を返すため、EU DCFTAなどの協定は適用可能性ありとしてフラグ付けされるが、適用はされない。

• 年次系列は約2年遅れている。 2026年8月時点で、ウクライナは2024年分を報告済みだが2025年分は未報告だった。月次系列は2025年9月まで到達しており、ワークリストはこちらを使用する。ランディングコスト計算ツールとランキングツールは依然として年次ベースで動作し、関税もまたさらに古い観測値から取得される——各結果は使用したベースを明示する。

• ユニットバリューは価格ではない。 Comtradeのユニットバリューは、総価値を総重量で割ったものであり、相場ではない。

• Logistics Performance Indexは年次系列ではない。 2022年が最新の観測値である。

• 税関のページは自動化されたクライアントをブロックする。 customs.gov.uaは、Akamaiエッジにおいて人間のブラウザ以外からのアクセスにはHTTP 403を返す一方、人間がアクセスすれば正常に開く。そのため、最新性の確認ステップはNational Bankの対外部門ページにフォールバックし、エージェントは実際に読んだページを明示する。これにより公開時期は確認できるが取引額は確認できないため、最新性チェックは偶然ではなく設計上部分的なものとなる。

• ポートフォリオは6品目で、シグナルを重視して選定されている。 リンゴ（HS 080810、$0.5M）と殻付きくるみ（HS 080231、ほぼゼロ）は除外された: ウクライナはこの両方を生産・輸出しているため、これらの輸入品目はノイズとなる。

• これはスクリーニングツールである。 調査に値する国のリストを絞り込むものであり、入札を代替するものではない。