Sonicake Pocket Master

pocket-master-mcp

AI アシスタント（Claude Desktop またはその他の MCP クライアント）から、USB MIDI 経由で Sonicake Pocket Master ギタープロセッサーを操作できる MCP サーバーです。デバイスの UI を他の言語に翻訳するオフラインツールも含まれており、ロシア語が組み込まれています。

希望するサウンドを平易な言葉で説明してください（「タイトなモダンメタルのリズム」「広がりのあるコーラスをかけたクリーンサウンド、リバーブは控えめ」など）。アシスタントがモデルを選び、パラメーターを設定し、チェーンを並べ替え、本体にプリセットを保存して名前を付けます。

非公式プロジェクトです。 Sonicake とは提携しておらず、同社からの承認も受けていません。プロトコルは PocketEdit によるリバースエンジニアリングの成果に基づいています。読み取り（現在のプリセット、プリセット名、編集バッファー全体）は、ファームウェア V1.3.3 を搭載した実機で検証済みです。プリセットの書き込みは、これまでハードウェアでのテストがあまり行われていないため、最初に backup_presets を実行してください。パッチ適用済みファームウェアも非公式です。ご自身の責任でご利用ください。

できること

• リアルタイム編集： 任意のブロックでモデルを選択できます（アンプ 22 種類＋キャプチャーアンプのプロファイル 5 種類、キャビネット／IR 20 種類、ドライブ 8 種類、FX1／FX2 は各 15～17 種類のエフェクト、ディレイ 9 種類、リバーブ 10 種類、EQ 3 種類、ノイズゲート）。ブロックのオン／オフを切り替え、名前で範囲チェック付きのパラメーター設定ができます（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 録音／モニター／Bluetooth 録音の各レベル。
• 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	auto	MIDI ポート名に含まれる文字列です。指定しない場合、サーバーは "Pocket"、"Sonicake"、"QME" を探し、それ以外の場合はすべてのポートを調べます。
PM_DATA_DIR	~/.pocket-master-mcp	バックアップ、トーンファイル、言語パック、ログの保存先です
PM_DEVICE_MAP	bundled	カスタムの device_map.json のパスです
PM_DEBUG_TOOLS	off	1 を指定すると、debug_send、debug_monitor、debug_raw_dump が公開されます

接続の確認

1. ソースのチェックアウトから python scripts/midi_check.py を実行します。読み取り専用のツールで、ポート、現在のプリセット、プリセット名が表示されます。
2. Claude で 「Pocket Master に接続して、デバイスの状態を表示して」 と指示します。モデルと値を本体の画面と比較します。
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)	1 回の呼び出しでトーン全体を適用します
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	2 つ目の 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 言語（ファームウェア）

ファームウェアには、英語と中国語の 2 つの 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 を参照してください。

例：「~/Downloads/Pocket Master Firmware V1.3.3.bin からロシア語ファームウェアをビルドして。ただし 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 は正しい順序で処理します）。

制限事項

• ダンプできるのは編集バッファーのみです。そのため、バックアップでは各プリセットを1つずつ読み込みます。また、未保存の編集内容は失われます。
• バックアップに保存されるのはデコード済みの設定であり、プリセットの生バイト列ではありません。そのため、デコーダーが認識しない情報があれば、復元されません。
• グローバル設定は書き込めますが、まだ読み込めません。
• ユーザー 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 は、それぞれの所有者の商標です。モデル名は、エミュレートする製品を指し、モデルを識別する目的でのみ使用しています。