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.

Related MCP server: Fabric MCP Agent

Tool surface

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.

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.