Cooling Planner

Cooling Planner v0.10 preview

English | 日本語

A browser app that operates equipment in a model dairy barn and compares environment, cow heat loss, water and energy use. It reuses the v0.4 geometry, physics and editing features with a rebuilt screen–calculation connection. v0.9 added a herd-average representative-day milk estimate linked to equipment changes (hypothesis model milk-heat-deficit-v0.1). v0.10 added hourly weather for the representative day (24 rows), per-day point/area aggregation, and constrained candidate comparison (compare_candidates).

This repository is a standalone version split out of Dairy Horizon. No FastAPI, API keys or parent project required. Requires Node.js 22.12+. First run: npm ci && npm run build, then npm start. The repository tracks both sources and built distributions; regenerate the distributions on change.

Live demo & branches

The english branch was created for an overseas hackathon and carries an English-only UI (no language switcher). Model calculations, save format and the MCP vocabulary are identical on both branches; only user-facing strings differ. Each branch auto-deploys to its own Amplify URL on push. UI labels quoted below are the English ones; the Japanese walkthrough is in docs/README.ja.md.

Quick start

cooling-planner-v0.10.html is a single file containing CSS, JavaScript and the calculation worker. Unzip it and open it in a desktop Chrome/Edge. No internet connection, login or API key is needed. If your browser refuses local files, use the local HTTP serving below.

For the current scope, see current plan; for how the acceptance criteria map to the current code, see acceptance criteria.

The milk-yield calculation spec is heat-load → milk hypothesis model v0.1; procedure and verification are in the implementation plan and report. The published 6-condition milk table is kept as reference material on the reference screen.

Verification scope and results are recorded in standalone validation record. Not every combination of public HTTPS, file://, and real Chrome/Edge/Safari has been checked.

First steps (3–5 minutes)

The screen is a barn-centered HUD. Place equipment from the bottom dock, configure it in the right panel, and compare results in the bottom sheet. On first run a short guide appears (skippable; replay from "?" help).

1. Wait for the initial calculation. "Draft A" starts as a copy of the baseline, so a heat-loss delta of 0 W is correct.
2. From the "Roof" button in the dock, turn on "reflective coating" and "20 mm insulation". At Feeding 7 the local air temperature goes 36.5 → 33.0 °C and the heat-loss improvement is about +384 W. These are model-calculated values.
3. Press "Fan" in the dock and click inside the barn to place a new device (Esc / Cancel to abort). Click an existing fan to select it and drag to move; change height and direction in the right panel. Dragging the background rotates the view. "Undo" reverts one operation.
4. In "Results & compare" → "Timeline", watch the 60-minute fixed-weather chart and playback. The metric chips at top-left (deficit / improvement / wind speed / air temperature) switch the floor colors. Cards and floor colors stay on 60-minute means.
5. In "Results & compare" → "Reference impacts", check the herd-average representative-day milk, its delta vs baseline, and the conception reference conditions. "View published table" shows the milk reference table.
6. In "Compare", review mean/max deficit, stall/feeding/waiting deficits, and water/energy deltas vs baseline. Pressing a top-deficit location jumps to the floor deficit view and that point's heat-loss breakdown.
7. Use "Save" at the top to store the placement and conditions as JSON, and "Load" to restore. An MCP scenario JSON can also be pasted via "Compare" or "Settings & save" → "Import MCP scenario JSON".

For the UI rework plan and verification, see game-style UI implementation plan and report.

The baseline is not "no equipment": it has 10 existing fans + 12 soakers and no roof measures. Draft B starts with the same fans, soakers stopped and mist running. A negative heat-loss delta for B means "worse than this baseline", not "mist has no effect".

Build and test

Requirements: Node.js 22.12+, TypeScript 5.8.3. 3D rendering uses Three.js 0.180.0 (bundled at build time as an npm dependency). No external network or CDN is needed at runtime.

npm ci

npm run typecheck npm test npm run build npm start

npm start serves dist-offline at http://127.0.0.1:4173/; change the port with PORT. If you only want to view the built distribution, npm start works with just Node — no npm install or rebuild needed.

Build outputs:

• cooling-planner-v0.10.html: standalone HTML (the older cooling-planner-v0.9.html is also kept).
• dist-offline/: HTML/CSS/app.js/worker.js for static hosting; serve the whole folder.

For the hackathon PoC, agent-side verification is typecheck, relevant unit/integration tests, and build. E2E and real-browser checks belong to humans and CI; agents run them only when explicitly asked.

The following E2E procedure is for humans/CI. Browser tests use Python Playwright/pytest and Chromium; headless is the default and Xvfb is not required. Point CHROMIUM_PATH at an existing Chromium, or omit it to use the Playwright-managed one. For headed runs, provide a display and set HEADLESS=0.

python -m pip install -r requirements-test.txt

python -m playwright install chromium npm run build npm run test:browser

By default the standalone HTML is exercised inline. Start npm start in another terminal and run COOLING_PLANNER_URL=http://127.0.0.1:4173/ npm run test:browser to check the HTTP version. WebGL-unavailable tests still use the standalone HTML under that setting.

Python reference implementations:

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

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

node scripts/make-examples.mjs regenerates the verified input examples and integrated calculation results. Run npm run build first.

MCP and WebMCP (external AI client integration)

Choose the integration for your demo:

WebMCP and local MCP use the live browser-side ProjectStore and share the screen's Undo history. The remote MCP is a separate, stateless calculation service. Implementation details: local MCP plan and WebMCP report.

Local MCP: launch and connect

1. Inside the repository, run npm ci && npm run build.
2. Register the following stdio server in your AI client (adjust the path to the real repository location; equivalent to npm run mcp):

{

"mcpServers": { "cooling-planner": { "command": "node", "args": ["/absolute/path/to/cooling-planner/scripts/mcp-server.mjs"] } } }

For Devin CLI, run inside the repository (registers to .devin/mcp_config.local.json):

devin mcp add cooling-planner -- node "$(pwd)/scripts/mcp-server.mjs"

1. Open http://127.0.0.1:4174/?mcp=1 in a single tab. npm start is not needed in this mode; the MCP process also serves dist-offline.
2. Call get_state from the AI.

The tools are get_state / edit / evaluate / compare_candidates / describe_model / set_view / get_results / undo — 8 in total. Edits apply to the current scenario, reflect on screen immediately, and recalculate through the existing path. Human screen operations and MCP operations share the same undo history.

• evaluate: evaluates a hypothesis without changing the screen. Pass the same operations as edit as an array; they are applied in order to a clone of the committed state, and the call returns the scenario's per-area aggregation, resources, roof and (with includeDaily) daily milk plus comparison stats vs baseline. Since it never touches the screen scenario, devices, undo history or recalculation, use this — not edit→undo — to explore "what if this measure" or "how far can the deficit go down".
• compare_candidates: applies 1–3 candidate operation lists separately to clones of the same committed project and returns daily results (mean deficit, water, energy use, worsened points), constraint verdicts and ranks. Candidates may only use update_device / update_system / update_roof; coefficients, weather, scenario switching and add/remove are rejected. Ranks hold only within the call.
• add_device in edit/evaluate can place at arbitrary coordinates with x and y (both required). Out-of-range or solid-zone positions are errors.
• describe_model: returns the model's calculation structure, input/output field meanings, main assumption constants, limits and verification status. Call it before interpreting or explaining numbers (also noted in the server instructions).
• Model coefficients can also be changed via MCP: update_model (physics: jet diffusion/decay, convective heat transfer, radiation offsets, roof model coefficients, profiles sensitivity assumption sets, etc.), update_milk (milk hypothesis: Qref, beta, lag weights, etc.), update_references (baseline milk and conception references). Model formulas and version identifiers cannot change, and out-of-range values are rejected by existing validation. Combined with evaluate, you can compare results under different coefficients without touching the screen.

• The MCP SDK is @modelcontextprotocol/server 2.1.0 (v2 line), pinned by the lockfile.
• Without ?mcp=1 no local WebSocket MCP connection is started. WebMCP tools are registered automatically when supported; ?webmcp=0 disables them.
• Serving and WebSocket are fixed to 127.0.0.1; a second tab connection is refused. Authentication, remote access, multi-user and in-app chat are out of PoC scope.
• If port 4174 is busy, the server prints a startup message and exits. Do not run a manual npm run mcp and an AI-client-launched server at the same time. COOLING_PLANNER_PORT changes the port (the browser auto-connects to the port of the opened page). The server exits automatically when the stdio client disconnects.
• Formulas, coefficients and the save schema are unchanged.

Browser integration check: CHROMIUM_PATH set + python3 -m pytest tests/e2e/test_mcp.py (drives a real MCP stdio session and verifies the screen changes).

WebMCP: operate the deployed screen

Both deployed branches expose the same WebMCP tools: English demo and Japanese demo.

The page automatically registers eight WebMCP tools against its live ProjectStore: get_state, edit, set_view, get_results, undo, describe_model, evaluate, and compare_candidates. No query parameter is required. The screen shows WebMCP ready after registrat