mml-composemusic-mcp

レトロチップ音源（2A03 APU）風のMMLをLLMに作曲させるためのMCPサーバです。

compose_mml という1つのツールで、MMLの作曲（WAV生成）、構文検証、テンプレート生成を行えます。

---

目次

1. 機能概要
2. 動作環境
3. インストール
4. MCPクライアントへの登録
5. ツールの使い方
6. MML形式
7. テスト・開発
8. ディレクトリ構成
9. ライセンス

---

機能概要

機能	説明
compose	MMLを解析し、レトロAPU風の矩形波/三角波/ノイズでWAVファイルを生成する
validate	MMLの構文を検証し、エラー・警告・チャンネル概要を返す
template	ppmck / pyxel 用のテンプレートMMLを生成する

対応MML形式

モード	特徴
ppmck	PPMCKインスパイアのクラシックAPU準拠形式。小文字コマンド、A/B/T/N トラック
pyxel	Pyxel MML準拠形式。大文字コマンド、0:〜3: トラック、リピート・ゲートタイム対応

---

動作環境

• Python 3.14 以上
• uv（推奨）
• 依存パッケージ: fastmcp, numpy

---

インストール

1. リポジトリをクローンまたは配置

cd C:\\path\\to\\mml-composemusic-mcp

2. 依存関係をインストール

uv を使う場合:

uv sync

pip を使う場合:

pip install -e .

3. 起動確認

uv run mml-composemusic-mcp --help

以下のように表示されればOKです。

usage: mml-composemusic-mcp [-h] [--output-dir OUTPUT_DIR]
       [--transport {stdio,http,sse,streamable-http}] [--host HOST] [--port PORT]

---

MCPクライアントへの登録

Claude Desktop の場合

1. 設定ファイルを開きます。

   OS	パス
   Windows	%APPDATA%\Claude\claude_desktop_config.json
   macOS	~/Library/Application Support/Claude/claude_desktop_config.json

2. mcpServers に以下を追加します。

   {
     "mcpServers": {
       "mml-composemusic": {
         "command": "uv",
         "args": [
           "run",
           "--project",
           "C:\\path\\to\\mml-composemusic-mcp",
           "mml-composemusic-mcp",
           "--output-dir",
           "C:\\path\\to\\mml-composemusic-mcp\\data"
         ]
       }
     }
   }
   

3. Claude Desktop を再起動します。

設定ファイル例

doc/mcp-client-config-example.json に設定例があります。必要に応じてコピーしてください。

トランスポートの選択

トランスポート	用途	設定方法
stdio	標準的なMCPクライアント接続（デフォルト）	command/args で指定
http	HTTPエンドポイント	--transport http で起動後、url で接続
sse	Server-Sent Events	--transport sse で起動後、url で接続
streamable-http	Streamable HTTP	--transport streamable-http で起動

SSEで使う場合の例

uv run mml-composemusic-mcp --transport sse --port 8080 --output-dir ./data

{
  "mcpServers": {
    "mml-composemusic": {
      "url": "http://127.0.0.1:8080/sse"
    }
  }
}

注意点

• --output-dir は相対パスでも動きますが、MCPクライアントの作業ディレクトリが不定なため、絶対パスを推奨します。
• 初回起動時は uv が依存関係を解決するため、少し時間がかかることがあります。

---

ツールの使い方

ツール名

compose_mml

引数

引数名	型	必須	デフォルト	説明
action	string	yes	—	compose, validate, template のいずれか
mml	string	compose/validate時	""	MMLソース文字列
mode	string	compose/validate時	""	ppmck または pyxel
template	string	template時	"basic"	basic, melody, chord, drum, empty
sample_rate	integer	no	44100	出力WAVのサンプリングレート（Hz）
normalize	boolean	no	true	出力振幅を正規化するか

action=compose — WAVを生成

{
  "action": "compose",
  "mml": "0: T120 L8 O4 V100 @1\n   C D E F | G A B >C",
  "mode": "pyxel",
  "sample_rate": 44100,
  "normalize": true
}

戻り値

{
  "success": true,
  "wav_path": "./data/output_20260711_120000_123.wav",
  "duration_sec": 2.0,
  "note_sequence": { ... },
  "validation": {
    "errors": [],
    "warnings": []
  }
}

• success が false の場合、wav_path は null になります。
• エラーがある場合は validation.errors に詳細なエラー情報が入ります。
• WAVファイル名は生成時刻ベースの output_YYYYMMDD_HHMMSS_mmm.wav 形式で出力されます。 毎回異なるファイル名になるため、複数回の compose 実行でファイルが上書きされることはありません。

action=validate — 構文チェック

{
  "action": "validate",
  "mml": "A t120 l8 o4 v15 q2\n  c d e f",
  "mode": "ppmck"
}

戻り値

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "note_sequence": { ... },
  "channel_summary": [
    {
      "channel": "Pulse1",
      "note_count": 4,
      "octave_range": [4, 5],
      "duration_ticks": 768
    }
  ]
}

action=template — テンプレート生成

{
  "action": "template",
  "mode": "pyxel",
  "template": "basic"
}

戻り値

{
  "mml": "0: T120 L8 O4 V100 @1\n   C D E F | ...",
  "description": "基本的な4ch構成（メロディ+和音+ベース+リズム）"
}

テンプレート種別

テンプレート	内容
basic	基本的な4ch構成（メロディ+和音+ベース+リズム）
melody	メロディ重視（Pulse1主旋律、他は伴奏最小限）
chord	コード伴奏重視（Pulse2で和音、Triangleでベース）
drum	リズム重視（Noise中心のビートパターン）
empty	各チャンネルのヘッダーのみ（空のテンプレート）

---

MML形式

ppmck 形式の例

#TITLE "My Song"
#COMPOSER "LLM"

A t150 l8 o4 v15 q2
  c d e f | g a b > c

B l8 o3 v12 q1
  c r g r c r g r

T l4 o3 v7
  c2 c2 g2 g2

N l8 v10
  r c r c r c r c

pyxel 形式の例

0: T150 L8 O4 V100 @1
   C D E F G A B >C

1: L8 O3 V80 @2
   E G B R E G B R

2: L4 O3 V60
   C2 G2 E2 C2

3: L8 V80
   C R C R C R C R

詳細仕様

詳細なMMLコマンド仕様、IR構造、エラーコードは doc/Design.md を参照してください。

---

テスト・開発

テスト実行

uv run pytest

リント・フォーマット

uv run ruff check .
uv run ruff format .

手動でサーバを起動

uv run mml-composemusic-mcp --output-dir ./data

または:

uv run python -m mml_composemusic_mcp.server --output-dir ./data

---

ディレクトリ構成

.
├── doc/                          # 設計書・設定例
│   ├── Design.md                 # 統合設計書
│   ├── mcp.md                    # MCPツールスキーマ
│   └── mcp-client-config-example.json  # MCPクライアント設定例
├── src/mml_composemusic_mcp/     # ソースコード
│   ├── server.py                 # MCPサーバ
│   ├── lexer.py                  # MML字句解析
│   ├── parser_ppmck.py           # ppmckパーサ
│   ├── parser_pyxel.py           # pyxelパーサ
│   ├── parser_base.py            # パーサ共通処理
│   ├── ir.py                     # 中間表現・エラー型
│   ├── synthesizer.py            # APU風合成・WAV出力
│   └── templates.py              # テンプレート
├── tests/                        # テスト
├── README.md                     # このファイル
└── pyproject.toml                # プロジェクト設定

---

ライセンス

MIT