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; 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:

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

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: