coffee-roaster-mcp

# RoastPilot

<!-- mcp-name: io.github.syamaner/coffee-roaster-mcp -->

RoastPilot is a spec-driven MCP server for autonomous coffee roasting.

The package name is `coffee-roaster-mcp`. It is published on production PyPI
and listed in the MCP Registry as
`io.github.syamaner/coffee-roaster-mcp`.

RoastPilot provides one local MCP runtime for roaster control, telemetry, first-crack detection integration, roast metrics, and log export.

## Status

✅ **v0.1 complete — verified end-to-end on real hardware (2026-06-07).**

The published `coffee-roaster-mcp` 0.1.3 package, installed through the MCP
Registry `uvx` path into the Warp agent, ran two complete supervised roasts
on a connected Hottop KN-8828B-2K+ with zero serial, control, or telemetry
faults:

| Validated | Result |
| --- | --- |
| Install path | Published PyPI 0.1.3 via `uvx` in a real MCP client (Warp) |
| Hardware control | Live heat/fan/drop/cooling through the driver-backed MCP tools |
| Automatic T0 | `beans_added` detected from the bean-temperature charge drop (`source: auto_t0`) |
| First-crack detection | Audio-detected live by the released INT8 ONNX model on a real USB microphone — sliding-window confirmation, confidence 0.907 over the 0.6 threshold with 5/5 positive windows |
| Safety actions | Same-day guarded `hottop-validate` run passed 8/8 steps, including drop and emergency stop |
| Log export | `roast.jsonl`, `roast.csv`, and `summary.json` with full first-crack and auto-T0 metadata |

Evidence:

- [Roast-day validation report](docs/session-summaries/2026-06-07-roast-day-validation.md)
  (formal pass/fail analysis, both roasts)
- [Roast #1 test summary](docs/session-summaries/2026-06-07-live-roast-test-summary.md)
  and [Roast #2 auto-validation summary](docs/session-summaries/2026-06-07-roast-2-auto-validation.md)
  (timelines, metrics, screenshots)
- [Committed artifacts](docs/validation/2026-06-07-live-roast/)
  (roast logs, guarded-validation JSON, transcripts, screenshots, checksums)

See the [v0.1 overall plan](docs/plans/coffee-roaster-mcp-v0.1-overall-plan.md)
and the [project state registry](docs/state/registry.md) for the plan and
state history.

## Related Project Artifacts

- Current architecture article: [The Architecture: The Agent-Spec Driven ML Development With Warp](https://dev.to/syamaner/part-1-the-architecture-the-agent-spec-driven-ml-development-with-warpoz-3al6)
- Original prototype intro: [Training a Neural Network to Detect Coffee First Crack from Audio](https://dev.to/syamaner/part-1-training-a-neural-network-to-detect-coffee-first-crack-from-audio-an-agentic-development-1jei)
- Original prototype MCP post: [Building MCP Servers to Control a Home Coffee Roaster](https://dev.to/syamaner/part-2-building-mcp-servers-to-control-a-home-coffee-roaster-an-agentic-development-journey-with-58ik)
- First-crack model: [syamaner/coffee-first-crack-detection](https://huggingface.co/syamaner/coffee-first-crack-detection)
- First-crack dataset: [syamaner/coffee-first-crack-audio](https://huggingface.co/datasets/syamaner/coffee-first-crack-audio)
- First-crack demo: [Coffee First-Crack Detection Space](https://huggingface.co/spaces/syamaner/coffee-first-crack-detection)

The current `coffee-roaster-mcp` package is a consolidated rebuild of the
prototype with the lessons learned folded into one deterministic local MCP
server, conservative hardware boundaries, and releaseable package metadata.

## What RoastPilot Is

RoastPilot is the human-facing product name. `coffee-roaster-mcp` is the infrastructure and packaging name used for the repository, Python package, and future distribution.

The v0.1 scope is one local stdio MCP server that owns:

- roaster control
- roast session timing and events
- first-crack detection integration
- derived roast metrics
- roast log export

All v0.1 epics are complete and live-validated. The package scaffold, config
loading, local development commands, pull-request CI, stdio MCP entrypoint,
roast-session tool surface, Hottop driver, audio first-crack runtime,
automatic T0 path, metrics/log export, release workflow, and MCP Registry
metadata are in place, and the full end-to-end path has been verified on
connected Hottop hardware with a real microphone through the published
package (E7-S6).

## Install

For local development today:

```bash
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e . --group dev
```

The user-facing install target is the published `coffee-roaster-mcp` package:

```bash
python -m pip install coffee-roaster-mcp
```

For operator setup, including mock install, Hottop configuration, Hugging Face
model configuration, offline model paths, and log output paths, see the
[install and hardware setup guide](docs/install-and-hardware-setup.md).

## Local Development

### Setup

Use the commands in the [Install](#install) section, then continue with the checks below.

### Test

```bash
python -m pytest
```

### Coverage

```bash
python -m pytest --cov=coffee_roaster_mcp --cov-report=term-missing:skip-covered --cov-report=html:htmlcov --cov-report=json:coverage.json
python .github/scripts/write_coverage_summary.py coverage.json
```

Pull-request CI publishes a Markdown coverage summary in the `Checks` job summary and uploads `html-coverage-report` as a workflow artifact for file-by-file drill-down.

### Lint

```bash
python -m ruff check .
```

### Format Check

```bash
python -m ruff format --check .
```

### Typecheck

```bash
python -m pyright
```

### CLI Smoke

```bash
coffee-roaster-mcp --help
coffee-roaster-mcp --version
```

## Local Mock Run

The default local path is intentionally mock-safe:

- default roaster driver: `mock`
- default first-crack mode: `disabled`
- no roaster hardware required
- no microphone required
- no model download required

RoastPilot now provides a local stdio MCP server entrypoint with a mock-safe
roast-session tool surface. The default configuration lets an MCP client start
a roast, adjust controls, read current device and session state, record explicit
override events, drop beans into cooling, and export snapshot logs without
roaster hardware, microphone input, model files, or network access.

### Start The Local MCP Server

```bash
coffee-roaster-mcp serve
```

The current MCP tool surface includes:

- `get_server_info`
- `get_runtime_config`
- `start_roast_session`
- `get_roast_state`
- `set_heat`
- `set_fan`
- `mark_beans_added`
- `mark_first_crack`
- `drop_beans`
- `start_cooling`
- `stop_cooling`
- `export_roast_log`
- `emergency_stop`

`export_roast_log` writes `roast.jsonl`, `roast.csv`, and `summary.json` files
for the current in-process session. Runtime events and sampled telemetry are
also appended to `roast.jsonl` during the roast.

### Operational MCP Flow

The mock-safe Claude/operator flow is:

1. Call `start_roast_session` to create the one active roast session and connect
   the configured driver.
2. Call `set_heat` and `set_fan` as operational decisions require. These tools
   go through the configured `RoasterDriver` boundary; the default mock driver
   stays local and deterministic.
3. Call `get_roast_state` to read both the authoritative session state and the
   current configured-device state. The response includes driver id, connected
   status, bean/environment temperatures when available, heat/fan levels,
   cooling state, safe raw diagnostics, T0 status, first-crack status, and
   lifecycle timestamps for beans added, first crack, bean drop, cooling
   started, and cooling stopped.
4. Use `drop_beans` as the normal drop command. For the mock path and the
   Hottop compound drop path, this records `beans_dropped`, records
   `cooling_started` when the driver reports cooling active, turns heat off,
   sets fan to `100%`, and enters the cooling phase.
5. Use `stop_cooling` when cooling is complete. `start_cooling` remains
   available as an explicit advanced/manual recovery tool, not as the normal
   roast flow after `drop_beans`.

`mark_beans_added` and `mark_first_crack` are explicit override tools. They are
kept available for operator recovery and controlled manual runs. The primary
automatic runtime paths are internal: automatic T0 detection can record
`beans_added` when `session.auto_t0_detection_enabled` is enabled, and
audio-mode first-crack confirmation is owned by the session-owned first-crack
runtime when `first_crack.mode: audio` is deliberately configured.

Automatic T0 is disabled by default. When enabled, `get_roast_state` reads the
configured driver, tracks the max preheat bean temperature before T0, and
records `beans_added` when the current bean temperature drops from that max by
`session.auto_t0_drop_threshold_c`. `get_roast_state.t0_status` exposes the
configured threshold, tracked charge temperature, current drop, and detected
bean temperature when automatic T0 records the event.

`get_roast_state.first_crack_status.status` is one of:

- `disabled`: first-crack detection is disabled and no first-crack event exists.
- `manual`: manual first-crack mode is configured and the override tool is
  available.
- `pending`: audio detection is configured and waiting for a confirmed event.
- `detected`: the authoritative session timeline has a first-crack event.
- `faulted`: the detector runtime or session has faulted.
- `unavailable`: configuration, artifacts, audio capture, or manual-override
  settings make first-crack detection unavailable.

### Mock-Safe Bootstrap Smoke

Use this mock-safe bootstrap smoke to confirm the default local path stays hardware-free and model-free from a guaranteed-empty temporary directory:

```bash
python -c "import os, tempfile; from coffee_roaster_mcp.config import load_config; tmp = tempfile.TemporaryDirectory(); os.chdir(tmp.name); c = load_config(environ={}); print(c.roaster.driver, c.first_crack.mode, c.first_crack.precision); tmp.cleanup()"
```

Expected output:

```text
mock disabled int8
```

This confirms the bootstrap