Supply Chain Decision Intelligence MCP

ローカルで動作し、決定的（deterministic）な MCP 研究プロジェクトであり、高信頼性ハードウェアのサプライチェーンアナリティクスを対象としています。LLM が自然言語でサプライチェーンの質問を尋ねる一方で、定量的な答えはモデルではなく SQL／Python ツールが担う、という仕組みを実証しています。

このプロジェクトが解決することを示す問題: サプライチェーンと製造立ち上げ（ramp）に関する判断（どのサプライヤーを認定するか、補充が到着する前に部品が品切れになるか、最安優先調達とデュアルソーシングのどちらが割増料金（プレミアム）に見合うか）には、サプライヤー・在庫・発注・品質のデータを結合し、一貫性のある監査可能な計算を実行することが必要です。それは LLM の見当推測ではありません。このプロジェクトは、そのパターンを合成データセット上でエンドツーエンドに示します。LLM は、どの統制対象（governed）計算を実行するかを選び、その結果を説明するだけです。

合成データのみ。 このリポジトリには、実際の 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"]

モデルは、どの管理統制（governed）計算を呼び出すかを選択し、その結果を説明します。モデルが MAPE、OTD、在庫カバー週数、ランデッドコスト、または容量の計算を記憶から再現することはありません。

この図の完全なラベル付き版（確率的 LLM レイヤーと決定的な統制レイヤーを明示的に区別したもの）、完全な MCP ツールマップ（全部で 13 個のツール → それぞれが読み取るデータセット）、および段階を追った意思決定フローの例については、docs/ARCHITECTURE.md を参照してください。エンティティ関係図については docs/DATA_MODEL.md を参照してください。

Related MCP server: Fabric MCP Agent

ツール一覧

さらに、research://catalog という MCP リソースに加え、supply_chain_investigation および supply_chain_question_generator のプロンプトがあります。

ローカルファースト：これまでの MCP セットアップ失敗を回避した正確な方法

このプロジェクトは、これまでのローカル MCP 構築で実績のあるランタイムパターンを意図的に使っています。

• 起動中データベースファイルを作成しない

• .venv を同梱しない

• .mcp.json を同梱しない

• すべてのデータパスは server.py から __file__ を使って導出しています

• DuckDB は、チェックイン済みの CSV に対して、新しいインメモリビューを生成します

• uv run --with ... により、開発・stdio 起動は編集可能インストール（editable-install）のメタデータに依存しません

1. 事前チェック（Preflight）

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. bull_source_risk

5. compare_landed_costs

6. dock_capacity

7. stockout_reduction

8. apacity_ramp

9. projected_ick hazard が予測、した在庫不足

10. quality_gate_risk

11. quality_rush_signal

12. quality_trend

3. Claude なしでアナリティクスをスモークテストする

uv run python scripts/smoke_test.py

エグゼクティブ向け Web アプリ

同じ governed（統制された）ツール上に構築された、ローカルで静的 な「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 個のツールが表示されます。

その後、以下のようなプロンプトを使うことをお勧めします：

サプライチェーンアナリストとして行動してください。まず list_research_questions に始めてください。量的な根拠を得るには、mcp:// は zipline-supply-chain のツールだけを使ってください。プロイジェクトのランプアップフェーズに対して、どのサプライヤー／部品のリスクが最も重要かを教えてください。その根拠が何を示しているのか、どこが解釈なのか、何が合成データでは確立できないのかを説明してください。生のCSVを直接調べたり、自分で指標を再度計算したりしないでください。

実践的なリサーチ質問の例

このデータセットは、絡み合うサプライチェーンを二つに分離しています。

製造（Manufacturing）： サプライヤーのパフォーマンス、予測の偏り、MRP 欠品、単一ソース（Single-source）濃度、岸地原価（landed cost）、複数年のキャパシティ。

運用ロジスティクス： ピーク時の到着地用機材容量（dock-fleet capacity）と、供給不足のリスク削減。

その分離は、ツールとプロンプトの概念に組み込まれています。

「DEMO_QUESTIONS.md」と「PROMPTS.md」 を参照してください。

ドキュメントマップ

完全なファイルツリー: docs/REPOSITORY_GUIDE.md。

このプロジェクトが主張しないこと

これはすでに主張される彼発表の ERP/MPM でも、ルーティングオプショナイザーでも、航空の品質システムでも、因果推計研究でも、実際の財務データでもありません。重要なのは、LLM が支援する意思決定のための、管理統制（governed）された分析の境界です。

整合性／再現性チェック

But this is awkward. Let's refine.

"その2番目のチェック" Do not use "まず" because "The first" vs "The second" in same sentence. Let's use "1番目のチェックは... 2番目のチェックは..." easy.

Need include "composite relationship" -> "複合関連" etc.

Let's create precise Japanese:

合成リレーショナルモデルは、受領および品質のファクトが有効な (part_id, supplier_id) キーを持つこと、資格ゲートが有効なサプライヤーマスターIDを持つこと、すべてのPOが有効な部品とサプライヤーのマッピングを使用すること、在庫が部品ごとに1行だけであることを保証します。現在のデータセットバージョンは、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が与えられれば、ツールの出力は決定論的です。再現可能な合成研究データであり、合成分布がジップラインを統計的に代表しているという主張ではありません。

データセット規模

12週間の demand.csv は、参照アンカーを伴支援する正確な管理済みランプケースです。annual_demand.csv は、より堅固なローリングエラー分析のために基本的に 52 週間の週次観測を追加し、forecast_accuracy(series="annual_52w") で利用できます。したがって、12週間の実例を暗黙に変更することはありません。

合成部品の世界は、6つのカテゴリーファミリーにわたる60個の部品で構成されており、意図的にデモ規模です。つまり、在庫と調達のランキングに十分な観測を提供しつつ、実行後に検証・説明できる十分なサイズです。

Need check "Zipline" should be "Zipline" unchanged. The term "ジップライン" is not allowed (should be kept verbatim). So "Zipline" in Latin.

Need "MCP を実行前に実行してください" repetitive. Better "MCP のコンテキスト" but keep meaning "MCP を実行する前に実行してこのステップする（ scripts/preflight.py でも実施）". Let's phrase "MCP の前に流して（ scripts/preflight.py でもカバされます）:" Actually "MCP" in input may mean "Model Context Protocol" server. We can use "MCP の起動前に実施してください（ scripts/preflight.py でもカバーされています）:" This is clear.

Need "composite relationships": "複合リレーションシップ" or "組み合わせリレーション". Use "複合リレーション".

Let's check "and important reference anchors": maybe "重要な参照アンカー" (fixed values). Good.

"second regenerates the stochastic/enriched fact tables from fixed seeds and master fixtures and byte-compares them with the checked-in outputs." "fact tables" plural. Good.

"no runtime randomness" means no "ランダム性" at runtime. Better "実行時のランダム性を一切含まない". Bold "実行時ランダム性は含まれません".

Maybe "runtime randomness" as a term: "実行時ランダム性". Use no bold around Japanese? Need same bold markers. In the input the phrase "no runtime randomness" is bold. So output "実行時にランダム性はありません" maybe.

But "no" is bold only on "no runtime" in English. Actually "no runtime randomness" means all three words are bold. In Japanese, "実行時にランダム性はありません" is a bit off. Could use "実行時ランダム性はありません". Good.

Need "Given the checked-in CSVs" maybe "チェックイン済みCSVがあれば".

Need "last part universe" "parts" not "pieces".

Final final

Let's produce final output with proper translation.

Need list details:

1. Keep "GXP8" as the blank line

2. "## データセット規模"

3. Keep em dash character.

4. "series="annual_52w"" must be in inline code as forecast_accuracy(series="annual_52w"). In the output, preserve exactly.

5. "forecast_accuracy(series="annual_52w")" translation: "再帰的誤差分析用に longer" -> "より長期間の rolling forecast error analysis". Translate "longer rolling-error analysis" = "積み上げ誤差分析" perhaps "ローリング誤差分析". Use "長期的なローリング誤差分析".

Let's craft the final answer now in a polished, natural Japanese style.

合成リレーショナルモデルが保証するのは、受領・品質ファクトが有効な (part_id, supplier_id) キーを持つこと、資格ゲートが有効なマスターマンサーIDを使うこと、すべてのPOが有効な部品–サプライヤーマッピングを使うこと、在庫が部品ごとに1行だけであることです。現在のデータセットバージョンは 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

最初のチェックは、外部キー、複合関係、一意性、重要な参照アンカー（このデータセットが再現されることを意図した固定値）を検査します。2つのチェックでは、ストキャスティクス／拡張されたファクトテーブルを固定シードとマスターフィクスチャから再生成し、チェックイン済みの出力とバイト比較します。

サーバーには実行時のランダム性はありません。チェックイン済みCSVがあれば、ツールの出力は決定論的です。再現可能な合成研究データであり、合成分布がZiplineの統計的な代表であるという主張ではありません。

データセット規模

12週間の demand.csv は、参照アンカーの背にある正確に制御されたランプケースです。annual_demand.csv は、より長期間のローリング誤差分析のため52個の確定な週次観測を追加し、forecast_accuracy(series="annual_52w") で利用できます。そのため、12週間の作業例を暗黙に変更しません。

合成部品サンプルは、6つのコモディティファミリーにまたがる60部品で構成されます。意図的にデモンストレーション規模であり、在庫・調達のランキング分析に要する観測を十分含みつつ、ライブで調べて説明できる有力な規模に収まります。

Wait "サーバー自身" should be "サーバー自体". Also "送前" typo. Let's fix.

Also "composite" = "複合".

Need final polishing:

Let's write the final exact text: