Xlights MCP Server

⚠️ 贝塔： 该项目目前处于测试阶段。功能可能会发生变化，您可能会遇到错误。欢迎反馈和贡献！

xLights MCP服务器

给它一个 .mp3，它将分析节拍、歌曲结构和能量，然后生成一个有效的 .xsq 序列文件，其中包含放置在所有灯光模型上的效果，并与音乐同步。

______________________________________________________________________

它的作用

🎵 音频分析

• 节拍和节奏检测 --识别每个节拍、下节拍和条形边界
• 歌曲结构 --检测前奏、韵文、合唱、桥牌和外音部分
• 频谱 --随时间变化的低音、中音和高音能量曲线
• 能源分析 --响度动态、峰值检测、动态范围
• 源分离 --通过以下方式隔离人声、鼓声、低音和其他声部 德马克斯 （可选）

💡 序列生成

• 生成有效 .xsq 文件 直接在xLights中打开——生成过程中不需要xLights GUI
• 读取您的实际节目配置 --了解您的模型、控制器、通道计数和模型类型
• 智能效果选择 --根据模型类型（拱门得到追逐，树木得到螺旋等）和音乐特征（节拍）选择效果→ 冲击波、合唱→ 高能量，诗句→ 温和）
• 主题感知调色板 --圣诞节（红色/绿色/金色）和万圣节（橙色/紫色）配色方案
• 三种发电模式：

- 自动 --AI选择一切，你在xLights中查看 - 引导 --AI显示歌曲结构，您可以选择每个部分的效果 - 模板 --定义可重复使用的效果食谱，人工智能将其置于节拍上

• 从不覆盖 --现有序列是安全的；生成的文件得到 (generated N) 后缀

📦 序列导入和重映射

• 导入社区序列 --采取任何 .xsq 或 .zip 从xLights社区打包并将其重新映射到您的节目布局
• 智能模型匹配 --按名称、类型和像素数自动将导入的模型映射到您的模型
• Zip包支持 --提取音频、视频、着色器和图像资源；重写硬编码的文件路径
• 歌唱模特意识 --歌唱面孔模特只能与其他歌唱模特相匹配
• 完整地图报告 --查看匹配的内容、匹配方式和跳过的内容
• 手动超控 --在生成重新映射的序列之前更正任何映射

📡 FPP集成

• 检查状态 你的猎鹰Pi玩家
• 上传序列 （.fseq+音频）转换为FPP
• 管理播放列表 --列表、开始、停止
• 与FPP的REST API配合使用

______________________________________________________________________

先决条件

• Python 3.11+
• 紫外线 （推荐）或pip
• FFmpeg --用于音频格式处理(brew install ffmpeg 在macOS上， apt install ffmpeg 在Linux上）
• xLights --安装时至少配置了一个显示文件夹

______________________________________________________________________

安装

步骤1：克隆存储库

git clone https://github.com/JohnBreault/xlights-mcp-server.git
cd xlights-mcp-server

步骤2：创建虚拟环境并安装

uv venv
uv pip install -e .

增强功能的可选附加功能：

# Stem separation — isolates vocals/drums/bass for smarter sequencing (~2GB model download)
uv pip install -e ".[separation]"

# Lyrics/singing faces — transcribes vocals for lip-sync animation
uv pip install -e ".[lyrics]"

# Better beat detection
uv pip install -e ".[beats]"

# Everything
uv pip install -e ".[all]"

步骤3：显示文件夹配置

首次运行时，服务器 自动检测 xLights通过扫描常见位置显示文件夹：

它查找包含以下内容的目录 xlights_rgbeffects.xml （文件xLights在每个显示文件夹中创建）。

如果自动检测未找到您的文件夹，创建或编辑 ~/.xlights-mcp/config.json:

{
  "show_folders": {
    "christmas": "/path/to/your/xLights/Christmas",
    "halloween": "/path/to/your/xLights/Halloween"
  },
  "active_show": "christmas",
  "fpp": {
    "host": "fpp.local",
    "port": 80
  }
}

步骤4：连接到您的AI工具

服务器使用 stdio传输 --您的AI工具将其作为子流程启动。

GitHub Copilot CLI

添加 ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "xlights": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/xlights-mcp-server", "xlights-mcp-server"]
    }
  }
}

保存后重新启动Copilot CLI。

Claude Desktop

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "xlights": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/xlights-mcp-server", "xlights-mcp-server"]
    }
  }
}

保存后重新启动Claude Desktop。

VS Code + Copilot Chat

添加到您的VS代码 settings.json:

{
  "mcp": {
    "servers": {
      "xlights": {
        "command": "uv",
        "args": ["run", "--directory", "/path/to/xlights-mcp-server", "xlights-mcp-server"]
      }
    }
  }
}

Cursor

添加到光标MCP设置（设置→ MCP服务器→ Add):

• 姓名： xlights
• 命令： uv
• Args： run --directory /path/to/xlights-mcp-server xlights-mcp-server

Other MCP clients

任何支持 模型上下文协议 可以使用此服务器。指向：

command: uv
args: run --directory /path/to/xlights-mcp-server xlights-mcp-server
transport: stdio

替换 /path/to/xlights-mcp-server 使用克隆仓库的实际路径。

______________________________________________________________________

用法

连接后，通过人工智能工具中的自然语言与服务器进行交互。以下是一些示例工作流：

探索您的节目

> List my xLights shows
> Switch to the Halloween show
> List all my light models
> Show me the controllers
> What sequences do I have?
> Inspect the "Deck The Halls" sequence

分析一首歌

> Analyze the song ~/Music/Jingle Bell Rock.mp3
> Show me the song structure for ~/Music/Monster Mash.mp3
> Get the beat map for this song
> What's the energy profile look like?

生成序列

> Create a sequence for ~/Music/Jingle Bell Rock.mp3
> Create a sequence for ~/Music/Jingle Bell Rock.mp3 using red and green colors
> Preview what a sequence would look like for this song before creating it

生成时，系统会要求您选择一种模式：

• 自动 --全自动，AI选择效果和颜色
• 引导的 --先看歌曲结构，然后选择每个部分的效果
• 模板 --将保存的效果配方应用于检测到的部分

导入社区序列

> Import the sequence ~/Downloads/Holly Jolly Christmas SD.zip to my show
> Import ~/Downloads/Christmas Time.xsq and show me the model mapping
> Import this sequence but map "Arch Left" to my "Arches-1" model

导入程序支持两种独立模式 .xsq 文件和 .zip 软件包（包括音频、视频资源和源节目的模型数据）。它使用以下命令自动将导入序列中的模型与布局进行匹配：

1. 名称完全匹配 → 相同的型号名称
2. 相似词 → 共享单词，如“雪花”、“拱门”、“树”
3. 型号 → same display_as 类型（例如，两个拱门）
4. 像素数 → 彼此相距70%以内
5. 手动超控 → 您可以选择特定的映射

管理FPP（控制器在线时）

> Check the FPP status
> List playlists on FPP
> Start the Christmas playlist
> Stop playback

______________________________________________________________________

可用工具

展会管理

音频分析

序列生成

序列导入和重映射

FPP集成

______________________________________________________________________

运作原理

效果选择逻辑

服务器映射 模型类型 达到适当效果：

还有地图 音乐特征 实现选择：

文件格式

生成 .xsq 文件是标准的xLights XML，包含：

• `` --歌曲元数据、媒体文件路径、持续时间、定时（25ms帧）
• `` --用于效果的主题调色板
• `` --重复数据消除效果参数定义
• `` --序列中包含的所有模型
• `` --每个模型、每层和时间的效果放置

______________________________________________________________________

项目结构

xlights-mcp-server/
├── pyproject.toml
├── README.md
├── src/xlights_mcp/
│   ├── server.py              # MCP server entry point & tool definitions
│   ├── config.py              # Configuration management
│   ├── audio/
│   │   ├── analyzer.py        # Full analysis pipeline orchestrator
│   │   ├── beats.py           # Beat/tempo/onset detection (librosa + madmom)
│   │   ├── structure.py       # Song section detection (verse/chorus/bridge)
│   │   ├── spectrum.py        # Frequency band & energy analysis
│   │   └── separator.py       # Demucs stem separation (optional)
│   ├── xlights/
│   │   ├── show.py            # Show folder parser (networks + models XML)
│   │   ├── xsq_reader.py     # Parse existing .xsq sequences
│   │   ├── xsq_writer.py     # Generate .xsq XML files
│   │   ├── effects.py         # Effect library & model/music mappings
│   │   ├── palettes.py        # Color palette definitions & themes
│   │   └── models.py          # Data models (Controller, LightModel, etc.)
│   ├── sequencer/
│   │   └── engine.py          # Sequence generation engine (auto/guided/template)
│   └── fpp/
│       ├── client.py          # FPP REST API client
│       ├── upload.py          # Sequence upload to FPP
│       └── schedule.py        # Schedule management
└── tests/

______________________________________________________________________

故障排除

MCP服务器未加载

• 验证您的MCP配置文件是有效的JSON（无注释，无尾随逗号）
• 检查 --directory 路径指向repo根（其中 pyproject.toml 是）
• 配置更改后重新启动AI工具
• 手动测试： cd /path/to/xlights-mcp-server && uv run xlights-mcp-server --应该没有错误地启动

“未找到xLights显示文件夹”

• 确保xLights已安装，并且您至少打开过一次（它会创建 xlights_rgbeffects.xml 在每个显示文件夹中）
• 如果您的节目文件夹位于非标准位置，请将其添加到 ~/.xlights-mcp/config.json

“未找到模型”错误

• 验证显示文件夹是否包含 xlights_networks.xml 和 xlights_rgbeffects.xml
• 使用 list_shows 检查哪个节目处于活动状态以及路径是否存在

音频分析速度慢

• 第一次运行下载librosa数据（~10MB）；后续运行速度更快
• Demucs词干分离在CPU上每首歌需要30-60s；结果已缓存
• 如果没有可选的deps，分析每首歌大约需要5秒

xLights中生成的序列看起来不正确

• 这 .xsq 是一个起点--调整xLights中的效果、时间和调色板
• 使用 inspect_sequence 查看打开前生成的内容

FPP连接失败

• 验证FPP是否已通电且位于同一网络上
• 检查中的主机名/IP ~/.xlights-mcp/config.json
• FPP工具优雅地报告连接错误；核心生成完全离线工作

______________________________________________________________________

许可证

麻省理工学院