Sonicake Pocket Master

pocket-master-mcp

一个 MCP 服务，可让 AI 助手（Claude Desktop 或任何其他 MCP 客户端）通过 USB MIDI 控制 Sonicake Pocket Master 吉他处理器。它还包含可离线将设备 UI 翻译成其他语言的工具，内置俄语支持。

用通俗语言描述你想要的音色（“紧实的现代金属节奏”“清音，带宽广的合唱效果，混响少一些”）。助手会选择模型、设置参数、重新排列效果链，并在设备上保存和命名预设。

非官方项目。 本项目与 Sonicake 无关，也未获其认可。所用协议基于 PocketEdit 的逆向工程成果。读取（当前预设、预设名称、完整编辑缓冲区）已在搭载 V1.3.3 固件的真实设备上验证。写入预设目前只经过少量硬件测试，因此请先运行 backup_presets。修改过的固件同样是非官方版本：使用风险由你自行承担。

功能

• 实时编辑： 在任意模块中选择模型（22 个放大器 + 5 种采样放大器配置、20 个箱体/IR、8 个过载效果、FX1/FX2 各有 15–17 种效果、9 种延迟、10 种混响、3 种 EQ、噪声门），开关模块，并按名称设置参数，同时进行范围检查（Gain、以 ms 为单位的 Time、以 Hz 为单位的 Rate、Mode = Bass、+3dB = on，……）。
• 信号链： 在固定的 DRV-AMP-IR-EQ 模块前后重新排列 NR / FX1 / FX2 / DLY / RVB。
• 读取状态： 解码编辑缓冲区（模型、开关状态、参数值、效果链、预设音量）并列出 100 个预设名称。
• 预设： 选择预设，将编辑缓冲区保存到带名称的用户插槽 P01–P50，重命名预设，以及备份和还原预设。
• 音色文件： 从 JSON 文件应用完整音色。示例见 examples/presets。
• 全局设置： 全局音量、输入 / FX rec / 监听 / BT rec 电平。
• UI 语言： 构建带翻译 UI 的固件文件（内置俄语，参见 UI 语言固件）。

要求

• 通过 USB 连接的 Sonicake Pocket Master。设备会显示为兼容类 MIDI 端口。
• Python 3.10+。
• MCP 客户端，例如 Claude Desktop。

由于需要直接访问 USB MIDI 端口，服务必须运行在连接了 Pocket Master 的电脑上。

安装

最简单的方式是使用 uv：uvx 会下载并运行该服务。

Claude Desktop

打开 Settings → Developer → Edit Config 并添加：

{
  "mcpServers": {
    "pocket-master": {
      "command": "uvx",
      "args": ["pocket-master-mcp"]
    }
  }
}

完全重启 Claude Desktop。如果 Claude 找不到 uvx，请使用其绝对路径（which uvx，通常是 ~/.local/bin/uvx）。如需固件预览（PNG），请使用 "args": ["--from", "pocket-master-mcp[preview]", "pocket-master-mcp"]。

或者，运行 pipx install pocket-master-mcp 或 pip install "pocket-master-mcp[preview]"，并使用 "command": "pocket-master-mcp"。

从源代码安装

git clone https://github.com/voronkovd/pocket-master-mcp.git
cd pocket-master-mcp
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

然后使用 "command": "/absolute/path/to/pocket-master-mcp/.venv/bin/pocket-master-mcp"。

配置

变量	默认值	含义
PM_PORT	自动	MIDI 端口名称的子字符串。未设置时，服务会查找名称包含 "Pocket"、"Sonicake"、"QME" 的端口；否则会探测所有端口。
PM_DATA_DIR	~/.pocket-master-mcp	存储备份、音色文件、语言包和日志的位置
PM_DEVICE_MAP	内置	自定义 device_map.json 的路径
PM_DEBUG_TOOLS	关闭	设为 1 后会开放 debug_send、debug_monitor 和 debug_raw_dump

检查连接

1. 在源代码检出目录中，运行 python scripts/midi_check.py。此操作只读：会打印端口、当前预设和预设名称。
2. 在 Claude 中输入："connect to the Pocket Master and show the device state"。将型号和值与设备屏幕上的内容进行比较。
3. 如果解码有误，请设置 PM_DEBUG_TOOLS=1 并调用 debug_raw_dump。它会将包含偏移量的原始转储写入 ~/.pocket-master-mcp/logs/。请将其附加到问题报告中。

工具

工具	功能
connect, list_midi_ports	查找并打开 Pocket Master
device_state	编辑缓冲区：预设、链路、音箱模式、型号、开关状态、参数值
list_models(block)	列出某个模块的型号及其参数和范围
set_model(block, model, on)	按名称选择型号
set_block(block, on)	打开或关闭模块
set_param(block, param, value)	设置当前型号的参数
set_chain(order)	设置信号链顺序
set_preset_volume, set_global	预设音量、全局设置
apply_preset(spec)	一次调用应用完整音色
list_presets, select_preset	列出预设名称、加载预设
save_preset(preset, name)	将编辑缓冲区保存到 P01–P50，并通过读回名称进行验证
rename_preset	重命名用户预设
backup_presets, list_backups, restore_preset	以 JSON 格式备份
save_preset_file, list_preset_files, load_preset_file	音色文件
list_user_slots	列出用户 IR 和采集的音箱配置文件名称
firmware_info, firmware_strings	检查固件 .bin：版本、区段、CRC、UI 字符串
list_language_packs, get_language_pack, save_language_pack	UI 翻译（英文字符串 → 译文）
build_language_firmware	构建将第二种 UI 语言替换为语言包的固件，并生成 PNG 预览
preview_firmware_strings	使用固件自带字体渲染其 UI 字符串

模块包括 nr（噪声门）、fx1、drv、amp、ir、eq、fx2、dly、rvb。gate、drive、cab、delay 和 reverb 等别名也可使用。采集的音箱配置文件（User Profile 1..5）在 amp 模块中选择，服务会自动切换音箱模式。

UI 语言（固件）

固件包含两种 UI 语言：英语和中文。build_language_firmware 会将中文替换为语言包：内置俄语（ru），你也可以使用 save_language_pack 保存自己的语言包。此操作会离线处理官方固件文件的副本，绝不会操作设备。使用官方 Sonicake Manager 刷入生成的固件，然后在设备设置中选择语言。若要恢复，请刷入官方固件文件。

• 语言包将英文 UI 字符串映射为译文。未列出的字符串会保持英文。固件中的效果和参数名称仅提供英文，不会翻译。
• 设备使用微型像素字体，因此字形需在 data/glyphs.json 中手工绘制。该文件已包含西里尔字母。对于其他文字系统，请先在此添加字形；如果有字符缺少字形，构建会停止并列出这些字符。
• 构建过程会检查结果：CRC、每个字符串、每个字符对应的字形，以及只有 UI 区段发生变化。它会拒绝已打补丁的输入文件，并且绝不会覆盖源文件。
• 这是非官方功能，使用风险由你自行承担。它已在 V1.3.3 上测试，并可构建适用于 V1.1.0 的固件。详情请参阅 docs/FIRMWARE.md。

示例："Build a Russian firmware from ~/Downloads/Pocket Master Firmware V1.3.3.bin, but use 'Сохр.' for Save."

无需 MCP 客户端也可以使用：

pocket-master-fw info  "Pocket Master Firmware V1.3.3.bin"
pocket-master-fw build "Pocket Master Firmware V1.3.3.bin" -l ru --set "Save=Сохр."

本项目不包含固件文件。请从 Sonicake 下载。

音色格式

{
  "chain": ["nr", "fx1", "drv", "amp", "ir", "eq", "fx2", "dly", "rvb"],
  "blocks": {
    "drv": {"model": "Scream", "params": {"Gain": 5, "Tone": 60, "Vol": 85}},
    "amp": {"model": "Sol 100 LD", "params": {"Gain": 62, "Middle": 58}},
    "ir":  {"model": "BritGN 4x12"},
    "dly": {"on": false},
    "rvb": {"model": "Room", "params": {"Mix": 10}}
  },
  "preset_volume": 70
}

选择型号会将其参数重置为默认值，因此参数应在型号之后应用（apply_preset 会按正确顺序执行）。

限制

• 只能导出编辑缓冲区。因此，备份会逐个加载每个预设，未保存的编辑内容会丢失。
• 备份存储的是解码后的设置，而非原始预设字节，因此解码器无法识别的内容（如果有）不会恢复。
• 可以写入全局设置，但目前还无法读取。
• 用户 IR / 捕获的音箱模拟内容无法上传，只能选择。

工作原理

• docs/PROTOCOL.md：MIDI SysEx 封装（半字节扩展、CRC-8）、命令、编辑缓冲区转储和预设名称。
• docs/FIRMWARE.md：HTFW 固件容器、Sonicake Manager 的更新协议，以及 LVGL UI 字体和字符串表。
• tools/build_device_map.py 会从 PocketEdit 检出版本重新生成型号和参数表。

开发

.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest

测试会重建从 PocketEdit 捕获的部分设备命令和设备的真实响应，并在虚拟 Pocket Master 上运行设备逻辑，因此无需硬件。如果 local/ 中有官方固件文件，或 PM_TEST_FIRMWARE 指向该文件，则会运行固件构建测试。

致谢和许可证

• suckyble 及其贡献者（hnikolov 等人）开发的 PocketEdit 是协议知识的来源。型号和参数表（data/device_map.json，由 tools/build_device_map.py 重新生成）以及 tests/fixtures/pocketedit_commands.json 中的命令样本均源自其库。PocketEdit 未声明许可证。如果您是其作者，并希望修改或删除这些文件，请提交 issue。
• 固件语言工具不包含任何 Sonicake 代码或数据。它们会修改用户提供的固件文件。

本代码采用 MIT 许可证，详见 LICENSE。Sonicake 和 Pocket Master 是其所有者的商标。型号名称指其模拟的产品，仅用于标识型号。