Metadata-Version: 2.4
Name: coldchain-mcp
Version: 0.1.0
Summary: MCP server for cold-chain sensor data analysis: threshold breaches, anomalies, journey segmentation. All processing local.
Project-URL: Homepage, https://github.com/matuzale/coldchain-mcp
Project-URL: Repository, https://github.com/matuzale/coldchain-mcp
Author: matuzale
License: MIT
License-File: LICENSE
Keywords: cold-chain,compliance,iot,mcp,sensor,temperature,time-series
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: mcp<2,>=1.27
Description-Content-Type: text/markdown

# Cold-Chain MCP Server

**Analiza danych z czujników łańcucha chłodniczego dla agentów AI.** Podłącz swój logger temperatury/wilgotności do Claude, Cursora czy dowolnego klienta MCP i pytaj naturalnym językiem: *"czy ten przejazd naruszył łańcuch chłodniczy?"*, *"znajdź anomalie w tym logu"*, *"rozdziel plik na osobne przejazdy"*.

> 🔒 **Prywatność: cała analiza dzieje się lokalnie. Twoje dane NIE opuszczają maszyny.** Żadnych zewnętrznych API, żadnej chmury. Idealne dla środowisk compliance.

## Dlaczego to narzędzie

Model językowy słabo liczy odchylenia statystyczne i naruszenia progów na tysiącach punktów pomiarowych — myli chwilowe artefakty czujnika z realnymi naruszeniami, gubi się w timestampach. Ten serwer daje agentowi **deterministyczne, powtarzalne** narzędzia, które robią tę robotę poprawnie za każdym razem.

## Narzędzia

| Narzędzie | Co robi |
|-----------|---------|
| `summary_stats` | Statystyki podsumowujące: min/max/średnia/mediana/odchylenie, zakres i czas trwania. |
| `detect_threshold_breaches` | Wykrywa naruszenia progów (np. 2–8°C) z **minimalnym czasem trwania** i **histerezą** — odróżnia realne naruszenie od chwilowego skoku. |
| `detect_anomalies` | Wykrywa punkty odstające (z-score globalny lub odchylenie od średniej kroczącej). |
| `segment_journey` | Dzieli ciągły log na osobne przejazdy na podstawie przerw czasowych (START/STOP). |

## Kluczowa różnica: naruszenie ≠ anomalia

Krótki skok czujnika do 40°C na jedną próbkę to **anomalia** (błąd sensora), nie **naruszenie** łańcucha. Otwarte drzwi podnoszące temperaturę do 12°C przez 20 minut to **naruszenie**, nawet jeśli każda pojedyncza wartość jest "prawdopodobna". To narzędzie rozróżnia oba przypadki — dokładnie to, czego wymaga audyt compliance.

## Instalacja

```bash
git clone https://github.com/matuzale/coldchain-mcp
cd coldchain-mcp
pip install "mcp[cli]"
```

## Podłączenie do Claude Desktop

Dodaj do `claude_desktop_config.json` (patrz `claude_desktop_config.example.json`):

```json
{
  "mcpServers": {
    "cold-chain": {
      "command": "python3",
      "args": ["/absolutna/sciezka/do/coldchain-mcp/server.py"]
    }
  }
}
```

Zrestartuj Claude Desktop. Narzędzia pojawią się automatycznie.

## Format danych

CSV z nagłówkiem lub JSON. Nazwy kolumn są konfigurowalne (parametry `ts_field`, `value_field`), a parser rozpoznaje popularne aliasy (`temp`, `temperature`, `time`, `czas`, `wartosc`).

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

## Przykład użycia (w rozmowie z agentem)

> *"Załaduj sample_data.csv i sprawdź, czy przejazd naruszył zakres 2–8°C. Naruszenie liczy się dopiero po 10 minutach."*

Agent wywoła `detect_threshold_breaches(min_temp=2, max_temp=8, min_duration_minutes=10)` i zwróci ustrukturyzowany raport.

## Roadmapa

- [ ] Eksport raportów PDF (płatny tier)
- [ ] MKT (Mean Kinetic Temperature) — standard farmaceutyczny
- [ ] Wilgotność + korelacja temperatura/wilgotność
- [ ] Detektory dla wielu stref w jednym transporcie

## Licencja

MIT
