The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the RoastPilot listing page.
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.
✅ 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-0.1.16 were metadata/docs releases; the selected 0.2.0 release
candidate carries the MCP-owned NumPy/SciPy, Torch/Torchaudio/Transformers-free
ONNX feature-extraction path and additive first-crack observability. D190 was
MCP-only component characterisation with artificial music: zero observed
overflow does not establish headroom for other conditions or prove the non-zero
allowance necessary; sanitised review did not rehash private evidence, and it
is not detector, live-roast, full-stack, or combined acceptance. D192 full-stack
30+30 and separate supervised >=20-minute live roast remain outstanding.
Publication remains operator-only after merge, a successful release-workflow
dry run, and protected-environment approval. See the
2026-08-16 agent-roast validation report
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:
See the v0.1 overall plan and the project state registry for the plan and state history.
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.
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:
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).
For local development today:
The user-facing install target is the published coffee-roaster-mcp package:
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.
Use the commands in the Install section, then continue with the checks below.
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.
Two explicit pre-roast checks cover the configured microphone and independent multi-device recording paths without starting a roast:
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.
The default local path is intentionally mock-safe:
mockdisabledRoastPilot 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.
The current MCP tool surface includes:
get_server_infoget_runtime_configstart_roast_sessionget_roast_stateset_heatset_fanmark_beans_addedmark_first_crackdrop_beansstart_coolingstop_coolingexport_roast_logemergency_stopset_recording_metadataexport_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.
The mock-safe Claude/operator flow is:
start_roast_session to create the one active roast session and connect
the configured driver.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.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.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.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.
Optional ambient sensing and roast recording are also disabled by default.
When enabled deliberately, get_roast_state exposes fail-soft Yoctopuce
ambient readings and live microphone/overflow status, while the recording
runtime can capture one or more independent microphone streams into a
session-scoped directory. Recording uses the audio first-crack capture runtime;
it therefore requires first_crack.mode: audio. A live roast recording also
requires audio.source: microphone, with recording.enabled and
recording.autocapture both set to true. When recording.devices is set,
its first entry must match audio.input_device: that stream is captured by the
detector and teed into the first WAV rather than opened independently. Any
additional entries are opened as independent recording streams. These paths
have been exercised together during the August 2026 hardware roasts described
in the current validation report.
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.Use this mock-safe bootstrap smoke to confirm the default local path stays hardware-free and model-free from a guaranteed-empty temporary directory:
Expected output:
This confirms the bootstrap defaults are still aligned with the mock vertical-slice plan.
The concise setup path is in the install and hardware setup guide; this section summarizes the guarded validation workflow.
Hottop support lives behind the RoasterDriver abstraction. The driver has
lifecycle, command-loop, packet, control-state, and temperature-unit support,
and has passed the full guarded validation (including drop and emergency
stop) on connected hardware — most recently on 2026-06-07 against the
published 0.1.3 PyPI package, followed by two complete supervised live
roasts through the MCP tool surface. Guarded manual validation remains the
required procedure before operating any new hardware setup.
Configuration lives in coffee-roaster-mcp.yaml. Keep local development on the mock driver unless you are intentionally validating connected Hottop hardware:
For guarded hardware validation, switch driver to hottop_kn8828b_2k_plus, set the serial port explicitly, and run the validation harness with an evidence output path:
The irreversible and safety-action checks are opt-in:
Hardware safety matters here: command-loop cadence, packet handling, temperature units, drop behavior, cooling behavior, emergency stop, and cleanup must be validated on a supervised roaster before the Hottop path is treated as release-ready. The current MCP roast-session tools call the configured driver boundary, so keep normal development on the mock driver unless a guarded Hottop validation run is explicitly intended.
Optional live Hottop MCP validation is gated manual work. Run it only with a
supervised roaster, an explicit hottop_kn8828b_2k_plus config, a known serial
port, and a clear stop plan. Expected evidence for a pass is: the MCP client can
start one session, set heat and fan, read connected device state with plausible
temperatures, call drop_beans to trigger drop plus cooling, read
beans_dropped and cooling_started timestamps from get_roast_state, stop
cooling when the roaster reports cooling off, and preserve any failure as a
fault event. Any serial, telemetry, command-loop, or safety uncertainty should
be treated as a failed validation and should not be required by normal CI.
RoastPilot loads configuration from coffee-roaster-mcp.yaml in the current directory by default. If the file is absent, mock-safe defaults are used so local development does not require roaster hardware, audio hardware, or model downloads.
See the install and hardware setup guide for setup-focused examples covering mock install, Hottop configuration, Hugging Face model configuration, offline model paths, and log output paths.
Supported environment overrides:
COFFEE_ROASTER_MCP_CONFIGCOFFEE_ROASTER_DRIVERCOFFEE_ROASTER_PORTCOFFEE_ROASTER_TEMP_UNITCOFFEE_FIRST_CRACK_MODECOFFEE_FIRST_CRACK_REPO_IDCOFFEE_FIRST_CRACK_REVISIONCOFFEE_FIRST_CRACK_PRECISIONCOFFEE_FIRST_CRACK_LOCAL_MODEL_DIRCOFFEE_FIRST_CRACK_ONNX_THREADSCOFFEE_FIRST_CRACK_CONFIDENCE_THRESHOLDCOFFEE_FIRST_CRACK_MIN_POSITIVE_WINDOWSCOFFEE_FIRST_CRACK_CONFIRMATION_WINDOW_SECONDSCOFFEE_AUDIO_SOURCECOFFEE_AUDIO_INPUT_DEVICECOFFEE_AUDIO_SAMPLE_RATECOFFEE_AUDIO_WAV_PATHCOFFEE_AUDIO_REPLAY_MODECOFFEE_AUDIO_WINDOW_SECONDSCOFFEE_AUDIO_OVERLAPCOFFEE_AUDIO_HOP_SECONDSCOFFEE_AMBIENT_MODECOFFEE_AMBIENT_DEVICECOFFEE_AMBIENT_POLL_INTERVAL_SECONDSCOFFEE_RECORDING_ENABLEDCOFFEE_RECORDING_AUTOCAPTURECOFFEE_RECORDING_EXPORT_LOCATIONCOFFEE_RECORDING_SAMPLE_RATECOFFEE_RECORDING_DEVICESCOFFEE_ROAST_LOG_DIRCOFFEE_AUTO_T0_DROP_THRESHOLD_CHF_HOMEaudio.source can be microphone or wav. Microphone capture uses a
PortAudio-backed sounddevice stream and keeps the configured device identifier
behind the audio-input boundary for macOS, Linux, and Raspberry Pi hosts. WAV
replay uses PCM .wav files, converts channels to the same mono float sample
contract as microphone capture, and requires the file sample rate to match
audio.sample_rate. WAV replay defaults to the background realtime capture
pipeline. For local labelled-fixture validation, set
audio.replay_mode: detector_paced and the detector-compatible
audio.window_seconds plus either audio.overlap or audio.hop_seconds so
each complete WAV window is processed as soon as the detector/runtime is ready,
without wall-clock sleeps and without normal queue drops.
The repository normally does not commit audio. The only current exception is
the small derived E7-S5a labelled replay fixture under tests/fixtures/audio/,
which is trimmed, resampled, retimestamped, and documented with a manifest.
Raw recordings, broad training/evaluation audio, model artifacts, roast logs,
and serial captures remain excluded from git.
The released-model labelled replay validation is opt-in/local, not part of the default CI suite:
That script starts the stdio MCP server on the mock roaster with pinned INT8
Hugging Face artifacts and detector-paced WAV replay, then uses public MCP
tools to validate first-crack detection against the fixture labels and export
roast.jsonl, roast.csv, and summary.json.
For microphone capture, audio.input_device: null uses the system default input
device. To pin a specific microphone, set audio.input_device to a
PortAudio-resolvable device name or platform device identifier. On Linux and
Raspberry Pi, use arecord -l and arecord -L to inspect ALSA devices; values
such as plughw:1,0 are often more forgiving than raw hw:1,0 because ALSA can
perform format conversion. On macOS, use the system sound settings or a
sounddevice device listing during manual validation. Real microphone checks
are optional and should be run only when first_crack.mode: audio and
audio.source: microphone are deliberately configured.
Optional real microphone validation is gated manual work. Before running it,
configure released Hugging Face ONNX artifacts or a validated
first_crack.local_model_dir, select the intended microphone, and confirm the
MCP process can start without artifact or audio-capture errors. Expected
evidence for a pass is: get_roast_state.first_crack_status moves from
pending to detected during a supervised roast or controlled replay, the
recorded first_crack_detected event includes detector metadata, and normal
roast controls continue to work. Missing artifacts, unavailable audio devices,
and detector failures should surface as unavailable or faulted status and
remain outside normal CI.
HF_HOME is consumed by Hugging Face tooling directly rather than copied into the RoastPilot config object.
This repository does not train, export, sync, or publish first-crack models.
The coffee-first-crack-detection repository remains the source of truth for:
RoastPilot only consumes released artifacts from syamaner/coffee-first-crack-detection. The runtime boundary for this repo is inference-time configuration and model selection, not model lifecycle management.
Current first-crack defaults are kept safe for local development:
mode: disabledprecision: int8repo_id: syamaner/coffee-first-crack-detectionThat default keeps local setup free from Hugging Face network access until
audio mode is deliberately configured.
When first_crack.mode: audio is deliberately configured, RoastPilot consumes
the released ONNX artifacts with ONNX Runtime and the released AST preprocessor
config through the MCP-owned NumPy/SciPy MelFrontend; model training, export, and Hub
publishing remain outside this repository.
In audio mode, starting a roast session prepares the configured audio capture
pipeline and released-artifact detector runtime. Detector windows are processed
only after T0 is recorded and the active session is in roasting. Confirmed
detector output records first_crack_detected once through the authoritative
session timeline. The runtime stops when first crack is recorded automatically
or through the explicit manual override, and also stops on drop, cooling
completion, emergency stop, and process shutdown. Missing artifacts,
unavailable audio capture, and detector errors are surfaced through
get_roast_state.first_crack_status as unavailable or faulted rather than
crashing normal roast controls. Disabled and manual first-crack modes do not
start audio capture or detector runtime.
RoastPilot currently supports snapshot export through export_roast_log for
the active in-process session.
Current export files:
roast.jsonl with append-only event and sampled telemetry rows during the
roastroast.csv with telemetry and event rows using the planned CSV columns for
timestamps, elapsed seconds, phase, temperatures, controls, event flags,
development percent, RoR/delta metrics, and first-crack model metadatasummary.json with session timestamps, total roast seconds, development
metrics, roaster driver, and first-crack model metadatalogs/roasts/{session_id}/Cross-format log schema completeness tests are in place. The June 2026 published-package baseline and August 2026 integrated agent-roast report record the current live-validation boundary; new hardware configurations still require their own supervised validation.