coffee-roaster-mcp

# RoastPilot

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

RoastPilot is an MCP server for coffee-roaster telemetry and controlled
actuation.

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 component scope complete, published on PyPI and in the MCP Registry,
and exercised in supervised agent-controlled hardware roasts through
2026-08-16.**

The latest integrated evidence is two completed Hottop roasts on 2026-08-16.
Together they exercised live telemetry and control, automatic T0, first-crack
handling, post-first-crack decisions, safety evaluation, advisor-triggered
drop, operator-controlled cooling completion, ambient sensing, log export, and
paired-microphone capture. The agent ledger recorded 19 successful advisor
decisions, each linked to an `allow` safety evaluation; both advisor-proposed
drops were executed, with no failed command events or safety alerts in either
completed run.

Those roasts used the pinned `coffee-roaster-mcp` 0.1.13 runtime. Versions
0.1.14 and 0.1.15 changed package metadata and release plumbing only; this
0.1.16 update changes documentation and release metadata only. Runtime
behaviour is unchanged. See the
[2026-08-16 agent-roast validation report](https://github.com/syamaner/coffee-roaster-mcp/blob/main/docs/session-summaries/2026-08-16-agent-roast-validation.md)
for the authority-ledger, session, ambient, and capture evidence, including its
provenance limits.

The original published-package baseline remains the 2026-06-07 validation:

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
published 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 MCP-component 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
```

### Hardware And Audio Checks

Two explicit pre-roast checks cover the configured microphone and independent
multi-device recording paths without starting a roast:

```bash
coffee-roaster-mcp mic-check --config coffee-roaster-mcp.yaml
coffee-roaster-mcp record-check --config coffee-roaster-mcp.yaml
```

`mic-check` reports whether the selected input contains a real signal and can
write a small JSON evidence record. `record-check` captures each configured
recording device into a temporary or explicit output directory and reports the
result. The resulting audio may contain ambient conversation and must not be
committed.

## 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`
- `set_recording_metadata`

`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.

Before a recorded roast, `set_recording_metadata` stores the bean-origin slug
and roast number used for capture filenames and the session sidecar. It sends
no hardware command and does not expose a generic file-write or tool-execution
surface.

### 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 phas