MCP Server Awtrix: AI Agent Display Orchestrator для Ulanzi и Pixel-часов

MCP Server Awtrix (mcp-server-awtrix) — это сервер Model Context Protocol (MCP) с открытым исходным кодом и декларативный оркестратор метрик, предназначенный для предоставления AI-агентам (Antigravity, Claude Desktop, Cursor, Cline, AutoGPT и др.) полного контроля над Ulanzi TC001 и совместимыми пиксельными матричными умными часами, работающими на Awtrix Light.

Он соединяет разговорных и автономных AI-агентов с физическими настольными дисплеями, обеспечивая:

• Мгновенные оповещения агентов: Отправка ad-hoc статусных оповещений, уведомлений о сбоях сборки и завершении задач на пиксельный экран.

• Динамические карусельные приложения: Регистрация, обновление и циклическое переключение пользовательских приложений телеметрии в реальном времени (здоровье сервера, метрики SaaS, счётчики выручки, статус сборки).

• Декларативный опрос метрик: Автоматизация фонового получения API и форматирования пороговых значений с помощью YAML-спецификаций без написания специализированных Python-скриптов.

• Телеметрия и управление оборудованием: Проверка уровня заряда батареи, регулировка яркости матрицы, управление состояниями питания и запуск пользовательских звуковых сигналов.

Содержание

1. Документ требований к продукту (PRD)

   • Постановка проблемы

   • Цели и не-цели

   • Целевые персоны и сценарии использования

   • Функциональные требования

   • Нефункциональные требования

2. Системная архитектура и дизайн

   • Высокоуровневая архитектура

   • Разбивка компонентов

   • Поток данных

3. Спецификация MCP-инструментов

4. Декларативный движок приложений (YAML-схема)

   • Пример 1: CI/CD и здоровье сервиса (Checkly)

   • Пример 2: Мультиметрическая SaaS-панель

5. Быстрый старт и установка

   • Предварительные требования

   • Локальная настройка с uv / pip

   • Конфигурация MCP-клиента

6. Дорожная карта и вклад

7. Лицензия

Related MCP server: pixoo-mcp-server

1. Документ требований к продукту (PRD)

Постановка проблемы

Разработчики и продвинутые пользователи умных пиксельных часов (например, Ulanzi TC001 с Awtrix Light) в настоящее время пишут разрозненные, жёстко закодированные Python- или Bash-скрипты cron для запросов к внешним API и обновления матричных приложений.

При работе с AI-агентами кодирования:

• Агенты должны генерировать и поддерживать сырой императивный код для каждой метрики.

• Нет стандартизированного набора инструментов для отправки уведомлений в реальном времени или управления жизненным циклом дисплея.

• Управление секретами подвержено ошибкам, что приводит к утечкам ключей API в промптах и журналах AI.

• Нет встроенного резервного механизма или проверки для многосегментного форматирования текста и пиксельных иконок.

Цели и не-цели

Цели

• Нативный MCP-интерфейс: Предоставить стандартный сервер Model Context Protocol с надёжными инструментами для уведомлений, пользовательских приложений, управления устройствами и предпросмотра.

• Декларативная телеметрия: Позволить агентам и людям определять правила опроса метрик в простых YAML-файлах со встроенными шаблонами (Jinja2) и стилизацией пороговых значений.

• Изоляция секретов: Отделить чувствительные учётные данные от контекста промпта с помощью подстановки переменных окружения .env.

• Горячая перезагрузка без простоев: Автоматически отражать изменения в YAML-конфигурационных файлах без перезапуска сервиса.

• Надёжные резервные механизмы: Корректно обрабатывать сетевые сбои, ограничения скорости API и офлайн-состояния дисплея.

Не-цели

• Замена прошивки Awtrix Light (этот инструмент взаимодействует исключительно с официальным REST/MQTT API Awtrix Light).

• Сложная синхронизация тайлов на нескольких мониторах (фокус на одиночных или мультиинстансных автономных пиксельных часах).

Целевые персоны и сценарии использования

Функциональные требования

1. FR-1: Мгновенные уведомления (/api/notify):

   • Поддержка пользовательского текста, многосегментного цветного текста, ID иконки, звуковых/RTTTL-мелодий, приоритетного удержания и длительности.

2. FR-2: Пользовательские карусельные приложения (/api/custom):

   • Возможность регистрировать, обновлять и удалять именованные приложения из цикла отображения.

   • Поддержка форматирования сегментов rich text ([{"t": "FAIL", "c": "FF0000"}, {"t": " (2/10)", "c": "FFFFFF"}]).

3. FR-3: Декларативный фоновый движок:

   • Встроенный планировщик (asyncio / apscheduler), выполняющий задания опроса, определённые в apps/*.yaml.

   • Шаблонный движок, поддерживающий вычисляемые переменные, арифметику и условные выражения.

4. FR-4: Состояние устройства и телеметрия:

   • Запрос процента заряда батареи, RSSI Wi-Fi, датчика освещённости, состояния матрицы и активных приложений.

   • Регулировка яркости, статуса сна/пробуждения и переходов.

5. FR-5: Пробный запуск и симуляция:

   • Инструмент предпросмотра, возвращающий точные отрендеренные JSON-полезные нагрузки и проверки цветов перед отправкой на оборудование.

Нефункциональные требования

• Задержка: Прямые выполнения MCP-инструментов должны отправляться на Awtrix в течение $< 150\text{мс}$ в локальных сетях.

• Устойчивость: Оркестратор повторяет неудачные запросы API с экспоненциальной задержкой, прежде чем пометить приложение как деградировавшее.

• Переносимость: Упакован как стандартный Python-пакет с поддержкой uv/pipx, Docker-контейнер и автономный CLI.

2. Системная архитектура и дизайн

Высокоуровневая архитектура

                                  ┌──────────────────────────┐
                                  │      AI Client/Host      │
                                  │ (Claude / Antigravity /  │
                                  │     Cursor / Cline)      │
                                  └────────────┬─────────────┘
                                               │
                                               │ stdio / SSE (MCP Protocol)
                                               ▼
┌────────────────────────────────────────────────────────────────────────────────────────┐
│                                  mcp-server-awtrix                                     │
│                                                                                        │
│  ┌───────────────────────┐   ┌──────────────────────────────┐   ┌───────────────────┐  │
│  │     MCP Interface     │   │      App Orchestrator        │   │   Config Watcher  │  │
│  │ (Tools / Resources)   │   │     (Async Scheduler)        │   │   (Hot-Reload)    │  │
│  └───────────┬───────────┘   └──────────────┬───────────────┘   └─────────┬─────────┘  │
│              │                              │                             │            │
│              ▼                              ▼                             ▼            │
│  ┌──────────────────────────────────────────────────────────────────────────────────┐  │
│  │                               Core Engine & Driver                               │  │
│  │  - Schema Validator (Pydantic)                                                   │  │
│  │  - Template & Expression Engine (Jinja2 / JSONPath)                              │  │
│  │  - Secret Resolver (.env)                                                        │  │
│  │  - Awtrix REST / WebSocket Client                                                │  │
│  └──────────────────────────────────────────┬───────────────────────────────────────┘  │
└─────────────────────────────────────────────┼──────────────────────────────────────────┘
                                              │
                                              │ HTTP REST (JSON)
                                              ▼
                                ┌──────────────────────────┐
                                │     Ulanzi TC001 Clock   │
                                │   (Awtrix Light Firmware)│
                                └──────────────────────────┘

Разбивка компонентов

1. Слой MCP-интерфейса:

   • Реализует конечные точки сервера Model Context Protocol через stdio и SSE.

   • Предоставляет инструменты со строгими JSON-схемами и человекочитаемой документацией для AI-моделей.

2. Декларативный движок опроса:

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

   • Выполняет HTTP-запросы, извлекает поля с помощью JSONPath/выражений и разрешает правила отображения.

3. Драйвер Awtrix:

   • Инкапсулирует связь с устройством, дедупликацию запросов, пул соединений и восстановление после ошибок.

4. Слой конфигурации и безопасности:

   • Изолирует чувствительные токены в .env. Конфигурационные файлы ссылаются на переменные через синтаксис ${VAR_NAME}.

3. Спецификация MCP-инструментов

AI-агенты могут выполнять следующие MCP-инструменты:

awtrix_notify

Отправляет немедленное уведомление с высоким приоритетом на экран (прерывает текущую карусель).

{
  "text": "Build Failed: Backend API",
  "icon": "10558",
  "color": "FF0000",
  "duration": 8,
  "sound": "alarm",
  "rtttl": "beep:d=4,o=5,b=100:16e6,16e6",
  "wakeup": true
}

awtrix_upsert_app

Регистрирует или обновляет постоянное пользовательское приложение в цикле карусели.

{
  "name": "app_users",
  "text": [
    {"t": "1,420", "c": "FFFFFF"},
    {"t": " (+42)", "c": "00FF00"}
  ],
  "icon": "2058",
  "duration": 5,
  "lifetime": 300
}

awtrix_delete_app

Удаляет пользовательское приложение из цикла устройства.

{
  "name": "app_users"
}

awtrix_get_device_state

Возвращает статистику оборудования и текущие операционные метрики.

Ответ:

{
  "online": true,
  "battery": 88,
  "charging": true,
  "lux": 140,
  "temp": 24,
  "ram_free": 128440,
  "active_app": "app_users",
  "brightness": 120
}

awtrix_set_settings

Настраивает параметры устройства, такие как яркость, переключение матрицы и скорость переходов.

{
  "brightness": 80,
  "power": true
}

awtrix_test_render

Вспомогательный инструмент пробного запуска, который анализирует выражения и возвращает отрендеренную полезную нагрузку без отправки на оборудование.

4. Декларативный движок приложений (YAML-схема)

Вместо поддержки пользовательских Python-скриптов размещайте манифесты .yaml в каталоге apps/.

Пример 1: Здоровье сервиса (Checkly)

apps/checkly.yaml

app_id: "checkly"
name: "checkly_status"
enabled: true
interval_seconds: 60

source:
  type: "http"
  url: "https://api.checklyhq.com/v1/checks"
  headers:
    Authorization: "Bearer ${CHECKLY_API_KEY}"
    X-Checkly-Account: "${CHECKLY_ACCOUNT_ID}"

transform:
  total: "len(data)"
  failures: "sum(1 for c in data if c.get('hasFailures'))"
  degraded: "sum(1 for c in data if c.get('isDegraded') and not c.get('hasFailures'))"

display:
  - condition: "failures > 0"
    icon: "10558"
    notify: true
    text:
      - { text: "FAIL ", color: "FF0000" }
      - { text: "({{failures}}/{{total}})", color: "FFFFFF" }

  - condition: "degraded > 0"
    icon: "10558"
    text:
      - { text: "WARN ", color: "FFA500" }
      - { text: "({{degraded}}/{{total}})", color: "FFFFFF" }

  - condition: "default"
    icon: "483"
    text:
      - { text: "UP ", color: "00FF00" }
      - { text: "({{total}})", color: "FFFFFF" }

Пример 2: Мультиметрическая SaaS-панель

apps/saas_metrics.yaml

app_id: "saas_metrics"
interval_seconds: 120

source:
  type: "http"
  url: "https://api.example.com/v1/admin/metrics"
  headers:
    X-API-Secret: "${SAAS_METRICS_API_SECRET}"

sub_apps:
  - name: "app_users"
    icon: "2058"
    text:
      - { text: "{{data.users_total}}", color: "FFFFFF" }
      - { text: " (+{{data.new_users_last_week}})", color: "00FF00" }

  - name: "app_premium"
    icon: "5336"
    text:
      - { text: "{{data.users_premium}}", color: "FFFFFF" }
      - { text: " (+{{data.new_users_premium_last_week}})", color: "FFD700" }

  - name: "app_orders"
    icon: "21072"
    text:
      - { text: "{{data.orders_total}}", color: "FFFFFF" }
      - { text: " (+{{data.new_orders_last_week}})", color: "00FF00" }

  - name: "app_support"
    icon: "10558"
    show_if: "data.tickets_open > 0"
    text:
      - { text: "{{data.tickets_open}}", color: "FF0000" }

5. Быстрый старт и установка

Предварительные требования

• Python 3.10 или выше

• Ulanzi TC001 (или совместимое устройство) с прошивкой Awtrix Light Firmware, подключённое к вашей Wi-Fi сети.

Локальная настройка с uv / pip

# Clone the repository
git clone https://github.com/klodnickik/mcp-server-awtrix.git
cd mcp-server-awtrix

# Copy example environment configuration
cp .env.example .env

# Edit device address and API keys in .env
# AWTRIX_BASE_URL=http://awtrix3.local

Запустите MCP-сервер локально через stdio:

# Using uv (recommended)
uv run mcp-server-awtrix

# Or standard pip
pip install -e .
python -m awtrix_mcp

Настройка Docker и Docker Compose

Запуск с помощью Docker Compose:

# 1. Clone & prepare environment
git clone https://github.com/klodnickik/mcp-server-awtrix.git
cd mcp-server-awtrix
cp .env.example .env

# 2. Start the MCP Server (SSE on port 8000) and Metric Daemon
docker compose up -d

# Or start only the metric poller daemon:
docker compose up -d metric-daemon

# View live logs:
docker compose logs -f

Конфигурация MCP-клиента

1. Google Antigravity

Добавьте в ваш mcp_servers.json:

{
  "mcpServers": {
    "awtrix": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-server-awtrix", "run", "mcp-server-awtrix"],
      "env": {
        "AWTRIX_BASE_URL": "http://awtrix3.local"
      }
    }
  }
}

2. Claude Desktop

Добавьте в claude_desktop_config.json:

{
  "mcpServers": {
    "awtrix": {
      "command": "python",
      "args": ["-m", "awtrix_mcp"],
      "env": {
        "AWTRIX_BASE_URL": "http://awtrix3.local"
      }
    }
  }
}

3. Cursor

В настройках Cursor $\rightarrow$ Features $\rightarrow$ MCP Servers $\rightarrow$ Add Server:

• Имя: awtrix

• Тип: command

• Команда: uv --directory /path/to/mcp-server-awtrix run mcp-server-awtrix

6. Дорожная карта и вклад

• Спецификация и дизайн основных MCP-инструментов

• Декларативная схема оркестрации YAML

• Реализация FastMCP с асинхронным HTTP-клиентом

• Живой визуальный веб-предпросмотр для пиксель-арта матрицы

• Поддержка транспортного уровня MQTT (альтернатива REST)

• Экспорт обнаружения сервисов Home Assistant

Вклад приветствуется! Пожалуйста, отправьте PR или откройте issue для обсуждения функций.

7. Лицензия

Распространяется под лицензией MIT. См. LICENSE для получения дополнительной информации.