Ableton Proj MCP

Ableton项目MCP服务器

  

解析Ableton Live.als XML文件，使项目元数据可通过自然语言查询。通过MCP完全在本地提取BPM、跟踪结构、插件清单、示例引用、设备链等。

与 文件系统MCP服务器 用于目录浏览。

用例

• 缺少样本：从项目XML中提取文件路径。返回用于批重链接的结构化JSON。
• 插件清单：列出具有实例计数的VST3/VST2/AU插件。对迁移很有用。
• 元数据查询：BPM、轨道计数、排列长度。JSON输出用于脚本编写。
• 重复检测：基于内容的哈希（轨道结构、设备链、MIDI模式）。
• 主链分析：比较不同项目的母版制作设置。

安装

需要Python 3.10+和 紫外线.

curl -LsSf https://astral.sh/uv/install.sh | sh

将服务器添加到MCP客户端的配置文件中（例如。， claude_desktop_config.json、光标设置或自定义客户端）：

{
  "mcpServers": {
    "ableton-manager": {
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "/path/to/ableton-proj-mcp",
        "music-manager-mcp"
      ]
    }
  }
}

注意：更新配置后重新启动MCP客户端。

可用工具

核心工具

scan_projects

扫描目录中的.als文件并返回基本元数据。

输入：

• directory （string）：扫描路径

输出：

• 项目名称、文件夹、大小、修改日期
• 自动应用安全限制

安全限制：

• 最多100个文件（可通过配置 MAX_FILES_TO_SCAN)
• 跳过大于50MB的文件（可通过以下方式配置 MAX_FILE_SIZE_MB)
• 最大深度：3个子目录（可通过配置 SCAN_DEPTH)

analyze_projects

对项目文件进行深入分析。解析gzip压缩的XML以提取全面的元数据。

输入：

• project_paths （array）：绝对.als文件路径列表

输出：

{
  "basic_info": {
    "bpm": 140.0,
    "track_count": 15,
    "audio_tracks": 6,
    "midi_tracks": 9,
    "frozen_tracks": 2
  },
  "structure": {
    "arrangement_length_bars": 128,
    "scene_count": 8,
    "markers": ["INTRO", "DROP", "OUTRO"],
    "automation_lanes": 24,
    "total_clips": 45
  },
  "devices": {
    "stock_ableton": ["Eq8", "Compressor2", "Reverb"],
    "third_party_vsts": ["Serum 2", "OTT", "ShaperBox 3"],
    "heavy_cpu_count": 3
  },
  "master_chain": ["Eq8", "GlueCompressor", "Limiter"],
  "completion": {
    "likely_finished": true,
    "has_arrangement": true,
    "has_master_chain": true
  }
}

支持的设备：

• 库存：所有Ableton Live乐器、效果和实用设备
• VST3:从插件元数据中提取全名
• VST2：支持传统插件格式
• AU：音频单元（macOS）

find_recent

查找最近修改的项目，按修改时间排序。

输入：

• directory （string）：扫描路径
• limit （整数，可选）：结果数量（默认值：10）

输出： 包含元数据的最新项目列表

增强的分析工具

find_duplicates

使用结构哈希进行基于内容的重复检测。

相似性因素：

• 轨道结构哈希：40%
• 曲目计数匹配：15%
• BPM匹配：10%
• 主链匹配：20%
• MIDI模式哈希：15%

输入：

• directory （string）：扫描路径
• threshold （数字，可选）：相似性百分比（默认值：80）

find_missing_plugins

枚举跨项目使用的所有第三方插件。

输出：

• 找到的唯一插件列表
• 使用每个插件的项目
• 注意：不验证系统安装

find_missing_samples

扫描项目以查找损坏的音频文件引用。

输入：

• directory （string）：扫描路径

输出：

{
  "projects_with_issues": [
    {
      "name": "project.als",
      "missing_count": 5,
      "total_samples": 20,
      "missing_samples": ["/path/to/missing.wav"]
    }
  ],
  "total_missing_samples": 142
}

analyze_master_chains

提取并比较不同项目的母带设备链。

输入：

• project_paths （数组）：.als文件路径列表

输出： 按独特的主链配置对项目进行分组

find_finished_projects

使用启发式方法将项目分类为已完成或草图。

完成指标（“完成”需要3+）：

• 具有3+个排列标记
• 主轨道上有2+台设备
• 布置长度>64巴
• 有5+个会话视图场景

技术细节

文件格式

als文件是gzip压缩的XML文档。服务器：

1. 使用gzip解压缩文件
2. 使用ElementTree解析XML
3. 从LiveSet结构中提取数据
4. 返回结构化JSON

设备检测

库存设备由XML标签名称标识。第三方插件解析自 PluginDevice 元素：

• VST3： Vst3PluginInfo/Name
• VST2： VstPluginInfo/PlugName
• AU： AuPluginInfo/Name

演出

• 扫描：每个项目约100ms（仅元数据）
• 深度分析：每个项目约200-500ms（全XML解析）
• 批处理操作使用安全限制来防止超时

配置

在中编辑常量 src/music_manager_mcp/__main__.py:

MAX_FILES_TO_SCAN = 100  # Maximum files per scan
MAX_FILE_SIZE_MB = 50    # Skip files larger than this
SCAN_DEPTH = 3           # Maximum subdirectory depth

支持的数据

摘录：

• BPM，曲目计数（音频/MID/冻结）
• 布置长度、场景、标记
• 所有设备（库存和第三方）
• 主链装置订单
• 自动化车道计数
• 剪辑数
• 示例文件引用
• 用于重复检测的内容哈希

目前未提取：

• MIDI音符数据
• 音频剪辑波形
• 插件参数值
• 路由/发送配置
• 夹信封

故障排除

未找到项目： 验证目录路径和.als文件是否存在

分析超时： 减少批量或增加 MAX_FILES_TO_SCAN

缺少插件名称： 确保项目来自Ableton Live 11+

跳过的大文件： 增加 MAX_FILE_SIZE_MB 或单独分析

贡献

欢迎拉取请求。请确保：

• 代码遵循现有样式
• 新功能包括测试
• 文档已更新

许可证

MIT许可证-有关详细信息，请参阅许可证文件