Smart Appliance MCP

MCP를 지원하는 모든 LLM 클라이언트가 로컬 네트워크에서 스마트 가전을 발견하고 제어할 수 있게 해주는 MCP 서버입니다.

핵심 설계 선택은 어댑터 중심 라우팅입니다.

1. discover_devices는 등록된 모든 어댑터로 스캔합니다.

2. 발견된 각 기기는 자신의 provider를 저장합니다.

3. 이후 호출은 deviceId만 사용하며, 서버는 기기를 찾아 발견 당시 확인된 어댑터로 명령을 라우팅합니다.

이 덕분에 클라이언트 프롬프트가 단순해집니다. LLM 클라이언트는 TV가 Roku, Home Assistant, Samsung, LG, Matter 또는 다른 어떤 것인지 알 필요가 없습니다.

도구

• discover_devices: 가전 기기를 찾아 이번 서버 선택세션 동안 기억합니다.

• diagnose_discovery: 사용자가 기술적인 설정을 직접 편집하지 않아도 디스커버리 상태와 유력한 네트워크 차단 원인을 설명합니다.

• list_known_devices: 이미 발견된 기기 목록을 반환합니다.

• get_device_controls: 한 기기에서 사용할 수 있는 기능을 보여줍니다.

• discover_apps: 발견된 미디어 기기가 노출하는 앱 실행 대상을 조사합니다.

• search_apps: 발견된 앱을 이름, 패키지 ID, 카테고리 힌트, 실행 가능성 기준으로 검색합니다.

• 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: SSDP 기반으로 Roku TV 및 Roku 스트리밍 기기를 발견하고, Roku ECP를 통해 제어합니다.

• smart_appliance_companion: mDNS로 선택형 TV 보조 앱을 발견하고, 설치된 앱 목록 제공 및 패키지 실행에 사용합니다.

• google_tv_remote: mDNS Google Cast 신호 및 DIAL/SSDP를 통해 Google TV / Android TV 기기를 발견한 후, 일반적인 리모컨 스타일 페어링 흐름을 제공합니다.

• home_assistant: TV, 조명, 스위치, 온도조절기 등을 위한 선택형 광범위 가전 브리지입니다.

• 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와 같은 로컬 네트워크 신호로 TV를 발견한 뒤, 발견된 기기 레코드에 주소를 내부적으로 저장합니다.

의도한 사용자 흐름은 다음과 같습니다:

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 remote 어댑터는 로컬 디스커버리, 소비자 페어링, 실시간 원격 제어, 앱 실행 조사, 어댑터 라우팅 명령 실행을 포함합니다. ADB 어댑터와 GOOGLE_TV_REMOTE_DEVICES 오버라이드는 일반 사용자 설정이 아닌, 선택적 개발 진단 용도로만 유지됩니다.

앱 디스커버리도 의도적으로 어댑터 기반입니다. Google TV에서 discover_app_s는 TV가 로컬로 노출하는 실행 진통점, 예를 들어 DIAL /apps/<name> 엔드포인트를 탐지합니다. TV가 리모컨이나 DIAL 인터페이스를 통해 설치된 앱 목록을 노출하지 않는 경우, 서버는 추측한 패키지나 브라우저 URL을 실제 디스커스된 것처럼 처리하지 않고, 그 한계를 명확히 보고합니다.

최상의 Google TV 환경을 원한다면 companion/google-tv에서 제공하는 옵션 보조 앱을 설치하세요. 이 보조 앱은 TV에서 실행되며 _smart-appliance._tcp.local을 광고하고, Android PackageManager로 설치된 Leanback 실행기 앱을 나열한 뒤, 패키지 이름으로 앱을 직접 실행합니다. 이 경로는 DIAL 시작 엔드포인트를 제공하지 않는 Crunchyroll 같은 앱을 위한 일반 사용자 경로입니다.

추천

추천 계층은 로컬 우선이며 어댑터를 인식합니다.

1. 어댑터의 시청 기록은 발견된 기기가 제공할 수 있을 때 우선 사용됩니다.

2. record_watch_event는 앱, 제목, 카테고리, 진행도, 상태를 포함하는 가벼운 로컬 대체 기록을 저장합니다.

3. recommend_content는 TV 기반 기록, 로컬 대체 기록, 제공된 콘텐츠 카탈로그, 초기 시드 행을 병합합니다.

4. 결과는 최신성, 최근 시청과 차지하는 카테고리 일치, 사용 가능한 앱, 실행 가능성, 시청/해제 상태를 기준으로 점수화됩니다.

5. 응답은 최신 recommendations와 alreadyWatched 및 dismissed 항목을 구분합니다.

6. 각 추천에는 표시용 요약인 userSummary/userReasons와, 내부(Inclusion) 상세 계획용 필드가 있습니다.

7. 바로 실행 가능한 추천 행에는 이미지와 작업이 포함됩니다:

   • artwork.thumbnailUrl, posterUrl, backdropUrl

   • actions.preview: 카탈로그가 previewUrl/trailerUrl을 제공할 때 위한 예고편/미리보기 클립

   • actions.primary: MCP 도구 호출 페이로드로 표현된 원클릭 시청 동작

8. chatCards와 format_recommendation_cards는 같은 결과를 채팅용 클라이언트 방식으로 렌더링합니다:

   • 이미지는 카탈로그가 제목별 고유 이미지를 제공할 때만 포함됩니다.

   • 미리보기 링크는 일반 웹 URL을 사용합니다.

   • 시청/검색 링크는 mcp://action?... URL을 사용하며, 이는 호스트 클라이언트가 사용확인 후 실행할 MCP 도구 호출을 나타냅니다.

현재 어댑터가 TV 시청 기록을 제공할 수 없으면 list_watch_history, recommend_content, format_recommendation_cards는 선택적으로 companionPrompt를 반환합니다. Google TV의 소비자 리모컨 프로토콜은 넷플릭스 스트리밍 기록을 비공개로 유지하므로, 정확한 콘텐츠 기록은 공급자 통합 또는 선택형 TV측 보조 앱이 필요합니다.

공급자 카탈로그는 계속 변하기 때문에 운영 환경 클라이언드는 항상 최신 카탈로그를 recommend_content에 직접 넘겨야 합니다. MCP는 어댑터나 커넥터가 제공하지 않는 한 Netflix/Crunchyroll 카탈로그를 제공한다고 주장하지 않습니다.

프런트엔드 시청 대기열

즉시 반응 가능한 추천을 위한 로컬 UI 실행:

npm run ui

http://localhost:5177을 여세요. UI는 MCP 추천 결과를 카드형태(이미지, 미리보기, 원클릭 시청, 필터, 검색, 이미 시청한 패널)로 표시합니다. {} 버튼을 누르면 어떤 LLM 클라이언트에서든 recommend_content 응답을 붙여넣기할 수 있습니다.

채팅용 카드가 필요하다면 recommend_content와 같은 입력으로 format_recommendation_cards를 호출하세요. 이 함수는 버튼 대신 링크로 연결된 cards와 마크다운을 반환합니다. 기본적으로 링크는 로컬 UI 작업 엔드포인트를 가리키므로 npm run ui를 유지하세요:

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

호스트 클라이언트가 mcp://action?... URL을 직접 지원한다면 linkMode: "mcp_scheme"을 사용할 수 있습니다.

도구 흐름 예시

먼저 클라이언트에 요청합니다:

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 TV가 provider: "samsung_tizen"으로 발견되면, 그 후 해당 deviceId의 모든 명령은 Samsung 어댑터로 자동 라우팅됩니다.

참고 사항

• 로컬 네트워크 디스커버리는 사용 네트워크가 멀티캐스트/SSDP를 허용해야 합니다.

• 일부 TV 생태계는 제어 전에 페어링을 요구합니다. 이러한 어댑터는 MCP 도구 또는 리소스로 페어링 흐름을 제공해야 합니다.

• 콘텐츠 추천은 어댑터를 인식하지만, 기기 기능과 호스트 LLM 클라이언트의 취향/프로파일 맥락을 결합하면 더 강력해질 수 있습니다.