Supply Chain Decision Intelligence MCP

一个本地、确定性的 MCP 研究项目，用于高可靠性硬件供应链分析。它演示了 LLM 如何用自然语言提出供应链问题，同时由 SQL/Python 工具——而非模型——负责定量答案。

该项目演示解决的问题： 供应链和制造爬坡决策（选择哪家供应商进行认证、某个零件是否会在补货到达前出现缺货、最便宜优先还是双源供应是否值得付出溢价）都需要关联供应商、库存、采购订单和质量数据，并执行一致、可审计的计算——而不是依赖 LLM 的估算。本项目在合成数据集上端到端演示了这一模式：LLM 只选择运行哪一个可治理受控的计算，并对结果进行叙述。

仅含合成数据。 本仓库不包含真实的 Zipline 供应商、生产、需求、客户或运营数据。它仅是一个受公共供应链问题模式启发的方法学演示：供应商绩效、爬坡预测、MRP 短缺风险、供应集中度、到岸成本、船队容量筛选、医疗补货，以及多年期供应商产能。

为什么这样设计

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"]

模型选择调用哪一个可治理计算，并解释结果。模型不会凭记忆重算 MAPE、OTD、周数覆盖、到岸成本或产能公式。

有关此图的完整标注版本（明确区分概率性 LLM 层与确定性可治理层）、完整的 MCP 工具映射（全部 13 个工具 -> 每个工具读取的数据集）以及一个逐步执行的决策流程示例，请参阅 docs/ARCHITECTURE.md。实体关系图请参阅 docs/DATA_MODEL.md。

Related MCP server: Fabric MCP Agent

工具列表

另外还有 research://catalog MCP 资源，以及 supply_chain_investigation 与 supplychain_chain_question_generator 提示词。

本地优先：成功规避此前 MCP 配置失败的路径

本项目有意采用一种在早期本地 MCP 构建中被证明稳定可靠的运行模式：

• 启动时不构建任何数据库文件

• 不附带 .venv

• 不附带 .mcp.json

• 所有数据路径均从 server.py 通过 __file__ 推导

• DuckDB 在签入的 CSV 之上创建全新的内存视图

• uv run --with ... 使开发/标准输入启动不依赖可编辑安装元数据

1. 预检

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

你应看到 PREFLIGHT PASSED。

2. 在 MCP Inspector 中启动

./scripts/run_mcp_dev.sh

如果 uv 询问，请允许依赖项安装。MCP Inspector 应打开并显示 13 个工具。

推荐的首批调用：

1. supplier_scorecard，传参 limit=5

2. forecast_accuracy

3. parts_at_risk，传参 limit=10

4. dual_source_risk

5. compare_landed_costs

6. dock_capacity

7. stockout_reduction

8. capacity_ramp

9. projected_shortage_risk，传参 horizon_weeks=8

10. quality_gate_risk

11. quality_rush_signal

12. quality_trend

3. 在 Claude 之外对分析功能进行冒烟测试

uv run python scripts/smoke_test.py

可执行 Web 应用

一个基于这些同一套受控治理工具构建的本地、静态 “Production Ramp Intelligence 可执行 Web 应用”——包含爬坡就绪、关键零件风险、供应集中度，以及产能 质量/资格 决策视图，每个视图都可追踪到其背后的 MCP 工具调用：

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

然后打开 http://127.0.0.1:8765/。参阅 docs/EXECUTIVE_APP.md。

运行测试

uv sync --extra dev
uv run pytest -q

这将运行数据完整性检查、工具行为断言、运行时契约检查，以及 JSON 安全性/打包/预检回归套件——关于每个测试文件分别证明什么，请参阅 docs/CODE_WALKTHROUGH.md（“每个文件实际证明了什么”）。

4. 仅在 Inspector 工作正常后才向 Claude Code 注册

./scripts/register_claude.sh
claude

在 Claude Code 中运行 /mcp。你应该看到 zipline-supply-chain 已连接并带有 13 个工具。

然后使用类似下面这样的提示：

以供应链分析师的身份。从 listresearch_questions 开始。定量证据仅使用 zipline-supply-chain MCP 工具。告诉我哪些供应商/零件风险对制造爬坡最重要，证据说明了什么，哪些是解读、哪些是合成数据无法建立的，并且不要直接查看原始 CSV。

示例研究问题

该数据集将两条交织的供应链区分开：

制造： 供应商绩效、预测偏差、物料短缺、双源集中度、到岸成本、多年度产能。

运营物流： 峰值船坞船队容量与医疗补货缺货下降。

这种区分已内置到工具和提示规则中。

参见 DEMO_QUESTIONS.md 和 PROMPTS.md。

文档地图

完整文件树：docs/REPOSITORY_GUIDE.md。

本项目不声称能做什么

它不是实际的生产系统，覆盖正式的 ERP/MRP、铁路优化、角色匹配、因果影响，或者真实公司数据。其重点在于 为 LLM 辅助决策提供受控分析边界。

完整性与可复现性检查

（末尾无其他内容，按原样处理并严格保留原文中所有保留词。）

合成关系模型保证：收货与质量事实表携带有效的 (part_id, supplier_id) 键，资格认定门使用真实的供应商主数据（supplier-master）ID，每个 PO 都使用有效的零件-供应商映射，且库存中每个零件恰好一行。有关当前数据集版本，请参阅 data/MANIFEST.json/DATASET_VERSION。

在 MCP 之前运行（也由 scripts/preflight.py 覆盖）：

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

第一项检查外键、复合关系、唯一性以及重要的参考锚点（本数据集旨在复现的固定值）。第二项使用固定随机种子和主数据夹具重新生成随机/增强事实表，并与检入的输出进行字节比较。

服务器本身不含运行时随机性。在给定已检入 CSV 的情况下，工具输出是确定性的。这是可复现的合成研究数据，而不是声称这些合成分布在统计上能代表 Zipline。

数据集规模

12 周的 demand.csv 是参考锚点背后的精确受治理爬坡场景；annual_demand.csv 为更长期的滚动误差分析添加了 52 个确定性的周观测值，并通过 forecast_accuracy(series="annual_52w") 公开，因此它不会悄悄改变 12 周的工作示例。

合成零件域涵盖 14 个物料族中的 60 个零件——刻意采用演示规模：有足够的观测值用于得出有意义的库存与寻源排名，同时规模仍足够小，便于实时检查和讲解。