Smart Appliance MCP

MCP-сервер, который позволяет любому MCP-совместимому LLM-клиенту обнаруживать умные приборы в локальной сети и управлять ими.

Ключевое проектное решение — маршрутизация на основе адаптеров:

1. discover_devices выполняет сканирование с помощью каждого зарегистрированного адаптера.

2. Каждое обнаруженное устройство сохраняет свой provider.

3. Последующие вызовы используют только deviceId; сервер находит устройство и направляет команду адаптеру, обнаруженному при сканировании.

Это упрощает запросы клиента. LLM-клиенту не нужно знать, является ли телевизор Roku, Home Assistant, Samsung, LG, Matter или чем-то ещё.

Инструменты

• discover_devices: находит приборы и запоминает их на время сессии сервера.

• diagnose_discovery: объясняет состояние обнаружения и вероятные сетевые блокировки, не требуя от пользователей правки технической конфигурации.

• list_known_devices: возвращает уже найденные устройства.

• get_device_controls: показывает доступные возможности для одного устройства.

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

• search_apps: ищет обнаруженные приложения по имени, идентификатору пакета, подсказкам категорий и возможности запуска.

• pair_device: запускает одноразовое пользовательское сопряжение, если провайдер этого требует.

• complete_pairing: завершает сопряжение с кодом, показанным на приборе.

• list_pairings: перечисляет локально сохранённые сопряжения.

• remove_pairing: удаляет локально сохранённое сопряжение.

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

• search_content: ищет в установленных приложениях или встроенных провайдерах контента, если это поддерживается.

• suggest_content: возвращает рекомендации к просмотру с учётом возможностей адаптера.

• record_watch_event: запоминает просмотренный, понравившийся, отклонённый или начатый контент.

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

• recommend_content: ранжирует, что посмотреть дальше, по категории, новизне, приложению, истории просмотров и возможности запуска приложения.

• get_device_state: возвращает состояние устройства, если адаптер это поддерживает.

Включённые адаптеры

• roku: обнаруживает телевизоры Roku и стриминговые устройства Roku через SSDP и управляет ими через Roku ECP.

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

• google_tv_remote: обнаруживает устройства Google TV / Android TV через сигналы Google Cast по mDNS и DIAL/SSDP, а затем моделирует обычный процесс сопряжения в стиле пульта.

• home_assistant: опциональный широкий мост для приборов: телевизоров, освещения, выключателей, термостатов и другого.

• google_tv: опциональный запасной вариант через ADB только для разработки/тестирования. Включается с помощью ENABLE_ADB_ADAPTER=true.

Быстрый старт

npm install
npm run build
npm start

Для локальной разработки:

npm run dev

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

Соберите проект, затем добавьте запись сервера в ваш MCP-клиент, например так:

{
  "mcpServers": {
    "smart-appliance": {
      "command": "node",
      "args": ["/absolute/path/to/smart-appliance-mcp/dist/index.js"]
    }
  }
}

Если вы используете Home Assistant, добавьте:

{
  "env": {
    "HOME_ASSISTANT_URL": "http://homeassistant.local:8123",
    "HOME_ASSISTANT_TOKEN": "your-long-lived-access-token"
  }
}

Для Google TV / Android TV используйте пользовательский процесс сопряжения. Сервер обнаруживает телевизор через сигналы локальной сети, такие как mDNS _googlecast._tcp.local и DIAL/SSDP, а затем внутренне сохраняет адрес в записи обнаруженного устройства.

Предусмотренный пользовательский сценарий:

Discover my smart appliances.
Pair my living room TV.
Complete pairing with code 123456.
Turn the TV volume up.

Обнаруженные устройства Google TV используют provider: "google_tv_remote". Состояние сопряжения хранится локально и маршрутизируется через тот же реестр адаптеров, что и любой другой провайдер.

Адаптер пульта Google TV включает локальное обнаружение, пользовательское сопряжение, live-управление с пульта, проверку запуска приложений и выполнение команд через маршрутизацию адаптеров. ADB-адаптер и переопределение GOOGLE_TV_REMOTE_DEVICES остаются доступны только как опциональные диагностические средства для разработки, а не для обычной настройки пользователем.

Обнаружение приложений также намеренно строится на адаптерах. На Google TV discover_apps проверяет локально доступные поверхности запуска, например конечные точки DIAL /apps/<name>. Если телевизор не предоставляет список установленных приложений через пользовательский пульт или интерфейсы DIAL, сервер чётко сообщает об этом, а не выдаёт угаданное имя пакета или URL браузера за обнаруженный путь запуска приложения.

Для наилучшего опыта с Google TV установите опциональное приложение-компаньон из companion/google-tv. Компаньон работает на телевизоре, публикует _smart-appliance._tcp.local, выводит список установленных приложений Leanback Launcher с помощью Android PackageManager и запускает приложения локально по имени пакета. Это обычный пользовательский путь для таких приложений, как Crunchyroll, которые не предоставляют конечных точек запуска DIAL.

Рекомендации

Слой рекомендаций работает по принципу «сначала локально» и учитывает адаптеры:

1. Сначала используется история просмотров адаптера, если обнаруженное устройство может её предоставить.

2. record_watch_event сохраняет лёгкую локальную запасную историю, включая приложение, название, категории, прогресс и статус.

3. recommend_content объединяет историю с телевизора, локальную запасную историю, предоставленный каталог контента и стартовые строки.

4. Результаты оцениваются по новизне, пересечению категорий с недавними просмотрами, доступности приложения, возможности запуска и статусу просмотрено/отклонено.

5. Ответ разделяет свежие recommendations и совпадения alreadyWatched и dismissed.

6. Каждая рекомендация включает userSummary/userReasons для понятных пользователю ответов, а также подробные поля для внутреннего планирования.

7. Рекомендации с действиями включают обложки и действия:

   • artwork.thumbnailUrl, posterUrl и backdropUrl для изображений.

   • actions.preview для трейлеров или превью-клипов, если каталог предоставляет previewUrl/trailerUrl.

   • actions.primary как действие просмотра в один клик, выраженное в виде полезной нагрузки вызова инструмента MCP.

8. chatCards и format_recommendation_cards отображают те же результаты для чат-клиентов:

   • Изображения включаются только тогда, когда каталог предоставляет обложки, специфичные для названия.

   • Ссылки на превью используют обычные веб-URL.

   • Ссылки просмотра/поиска используют URL mcp://action?..., которые описывают вызов инструмента MCP для подтверждения и выполнения хост-клиентом.

Если текущий адаптер не может предоставить историю просмотров телевизора, list_watch_history, recommend_content и format_recommendation_cards возвращают опциональный companionPrompt. Пользовательский протокол пульта Google TV не раскрывает приватную историю потокового просмотра по приложениям, поэтому точная история контента требует интеграции с провайдером или опционального источника-компаньона на стороне телевизора.

Каталоги провайдеров постоянно меняются, поэтому production-клиенты должны передавать свежие строки каталога в recommend_content из интеграции с провайдером, поискового коннектора или пользовательского медиаисточника. MCP не заявляет о наличии живых каталогов Netflix/Crunchyroll, если только их не предоставляет адаптер или коннектор.

Очередь просмотра во фронтенде

Запустите локальный интерфейс для рекомендаций с действиями:

npm run ui

Откройте http://localhost:5177. Интерфейс отображает выходные данные рекомендаций MCP в виде карточек с обложками, превью, действиями просмотра в один клик, фильтрацией, поиском и панелью уже просмотренного. Используйте кнопку {}, чтобы вставить ответ recommend_content из любого LLM-клиента.

Для чат-нативных карточек вызовите format_recommendation_cards с теми же входными данными, что и recommend_content. Он возвращает cards плюс Markdown, используя ссылки вместо кнопок. По умолчанию ссылки указывают на локальную конечную точку действий интерфейса, поэтому держите npm run ui запущенным:

[Watch on TV](http://127.0.0.1:5177/api/actions/run?payload=...)

Используйте linkMode: "mcp_scheme", если хост-клиент поддерживает ссылки mcp://action?... напрямую.

Пример потока работы с инструментами

Сначала попросите клиент:

Discover my smart appliances.

Затем:

Turn the living room TV volume up.

MCP-сервер обрабатывает маршрутизацию внутренне:

const device = registry.getDevice(deviceId);
const adapter = registry.adapterFor(device);
await adapter.control(device, request);

Добавление нового адаптера

Создайте класс, реализующий SmartApplianceAdapter:

export class SamsungTizenAdapter implements SmartApplianceAdapter {
  readonly id = "samsung_tizen";
  readonly label = "Samsung Tizen TV";

  async discover(options: DiscoveryOptions): Promise<SmartDevice[]> {
    return [];
  }

  async control(device: SmartDevice, request: ControlRequest) {
    return { ok: true };
  }
}

Затем зарегистрируйте его в src/index.ts:

registry.register(new SamsungTizenAdapter());

Обнаружение остаётся источником истины. Как только телевизор Samsung обнаружен с provider: "samsung_tizen", все последующие команды для этого deviceId автоматически направляются адаптеру Samsung.

Примечания

• Обнаружение в локальной сети зависит от того, разрешает ли ваша сеть многоадресную рассылку/SSDP.

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

• Рекомендации контента учитывают адаптеры, но их можно усилить, объединив возможности устройства с контекстом вкусов/профиля хост-LLM-клиента.