ChillClock

A food-cooling coach that estimates cooling deadlines, suggests practical next steps, and records decisions in a local hash-linked audit trail.

ChillClock is a prototype for commercial kitchens, caterers, and food-service teams. It uses two temperature readings from the same food batch to estimate whether the batch may reach key cooling temperatures on time.

Safety note: ChillClock is a decision-support prototype, not a food-safety determination. Its estimates can be wrong. Always measure food with a suitable thermometer and follow your approved procedures and applicable local food-safety requirements. The app never certifies food as safe.

What it does

• Cooling-time estimates: A two-point Newton-cooling model estimates when a batch may reach 70°F and 41°F, assuming a stable ambient temperature and broadly consistent cooling conditions.

• Deadline indicators: Estimates are compared with prototype reference targets of 120 minutes for the first stage and 360 minutes total. These are examples for coaching, not a determination of which rules apply to your operation.

• Context-aware suggestions: Optional batch name, food depth, cover or ventilation status, and cooling method help produce a deterministic action plan. Suggestions may include using shallower pans, appropriate ventilation while protecting food from contamination, an ice-water bath with stirring, rapid-cooling equipment, and rechecking with a thermometer. These are practical suggestions; follow applicable mandatory requirements and approved procedures.

• Direct and MCP predictions: Use the dashboard's Predict directly path or Run via MCP to call the predict_cooling tool on the local MCP server.

• MCP tools: The server provides predict_cooling and get_cooling_guidance over the Model Context Protocol.

• Audit trail: Prediction and corrective-action events are stored in a local JSON Lines ledger and linked with SHA-256 hashes. The verifier checks the chain across both event types.

• Quick demo: Example readings let you try the workflow without waiting for a full cooling cycle.

Coaching is rule-based. ChillClock does not call AWS Bedrock or another hosted AI model at runtime. It is not an Alexa skill, voice assistant, or public hosted service.

Related MCP server: Food Core MCP

Run locally

Requirements: Node.js 20 or newer and npm.

From the repository root, install dependencies:

npm install

Start the dashboard and API:

npm run dev

Open http://localhost:3000 and keep this terminal running. The dashboard server defaults to port 3000; set PORT to change it.

To use Run via MCP, open a second terminal in the project folder and start the MCP server:

npm run mcp

The MCP server listens on 127.0.0.1:3001 by default. Set MCP_PORT to use another port. Keep both servers running while using the MCP path. If the MCP server is unavailable, the dashboard will explain how to start it.

You can copy .env.example to .env to configure the ports. The app loads .env automatically.

Quick demo

1. In the dashboard, choose Load example A or enter two readings from the same batch.

2. Enter the elapsed time and any known batch context, such as food depth and cooling method.

3. Choose Predict directly and review the estimated times, prototype deadline indicators, and action plan.

4. Choose Run via MCP to make the same prediction through the actual MCP predict_cooling tool.

5. Use a Log action button to add a selected action to the audit chain, then choose Verify and view recent records to check the recent entries.

How estimates work

The engine estimates a cooling curve from two temperature readings and a known time interval using a simplified Newton-cooling model. It assumes broadly stable food and ambient conditions. Food composition, depth, container shape, stirring, airflow, refrigeration, and changes in cooling method can all make real cooling differ from the estimate.

The displayed reading interval heuristic is based only on the time between readings. Low, medium, or high is not a statistically validated confidence estimate and does not describe the probability that a prediction is accurate. If the model flags a potential missed target, physically recheck the batch and follow your operation's corrective procedure.

The 120-minute first-stage and 360-minute total values are prototype reference targets. Follow the requirements that apply to your location and operation.

Audit trail limitations

Audit events are written to data/ledger.jsonl; the data directory is ignored by Git. The verifier checks whether the stored entries form an intact SHA-256 hash chain. This can reveal many unexpected changes, but the trail is tamper-evident, not tamper-proof. It is local to the running app and is not a replacement for regulated recordkeeping or an independently secured audit service.

HTTP API

The dashboard server exposes:

• GET /api/health — basic server health.

• POST /api/predict — accepts startTempF, currentTempF, elapsedMinutes, and optional ambientTempF; returns an estimate and saves a prediction event.

• POST /api/predict/mcp — accepts the same readings plus optional batch context; calls the MCP predict_cooling tool and saves the result.

• POST /api/actions — validates a selected action and optional batch context, then appends a corrective_action event to the hash chain.

• GET /api/log — verifies the complete ledger and returns up to ten recent entries.

Example direct prediction request:

curl -X POST http://localhost:3000/api/predict \
  -H "Content-Type: application/json" \
  -d '{"startTempF":135,"currentTempF":100,"elapsedMinutes":45,"ambientTempF":37}'

The example output is an estimate, not a food-safety recommendation.

Development

npm run typecheck
npm test
npx tsx apps/server/src/mcp-smoke.ts

The MCP smoke test requires the MCP server to be running in another terminal. The project uses TypeScript, Node.js, Express, the Model Context Protocol TypeScript SDK, and Vitest.

Project structure

apps/server/       Dashboard, HTTP API, and MCP server
packages/engine/   Cooling estimate and supporting logic

License

MIT. See LICENSE.