Supply Chain Decision Intelligence MCP

A local, deterministic MCP research project for high-reliability hardware supply-chain analytics. It demonstrates how an LLM can ask supply-chain questions in natural language while SQL/Python tools—not the model—own the quantitative answer.

The problem this demonstrates solving: supply-chain and manufacturing-ramp decisions (which supplier to qualify, whether a part will stock out before replenishment arrives, whether cheapest-first or dual-sourcing is worth the premium) require joining supplier, inventory, purchase-order, and quality data and running consistent, auditable math — not an LLM's best guess. This project shows that pattern end-to-end on a synthetic dataset: the LLM only chooses which governed calculation to run and narrates the result.

Synthetic data only. This repository does not contain real Zipline supplier, production, demand, customer, or operational data. It is a methodology demo inspired by public supply-chain problem patterns: supplier performance, ramp forecasting, MRP shortage risk, source concentration, landed cost, fleet-capacity screening, medical replenishment, and multi-year supplier capacity.

Why this design

flowchart LR
  Q["Natural-language research question"] --> L["LLM chooses a tool"]
  L --> M["MCP typed interface"]
  subgraph D["Deterministic analytics boundary"]
    M --> A["Governed SQL / Python"]
    A --> C["Checked-in synthetic CSVs"]
    A --> R["Structured result + trust block"]
  end
  R --> L2["LLM interprets the result"]

The model chooses which governed calculation to call and explains the result. The model does not recreate MAPE, OTD, weeks of cover, landed cost, or capacity math from memory.

See docs/ARCHITECTURE.md for the fully-labeled version of this diagram (explicitly distinguishing the probabilistic LLM layer from the deterministic governed layer), a complete MCP tool map (all 13 tools -> the datasets each one reads), and a worked example decision flow. See docs/DATA_MODEL.md for the entity-relationship diagram.

Tool surface

Tool	Decision question
list_research_questions	What can this governed dataset answer?
supplier_scorecard	Which suppliers underperform on OTD + quality?
forecast_accuracy	Is the ramp forecast inaccurate, biased, or improving?
parts_at_risk	Which parts can stop the line inside lead time?
dual_source_risk	Where is single-source exposure concentrated?
compare_landed_costs	Does sticker-price advantage survive tariff/freight/transit carrying cost?
dock_capacity	How many aircraft are needed to stay away from the queueing wall?
stockout_reduction	How does shorter replenishment change synthetic stockout exposure?
capacity_ramp	What does cheapest-first vs 60/40 resilience cost, and where is the capacity wall?
projected_shortage_risk	Which parts cross zero inside the next eight weeks after open POs and expected yield?
quality_gate_risk	Which APQP/PPAP gates threaten the ramp?
quality_rush_signal	Does late/rushed supply show worse defect PPM?
quality_trend	Is quality deteriorating over a true trailing seven-day date window?

There is also a research://catalog MCP resource plus supply_chain_investigation and supply_chain_question_generator prompts.

Local first: the exact path that avoided earlier MCP setup failures

This project intentionally uses a runtime pattern that has proved robust in earlier local MCP builds:

• no database file is built during startup
• no .venv is shipped
• no .mcp.json is shipped
• every data path is derived from server.py via __file__
• DuckDB creates fresh in-memory views over checked-in CSVs
• uv run --with ... makes dev/stdio launch independent of editable-install metadata

1. Preflight

cd <where-you-cloned-this-repo>
uv sync --extra dev
uv run python scripts/preflight.py

You want PREFLIGHT PASSED.

2. Launch in MCP Inspector

./scripts/run_mcp_dev.sh

Approve dependency installation if uv asks. MCP Inspector should open with 13 tools.

Recommended first calls:

1. supplier_scorecard with limit=5
2. forecast_accuracy
3. parts_at_risk with limit=10
4. dual_source_risk
5. compare_landed_costs
6. dock_capacity
7. stockout_reduction
8. capacity_ramp
9. projected_shortage_risk with horizon_weeks=8
10. quality_gate_risk
11. quality_rush_signal
12. quality_trend

3. Smoke-test the analytics without Claude

uv run python scripts/smoke_test.py

Executive web app

A local, static "Production Ramp Intelligence" application built on these same governed tools -- ramp readiness, critical-part risk, source concentration, and a capacity/qualification decision view, each traceable to the MCP tool call behind it:

uv run python scripts/generate_executive_dataset.py
uv run python scripts/serve_executive_site.py

Then open http://127.0.0.1:8765/. See docs/EXECUTIVE_APP.md.

Running the tests

uv sync --extra dev
uv run pytest -q

This runs data-integrity checks, tool-behavior assertions, runtime-contract checks, and the JSON-safety/packaging/preflight regression suite — see docs/CODE_WALKTHROUGH.md ("Tests: what each file actually proves") for what each test file specifically verifies.

4. Register with Claude Code only after Inspector works

./scripts/register_claude.sh
claude

Inside Claude Code run /mcp. You should see zipline-supply-chain connected with 13 tools.

Then use a prompt such as:

Act as a supply-chain analyst. Start with list_research_questions. Use only the zipline-supply-chain MCP tools for quantitative evidence. Tell me which supplier/part risks matter most for the manufacturing ramp, what the evidence says, what is interpretation, and what the synthetic data cannot establish. Do not inspect raw CSVs or recompute the metrics yourself.

Example research questions

This dataset separates two intertwined supply chains:

Manufacturing: supplier performance, forecast bias, MRP shortage, dual-source concentration, landed cost, and multi-year capacity.

Operational logistics: peak dock fleet capacity and medical stockout reduction.

That separation is built into the tools and prompt discipline.

See DEMO_QUESTIONS.md and PROMPTS.md.

Documentation map

Full file tree: docs/REPOSITORY_GUIDE.md.

Doc	What it covers
docs/ARCHITECTURE.md	System/MCP architecture, tool map, entity relationships, and a worked decision-flow — all as GitHub-renderable Mermaid diagrams
docs/CODE_WALKTHROUGH.md	Implementation walkthrough: every tool's inputs/logic/outputs, SQL/DuckDB patterns, JSON safety, error handling, and design tradeoffs, cross-referenced to server.py
docs/DATA_MODEL.md	What each CSV represents, foreign-key relationships, the entity-relationship diagram, deterministic generation/seeds, and two intentional, documented quirks: (1) capacity_ramp distinguishes currently-qualified supplier capacity from a candidate/hypothetical second source, and (2) inventory.csv's current run rate and capacity_plan.csv's forward-looking ramp target are independent planning bases not meant to numerically reconcile
docs/RESEARCH_METHODS.md	The formula/definition behind every analytical tool (scorecard weights, landed-cost formula, MAPE/bias, etc.)
docs/LIMITATIONS.md	What this project deliberately does not claim
docs/LOCAL_RUNBOOK.md	Ordered local setup steps and troubleshooting
docs/RUNTIME_DESIGN_LESSONS.md	Why the runtime is built the way it is (no startup DB build, no persistent connection, etc.)
docs/EXECUTIVE_APP.md	The local executive web app: architecture, how to run it, and exactly which governed tool call backs each chart

What this project does not claim

It is not a production ERP/MRP, a route optimizer, an aerospace qualification system, a causal impact study, or real company data. The point is governed analytical boundaries for LLM-assisted decision support.

Integrity / reproducibility checks

The synthetic relational model guarantees: receipt and quality facts carry valid (part_id, supplier_id) keys, qualification gates use true supplier-master IDs, every PO uses a valid part-supplier mapping, and inventory has exactly one row per part. See data/MANIFEST.json/DATASET_VERSION for the current dataset version.

Run before the MCP (also covered by scripts/preflight.py):

uv run python scripts/audit_data_relationships.py
uv run python scripts/generate_synthetic_facts.py --check

The first checks foreign keys, composite relationships, uniqueness, and important reference anchors (fixed values this dataset is designed to reproduce). The second regenerates the stochastic/enriched fact tables from fixed seeds and master fixtures and byte-compares them with the checked-in outputs.

The server itself contains no runtime randomness. Given the checked-in CSVs, tool outputs are deterministic. This is reproducible synthetic research data, not a claim that the synthetic distributions are statistically representative of Zipline.

Dataset scale

The 12-week demand.csv is the exact governed ramp case behind the reference anchors; annual_demand.csv adds 52 deterministic weekly observations for longer rolling-error analysis, exposed via forecast_accuracy(series="annual_52w"), so it does not silently change the 12-week worked example.

The synthetic part universe spans 60 parts across 14 commodity families — intentionally demonstration-scale: enough observations for meaningful inventory and sourcing rankings, still small enough to inspect and explain live.