Yeelight Metadata MCP Server

Yeelight メタデータ MCP サーバー

简体中文

公式リポジトリとミラー

GitHub は、課題、コントリビューション、CI、リリースの正規の情報源です。GitHub に安定してアクセスできないユーザー向けに、読み取り専用のミラーを Gitee と GitCode で利用できます。また、追加のグローバルな代替先として GitLab.com も利用できます。アクセス可能なソースからクローンできますが、課題の報告や変更のコントリビューションは GitHub で行ってください。

このリポジトリには、Yeelight MCP 内のホーム理解・管理サービスが含まれています。一般ユーザーは Yeelight MCP スイート全体に一度接続するだけで、このサーバーを個別に選択したりインストールしたりする必要はありません。制御されたタスクインターフェースは、ホーム、部屋、デバイス、グループ、パネル、シーン、オートメーション、お気に入り、メンテナンス、アカウント操作をカバーします。

ヒント

Yeelight MCP を初めてお使いですか？公式の英語版 Yeelight MCP チュートリアルに沿って Yeelight Home を準備し、Metadata と IoT の全機能スイートに接続して、最初の実際の応答を確認してください。簡体字中国語版チュートリアルも利用できます。

Yeelight Cloud MCP スイート

Yeelight Metadata MCP と Yeelight IoT MCP は、公式の Yeelight MCP クラウドスイートを構成します。これらは独立してデプロイされるサービスで、一般ユーザー向けのセットアップで一緒に設定されます。

サーバー	スイート内の役割	主な機能
Metadata MCP	ホームの理解と制御された管理。	ホーム、部屋、デバイス、グループ、パネル、シーン、オートメーション、お気に入り、メンテナンス、アカウント、複数リージョンの認証、リクエスト単位のホーム選択に関する幅広い検出と制御されたワークフロー。
IoT MCP	ライブ状態の取得と対象を絞った制御。	トポロジーとライブ状態への直接アクセス、control_node によるデバイス制御、execute_scene によるシーン実行。

推奨する構成： Yeelight MCP のセットアップを 1 つ実行してください。同じ AI クライアント内で両方のサービスが設定されるため、2 回目のインストールやスキャンを行わなくても、モデルはホームの理解、管理、ライブ状態、制御を利用できます。

Yeelight AI における位置づけ

yeelight-home は、推奨されるインストール、QR サインイン、クライアント設定のフローを提供します。一般ユーザーには、完全版の yeelight-smart-home Skill を推奨します。クライアントに Skill をインストールできない場合は、1 回のクラウドセットアップで Yeelight MCP スイート全体に接続できます。その後、クラウドサービスはローカル Runtime とは独立して実行されます。

簡単に言えば、このサーバーは MCP のみを利用する AI に、ホームの構造化された情報と、制御された管理方法を提供します。これは別の CLI ではなく、yeelight-home や Smart Home Skill に必須でもありません。

こちらを選ぶ状況	別のものを選ぶ状況
AI クライアントが MCP に対応しているものの、Agent Skills をインストールできない場合。	クライアントに Skill をインストールできる場合：完全なガイド付きエクスペリエンスを利用するには、yeelight-smart-home を使ってください。
AI に部屋、デバイス、グループ、シーン、オートメーション、パネル、またはホーム管理が必要な場合。	ターミナルでスクリプトを作成したり、トラブルシューティングを行ったりする場合：yeelight-home を直接使ってください。
Yeelight MCP 内のホーム理解サービスを開発またはトラブルシューティングする必要がある場合。	既存の専用 control_node または execute_scene インテグレーションだけが必要な場合：IoT サービスのドキュメントを使ってください。

主な特長

• 低レベルの HTTP 操作を多数用意する代わりに、名前空間付きツールを 6 つ提供します。
• 7 つのタスクグループ、23 のタスク、実行時アクションカタログを提供します。
• デフォルトで安全に実行できます。dryRun のデフォルト値は true です。
• S2／S3 の副作用を伴う操作には明示的な確認が必要です。
• 候補アクションは、デフォルトで本番環境での実行がブロックされます。
• タスクの探索や変更計画に使用できる MCP リソースとプロンプトを提供します。
• METADATA_MCP_* と従来の APP_MCP_* 環境変数に対応しています。

ホスト型サービス

公式の Streamable HTTP エンドポイントは次のとおりです。

https://api.yeelight.com/apis/metadata_mcp_server/v1/mcp

必須のリクエストヘッダー：

• Authorization

推奨される任意のヘッダー：

• Yeelight-Region：cn、sg、us、または eu。デプロイ先の Region がデフォルトです（デフォルトは cn）。
• House-Id

必須のユーザー認証情報は Authorization のみです。Yeelight-Region が指定されていない場合、サーバーは JWT の Region クレームを使用して公式エンドポイントを選択し、そのエンドポイントでトークン全体を検証します。Yeelight サービスは、検証済みの認証コンテキストからクライアントの識別情報を取得するため、ユーザーが Client ID を入力することはありません。ホームを必要とするアクションでは、context.houseId -> House-Id -> 同じ Region 内にある最初の Pro ホームの順に優先されます。このフォールバックはリクエスト単位で適用され、グローバルな現在のホーム状態として保持されるものではありません。

MCP の機能

ツール：

• yeelight_metadata.list_groups
• yeelight_metadata.list_houses
• yeelight_metadata.list_tasks
• yeelight_metadata.list_actions
• yeelight_metadata.get_action_schema
• yeelight_metadata.execute_task

リソース：

• yeelight-metadata://tasks
• yeelight-metadata://actions
• yeelight-metadata://schema/{task}/{action}

プロンプト：

• yeelight_metadata.inspect_home_metadata
• yeelight_metadata.plan_metadata_change
• yeelight_metadata.troubleshoot_automation_metadata

ツールスキーマの正確な情報源として、実際の MCP tools/list レスポンスを使用してください。

クイックスタート

推奨：Yeelight Home でサインインと設定を完了する

npm install --global yeelight-home
yeelight-home setup --lang en-US --mode mcp --agent cursor --mcp-source cloud --yes

このコマンドを実行すると、QR コードが表示されます。Yeelight Pro アプリで、Home の右上にある + をタップし、MCP Authorization を選択して QR コードをスキャンしてください。Pro ホームが 1 つの場合は自動的に選択され、複数ある場合にのみ名前で選択する必要があります。cursor をお使いのクライアントに置き換えるか、検出機能を使用する場合は --agent auto を指定してください。生成されるクライアント設定では、ローカルの認証情報プロキシが起動し、Authorization の値は含まれません。トークンを手動で設定する方法も、高度な互換性向けの手段として引き続き利用できます。トークンを AI チャットに貼り付けないでください。

ホスト型サーバーに接続する

{
  "mcpServers": {
    "yeelight-metadata": {
      "url": "https://api.yeelight.com/apis/metadata_mcp_server/v1/mcp",
      "headers": {
        "Authorization": "<YOUR_AUTHORIZATION>",
        "Yeelight-Region": "cn",
        "House-Id": "<YOUR_HOUSE_ID>"
      }
    }
  }
}

どちらの任意ヘッダーも省略できます。JWT トークンには Region クレームが含まれます。オペークンにはデプロイ先のデフォルト値が使用されます。エンドポイントホストを明示的に選択する場合は、Region に対応するホスト（api.yeelight.com、api-sg.yeelight.com、api-us.yeelight.com、または api-de.yeelight.com）を指定してください。ホームを切り替えるには、yeelight_metadata.list_houses を呼び出し、その後の呼び出しで選択した ID を request.context.houseId として渡します。

Cursor、Claude Desktop、ローカルソース、IoT／Metadata の統合設定については、統合ガイドを参照してください。

ソースから実行する

要件：Python 3.10 以降。ローカル開発には Python 3.12 を推奨します。

uv venv .venv
source .venv/bin/activate
uv pip install -e '.[test]'

METADATA_MCP_RUNTIME_ENV=local ./service.sh start
./service.sh status

ローカルエンドポイントは http://127.0.0.1:9010/mcp です。Authorization ヘッダーを含まないリクエストは、仕様上 401 を返します。

直接起動する方法にも対応しています。

METADATA_MCP_RUNTIME_ENV=local \
METADATA_MCP_BIND_HOST=127.0.0.1 \
PYTHONPATH=src \
.venv/bin/uvicorn main:streamable_http_app --host 127.0.0.1 --port 9010

安全性モデル

各アクションには、実行モード、副作用のレベル、ステータス、パラメータスキーマが設定されています。

レベル	意味	例
S0	読み取り専用	list、get、search
S1	診断または外部への操作	diagnose、download、poll
S2	作成または更新	create、update、configure
S3	破壊的操作または ID に関わる操作	delete、unbind、transfer、login

execute_task は、デフォルトで計画のみを行うリクエストです。

{
  "request": {
    "task": "family_space.manage_room",
    "action": "create",
    "payload": {"name": "Sample Room"},
    "options": {"dryRun": true}
  }
}

S2／S3 の本番実行には confirmSideEffect=true が必要です。候補アクションには allowCandidate=true も必要で、実行時ポリシーによる制限が適用されます。まずドライランを実行して plan.httpRequest を確認し、テスト可能または復元可能なデータに対してのみ実行してください。

設定

変数	デフォルト	用途
METADATA_MCP_RUNTIME_ENV	prod	prod、dev、local、または test
METADATA_MCP_BIND_HOST	local/test: 127.0.0.1; prod/dev: 0.0.0.0	リッスンアドレス
METADATA_MCP_PORT	9010	リッスンポート
METADATA_MCP_PATH	/mcp	MCP ルート
METADATA_MCP_DEFAULT_REGION	cn	Yeelight-Region がない場合のデフォルトリージョン
METADATA_MCP_HOST_PREFIX	https://api.yeelight.com	Yeelight API ホスト
METADATA_MCP_API_BASE_URL	ホストプレフィックス	明示的な API ベース URL
METADATA_MCP_HTTP_TIMEOUT	15	上流へのタイムアウト（秒）
METADATA_MCP_RESOURCE_DIR	resources/catalog	実行時のカタログの上書き先
METADATA_MCP_NACOS_ENABLE	環境に依存	Nacos 登録の切り替え
METADATA_MCP_NACOS_SERVER	環境に依存	Nacos サーバー
METADATA_MCP_ALLOW_CANDIDATE_EXECUTION	false	候補実行のゲート

デプロイ時の互換性を維持するため、従来の APP_MCP_* 名も引き続きサポートされます。 標準の Yeelight クラウドオリジンでは、リクエストごとのリージョンルーティングがサポートされます。カスタム API ベースは METADATA_MCP_DEFAULT_REGION に固定されます。別のリージョンを指定するリクエストは、 誤ったルーティングが黙って行われるのではなく、拒否されます。

ドキュメント

• 連携ガイド
• 使用ガイド
• 中文接入指南
• 中文使用指南

開発

PYTHONPATH=src python -m pytest -q
python -m compileall -q main.py src tests scripts

このリポジトリには、scripts/ 以下にプロトコルおよび受け入れテスト用のユーティリティも含まれています。 ライブ受け入れテストのコマンドはクラウドデータを変更する可能性があります。明示的な認証情報、本番環境以外のホーム、および復元可能なフィクスチャを使用してください。

ライセンス

Apache License 2.0 のもとでライセンスされています。