Библиотека Anova Precision Oven + MCP-сервер

Этот проект содержит два намеренно раздельных уровня:

• anova_oven: асинхронная Python-библиотека для аутентификации Anova, обнаружения устройств, температур, управления приготовлением, этапов и кадров камеры WebRTC APO 2.0.

• anova_oven_mcp: тонкий адаптер MCP 2.x поверх этой библиотеки.

Разделение сохраняет код устройства пригодным для повторного использования в будущем сервисе на Raspberry Pi или расширении, не делая MCP основной зависимостью.

Возможности

• Захват одного JPEG-кадра камеры или потребление кадров как асинхронного итератора.

• Чтение четырёх физических датчиков приготовления: сухой верх, сухой низ, влажный термометр и щуп для еды. Активное значение сухого контроля возвращается отдельно.

• Запуск и остановка приготовления. Таймерные этапы поддерживают от 1 секунды до максимальных 359 940 секунд (99 ч 59 мин); пропущенная длительность означает работу до остановки.

• Использование этапов, завершаемых по щупу, и последовательных, таймерных, с предварительным нагревом или ручным продвижением этапов.

• Замена списка этапов активного приготовления.

• Возврат времени суток в UTC как часов, минут и секунд.

• Загрузка учётных данных из связки ключей macOS, приватного файла с режимом 0600 или внедрённого секрета окружения.

Related MCP server: fireboard-mcp

Важные примечания о статусе и безопасности

Команды приготовления физически активируют прибор. Инструменты MCP, которые запускают или изменяют приготовление, требуют acknowledge_physical_action=true и проверяют задокументированные пределы температуры, таймера, щупа, нагревательного элемента, пара, вентилятора и решёток духовки.

Путь камеры — это приватный протокол мобильного приложения, не входящий в задокументированную поверхность команд Personal Access Token от Anova. В настоящее время он требует:

• Anova Precision Oven 2.0

• активное приготовление

• совместимую/текущую прошивку

• подходящую подписку Anova

Форма команды или ответа для живого видео может измениться с будущим релизом приложения/бэкенда Anova. Подписанные URL для воспроизведения хранятся внутри и никогда не возвращаются библиотекой или MCP-сервером.

См. VALIDATION.md для завершённых проверок датчиков, приготовления, камеры и безопасности после тестов.

Установка

Требуется Python 3.11 или новее. Рекомендуется Python 3.12.

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[server]"

Для использования библиотеки без MCP или видео:

python -m pip install -e .

Дополнительные опции: camera, mcp, server и test. Базовая установка сохраняет основную библиотеку лёгкой; команда anova-oven-mcp укажет вам установить дополнение mcp или server, если его необязательный рантайм отсутствует.

Учётные данные

Порядок поиска учётных данных по умолчанию:

1. ANOVA_FIREBASE_REFRESH_TOKEN

2. файл, указанный в ANOVA_FIREBASE_REFRESH_TOKEN_FILE

3. элемент связки ключей macOS с типом "generic-password" со следующими параметрами:

   • сервис com.codex.anova-camera.firebase-refresh-token

   • аккаунт anova-oven-mcp

Фиксированная метка аккаунта в связке ключей предотвращает случайный выбор старого учётного данного под тем же сервисом. Чтение связки ключей и ротация токенов используют напрямую фреймворк Security от Apple, поэтому секрет не попадает в аргументы процесса.

Не помещайте токен обновления в исходный код, конфигурацию MCP, историю оболочки или журналы. Для Pi рекомендуется адаптер через менеджер секретов хоста или файл учётных данных с режимом 0600, принадлежащий root:

chmod 600 /run/credentials/anova-refresh-token
export ANOVA_FIREBASE_REFRESH_TOKEN_FILE=/run/credentials/anova-refresh-token

Если подключено более одной духовки, установите ANOVA_OVEN_ID в окружении процесса. Инструмент списка устройств MCP намеренно возвращает только сокращённые ID; настраивайте полный ID вне контекста, видимого модели.

MCP-сервер

Локальный стандарт — stdio, поэтому он не открывает слушающий порт:

.venv/bin/anova-oven-mcp

Типичная конфигурация MCP для рабочего стола выглядит так:

{
  "mcpServers": {
    "anova-oven": {
      "command": "/absolute/path/to/anova-oven-mcp/.venv/bin/anova-oven-mcp"
    }
  }
}

Доступные инструменты:

Claude Code и Claude Desktop

Включённый конфигуратор может зарегистрировать этот локальный stdio-сервер в Claude Code, Claude Desktop или в обоих. Он не копирует учётные данные Anova ни в один из клиентов.

Сначала просмотрите изменения:

python scripts/configure_claude.py --dry-run

Настройте оба клиента (Claude Code по умолчанию использует пользовательскую область):

python scripts/configure_claude.py --target both

Полезные альтернативы:

# One client only
python scripts/configure_claude.py --target code
python scripts/configure_claude.py --target desktop

# Update an existing same-named Claude Code entry
python scripts/configure_claude.py --target code --replace

# Remove the entry from both clients
python scripts/configure_claude.py --remove

Конфигурация Claude Desktop объединяется атомарно, сохраняя другие серверы и создавая резервную копию с меткой времени и режимом 0600. После этого закройте и снова откройте Claude Desktop. Для распространения за пределами локальной копии текущий предпочтительный формат Anthropic — устанавливаемый MCP Bundle (.mcpb).

Для будущего сервиса на Pi тот же адаптер может использовать Streamable HTTP:

anova-oven-mcp --transport streamable-http

Это привязывается к 127.0.0.1:8766. Не-loopback привязка требует --allow-lan; не открывайте его, пока не будет настроен аутентифицированный обратный прокси или уровень авторизации MCP.

Пример библиотеки

import asyncio

from anova_oven import CookPlan, CookingStage, PrecisionOvenClient


async def main() -> None:
    async with PrecisionOvenClient() as oven:
        temperatures = await oven.get_temperatures()
        print(temperatures.as_dict())

        plan = CookPlan(
            title="Two-stage example",
            stages=(
                CookingStage(
                    title="Warm",
                    target_celsius=60,
                    duration_seconds=600,
                ),
                CookingStage(
                    title="Finish",
                    target_celsius=180,
                    duration_seconds=300,
                ),
            ),
        )

        # This physically starts the oven:
        receipt = await oven.start_cook(plan)
        print(receipt.stage_ids)

        try:
            frame = await oven.capture_frame(timeout=60)
            with open("oven-frame.jpg", "wb") as output:
                output.write(frame.jpeg_bytes)
        finally:
            await oven.stop_cook()


asyncio.run(main())

Для повторяющихся кадров используйте oven.frames() как асинхронный итератор. MCP намеренно предоставляет одноразовые изображения, потому что бесконечная потоковая передача вызовов инструментов плохо переносится между хостами.

Проверка

python -m pip install -e ".[server,test]"
ruff check .
mypy src
pytest
python -m pip check

Проверка учётной записи только для чтения:

python scripts/live_read_only.py

Защищённый смоук-тест камеры запускает трёхминутное приготовление при минимальной температуре, ожидает независимое событие состояния, подтверждающее это приготовление, захватывает один кадр и выполняет физическую остановку перед очисткой медиа с максимальными усилиями:

python scripts/live_camera_smoke.py --acknowledge-empty-oven-and-start-cook

Этот тест успешно прошёл на APO 2.0. Захваченный проверочный кадр включён как oven-camera-smoke.jpg.

Источники протокола

• Аутентификация Anova Wi-Fi

• Обнаружение устройств Anova

• Команды духовки Anova и примеры этапов v2

• Официальный справочный проект Anova Wi-Fi

• Официальный MCP Python SDK