RoastPilot

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:

Evidence:

• Roast-day validation report (formal pass/fail analysis, both roasts)
• Roast #1 test summary and Roast #2 auto-validation summary (timelines, metrics, screenshots)
• Committed artifacts (roast logs, guarded-validation JSON, transcripts, screenshots, checksums)

See the v0.1 overall plan and the project state registry for the plan and state history.

Related Project Artifacts

• Current architecture article: The Architecture: The Agent-Spec Driven ML Development With Warp
• Original prototype intro: Training a Neural Network to Detect Coffee First Crack from Audio
• Original prototype MCP post: Building MCP Servers to Control a Home Coffee Roaster
• First-crack model: syamaner/coffee-first-crack-detection
• First-crack dataset: syamaner/coffee-first-crack-audio
• First-crack demo: Coffee First-Crack Detection Space

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

python -m pytest

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

python -m ruff check .

Format Check

python -m ruff format --check .

Typecheck

python -m pyright

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

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

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
• finalise_cold_characterisation_session

Per-poll cold-characterisation observation

get_roast_state.cold_characterisation_observation is meaningful only for a purpose="cold_characterisation" session; consumers must gate on session_purpose. It reports the commanded roast-fan level as a typed, read-only observation. It is neither physical, link, nor freshness proof, and is not atomic with device_state; it does not duplicate heat, main-fan, or cooling state.

Cold-characterisation finalisation

finalise_cold_characterisation_session is a non-actuating teardown tool for an active, latest session started with purpose="cold_characterisation"; it is not for normal roasts. It only admits known connected safe-zero drive