Cooling Planner MCP Server

Cooling Planner v0.10 preview

モデル牛舎で設備を操作し、環境と牛の放熱を比べるブラウザアプリです。既存v0.4の幾何・物理・編集機能を再利用し、画面と計算の接続を組み直しました。v0.9では、設備変更に連動する牛群平均の代表日乳量（仮説モデル milk-heat-deficit-v0.1）を追加しました。v0.10では代表日の時刻別気象（24行）と日単位の地点・区画別集計、制約付き候補比較 compare_candidates を追加しました。

このリポジトリはDairy Horizonから切り出した独立版です。FastAPI・APIキー・親プロジェクトは不要です。 Node.js 22.12以上で、初回は npm ci && npm run build、以降は npm start で起動します。 ソースとビルド済み配布物を管理し、変更時は配布物も再生成します。

まず動かす

cooling-planner-v0.10.html は、CSS・JavaScript・計算Workerを内包した単体ファイルです。ZIPを展開し、PCのChrome/Edge等で開いてください。インターネット接続、ログイン、APIキーは不要な構成です。ブラウザの制限でローカルファイルを開けない場合は、下のローカルHTTP配信を利用してください。

現在の目的・対象範囲は現在計画、設備操作から案比較までの受入条件案と現行コードの対応は受入条件を参照してください。

乳量の計算仕様は暑熱負荷→乳量の仮説モデルv0.1、作業手順と検証結果は実装計画・実装報告です。掲載6条件の乳量表は資料として参照条件画面に残しています。

検証範囲と結果は 独立版の検証記録 に記載します。 公開HTTPS、file://、実機のChrome/Edge/Safariの全組合せを確認したものではありません。

最初の操作（3〜5分）

画面は牛舎中心のHUD構成です。下部ドックから設備を置き、右パネルで設定、下部シートで結果を比べます。初回は3ステップのガイドが出ます（スキップ可、ヘルプの？から再表示可）。

1. 初期計算の完了を待つ。初期の「編集案A」は基準案の複製なので、放熱差0Wが正常です。
2. 下部ドックの「屋根対策」から「遮熱塗装」「断熱材20mm」をONにする。採食7では局所気温36.5→33.0℃、放熱差は約+384Wになります。この値はモデル計算です。
3. ドックの「ファン」を押し、牛舎内をクリックして新しい設備を置く（Esc/中止でキャンセル）。既存のファンはクリックで選択しドラッグで移動、高さ・向きは右パネルで変更します。背景ドラッグは視点回転です。「戻す」で1回の操作を戻せます。
4. 「結果・比較」→「時間変化」で固定気象60分間のグラフと再生を見る。左上の指標チップ（放熱不足／放熱改善／風速／気温）で床の色を切り替えます。カードと床の色は60分平均のままです。
5. 「結果・比較」→「参考影響」で牛群平均の代表日乳量と基準案との差、受胎の代表条件を確認する。「掲載表（資料）を見る」で乳量の表も参照できます。
6. 「案比較」で平均・最大不足、牛床／採食／待機の不足、水・電力と基準差を確認する。不足上位の地点を押すと、床の不足表示と場所の放熱内訳へ移動する。
7. 上部の「保存」で配置・条件をJSONに保存し、「読込」で復元する。MCP案は「案比較」または「設定・保存」の「MCP案のJSONを読込」から貼り付けても復元できる。

UI改修の計画と検証結果はゲーム風UI実装計画・実装報告を参照してください。

基準案は無設備ではありません。既存ファン10台＋ソーカー12個、屋根対策なしです。 編集案Bの初期状態は、同じファンでソーカー停止・ミスト稼働です。Bの負の放熱差は、この基準との比較であり「ミストに効果がない」という意味ではありません。

ビルドとテスト

開発条件：Node.js 22.12以上、TypeScript 5.8.3。3D描画はThree.js 0.180.0（npm依存としてビルド時に同梱）。ブラウザ実行時の外部通信・CDNは不要です。

npm ci
npm run typecheck
npm test
npm run build
npm start

npm start は http://127.0.0.1:4173/ で dist-offline を配信します。PORT 環境変数でポートを変更できます。ビルド済み配信物だけを見る場合、npm install や再ビルドは不要で、Nodeがあれば npm start を使えます。

ビルド出力：

• cooling-planner-v0.10.html：単体HTML（旧cooling-planner-v0.9.htmlも残しています）。
• dist-offline/：静的配信用のHTML/CSS/app.js/worker.js。フォルダー全体を配信対象にします。

ハッカソンPOCでは、エージェントの検証は型チェック・関連する単体／統合テスト・ビルドを基本とします。E2E・実ブラウザの操作確認は人間とCIが担当し、エージェントは明示的に依頼された場合のみ実行します。

以下は人間／CI向けのE2E手順です。ブラウザテストはPython Playwright/pytestとChromiumを使います。既定ではヘッドレス実行でXvfbは不要です。 CHROMIUM_PATH で既存のChromiumを指定でき、省略時はPlaywright管理のChromiumを使います。 有画面で実行する場合は、表示環境を用意したうえで HEADLESS=0 を指定します。

python -m pip install -r requirements-test.txt
python -m playwright install chromium
npm run build
npm run test:browser

既定では単体HTMLのインライン実行を確認します。別ターミナルで npm start を起動し、 COOLING_PLANNER_URL=http://127.0.0.1:4173/ npm run test:browser とするとHTTP版を確認できます。 WebGL利用不可の試験は、この設定時も単体HTMLを使用します。

Python参照実装の確認：

(cd reference/thermal && python -m unittest -v)
(cd reference/fertility && python -m unittest -v)

node scripts/make-examples.mjs で、検証済みの入力例と統合計算結果を再生成できます。先に npm run build を実行してください。

MCP PoC（外部AIクライアント連携）

docs/MCP_POC_IMPLEMENTATION_PLAN.md のPoC実装です。外部のMCP対応AIクライアントが、開いている画面そのものを読み取り・操作します。状態の正本はブラウザのProjectStoreで、サーバー側は計算・保存のコピーを持ちません。

起動と接続

1. リポジトリ内で npm ci && npm run build。
2. AIクライアントへ下記のstdioサーバーを登録して接続する（パスはリポジトリの実位置に合わせる。npm run mcp と同等）。

{
  "mcpServers": {
    "cooling-planner": {
      "command": "node",
      "args": ["/home/hddwm390/tmp/cooling-planner/scripts/mcp-server.mjs"]
    }
  }
}

Devin CLI ではリポジトリ内で次を実行します（.devin/mcp_config.local.json へ登録）。

devin mcp add cooling-planner -- node /home/hddwm390/tmp/cooling-planner/scripts/mcp-server.mjs

1. http://127.0.0.1:4174/?mcp=1 を1タブで開く。このモードでは npm start は不要です。MCPプロセスが dist-offline の静的配信も担当します。
2. AIから get_state を呼ぶ。

ツールは get_state / edit / evaluate / describe_model / set_view / get_results / undo の7つです。編集は現在の案へ適用され、画面へ即時反映・既存経路で自動再計算されます。人の画面操作とMCPの操作は同じUndo履歴を共有します。

• evaluate：画面を変えずに仮説を評価します。edit と同じ操作を配列で渡すと、現在の確定状態の複製へ順に適用して計算し、その案の区画別集計・resources・roof・（includeDaily指定時）日乳量と基準案の比較集計を返します。画面の案・設備・Undo履歴・再計算には一切影響しないため、「この対策ならどうなるか」「どこまで不足を減らせるか」の探索は edit→undo ではなくこちらを使います。

• edit/evaluate の add_device は x・y（両方指定）で任意座標へ直接配置できます。範囲外・立体ゾーンはエラーになります。

• describe_model：計算モデルの構造・入力/出力フィールドの意味・主な仮定定数・限界・検証状態を返します。数値を解釈・説明する前に呼ぶことを想定しています（サーバーinstructionsにも記載）。

• モデルの係数もMCPで変更できます。update_model（物理モデル：噴流拡散・減衰、対流熱伝達、放射オフセット、屋根モデル係数、profilesの感度仮定セットなど）、update_milk（乳量仮説：Qref・beta・遅れ重みなど）、update_references（基準乳量・受胎参照）。モデル式とバージョン識別子は変更できず、値域は既存の検証が拒否します。evaluate と組み合わせると、係数を変えた場合の結果を画面を汚さず比較できます。

• MCP SDKは @modelcontextprotocol/server 2.1.0（v2系）を使用し、lockfileで固定しています。

• 通常の npm start（ポート4173）や単体HTMLでは従来どおり利用でき、?mcp=1 なしではMCP接続を開始しません。

• 配信とWebSocketは 127.0.0.1 固定です。2タブ目の接続は拒否されます。認証・遠隔接続・複数ユーザー・アプリ内チャットはPoC対象外です。

• ポート4174が使用中だとサーバーは起動時メッセージを出して終了します。手動起動の npm run mcp とAIクライアント起動の両方を同時に立ち上げないでください。環境変数 COOLING_PLANNER_PORT でポートを変えられます（ブラウザ側は開いたページのポートへ自動で接続します）。stdioクライアントが切断されるとサーバーは自動終了します。

• 計算式・係数・保存スキーマは変更していません。

ブラウザ結合確認：CHROMIUM_PATH を指定し python3 -m pytest tests/e2e/test_mcp.py（実際のMCP stdio会話で画面が変わることまで確認します）。

AWS へのデプロイ

実装計画は docs/AWS_DEPLOY_PLAN.md。Amplify Hosting（静的サイト、GitHub連携で main への push で自動デプロイ）＋ Lambda Function URL（REST と リモートMCP）構成です。リモートMCPはブラウザを持たないステートレス版で、ツールは get_default_project / evaluate / describe_model / get_doc（操作語彙はローカル版と同一）。

リモートMCP への接続

Kiro・Claude・その他のMCPクライアントに以下を登録します。公開デモトークン demo-581fKusGqNgk7YrycFNw6M_5 は誰でも利用可能です（悪用時はローテーション）。管理用の私有トークンは aws/deploy.local.json の mcpBearerToken（git管理外）：

{"cooling-planner-remote":{"type":"http","url":"https://puzxplbkg2qglia72tkhs2z7km0jrusa.lambda-url.us-east-1.on.aws/","headers":{"Authorization":"Bearer demo-581fKusGqNgk7YrycFNw6M_5"}}}

cd aws && npm ci && cd ..
npm run deploy:aws   # サイトbuild → Lambda bundle → cdk deploy（Lambdaバックエンドのみ）

デプロイ状態（Bearerトークン・URL）は aws/deploy.local.json（git管理外）に保存されます。初回はCDK bootstrapが必要な場合自動で実行します。サイトの公開はGitHub接続済みAmplifyアプリが main へのpushをトリガーに amplify.yml でビルドして行います。

保存形式

schemaVersion: 10。配置・屋根条件・気象（固定＋代表日の時刻別）・係数・参照モデルの仮定・日運転開始時刻・乳量モデル設定・表示設定を保存します。v8・v4のJSONは自動変換せず拒否し、現在の案を保持します。既存のv8本体・データを別途残してください。

配置JSONに加え、トップレベルにprojectを含むMCPのevaluate応答JSONも読込・貼付できます。projectの配置・気象・係数・基準案を検証して復元し、画面で再計算します。受信した計算結果やハッシュは信用して表示しません。最大2MiB、対応版はschema 10（v9は自動変換）です。

「結果JSON」はプロジェクトと計算結果を合わせた検証用ファイルです。2MiB以内ならprojectを取り出して復元できますが、結果を含むため通常の受け渡しには配置JSONまたはMCP応答のprojectを使ってください。

端末内保存は使えるブラウザで行いますが、初回起動は必ず標準デモから始めます。「共通設定・保存」から端末内保存を復元できます。案JSONは端末内保存が使えない環境でも利用できます。

区画別可視化

標準3D / リアル3D / 2D

牛舎上部のタブで切り替えます。従来の描画は「標準3D」に残し、配置・選択地点・計算結果を共用します。 「リアル3D」は鋼材、牛床、床材、牛・設備の形状、照明と影を加えた表示です。追加ダウンロードは不要です。 ホルスタインを意識した体形と大きな斑模様で立位・休息姿勢を描き分け、50頭のうち3頭をソーカーのある採食帯に表示します。牛の表示位置・姿勢は演出で、計算地点や滞在時間の設定を変更しません。

• 背景ドラッグで回転、ホイールで拡大、Shift＋ドラッグまたは右ドラッグで平行移動。
• ファン・ノズルを選んでドラッグすると、標準3Dと同じ設備を編集します。「戻す」も共通です。
• 「風」で流れる筋、「散水」でソーカーの水滴／ミストの粒子を表示します。時間スライダーで運転のON/OFFを確認できます。
• 「ヒートマップ」で床に既存の計算結果を重ねます。「分析表示」は牛を隠してヒートマップを表示します。
• 「屋根断面」は片側の屋根を表示します。柱とトラスは内部構造を確認できるよう常時表示します。

風はファンの向き・モデルの広がりと減衰・障害物に基づく模式表現です。粒子の軌道はCFDではありません。 粒子アニメーションは表示用で、時刻を進めたりモデル計算を書き換えたりしません。 材質と形状はコードで生成しており、写真測量や実写品質の牛モデルではありません。 実装と検証の詳細はリアル3D実装記録を参照してください。

区画別の暑熱・冷却可視化仕様v0.1を実装しています。50牛床・採食12区画・待機8区画の面を、放熱不足（Qrefに対する秒積算平均）・放熱改善・風速・気温で色分けします。面や表のクリックで代表地点を選択し、濡れ方・放熱内訳・設備作用の診断を表示します。各面はその地点の代表値であり、面全体の空間計算ではありません。schemaVersionは10です。

モデルの対応範囲

• フリーストール1テンプレート・50床・70独立評価点。CFDや実農場の精度保証ではありません。
• 熱・水は固定気象60分、基本1秒刻み。再生は計算済みサンプルの表示です。
• 日乳量は別の代表日計算です。固定気象を24時間反復し、準備24時間の後で評価24時間を集計します。設備ごとの日運転開始時刻・運転時間・ON/OFF周期、日付をまたぐ残水を含みます。
• 送風体感温度、放熱改善W、乳量、受胎は別の意味の指標です。
• 日乳量は milk-heat-deficit-v0.1（demo_assumption）による牛群平均の参考値です。H=max(0,Qref−Q) を70地点・区域別滞在割合（14/6/4時間相当）・時間で加重し、遅れ込みEから Y=Y0−min(Y0×25%,beta×E) を計算します。係数は文献回帰値ではなく、実農場での精度は未検証です。
• 掲載表の乳量は全酪連掲載6条件・RH60〜70%・静的条件のみ。未掲載値はnull、補間・外挿なし。資料として保持します。
• 受胎は5期間のTHI区分と仮の基準受胎率から計算する参考シナリオ。初期値は独立した代表26℃・RH70%、基準受胎率40%。設備から自動的に総合受胎改善を算出するものではありません。
• 60分平均を授精前後52日の代表条件へ適用する場合は、参照条件画面のチェックで明示的に選びます。ファン・ソーカーの放熱WをTHIへ変換しません。
• 5期間別のTHIを渡す関数はありますが、初版UIは全期間共通の代表条件だけです。

ファイル案内

docs/IMPLEMENTATION_REPORT.md：作り直した意図・実装内容・数値結果・検証・残件。

docs/DECISIONS_v0_8.md：統合時に固定した実装契約。

docs/REUSE_MAP.json：v0.4とのファイル別比較とSHA-256。

docs/evidence-v08/：切り出し前のv0.8実装時のログ・画面・計算結果。

evidence/：テスト実行時の出力先。Git管理対象外。

reference/：照合に使用した元のPythonモデルと仕様。

examples/：読込可能なschema9の配置例。

課題と独立リポジトリ化

• 遮熱モデルと乳量参照表示の課題：評価結果、感度確認、未実装の改善候補。
• 単独リポジトリへの切り出し：必要ファイルの書き出し、独立したビルド・起動、Git初期化の手順。
• AGENTS.md：独立版で作業するエージェント向けの範囲・検証規則。

MCPで作った案を画面で確認する

1. AIに既存MCPのevaluateで案を計算させる。日資源の照合にはincludeDaily: trueを指定する。
2. 「evaluateの返値のprojectをJSONファイルとして渡して」と依頼する。添付を作れないクライアントなら、JSONの本文を受け取る。
3. 画面上部の「読込」でファイルを開くか、「案比較」／「設定・保存」→「MCP案のJSONを読込」で本文を貼り付ける。応答全体のJSONも対応する。
4. 再計算完了後、選択案・配置・気象・区域別不足と水・電力を確認する。読込は全案・共通条件を復元する操作で、「戻す」で読込前の条件へ戻せる。不正JSONは現在の案を保持する。

比較の平均は70代表点の単純平均で、牛群の頭数・滞在時間加重ではない。最大不足は地点ごとの60分平均不足の最大。「不足が減らず残る」は不足があり基準から低減していない地点、「局所作用なし」は局所設備の作用診断（屋根対策の改善を含まない）として区別する。地点の放熱内訳の差は複合設備の同時計算であり、設備別の独立寄与ではない。

MCP案復元と比較の実装報告に今回の検証範囲を記載する。ソース・配布物の更新と、公開AWS版への反映は別の作業である。

今回の変更を手動確認する（人間／CI向け）

1. MCPの案JSONを「MCP案のJSONを読込」に貼付し、配置・屋根条件が反映されることを確認する。「戻す」で元へ戻ることを確認する。
2. 「案比較」で平均・最大不足、牛床／採食／待機、水・電力を見る。不足上位の地点を押して、選択地点と放熱内訳が切り替わることを確認する。

専用のE2Eは python3 -m pytest tests/e2e/test_mcp_comparison.py -v の2件に絞っています。エージェントによる実行は省略します。