RoastPilot
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-0.1.16 were metadata/docs releases. Public PyPI metadata lists 0.2.3,
and the matching release workflow reports successful PyPI and MCP Registry
publication; the current live MCP Registry listing is not independently checked.
Those are public metadata and workflow observations, not independent verification
of public artefact bytes, contents, tag provenance, or installed bytes.
The repository's 0.2.3 candidate record includes D209's typed cold-only
temperature and packet projection alongside #222's roast-fan-only cold-session
get_roast_state observation, and PR #231's stopped-fault exact-session
recovery semantics. The #222 observation reports commanded roast-fan state
only. The D209 projection reports telemetry, packet validity and counters, and
raw and typed temperature information. Packet progress screening is an Agent
comparison between observations, not a continuous freshness or link watchdog.
Those source records and publication observations do not prove physical
actuation, calibration, accuracy, continuous freshness, link health, readiness,
or safety. Issue #225 remains open for release-process reconciliation; issue
#227 is closed for the D209 software projection.
Relative to public current-tag source
3e40487686880825f93ae2015cc4253d9183623b, the only new runtime content in
0.2.4 is S1's deferred local SciPy symmetric-Hann-window import. Numerical
output and interfaces are unchanged. A version string, wheel name, or declared
command-line digest does not attest which bytes the intended interpreter imports.
Verifying installed bytes is a separate, operator-authorised gate that this
documentation does not perform or claim for either distribution. 0.2.4
preparation is complete only up to the merged head and a successful
non-publishing dry run; tag creation, protected release environment approval,
publication, and live artefact verification remain human-operator actions. It
does not authorise hardware, beans, or a readiness claim.
A successful non-publishing dry run must be recorded after merge; no pending
dry-run success is asserted here.
This packaged README Status is a preparation-time snapshot. It records the
current source and public-metadata observations above, and makes no current
publication claim for 0.2.4.
D191's ratified limits remain N = 1 and X = 200 ms; the production fatal
streak remains 30. 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. #157 and #194 remain open. 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.
Related Project Artifacts
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:
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:
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.
Local Development
Setup
Use the commands in the Install section, then continue with the checks below.
Test
Coverage
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
Format Check
python -m ruff format --check .
Typecheck
CLI Smoke
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:
coffee-roaster-mcp mic-check --config coffee-roaster-mcp.yaml
coffee-roaster-mcp record-check --config coffee-roaster-mcp.yaml