CheerLights MCP Server

CheerLights MCP Server

CheerLights API に包括的にアクセスできる、最新の Model Context Protocol（MCP）サーバーです。CheerLights は、世界中の何千もの接続されたライトの色を同期し、リアルタイムで共有される体験を生み出すグローバルな IoT プロジェクトです。

🌈 特長

ツール（アクション）

• 現在の色：グローバルネットワークで最新の CheerLights の色を取得します
• 色の履歴：件数（1～100）を指定して、直近の色の変更を取得します
• 色の統計情報：色の使用パターンと経時的な人気度を分析します
• 色の検索：履歴データから特定の色を検索します
• 16 進カラーコード：CheerLights の色の 16 進コードと RGB 値を取得します

リソース（コンテキスト）

• 現在の色のリソース：リアルタイムの現在の色を、読み取り可能なリソースとして提供します
• 履歴リソース：コンテキストに挿入する、書式設定済みの色の履歴です
• 対応色：有効な CheerLights の色と 16 進コードの完全な一覧です

プロンプト（テンプレート）

• トレンド分析：CheerLights の色のトレンドを分析するプロンプトを生成します
• 色のレポート：特定の色に関する詳細なレポートを作成します

🚀 クイックスタート

uv を使う（推奨）

# Clone the repository
git clone https://github.com/cheerlights/cheerlights-mcp.git
cd cheerlights-mcp

# Install with uv
uv sync

# Run the server
uv run cheerlights-mcp

pip を使う

# Clone and install
git clone https://github.com/cheerlights/cheerlights-mcp.git
cd cheerlights-mcp
pip install -e .

# Run the server
python -m cheerlights_mcp.server

📦 インストール

開発環境向け

# Install with development dependencies
uv sync --dev

# Install pre-commit hooks
uv run pre-commit install

PyPI から（公開後）

pip install cheerlights-mcp

🔧 使い方

Claude Desktop で使う

Claude Desktop の設定に追加します：

Windows：%APPDATA%\Claude\claude_desktop_config.json
macOS：~/Library/Application Support/Claude/claude_desktop_config.json

{
    "mcpServers": {
        "cheerlights": {
            "command": "uv",
            "args": ["run", "cheerlights-mcp"],
            "cwd": "/path/to/cheerlights-mcp"
        }
    }
}

直接実行

# Standard I/O (default)
python -m cheerlights_mcp.server

# With specific transport
python -m cheerlights_mcp.server stdio
python -m cheerlights_mcp.server sse
python -m cheerlights_mcp.server streamable-http

プログラムからの使用

from cheerlights_mcp import create_server

# Create and run server
server = create_server("My CheerLights Server")
server.run()

🛠️ API リファレンス

ツール

get_current_cheerlights_color()

構造化された ColorData を返します。内容は以下のとおりです：

• color：現在の色の名前
• timestamp：色が設定された日時
• entry_id：一意の識別子
• created_at：解析済みの日時（任意）

get_cheerlights_history(count: int = 5)

直近の変更を含む ColorHistory を返します（1～100 件）。

analyze_color_statistics(sample_size: int = 50)

以下の情報を含む ColorStatistics を返します：

• 色の出現頻度
• 最も人気のある色／最も人気のない色
• 分析期間に関する情報
• 色の種類数

search_colors(color: str, limit: int = 20)

一致するエントリーを含む ColorSearchResult を返します。

get_hex_color_code(color_name: str)

16 進コードと RGB 値を含む HexColor を返します。

リソース

• cheerlights://current - 現在の色の状態
• cheerlights://history/{count} - 直近の色の履歴
• cheerlights://colors/supported - 対応しているすべての色

Claude へのクエリ例

• 「現在の CheerLights の色は何ですか？最後に変更されたのはいつですか？」
• 「直近 20 回の CheerLights の色の変更を表示してください」
• 「直近 100 回の変更について、色の使用状況を分析してください」
• 「最近、色が 'blue' だったすべての時点を検索してください」
• 「CheerLights の 'warmwhite' 色の 16 進コードは何ですか？」
• 「CheerLights の色のトレンドに関するレポートを作成してください」

🧪 テスト

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=cheerlights_mcp

# Run specific test files
uv run pytest tests/test_tools.py -v

🏗️ アーキテクチャ

cheerlights-mcp/
├── src/cheerlights_mcp/
│   ├── api/              # ThingSpeak API client
│   ├── models/           # Pydantic data models
│   ├── tools/            # MCP tool implementations
│   ├── utils/            # Utilities (color mapping, statistics)
│   └── server.py         # Main FastMCP server
├── tests/                # Comprehensive test suite
└── examples/             # Usage examples

主なコンポーネント

• ThingSpeakClient：CheerLights API 用の非同期 HTTP クライアント
• Pydantic モデル：型安全なデータ検証とシリアル化
• 構造化出力：MCP の構造化レスポンスを完全にサポート
• 包括的なエラー処理：適切なログ記録と、エラー発生時の機能低下
• 統計エンジン：色の使用状況分析とトレンドの算出

🎨 対応色

CheerLights は、以下の標準色に対応しています：

• 基本色：red、green、blue
• 二次色：cyan、magenta、yellow
• 拡張色：orange、pink、purple、white、warmwhite、oldlace
• ユーティリティ色：black

各色には、正確な表現のための 16 進コードと RGB 値が含まれています。

📊 データ例

現在の色のレスポンス

{
  "color": "red",
  "timestamp": "2024-01-15 14:30:22 UTC",
  "entry_id": "12345",
  "created_at": "2024-01-15T14:30:22Z"
}

統計レスポンス

{
  "color_counts": {"red": 15, "blue": 12, "green": 8},
  "most_popular": "red",
  "least_popular": "green", 
  "total_changes": 35,
  "unique_colors": 3,
  "analysis_period": "2 hours"
}

開発環境のセットアップ

# Clone and setup
git clone https://github.com/cheerlights/cheerlights-mcp.git
cd cheerlights-mcp
uv sync --dev

# Install pre-commit hooks
uv run pre-commit install

# Run tests
uv run pytest -v

📝 変更履歴

バージョン 2.0.0

• 全面的な書き換え：最新の MCP Python SDK を使用
• 構造化出力：すべてのツールでサポート
• 強化された API クライアント：適切なエラー処理を実装
• 包括的なテストスイート：カバレッジ 90% 超
• 型安全性：全体を通じて Pydantic モデルを使用
• 新しいツール：統計、検索、16 進数カラーコード
• リソースとプロンプト：より豊かな統合を実現
• 最新のパッケージ管理：uv と pyproject.toml を使用

バージョン 1.0.0

• 初期の FastMCP 実装
• 基本的な現在のカラーと履歴のツール
• シンプルな ThingSpeak 統合

📄 ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細については、LICENSE ファイルをご覧ください。

🔗 リンク

• CheerLights プロジェクト：cheerlights.com
• MCP ドキュメント：modelcontextprotocol.io
• ThingSpeak API：thingspeak.com
• 元のチュートリアル：MCP サーバーの作成

🎄 CheerLights について

CheerLights は、世界中の色付きライトを同期させ、一体となった光の演出を作り出す、グローバルなモノのインターネットプロジェクトです。このプロジェクトは Hans Scharler によって作成され、2011 年以来、世界中の数千ものライトをつないできました。CheerLights Discord Server で誰かが色を変更すると、参加しているすべてのライトがほぼリアルタイムでその色に変わります。

この MCP サーバーは、AI アシスタントに CheerLights のデータへの豊富なアクセスを提供し、この独自の IoT データセットにおける世界的な照明の傾向、色の人気度、時間的なパターンの分析を可能にします。