coffee-roaster-mcp 0.1.0__tar.gz

coffee_roaster_mcp-0.1.0/.claude/skills/code-quality/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: code-quality
+description: Run RoastPilot quality gates for tests, linting, formatting, type checking, and CLI smoke checks. Use before marking a story complete or before opening a PR.
+---
+
+# Code Quality - RoastPilot
+
+Use this skill before marking implementation work complete.
+
+## Prerequisites
+
+- Work from the repository root.
+- Use Python 3.11+.
+- Dependencies must be installed from project metadata:
+
+```bash
+python -m pip install -e . --group dev
+```
+
+## Required Checks
+
+Run:
+
+```bash
+python -m pytest
+python -m ruff check .
+python -m ruff format --check .
+python -m pyright
+coffee-roaster-mcp --help
+coffee-roaster-mcp --version
+```
+
+## Acceptance
+
+- `pytest` passes.
+- `ruff check .` passes.
+- `ruff format --check .` passes.
+- `pyright` reports 0 errors.
+- CLI help and version commands exit successfully.
+
+## If The Environment Is Incomplete
+
+- Do not silently skip checks.
+- Create a temporary virtual environment if needed.
+- Install dependencies from `pyproject.toml`.
+- Record exactly which checks passed and which could not be run.
+
+## Do Not
+
+- Add production test fakes to make tests easier.
+- Install dependencies without declaring them in `pyproject.toml`.
+- Mark hardware stories complete from unit tests alone.
+

coffee_roaster_mcp-0.1.0/.claude/skills/hottop-validation/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: hottop-validation
+description: Review the guarded manual validation path for Hottop hardware work. Use when planning or verifying hardware-facing changes without overstating what the repo can currently run.
+---
+
+# Hottop Validation - RoastPilot
+
+Use this skill for Hottop-facing work and release-readiness review.
+
+## Current Scope
+
+- Hottop lifecycle, command-loop streaming, packet build/parse, control command state, and temperature-unit handling exist behind the `HottopRoasterDriver` boundary.
+- The MCP roast-session tools call the configured `RoasterDriver` boundary
+  while preserving the one-session store semantics and fail-closed behavior.
+- The runnable validation entrypoint is `coffee-roaster-mcp hottop-validate`.
+- Hardware stories are not complete from mock tests alone.
+- For operator setup details, including the Hottop config block and log output
+  paths, use `docs/install-and-hardware-setup.md`.
+
+## Pre-Validation Gates
+
+Complete these gates in order before any Hottop hardware session.
+
+### 1. Story And Source Readiness
+
+- Confirm E3-S4 through E3-S8 are complete in `docs/state/epics/coffee-roaster-mcp-v0.1.md`.
+- Confirm the current Hottop validation story or release-readiness task is active, not a broader driver redesign.
+- Confirm unit and integration coverage exists in `tests/test_drivers.py` and `tests/test_hottop_validation.py`.
+- Confirm fail-closed behavior in `src/coffee_roaster_mcp/drivers.py`.
+
+### 2. Operator And Hardware Readiness
+
+- Confirm the roaster is supervised for the full run.
+- Confirm the operator understands emergency stop, bean drop, cooling, and physical power-off expectations.
+- Confirm the serial port is known.
+- Confirm the config file explicitly sets `roaster.driver: hottop_kn8828b_2k_plus`.
+- Confirm the operator accepts that `--include-drop` is irreversible for loaded beans.
+
+### 3. Run Readiness
+
+- Run the non-destructive validation before any full validation.
+- Proceed to `--include-drop` only when the roaster is ready for an actual drop check.
+- Proceed to `--include-emergency-stop` only when the operator is ready to verify the safety action.
+
+Confirm these source artifacts before running hardware:
+
+- `src/coffee_roaster_mcp/drivers.py`: `HottopRoasterDriver`, command-loop lifecycle, command state, packet build/parse, status read, temperature normalization, and emergency stop.
+- `src/coffee_roaster_mcp/hottop_validation.py`: guarded `hottop-validate` runner, JSON evidence shape, skipped-step behavior, and release-label decision.
+- `src/coffee_roaster_mcp/cli.py`: `hottop-validate` CLI options and acknowledgement flag.
+- `docs/state/epics/coffee-roaster-mcp-v0.1.md`: E3-S4 through E3-S9 status and validation notes.
+
+## Hard Abort Conditions
+
+Stop the validation session immediately if any of these occur:
+
+- The serial port cannot be identified confidently or opens the wrong device.
+- The command reports repeated serial write, read, checksum, or command-loop errors.
+- The roaster heats when the current step expects heat off.
+- Heat, fan, drop, cooling, or emergency stop causes a physical action inconsistent with the expected state.
+- Temperature readings are absent, implausible, or jump unexpectedly after the telemetry wait.
+- The command loop does not stop cleanly on disconnect.
+- The operator loses direct supervision of the roaster.
+- Smoke, electrical smell, uncontrolled heat, jammed drop, or unexpected mechanical behavior appears.
+
+Abort procedure:
+
+1. Run or trigger emergency stop if it is safe to do so.
+2. Physically power off the roaster if software control is uncertain.
+3. Preserve the JSON evidence file and terminal output.
+4. Do not continue to later steps in the same run.
+5. Record the failed step, observed behavior, and whether the roaster was physically powered off.
+
+## Guarded Validation Command
+
+Use a local config file with an explicit Hottop driver and serial port:
+
+```yaml
+roaster:
+  driver: hottop_kn8828b_2k_plus
+  port: /dev/cu.usbserial-XXXX
+  baudrate: 115200
+  temperature_unit: auto
+  command_interval_seconds: 0.3
+```
+
+Run the non-destructive portion first:
+
+```bash
+coffee-roaster-mcp hottop-validate \
+  --config coffee-roaster-mcp.yaml \
+  --output docs/validation/hottop-e3-s9-non-destructive.json \
+  --i-understand-this-controls-hardware
+```
+
+Run the full validation only when the roaster is supervised and ready for drop and emergency-stop checks:
+
+```bash
+coffee-roaster-mcp hottop-validate \
+  --config coffee-roaster-mcp.yaml \
+  --output docs/validation/hottop-e3-s9-full.json \
+  --i-understand-this-controls-hardware \
+  --include-drop \
+  --include-emergency-stop
+```
+
+Do not commit generated validation JSON unless the file is sanitized to remove sensitive data and formatted for long-term storage. Never commit raw serial captures.
+
+## Pass/Fail Criteria
+
+Use this table with the JSON evidence from `hottop-validate` plus direct operator observation.
+
+| Area | Pass | Needs Review Or Skipped | Fail |
+| --- | --- | --- | --- |
+| Connection and cleanup | `connect` is `passed`, `raw.command_loop_running` is true while connected, command writes increase, and disconnect exits cleanly. | Not applicable. | Serial open fails, writes do not occur after connection, command-loop errors increase, or disconnect reports the loop did not stop. |
+| Startup safe state | First connected state shows heat `0`, fan `0` unless cooling is commanded, cooling false, solenoid false, and drum false before heat is requested. | Not applicable. | Heat, cooling, drop/solenoid, or unexpected fan behavior starts without an explicit validation step. |
+| Packet parsing and telemetry | `stable_telemetry` is `passed`, `raw.status_packet_count` is greater than zero, `bean_temp_c` and `env_temp_c` are plausible, and `raw.status_read_error_count` is zero. | `stable_telemetry` is `needs_review`, startup zero readings are ignored, or temperatures are missing while the command loop otherwise runs. | Packet counts never increase, checksum/read errors repeat, command echoes are parsed as telemetry, or normalized temperatures are physically impossible. |
+| Temperature units | Configured `temperature_unit` matches the run plan, `raw.resolved_temperature_unit` is stable after plausible telemetry, and Celsius-normalized values are plausible. | `auto` changes resolved unit during warmup or after ignored packets. | Fahrenheit readings are exposed as Celsius, Celsius readings are double-converted, or unit resolution remains absent after stable telemetry. |
+| Heat | Heat step sets `heat_level_percent` to the requested conservative value, drum is on when heat is nonzero, then `heat_off` returns heat to `0`. | Not applicable. | Heat remains on after `heat_off`, heat changes without command, or drum behavior contradicts the heat command. |
+| Fan | Fan step sets `fan_level_percent` to the requested value and the Hottop main fan responds consistently. | Not applicable. | Fan value is outside the requested range, fan does not respond, or fan remains high after cooling stop except as part of emergency stop. |
+| Drop | In a full run, `drop` is `passed`, heat is `0`, drum is off, solenoid/drop path is active, cooling is on, and fan is high. | `drop` is skipped in a non-destructive run. This blocks hardware-ready release approval. | Drop is triggered unintentionally, fails to trigger when requested, or does not force heat off and cooling/fan on. |
+| Cooling stop | `cooling_start` turns cooling on with high fan, and `cooling_stop` clears cooling, solenoid/drop path, and fan. | Not applicable. | Cooling does not start, does not stop, or leaves drop/solenoid state active. |
+| Emergency stop | In a full run, emergency stop sets heat `0`, drum off, solenoid closed, cooling on, fan high, and evidence preserves diagnostic state. | Emergency stop is skipped in a non-destructive run. This blocks hardware-ready release approval. | Emergency stop does not force heat off, does not leave cooling/fan in a safe state, or loses diagnostic evidence. |
+
+## Troubleshooting
+
+### Serial Connection Fails
+
+- Check the port with `ls /dev/cu.*` before and after plugging in the USB adapter.
+- Confirm the config uses that exact `roaster.port`.
+- Confirm no other process has the serial port open.
+- Re-run only the non-destructive command until connection and cleanup pass.
+
+### Command Loop Or Write Counters Do Not Advance
+
+- Check `raw.command_loop_running`, `raw.command_loop_iterations`, `raw.command_send_attempts`, `raw.command_write_count`, `raw.command_loop_error_count`, and `raw.last_command_write_size`.
+- Treat repeated errors or partial writes as a hard abort.
+- Review `HottopRoasterDriver._send_command_frame` and disconnect/write review notes in the active epic before changing code.
+
+### Packet Or Temperature Problems
+
+- Check `raw.status_packet_count`, `raw.ignored_temperature_packet_count`, `raw.status_read_error_count`, `raw.raw_bean_temperature`, `raw.raw_env_temperature`, and `raw.resolved_temperature_unit`.
+- If readings are zero during startup but later become plausible, record it as acceptable warmup behavior.
+- If values are consistently implausible, stop and review packet offsets, checksum behavior, and configured `temperature_unit`.
+
+### Drop Or Cooling Problems
+
+- Stop immediately if drop, solenoid, cooling, or fan behavior differs from the expected compound state.
+- Do not retry full validation until the physical state is understood and the roaster is safe.
+- Record whether the mismatch was software state only, physical behavior only, or both.
+
+### Emergency Stop Problems
+
+- Physically power off the roaster if emergency stop does not force heat off.
+- Preserve evidence and do not continue the run.
+- Treat this as release-blocking until fixed and revalidated.
+
+## Report Template
+
+Use this structure in issue comments, PR descriptions, or durable validation notes:
+
+```markdown
+## Hottop Validation Report
+
+- Date/time:
+- Operator:
+- Roaster model:
+- Firmware/context if known:
+- Serial port:
+- Baudrate:
+- Configured temperature unit:
+- Command interval seconds:
+- Command:
+- Evidence file:
+- Non-destructive run or full run:
+
+## Source State
+
+- Branch/commit:
+- E3-S4 through E3-S8 marked complete in epic state: yes/no
+- Required tests before hardware run:
+  - pytest:
+  - ruff check:
+  - ruff format --check:
+  - pyright:
+
+## Results
+
+- Connection and cleanup: pass/fail/needs review
+- Startup safe state: pass/fail/needs review
+- Packet parsing and telemetry: pass/fail/needs review
+- Temperature units: pass/fail/needs review
+- Heat: pass/fail/needs review
+- Fan: pass/fail/needs review
+- Drop: pass/fail/skipped
+- Cooling stop: pass/fail/needs review
+- Emergency stop: pass/fail/skipped
+
+## Observations
+
+- Observed temperatures:
+- Observed command counters:
+- Physical roaster behavior:
+- Deviations:
+- Abort conditions encountered:
+
+## Decision
+
+- Hardware-ready release label allowed: yes/no
+- Follow-up fixes required:
+- Final driver decision:
+```
+
+## Required Notes
+
+For every manual validation run, record:
+
+- roaster model and firmware context if known
+- serial port and configured temperature unit
+- what commands were exercised
+- whether heat, fan, drop, cooling, and emergency stop behaved as expected
+- any uncertainty that keeps the hardware path from being release-ready
+- the JSON evidence path, or a note explaining why evidence was not retained
+
+## Do Not
+
+- Do not mark Hottop stories complete from mock-only validation.
+- Do not improvise control commands against real hardware.
+- Do not run the full validation flags unless the operator intends to exercise drop and emergency stop on the connected roaster.
+- Do not add training, ONNX export, or Hugging Face sync steps here. Those stay in `coffee-first-crack-detection`.

coffee_roaster_mcp-0.1.0/.claude/skills/mcp-dev/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: mcp-dev
+description: Set up the RoastPilot development environment and run current scaffold-level validation commands. Use when bootstrapping local development or validating early MCP scaffold work.
+---
+
+# MCP Dev - RoastPilot
+
+Use this skill for local development setup and scaffold validation.
+
+## Setup
+
+```bash
+python3.11 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e . --group dev
+```
+
+## Current Validation
+
+```bash
+python -m pytest
+python -m ruff check .
+python -m ruff format --check .
+python -m pyright
+coffee-roaster-mcp --help
+coffee-roaster-mcp --version
+coffee-roaster-mcp serve
+```
+
+## Mock-Safe Bootstrap Smoke
+
+For bootstrap work, confirm the default config still requires no roaster hardware, no microphone, and no model download from a guaranteed-empty temporary directory:
+
+```bash
+python -c "import os, tempfile; from coffee_roaster_mcp.config import load_config; tmp = tempfile.TemporaryDirectory(); os.chdir(tmp.name); c = load_config(environ={}); print(c.roaster.driver, c.first_crack.mode, c.first_crack.precision); tmp.cleanup()"
+```
+
+Expected output:
+
+```text
+mock disabled int8
+```
+
+## Notes
+
+- `E2-S1` adds the first stdio MCP server entrypoint with bootstrap-safe introspection tools only.
+- The full mock roast flow is still pending later Epic 2 stories.

coffee_roaster_mcp-0.1.0/.claude/skills/mock-roast/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: mock-roast
+description: Validate the current mock-first RoastPilot path without roaster hardware or model download. Use for bootstrap checks now and for the early MCP tool flow while the full vertical slice is still landing.
+---
+
+# Mock Roast - RoastPilot
+
+Use this skill for the mock-first local workflow.
+
+## Current Scope
+
+- `E2-S1` provides a real stdio MCP server entrypoint.
+- `E2-S4` now provides the first roast-session MCP tool surface on the mock path.
+- This workflow validates the mock-safe bootstrap path and the in-process tool
+  flow without roaster hardware, microphone access, model download, or network.
+  For full operator setup details, use `docs/install-and-hardware-setup.md`.
+
+## Current Validation
+
+Run from the repository root:
+
+```bash
+python -c "import os, tempfile; from coffee_roaster_mcp.config import load_config; tmp = tempfile.TemporaryDirectory(); os.chdir(tmp.name); c = load_config(environ={}); print(c.roaster.driver, c.first_crack.mode, c.first_crack.precision); tmp.cleanup()"
+coffee-roaster-mcp --help
+coffee-roaster-mcp --version
+coffee-roaster-mcp serve
+```
+
+Expected bootstrap output:
+
+```text
+mock disabled int8
+```
+
+## What This Confirms
+
+- The default roaster driver stays on `mock`.
+- First-crack detection stays `disabled` by default.
+- Default precision stays `int8`.
+- Local bootstrap does not require roaster hardware, microphone access, or model download.
+- The MCP server now exposes the first session-control tool surface for the mock path.
+
+## Do Not Claim Here
+
+- Do not claim final end-to-end release readiness before `E7-S1`.
+- Do not add model download, model export, or Hugging Face sync steps here. Those stay in `coffee-first-crack-detection`.
+
+## Current MCP Tool Flow
+
+The current mock-path tools are:
+
+- `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`
+
+`export_roast_log` writes `roast.jsonl`, `roast.csv`, and `summary.json` under
+the configured log directory for the active session.
+
+## Extend Later
+
+Extend this workflow with:
+
+- full mock roast start-to-export smoke checks
+- log file content validation
+- MCP client fixture reuse across runtime stories

coffee_roaster_mcp-0.1.0/.claude/skills/release-registry/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: release-registry
+description: Review the staged PyPI and MCP Registry release workflow for RoastPilot. Use when preparing distribution work and keep current prereqs explicit until release stories land.
+---
+
+# Release Registry - RoastPilot
+
+Use this skill for package and registry release preparation.
+
+## Current Scope
+
+- This is a staged runbook for future release work.
+- `server.json`, registry publishing automation, and full release verification land in later Epic 6 stories.
+- Do not present this workflow as fully runnable until those stories are complete.
+
+## Release Targets
+
+- Package name: `coffee-roaster-mcp`
+- MCP Registry name: `io.github.syamaner/coffee-roaster-mcp`
+- Display title: `RoastPilot`
+
+## Planned Release Flow
+
+1. Confirm the package version is intentional.
+2. Build and validate sdist plus wheel artifacts.
+3. Confirm README contains the MCP verification string when the release story adds it.
+4. Confirm `server.json` exists and matches the package version when the registry metadata story lands.
+5. Publish the package to PyPI.
+6. Install the published package in a clean environment.
+7. Run mock-safe smoke checks against the published package.
+8. Publish MCP Registry metadata.
+9. Verify the registry listing renders the expected package and install metadata.
+
+## Current Review Checklist
+
+Until Epic 6 lands, use this skill to review readiness only:
+
+- package name is still `coffee-roaster-mcp`
+- registry name is still `io.github.syamaner/coffee-roaster-mcp`
+- release docs do not imply hardware-ready support without Hottop validation
+- default first-crack mode remains `disabled` so package install smoke does not require audio or model download
+- version alignment across package metadata, tags, and future `server.json` remains part of the release plan
+
+## Mock-Safe Published Smoke Target
+
+When published package verification becomes available, the minimum smoke target remains:
+
+```bash
+coffee-roaster-mcp --help
+coffee-roaster-mcp --version
+python -c "import os, tempfile; from coffee_roaster_mcp.config import load_config; tmp = tempfile.TemporaryDirectory(); os.chdir(tmp.name); c = load_config(environ={}); print(c.roaster.driver, c.first_crack.mode, c.first_crack.precision); tmp.cleanup()"
+```
+
+Expected bootstrap output:
+
+```text
+mock disabled int8
+```
+
+## Do Not
+
+- Do not add Hugging Face model sync, model export, model cards, or dataset cards to this release workflow.
+- Do not claim MCP Registry publishing is verified before `server.json`, PyPI verification, and `mcp-publisher` stories are complete.
+- Do not label a release hardware-ready before the Hottop manual validation path passes.

coffee_roaster_mcp-0.1.0/.github/instructions/copilot.instructions.md

@@ -0,0 +1,57 @@
+# Copilot Code Review Instructions
+
+## Project Overview
+
+RoastPilot is a spec-driven Python MCP server for autonomous coffee roasting. The server will own roaster control, telemetry, first-crack event integration, roast timing, derived metrics, event logging, and export in one local stdio process.
+
+Full project rules are in `AGENTS.md` at the repo root.
+
+## Key Conventions
+
+### Runtime Boundary
+
+- v0.1 is a local stdio MCP server.
+- Agent orchestration and n8n are out of scope.
+- One `RoastSession` runtime will own timing, telemetry, events, metrics, and logs.
+- `beans_added_at` is T0. Auto-T0 detection is disabled by default.
+
+### Configuration
+
+- Config defaults must allow a local mock run with no config file.
+- Default roaster driver is `mock`.
+- Default first-crack mode is `disabled`.
+- YAML config is loaded from `coffee-roaster-mcp.yaml`.
+- Environment overrides must be applied after file config.
+- Use explicit `is None` checks where falsy values such as `0`, `0.0`, or empty strings have distinct meaning.
+
+### Hugging Face Models
+
+- This repo consumes released artifacts from `syamaner/coffee-first-crack-detection`.
+- Do not add model training, model export, Hugging Face sync, model card, or dataset card publishing here.
+- INT8 ONNX is the default runtime precision.
+- FP32 ONNX is supported by config.
+
+### Roaster Safety
+
+- Hardware behavior must be conservative.
+- Hottop command-loop behavior, packet handling, temperature units, drop, cooling, and emergency stop need explicit tests or manual validation notes.
+- Do not accept mock-only validation for hardware-ready claims.
+
+### Code Style
+
+- Python 3.11+ with full type hints on public functions and methods.
+- Google-style docstrings for public APIs.
+- `ruff check .`, `ruff format --check .`, `pyright`, and `pytest` should pass.
+- Dependencies must be declared in `pyproject.toml`.
+
+### Generated And Local Files
+
+- Do not commit model weights, ONNX files, audio recordings, roast logs, serial captures, `.env` files, or IDE folders.
+- Generated roast logs will belong under ignored log directories once logging lands.
+
+### Testing
+
+- Tests live under `tests/`.
+- Avoid production-only fakes created solely for tests.
+- Config tests should cover defaults, YAML overrides, environment overrides, and validation failures.
+