Supply Chain Disruption Monitor

An MCP server exposing supply chain intelligence tools, with a PydanticAI agent that synthesizes them to answer disruption questions.

Demo scenario: "What disruptions could affect shipments from Shanghai to Rotterdam right now?"

The agent calls multiple tools, synthesizes the results, and produces a structured risk assessment — demonstrating that the value is in the reasoning across sources, not any single data lookup.

Built as a self-training project and portfolio artifact.

---

Tech stack

Layer	Choice	Notes
MCP server	Python MCP SDK (mcp)	FastMCP decorator API, stdio transport
Agent framework	PydanticAI	MCPToolset + StdioTransport to wire agent → server
LLM	qwen2.5:7b via Ollama	Local, reliable tool calling
Vessel data	AISStream.io	Free WebSocket AIS feed
Weather	Open-Meteo	Free, no API key
News	NewsAPI	Free tier (100 req/day)
Port congestion	Mocked	Realistic synthetic data

---

Setup

1. Prerequisites

• Python 3.11+
• uv — pip install uv or brew install uv
• Ollama — for the local LLM

2. Install dependencies

cd supply-chain-disruption-monitor
uv sync

3. Pull the model

ollama pull qwen2.5:7b

4. Configure API keys

cp .env.example .env

Edit .env and fill in:

• AISSTREAM_API_KEY — Free at aisstream.io. Provides real-time vessel positions via WebSocket AIS feed.
• NEWS_API_KEY — Free at newsapi.org. 100 requests/day on the free tier.

The weather tool (Open-Meteo) needs no key.

---

Running

MCP server (standalone — for development / MCP Inspector)

uv run mcp dev server.py

This opens the MCP Inspector in your browser so you can call tools interactively.

Agent only

Note: agent.py is a sample MCP client, not part of the server itself. It plays the same role Claude Desktop, Codex, or any other MCP client would — it launches server.py over stdio, runs the agent loop against a local model (Ollama), and synthesizes the tool results. The server is the deliverable; the agent is just one interchangeable consumer of it. It imports nothing from server.py and talks to it purely over the MCP protocol, so you can swap in any other MCP client without touching the server.

# Default query: Shanghai to Rotterdam risk assessment
uv run agent.py

# Custom query
uv run agent.py "What risks affect container ships transiting the Red Sea?"

Full demo (tool outputs + agent synthesis)

uv run demo.py              # tools + agent
uv run demo.py --tools-only # just raw tool outputs
uv run demo.py --agent-only # just the agent synthesis

---

MCP tools

Tool	Source	Returns
list_major_ports(region)	Static	Major ports by region — use this first to identify route waypoints
get_port_weather(port_name)	Open-Meteo	Current conditions + 24h forecast, wind speed in knots, operational impact
get_vessel_positions(region)	AISStream.io	Live vessel snapshot: MMSI, name, position, speed, nav status
search_disruption_news(query, days)	NewsAPI	Recent headlines + high-signal flag (strikes, attacks, blockages)
get_port_congestion(port_name)	Mocked	Utilization %, queue depth, wait hours, trend, advisory

The agent synthesizes across all five — there is no single assess_route_risk tool. The multi-tool reasoning is the point.

---

Add this server to Claude Desktop

Add to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "supply-chain-monitor": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/supply-chain-disruption-monitor", "python", "server.py"],
      "env": {
        "AISSTREAM_API_KEY": "your_key_here",
        "NEWS_API_KEY": "your_key_here"
      }
    }
  }
}

---

Project structure

supply-chain-disruption-monitor/
├── server.py           # FastMCP server — all 5 tools
├── agent.py            # Sample MCP client (PydanticAI) — interchangeable with Claude Desktop, Codex, etc.
├── demo.py             # Demo script (tool outputs + agent synthesis)
├── tools/
│   ├── ports.py        # Static port data + coordinates (27 major ports)
│   ├── weather.py      # Open-Meteo integration
│   ├── vessels.py      # AISStream.io WebSocket integration
│   ├── news.py         # NewsAPI integration
│   └── congestion.py   # Mocked port congestion (realistic synthetic data)
├── pyproject.toml
├── .env.example
└── README.md

---

Design notes

Why mock port congestion? Live data (MarineTraffic, FreightWaves) requires enterprise subscriptions (£100+/month). Mocking gives full demo control — a "Shanghai congestion spike" can be shown without paywall friction. The tool interface is identical to what a real API would return.

Why AISStream.io? It's a free, real-time WebSocket AIS feed. A vessel actually moving through the South China Sea is a better demo moment than a static mock.

Why qwen2.5:7b? Reliable tool-calling behavior at a size that runs well on consumer hardware (16 GB RAM). Swap in any model with Ollama support by changing OLLAMA_MODEL in .env.

Why PydanticAI? PydanticAI co-maintains the official Python MCP SDK, so using their stack is thematically coherent. MCPServerStdio is the native path for agent → MCP server wiring.