内容
# 血清-MCP
[](LICENSE)
[](https://www.python.org/downloads/)
[](.github/workflows/ci.yml)
**从纯英文描述中生成、编辑和保存Xfer Serum 2预设——作为一个MCP服务器，因此任何MCP客户端（Claude Code、Claude Desktop等）可以直接驱动它。**
```
你： 生成一个黑暗、演变的垫子，带有缓慢的合唱效果
克劳德： [根据你的描述构建一个PresetSpec，调用
generate_preset(spec)]
编写 ~/Documents/Xfer/Serum 2 预设/预设/用户/PD - 黑暗演变合唱.SerumPreset
振荡器A：开启 八度=-1 音量=0.75 表位置=42.0
过滤器1：开启 类型=低通滤波器_24 截止频率=0.32 共振=18%
环境1：攻击=0.8s 衰减=2.5s 持续=0.70 释放=3.0s
特效链：特效合唱（湿=45%）
```
在您使用的任意DAW（FL Studio、Ableton、Bitwig等）中打开Serum，加载预设即可完成。`serum-mcp`从不触及您的DAW，从不渲染音频，从不加载Serum插件本身——它直接读写`.SerumPreset`文件格式。
## 为什么
现有的“AI Serum预设”工具要么是闭源SaaS产品，要么是一次性配置到预设的生成器。`serum-mcp`是：
- **开源**，MIT许可。
- **原生于您的代理编码工作流** — 它是一个MCP服务器，而不是一个单独的Web应用程序。像询问代码更改一样询问声音。
- **对话式和迭代式** — `edit_preset`允许您细化现有的补丁（“使其更温暖”，“添加更多共振”），而不仅仅是从头开始生成。
- **对其自身的局限性保持透明** — 此工具了解的每个参数都记录了其验证的置信度（参见[`docs/PARAMETER_SCHEMA.md`](docs/PARAMETER_SCHEMA.md）），因为Xfer不发布此格式，我们也不假装相反。
参见[先前的工作](#先前的工作)，了解它与[Serum-Preset-Generator](https://github.com/Tdub206/Serum-Preset-Generator)、[SerumPresetGenerator](https://github.com/potatoTeto/SerumPresetGenerator)和[Pounding Systems' AI预设生成器](https://pounding.systems/products/ai-serum-preset-generator)的比较。
## 范围——这是什么 *不是*
根据设计，并且故意不计划在以后：
- 无MIDI生成或写入。
- 无实时DAW控制、自动化或插件脚本（无FL Studio MIDI脚本，无Ableton远程脚本，无ReaScript）。
- 无加载Serum插件本身——该工具不渲染或预览音频。输入是文本，输出是`.SerumPreset`文件。
- 在管道中没有任何DAW依赖。FL Studio只是作者随后打开Serum的地方；任何DAW都完全相同。
[V2方向](#路线图)—“从音频文件中重现声音”—在架构上有所考虑，但尚未开始。
## 安装
需要Python 3.11+和[uv](https://docs.astral.sh/uv/)。无需任何类型的API密钥——请参见[工作原理](#工作原理)以了解原因。
```bash
git clone https://github.com/Celian-mrc/serum-mcp
cd serum-mcp
uv sync
```
### 配置您的Serum预设文件夹
Serum的用户预设文件夹位置因安装而异—通过Serum的汉堡菜单找到您自己的位置→“显示Serum预设文件夹”→`预设/用户`子文件夹。然后设置：
```bash
export SERUM_PRESETS_PATH="/path/to/Serum 2 预设/预设/用户"
```
如果未设置，`serum-mcp`将退回到几个已知的默认安装位置（参见`src/serum_mcp/config.py`），然后在出现清晰的错误之前失败。
它从不沉默地猜测或硬编码路径。
如果您请求自定义合成的波表（`custom_harmonics`）或从您自己的音频文件切片的波表（`sample_source`，例如“将此鼓点转换为波表”—参见[工作原理](#工作原理)），`serum-mcp`还需要Serum的**Tables**文件夹（`预设/`的兄弟目录）来写入生成的`.wav`文件。它由`SERUM_PRESETS_PATH`自动派生；如果您的安装不遵循标准布局，请使用`SERUM_TABLES_PATH`覆盖。
如果您请求保持单次采样/样本可识别（`sample_playback_source`，例如“将此鼓击转换为预设”或“将此人声剪辑与合成垫层叠”—参见[工作原理](#工作原理)），`serum-mcp`使用Serum的实际样本播放引擎（`SampleOsc`）并将文件复制到Serum的**Samples**文件夹（也是`预设/`的兄弟目录，由`SERUM_SAMPLES_PATH`派生或覆盖）。仅支持`.wav`（确认工作正常，尽管每个工厂预设都引用`.flac`—参见`docs/PARAMETER_SCHEMA.md` §8）。样本以其原始录制的音高/速度播放，当**C5**被播放时—一个固定的参考音符，不可配置。如果源文件是立体声，其通道默认通过`sample_center_pan`平衡增益，以纠正原始录制中可能存在的左右水平偏差（常见—实际单次采样通常稍微偏离中心）而不改变任何通道的实际内容。
可选地，设置`SAMPLE_BANK_PATH`为您的自定义单次采样/鼓库的根目录（与Serum自己的文件夹无关—此路径可以指向任何地方）。设置后，`list_sample_files()`可以不带参数调用，默认为浏览该文件夹，这允许调用模型主动检查您是否有适合请求的合适单次采样，即使您没有明确提及您的样本库。默认情况下不设置，并且除非您配置此选项或模型指向目录，否则不会读取您的文件系统。
### 添加到Claude Code
```bash
claude mcp add serum-mcp -- uv --directory /path/to/serum-mcp run serum-mcp
```
或手动添加到`.claude/settings.json` / `~/.claude.json`：
```json
{
"mcpServers": {
"serum-mcp": {
"command": "uv",
"args": ["--directory", "/path/to/serum-mcp", "run", "serum-mcp"],
"env": {
"SERUM_PRESETS_PATH": "/path/to/Serum 2 预设/预设/用户"
}
}
}
}
```
### 添加到Claude Desktop
形状相同，在Claude Desktop的`claude_desktop_config.json`（设置→开发者→编辑配置）：
```json
{
"mcpServers": {
"serum-mcp": {
"command": "uv",
"args": ["--directory", "/path/to/serum-mcp", "run", "serum-mcp"],
"env": {
"SERUM_PRESETS_PATH": "/path/to/Serum 2 预设/预设/用户"
}
}
}
}
```
## 工具
| 工具 | 描述 |
|---|---|
| `generate_preset(spec, subfolder=None)` | 从`PresetSpec`构建一个新的预设并将其写入您的Serum预设文件夹。`subfolder`（例如`"RAGE Bank"`）将一组主题预设放在一起，而不是直接写入。 |
| `edit_preset(preset_path, spec)` | 将部分`PresetSpec`更新应用于现有预设。如果`spec.name`更改，则重命名文件（Serum的浏览器显示文件名，而不显示内部元数据）。 |
| `list_parameters()` | 完整的文档参数架构（名称、范围、单位、枚举值、置信度）为JSON。 |
| `describe_preset(preset_path)` | 预设当前声音整形参数的人类可读摘要。 |
| `list_sample_files(directory=None)` | 将文件夹下的音频文件以JSON列出—路径、名称、大小和持续时间/采样率/通道（仅限`.wav`），以便按名称/文件夹上下文选择特定文件。默认为`SAMPLE_BANK_PATH`（如果未设置`directory`）。 |
| `analyze_sample_file(path)` | 针对单个`.wav`单次采样的轻量级声学描述符为JSON—亮度、音调/噪声纹理、门控音高估计、攻击/持续形状—当文件名在样本库类别中不够描述时也会显示。还会显示`embedded_metadata`（根音符、样本准确循环点），如果样本包的创建者嵌入了RIFF `inst`/`smpl`标签—不通用，为空时不存在。 |
您不会手动编写`PresetSpec` JSON—调用模型（Claude Code、Claude Desktop等）使用工具描述和`list_parameters()`作为指南，从您的自然语言请求中构建它，就像为其他MCP工具构造参数一样。
## 工作原理
```
提示（自然语言）
│
▼
调用模型（Claude Code / Claude Desktop）将请求
转换为PresetSpec（generation/spec.py）本身—无需单独的LLM调用。
此服务器没有自己的模型来调用。
│
▼
generate_preset(spec) / edit_preset(path, spec) （MCP工具）
│
▼
preset/mapping.py ── 将验证的PresetSpec合并到基础预设
│ （fixtures/init_preset.SerumPreset用于生成，现有文件的自身状态用于编辑），
│ 在触及任何内容之前，将每个值与preset/schema.py的真实边界进行验证
▼
preset/packer.py ── 将结果编码回实际的Serum 2容器
│ 格式（XferJson头部+zstd压缩的CBOR）
▼
写入$SERUM_PRESETS_PATH为实际的.SerumPreset文件
```
故意 **在此服务器中不发生LLM调用**。早期设计曾有`generate_preset`调用Claude API内部以将纯文本转换为`PresetSpec`—但每个MCP工具调用都是由LLM驱动的客户端 **完成**的，因此第二次调用是纯粹的冗余：相对于您已经为Claude Code/Desktop支付的费用，多余的、单独计费的API请求只是您无需额外付费即可由调用模型自行完成的推理（从您的角度来看），因此不会损失任何正确性。现有的预设中未包含在此架构中的所有内容（琶音器、MIDI剪辑、GUI状态、未解析的调制矩阵源...）在编辑过程中完全不受影响。
完整的参数文档，包括每个边界的验证方式（或未验证）：[`docs/PARAMETER_SCHEMA.md`](docs/PARAMETER_SCHEMA.md)。
## 先前的工作
- [Serum-Preset-Generator](https://github.com/Tdub206/Serum-Preset-Generator) — Python API，从您手动编写的JSON配置中生成。
- [SerumPresetGenerator](https://github.com/potatoTeto/SerumPresetGenerator) — 清洁室C#库。
- [Pounding Systems' AI Serum预设生成器](https://pounding.systems/products/ai-serum-preset-generator) — 闭源，付费SaaS。
`serum-mcp`的不同之处不是更好的AI—它是分发（一个MCP工具，而不是一个单独的应用程序），可编辑性（迭代现有的补丁，而不仅仅是单次生成），以及对格式覆盖范围的诚实（参见[已知空白](docs/PARAMETER_SCHEMA.md#5-known-gaps-and-open-questions)）。
## 免责声明
- **与Xfer Records无关，不受Xfer Records支持或认可**。“Serum”是Xfer Records的商标；这是独立的、社区驱动的互操作性项目。
- `.SerumPreset`文件格式 **没有官方文档**。关于它的所有内容都来自社区反向工程和经验验证与实际的Serum 2安装（参见[`docs/PARAMETER_SCHEMA.md`](docs/PARAMETER_SCHEMA.md)，了解方法和参数置信度）。
- **这可能会因Serum更新而破坏**未来Serum更新可能会更改文件格式或参数集。如果它对您造成破坏，请打开一个问题—最好附上从新版本导出的预设。
- 生成的预设仅限于调用模型的音效设计判断和该项目的参数覆盖范围（当前：振荡器、滤波器、包络、宏、LFO/宏调制路由和16种特效类型中的9种—参见[已知空白](docs/PARAMETER_SCHEMA.md#5-known-gaps-and-open-questions))。
## 路线图
- **V1**（此仓库，当前）：从描述中生成，编辑现有预设，直接写入您的Serum预设文件夹，文档化和测试的参数架构。
- **V2**（未启动）：从音频文件中“重现声音”，通过音频渲染（例如[`spotify/pedalboard`](https://github.com/spotify/pedalboard））和光谱比较。目前的架构故意避免做出可能排除此功能的后续选择。
## 贡献
参见[`CONTRIBUTING.md`](CONTRIBUTING.md)—填充`docs/PARAMETER_SCHEMA.md`中记录的空白是您可以做的最有价值的事情之一，即使不编写代码。
## 许可证
[MIT](LICENSE)
