# Cold-Chain MCP Server

[![PyPI version](https://img.shields.io/pypi/v/coldchain-mcp)](https://pypi.org/project/coldchain-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Analyze cold-chain sensor data with AI agents.** Connect your temperature/humidity logger to Claude, Cursor, or any MCP client and ask in plain language: *"did this shipment breach the cold chain?"*, *"find the anomalies in this log"*, *"split this file into separate journeys."*

> 🔒 **Privacy: all analysis runs locally. Your data never leaves your machine.** No external APIs, no cloud. Suitable for compliance-sensitive environments.

---

## What is this? (start here if you're new to MCP)

**MCP (Model Context Protocol)** is a standard way to give an AI assistant access to external tools. This project is an **MCP server** — a small program that runs on your computer and gives an AI agent four specialized tools for analyzing sensor time-series data.

The idea: instead of pasting thousands of temperature readings into a chat and hoping the AI does the math right, the AI calls these tools, which compute the answer **deterministically** (same input, same result, every time). You ask a question in plain language; the agent runs the right tool and gives you a structured report.

---

## Why use it

Language models are unreliable at statistics over large numeric series. They confuse a one-off sensor glitch with a real breach, lose track of timestamps, and produce different answers on re-runs. This server hands the agent **deterministic, repeatable** tools that get it right every time.

---

## Tools

| Tool | What it does |
|------|--------------|
| `summary_stats` | Summary statistics: min / max / mean / median / standard deviation, time range and duration. |
| `detect_threshold_breaches` | Detects threshold breaches (e.g. 2-8 degrees C) with **minimum duration** and **hysteresis** — separates a real breach from a momentary spike. |
| `detect_anomalies` | Flags outliers (global z-score, or deviation from a rolling mean). |
| `segment_journey` | Splits a continuous log into separate journeys based on time gaps (START/STOP). |

---

## Key distinction: a breach is not an anomaly

A sensor spiking to 40 degrees C for a single sample is an **anomaly** (a sensor glitch) — not a **breach** of the cold chain. A door left open, pushing the temperature to 12 degrees C for 20 minutes, **is** a breach, even though every individual reading looks plausible. This server distinguishes the two cases — exactly what a compliance audit requires.

---

## Installation

The easiest way is with pip:

```bash
pip install coldchain-mcp
```

This installs the server and a command called `coldchain-mcp`. It's now ready to connect to any MCP client.

### Alternative: from source

If you want to modify the server locally:

```bash
git clone https://github.com/matuzale/coldchain-mcp
cd coldchain-mcp
pip install -e .
```

---

## Connecting to Claude Desktop

An MCP client (like Claude Desktop) needs to know how to start your server. You tell it through a small configuration file. Open Claude Desktop, go to **Settings -> Developer -> Edit Config**, and add a `cold-chain` entry.

**If you installed with pip** (recommended), the config is short — you just name the command:

```json
{
  "mcpServers": {
    "cold-chain": {
      "command": "coldchain-mcp"
    }
  }
}
```

This works because `pip install` created a `coldchain-mcp` command that already knows where the code lives — so you don't have to point at any file.

**If you're running from source instead**, point at the script directly:

```json
{
  "mcpServers": {
    "cold-chain": {
      "command": "python",
      "args": ["/full/path/to/coldchain-mcp/server.py"]
    }
  }
}
```

> **Windows note:** if the short `"command": "coldchain-mcp"` form doesn't start the server, the install directory may not be on your system PATH. Either add Python's `Scripts` folder to PATH, or use the full path to `coldchain-mcp.exe` as the command.

After editing, fully restart Claude Desktop (quit from the system tray, not just the window). The tools appear automatically.

---

## Data format

CSV with a header, or JSON. Column names are configurable via the `ts_field` and `value_field` parameters, and the parser recognizes common aliases (`temp`, `temperature`, `time`, `value`).

```csv
timestamp,value
2026-07-20T08:00:00,5.1
2026-07-20T08:05:00,4.9
```

JSON is also accepted:

```json
[
  {"timestamp": "2026-07-20T08:00:00", "value": 5.1},
  {"timestamp": "2026-07-20T08:05:00", "value": 4.9}
]
```

---

## Example (talking to the agent)

> *"Load sample_data.csv and check whether the shipment breached the 2-8 degrees C range. A breach only counts after 10 minutes."*

The agent calls `detect_threshold_breaches(min_temp=2, max_temp=8, min_duration_minutes=10)` and returns a structured report of any breaches, with start time, end time, duration, and peak value.

---

## Roadmap

- [ ] PDF report export
- [ ] MKT (Mean Kinetic Temperature) — pharmaceutical standard
- [ ] Humidity support and temperature/humidity correlation
- [ ] Multi-zone detectors for a single shipment

---

## License

MIT — see [LICENSE](LICENSE). You're free to use, modify, and distribute this, including commercially, as long as the copyright notice is retained.