CheerLights MCP Server

CheerLights MCP 服务

一个现代化的模型上下文协议（MCP）服务，可全面访问 CheerLights API。CheerLights 是一个全球物联网项目，可在全球数千盏互联灯光之间同步颜色，打造实时共享体验。

🌈 功能

工具（操作）

• 当前颜色：获取全球网络中最新的 CheerLights 颜色
• 颜色历史记录：获取最近的颜色变化，可配置数量（1-100）
• 颜色统计：分析颜色使用模式及其随时间变化的受欢迎程度
• 颜色搜索：在历史数据中查找指定颜色
• 十六进制颜色代码：获取 CheerLights 颜色的十六进制代码和 RGB 值

资源（上下文）

• 当前颜色资源：以易读资源的形式提供实时当前颜色
• 历史记录资源：格式化的颜色历史记录，可用于注入上下文
• 支持的颜色：包含十六进制代码的有效 CheerLights 颜色完整列表

提示词（模板）

• 趋势分析：生成用于分析 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)

返回包含十六进制代码和 RGB 值的 HexColor。

资源

• cheerlights://current - 当前颜色状态
• cheerlights://history/{count} - 最近的颜色历史记录
• cheerlights://colors/supported - 所有受支持的颜色

Claude 查询示例

• “当前的 CheerLights 颜色是什么？最近一次更改是什么时候？”
• “显示最近 20 次 CheerLights 颜色变化”
• “分析最近 100 次变化的颜色使用统计数据”
• “搜索最近所有颜色为 ‘blue’ 的记录”
• “CheerLights 的 ‘warmwhite’ 颜色对应的十六进制代码是什么？”
• “创建一份关于 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 Models：类型安全的数据验证与序列化
• 结构化输出：全面支持 MCP 结构化响应
• 完善的错误处理：优雅降级与日志记录
• 统计引擎：颜色使用分析与趋势计算

🎨 支持的颜色

CheerLights 支持以下标准颜色：

• 原色：red、green、blue
• 间色：cyan、magenta、yellow
• 扩展颜色：orange、pink、purple、white、warmwhite、oldlace
• 实用颜色：black

每种颜色都包含十六进制代码和 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 模型，确保类型安全
• 新增工具：统计、搜索、十六进制颜色代码
• 提供资源和提示词，实现更丰富的集成
• 使用 uv 和 pyproject.toml 实现现代化打包

版本 1.0.0

• 初始 FastMCP 实现
• 基础的当前颜色和历史记录工具
• 简单的 ThingSpeak 集成

📄 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

🔗 链接

• CheerLights 项目：cheerlights.com
• MCP 文档：modelcontextprotocol.io
• ThingSpeak API：thingspeak.com
• 原始教程：创建 MCP 服务

🎄 关于 CheerLights

CheerLights 是一个全球物联网项目，通过同步世界各地的彩灯，打造同步灯光秀。该项目由 Hans Scharler 创建，自 2011 年以来已连接全球数千盏彩灯。当有人在 CheerLights Discord Server 上更改颜色时，所有参与的彩灯都会近乎实时地切换到该颜色。

此 MCP 服务为 AI 助手提供对 CheerLights 数据的丰富访问能力，可分析这一独特物联网数据集中的全球灯光趋势、颜色流行度和时间模式。