Import Sourcing Advisor

Ein domänenspezifischer Daten-Agent für makroskopisches Import-Sourcing-Screening für die Ukraine. Fragen Sie ihn, aus welchen Ländern eine Produktgruppe bezogen werden sollte, und er arbeitet die Frage anhand offener Handelsdaten durch: welche Ursprünge sie tatsächlich liefern, wie konzentriert dieses Angebot ist, was jeder Kandidat geliefert kosten würde und wie die Kandidaten im Vergleich zueinander abschneiden.

Der Agent wird über zwei MCP-Verbindungen erweitert:

Alles läuft mit öffentlichen Daten ohne vertrauliche Eingaben, und der eigene Server benötigt keinerlei API-Anmeldedaten.

What you see first

Eine Arbeitsliste, kein Chatfenster. Sechs verfolgte Importpositionen, jeweils eine Zeile, sortiert nach Risikostufe und dann nach Geldbetrag: Hauptlieferant, dessen Anteil, was dieser Anteil wert ist, wie viele effektive Ursprünge dahinterstehen, und ein Ein-Wort-Status. Beim Öffnen einer Zeile werden die Ursprungsdetails direkt an Ort und Stelle erweitert; der Agent-Lauf ist von dort aus eine bewusste Aktion.

Über der Liste ein Streifen mit Aggregaten. Im aktuellen Fenster: 554 Mio. USD importiert, davon 346 Mio. in einem einzigen Ursprung pro Position konzentriert (62 %), und die Türkei führt 3 der 6 Positionen an — 183 Mio. des Engagements. Diese letzte Zahl ist diejenige, die kein produktbezogener Bericht zeigen kann: Positionen, die gemeinsam ausfallen würden.

Die Liste wird berechnet, nicht erschlossen. web/portfolio.py öffnet eine MCP-stdio-Sitzung zu demselben eigenen Server, den auch der Agent verwendet, und ruft die Tools direkt auf, ohne Modell in der Schleife. Der erste Bildschirm, den ein Besucher lädt, sollte nicht auf einen Agenten warten oder etwas kosten.

Aktualität. Die jährliche Handelsreihe hinkt etwa zwei Jahre hinterher, daher läuft die Liste auf einem rollierenden Zwölfmonatsfenster, das aus Monatsberichten aufgebaut ist und mit dem Monat endet, den die Quelle tatsächlich veröffentlicht hat — derzeit Okt. 2024 bis Sep. 2025, etwa elf Monate neuer als das letzte vollständige Jahresdatum. Das ist nicht kosmetisch: Bei den Jahresdaten 2024 weisen frische Tomaten 71,8 Prozent türkischen Ursprungs auf und trugen ein Einzelquellen-Flag; im Fenster weisen sie 64,6 Prozent auf und tun das nicht.

Related MCP server: supply-chain-mcp-server

Voraussetzungen

Für keine der drei Daten-APIs ist ein Schlüssel, Token oder Konto erforderlich.

Installation

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

Browser-Server und eine Chromium-Build einmal installieren (Node 18+ im PATH):

npm install
npx -y playwright install chromium

npm install pinnt @playwright/mcp, und der Agent startet es dann als node node_modules/@playwright/mcp/cli.js. Es läuft nicht über npx: Unter Windows gibt es keine ausführbare Datei namens npx, und Node weigert sich, npx.cmd ohne Shell zu starten, sodass das Starten des Servers unter diesem Namen stillschweigend fehlschlug — der Lauf wurde fortgesetzt und das Modell meldete, es habe kein Browser-Tool. Ohne npm install fällt der Agent auf npx -y @playwright/mcp@latest zurück, was funktioniert, wo eine POSIX-Shell es auflöst.

Konfiguration

cp .env.example .env

.env ist git-ignoriert. Nichts darin ist für den eigenen MCP-Server erforderlich; die Werte betreffen nur den Agenten und den Datentransportmodus.

Die Komponenten unabhängig ausführen

Der eigene MCP-Server ist ein separater Prozess und wird eigenständig gestartet. Nichts an ihm hängt vom Agenten ab.

1. Eigener MCP-Server

python -m mcp_server.server

Er bedient MCP über stdio und gibt beim Start seinen Transport- und Datenmodus auf stderr aus. Um die Verträge, die er veröffentlicht, ganz ohne Agenten zu inspizieren:

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

Oder steuern Sie ihn mit dem offiziellen Inspector:

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

2. Playwright-MCP-Server

Der Agent startet diesen selbst; führen Sie ihn nur von Hand aus, um ihn zu inspizieren.

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

3. Agent und Web-Anwendung

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

Die Web-App startet beide MCP-Verbindungen als Kindprozesse und zeigt, welche Tools jede davon bereitgestellt hat.

Installation überprüfen

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 ist die Prüfung, auf der die Demo beruht. Sie lässt den Lauf fehlschlagen, sofern nicht beide Server verbunden waren und alle fünf eigenen Tools tatsächlich aufgerufen wurden — ein Lauf, bei dem der eigene Server nicht startete, erzeugt trotzdem eine flüssige Antwort, weil das Modell einfach meldet, es habe keine Tools. Jedes Ereignis wird in scripts/last_e2e_trace.jsonl geschrieben, damit der Lauf anschließend geprüft werden kann, statt ihm zu vertrauen. Ein vollständiger Lauf dauert etwa 10 Minuten, 20 Runden und kostet etwa 0,55 $. Eine fehlgeschlagene Navigation auf einer Fallback-Aktualitäts-URL wird toleriert, sobald eine andere Seite in der Kette geladen wurde — die Kette ist geordnet und der Agent stoppt bei der ersten Seite, die antwortet — aber eine Kette, in der nichts geladen wurde, sowie jeder Fehler vom eigenen Server lassen den Lauf weiterhin fehlschlagen.

run_failure_demo.py ist die andere Hälfte: Es richtet den Browser auf einen nicht auflösbaren Host ohne Fallbacks und besteht nur, wenn die Navigation als Fehler meldet, nichts anderes fehlschlägt und dennoch eine Empfehlung herauskommt, in der die fehlgeschlagene Prüfung genannt wird. Die Anforderung ist nicht, dass nichts fehlschlägt — sondern dass ein Fehlschlag von einer leeren Antwort unterscheidbar ist.

Offline-/Wiedergabemodus

Der eigene Server ruft drei Netzwerk-APIs auf, daher werden echte Antworten unter fixtures/ aufgezeichnet und können ohne Netzwerkzugriff wiedergegeben werden:

# Offline
SOURCING_MODE=replay python -m mcp_server.server

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

Die Substitution erfolgt an der Transportgrenze (mcp_server/sources/http.py): Die Wiedergabe reicht dasselbe rohe JSON zurück, das das Netzwerk geliefert hat, und jeder Parser, jeder Deduplizierungsschritt und jede Berechnung darüber läuft unverändert. Kein Codepfad liefert eine vorbereitete Antwort.

Jedes Fixture ist ein Umschlag, der die genaue URL, den Abrufzeitstempel und den wörtlichen Antworttext aufzeichnet.

Was offline abgedeckt ist. Das Portfolio, das Ranking jedes Produkts, wie es der Einstiegsbildschirm zeigt, und der Agent-Ablauf. Verifiziert, indem das Ranking eines Produkts live und in der Wiedergabe ausgeführt und jedes Feld verglichen wurde: bis zur letzten Dezimalstelle identisch. Diese Prüfung ist es wert, behalten zu werden — so wurde der Zollfehler unten gefunden, und bevor die Ranking-Fixtures aufgezeichnet wurden, wurden auf diese Weise auch die kollabierten Offline-Werte gefunden.

Was es nicht abdeckt. Es ist nur ein Referenzfenster aufgezeichnet (Okt. 2024 – Sep. 2025), daher schlägt eine Anfrage für ein anderes nachlaufendes Fenster offline fehl, statt auf etwas zurückzufallen. Zwei Produkte enthalten einen Kandidaten, der in keinem der beiden Modi bepreist werden kann — USA und NLD für Mandeln, AZE für Kiwis melden kein Gewicht, sodass kein Stückwert abzuleiten ist. Diese Zeilen werden auf dem Bildschirm als unvollständig markiert und in einem Hinweis genannt; sie sind eine Lücke in der Quelle, nicht in der Aufzeichnung.

Datenquellen

Verifiziertes Endpunktverhalten, Ratenlimits und Eigenheiten sind in docs/01-data-sources-verified.md dokumentiert.

Repository-Struktur

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

Dokumentation

Bekannte Einschränkungen

Im Voraus genannt, statt sie zu verstecken:

• Frachtkosten sind modelliert, nicht eingeholt. Keine offene Quelle veröffentlicht Frachtraten. Jede modellierte Zahl ist im Tool-Ausgang als geschätzt gekennzeichnet.

• Zölle sind der MFN-Satz. WITS liefert für Präferenzabkommen einen HTTP-404-Fehler, daher werden Abkommen wie das EU-DCFTA als möglich markiert, aber nicht angewendet.

• Die Jahresreihe hinkt etwa zwei Jahre hinterher. Im August 2026 hatte die Ukraine Daten für 2024 gemeldet, aber nicht für 2025. Die Monatsreihe reicht bis September 2025, und genau die nutzt die Arbeitsliste. Die Fracht- und Ranglisten-Tools laufen weiterhin auf Jahresbasis, und der Zoll stammt aus einer älteren Beobachtung — jedes Ergebnis nennt die Grundlage, die es verwendet hat.

• Stückwerte sind keine Preise. Ein Comtrade-Stückwert ist Gesamtwert geteilt durch Gesamtgewicht, nicht ein Angebotspreis.

• Der Logistikleistungsindex ist keine Jahresreihe. 2022 ist die letzte Beobachtung.

• Die Zollseite blockiert automatisierte Clients. customs.gov.ua antwortet an seiner Akamai-Kante mit HTTP 403 auf alles, was kein menschlicher Browser ist, während sie sich für einen Menschen normal öffnet. Der Aktualitätsschritt weicht daher auf die Außenwirtschaftsseite der Nationalbank aus, und der Agent benennt die Seite, die er tatsächlich gelesen hat. Das bestätigt den Veröffentlichungsstand, aber nicht eine Umsatzzahl, daher ist die Aktualitätsprüfung bewusst nur eine Teillösung.

• Das Portfolio umfasst sechs Positionen, ausgewählt wegen ihrer Aussagekraft. Äpfel (HS 080810, 0,5 Mio. USD) und Walnüsse in der Schale (HS 080231, nahe null) wurden gestrichen: Die Ukraine erzeugt und exportiert beides, daher sind ihre Importpositionen Rauschen.

• Dies ist ein Screening-Tool. Es grenzt eine Liste von Ländern ein, die eine genauere Untersuchung lohnen; es ersetzt keine Ausschreibung.