# mml-composemusic-mcp

LLMにMMLを書かせ、レトロゲーム機風の音楽をWAVとして生成するMCPサーバです。

Pulse 2ch、Triangle 1ch、Noise 1chの構成を持つ簡易2A03 APU風シンセサイザーを内蔵しています。MCPクライアントから単一の`compose_mml`ツールを呼び出すことで、作曲、検証、作例テンプレートの取得まで行えます。

> [!IMPORTANT]
> `ppmck`と`pyxel`は、このプロジェクトが受理するMML構文モードの名前です。オリジナルのPPMCK/mckcやPyxelとの完全な互換性は保証しません。

## 主な機能

- MMLを解析し、モノラル16-bit PCMのWAVファイルを生成
- 構文・値域・チャンネル適合性を合成前に検証
- Pulse1、Pulse2、Triangle、Noiseの4チャンネルに対応
- ppmck風の小文字MMLと、Pyxel風の大文字MMLに対応
- 音量・音色エンベロープ、ビブラート、LFO、グライド、スイープなどを合成へ反映
- LLMがコピーして改変できる8種類の作例テンプレートを収録
- stdio、HTTP、SSE、Streamable HTTPトランスポートに対応

## サンプルデータ

実際にLLMを使用してこのMCPツールで作曲させてみたサンプルデータです。

ppmck版
- [音声](https://github.com/takashi000/mml-composemusic-mcp/blob/main/samples/ppmck/output.wav)
- [mml](https://github.com/takashi000/mml-composemusic-mcp/blob/main/samples/ppmck/output.mml)

pyxel版
- [音声](https://github.com/takashi000/mml-composemusic-mcp/blob/main/samples/pyxel/output.wav)
- [mml](https://github.com/takashi000/mml-composemusic-mcp/blob/main/samples/pyxel/output.mml)

## 必要環境

- Python 3.14以上
- [uv](https://docs.astral.sh/uv/)（推奨）

## セットアップ

リポジトリを取得し、プロジェクトのディレクトリで依存関係をインストールします。

```bash
uv sync
uv run mml-composemusic-mcp --help
```

pipを使う場合は、仮想環境内で次のようにインストールできます。

```bash
python -m pip install -e .
mml-composemusic-mcp --help
```

## MCPクライアントへの登録

標準入出力で起動する設定例です。`C:\path\to\mml-composemusic-mcp`と出力先を実際の絶対パスへ置き換えてください。

```json
{
  "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"
      ]
    }
  }
}
```

`--output-dir`を省略した場合は、サーバの作業ディレクトリにある`./data`へ出力します。MCPクライアントによって作業ディレクトリが異なるため、通常は絶対パスの指定を推奨します。

HTTP系トランスポートで手動起動する場合は、次のオプションを利用できます。

```bash
uv run mml-composemusic-mcp \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8080 \
  --output-dir ./data
```

利用可能な`--transport`は`stdio`（デフォルト）、`http`、`sse`、`streamable-http`です。HTTP側の接続URLは、使用するFastMCPとMCPクライアントのトランスポート設定に合わせてください。

## LLMからの使い方

公開されるツールは`compose_mml`の1つです。基本的には、テンプレートを取得して編集し、検証してから合成します。

1. `action: "template"`で作例を取得する
2. 作りたい曲に合わせてLLMがMMLを書き換える
3. `action: "validate"`でエラーと警告を確認する
4. 問題がなければ`action: "compose"`でWAVを生成する

MCPクライアントでは、たとえば次のように依頼できます。

> pyxelモードのvibrato_leadテンプレートを参考に、テンポ150の明るい8小節のボス戦BGMを作ってください。まずvalidateし、問題を直してからcomposeしてください。

### `compose_mml`の引数

| 引数 | 型 | 使用するaction | デフォルト | 説明 |
|---|---|---|---|---|
| `action` | string | すべて | 必須 | `template`、`validate`、`compose` |
| `mode` | string | すべて | `""` | `ppmck`または`pyxel` |
| `mml` | string | validate/compose | `""` | 検証・合成するMML |
| `template` | string | template | `"basic"` | 取得するテンプレート名 |
| `sample_rate` | integer | compose | `44100` | WAVのサンプリング周波数 |
| `normalize` | boolean | compose | `true` | 合成後に振幅を正規化するか |

未知の`mode`をtemplateで指定した場合は`ppmck`、未知のテンプレート名を指定した場合は`basic`へフォールバックします。validate/composeでは`mml`と`mode`が必須です。

### テンプレートを取得する

```json
{
  "action": "template",
  "mode": "pyxel",
  "template": "vibrato_lead"
}
```

| テンプレート | 用途 |
|---|---|
| `basic` | メロディ、伴奏、ベース、リズムの基本4ch構成 |
| `melody` | Pulse1の主旋律を中心にした構成 |
| `chord` | Pulseのコード伴奏とTriangleベースを中心にした構成 |
| `drum` | Noiseのビートを中心にした構成 |
| `empty` | 各チャンネルを休符だけにした最小構成 |
| `expressive_lead` | 音量・音色エンベロープを使うリード |
| `vibrato_lead` | ビブラート、ピッチ変化、デチューンを使うリード |
| `pitch_motion` | アルペジオ、スイープ、グライドを使う効果的な音程変化 |

テンプレートは両モードに用意され、同じ目的を各モード固有のコマンドで表現します。

### MMLを検証する

```json
{
  "action": "validate",
  "mode": "ppmck",
  "mml": "A t120 l8 o4 v15 q7 @2\n  c d e f | g a b >c"
}
```

`valid`、`errors`、`warnings`に加え、解析済みの`note_sequence`とチャンネルごとの`channel_summary`を返します。エラーには行・列、原因、修正ヒントが含まれます。

### WAVを生成する

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

成功時は、MCPレスポンスの`content`に`audio/wav`の`AudioContent`を返します。WAVデータはbase64エンコードされ、ファイルサイズにかかわらず同じ形式で返されます。`structuredContent`には`success: true`、`duration_sec`、音声メタデータ、解析済みの`note_sequence`、検証結果が入ります。

指定した出力ディレクトリの下には、従来どおり生成時刻を表す`YYYYMMDD_HHMMSS_mmm`ディレクトリを作り、`output.wav`と合成に使用したMML原文の`output.mml`を保存します。この保存先はサーバ内部の情報であり、MCPレスポンスにはファイルパスを含めません。

MCPツールとしての成否は`isError`で判定します。compose、引数、actionなどのエラーは`isError: true`、正常に完了したvalidateは対象MMLが不正でも`isError: false`です。composeの`success`とvalidateの`valid`は、それぞれの処理結果を表す構造化フィールドです。

## MMLの書き方

### チャンネル対応

| 音源 | ppmck | pyxel | 特徴 |
|---|---|---|---|
| Pulse1 | `A` | `0:` | デューティ比を変更できる矩形波 |
| Pulse2 | `B` | `1:` | デューティ比を変更できる矩形波 |
| Triangle | `T` | `2:` | 主にベース向けの三角波 |
| Noise | `N` | `3:` | ドラムや効果音向けのノイズ |
| Loop | `L` | — | ppmckのループトラック |

ppmckは音符と基本コマンドに小文字、pyxelは大文字を使います。

### ppmckモード

```mml
#TITLE "My Song"
#COMPOSER "LLM"

A t150 l8 o4 v15 q7 @2
  c d e f | g a b >c

B l8 o3 v11 @1
  c r g r | c r g r

T l4 o2 v7
  c2 g2 | a2 f2

N l8 v10
  c r c c | c r c r
```

主な拡張機能:

- `D`: セント単位のデチューン
- `s`: Pulseハードウェアスイープ
- `v+` / `v-`: 相対音量
- `@v` / `@@`: 音量・デューティエンベロープ
- `@MP` / `MP` / `MPOF`: LFOの定義・適用・解除
- `@EP` / `EP` / `EPOF`: ピッチエンベロープ
- `@EN` / `EN` / `ENOF`: 高速アルペジオ向けノートエンベロープ
- `^`: タイ、`&`: スラー

### pyxelモード

```mml
0: T150 L8 O4 V110 Q90 @1
   C D E F | G A B >C

1: L8 O3 V80 @2
   C R G R | C R G R

2: L4 O2 V60
   C2 G2 | A2 F2

3: L8 V80
   C R C C | C R C R
```

主な拡張機能:

- `K`: 半音単位のトランスポーズ
- `Y`: セント単位のデチューン
- `@ENV`: 音量エンベロープ
- `@VIB`: ビブラート
- `@GLI`: グライド
- `[...]N`: 回数付きリピート
- `&`: スラー

値域や正確な文法は[MML構文規則](https://github.com/takashi000/mml-composemusic-mcp/blob/main/doc/MML_BNF.md)、MCPの入出力は[MCPツール仕様](https://github.com/takashi000/mml-composemusic-mcp/blob/main/doc/mcp.md)、内部構造は[設計書](https://github.com/takashi000/mml-composemusic-mcp/blob/main/doc/Design.md)を参照してください。

## 現在の制約

- DPCM、NSF出力、GUI、Webプレイヤーはありません。
- 実機や既存ドライバの音を厳密に再現するエミュレーターではありません。
- Pulse専用コマンドをTriangleやNoiseへ指定すると、エラーまたは警告になります。
- ppmckの区間リピートなど、設計上予約されていても未実装の構文があります。
- pyxelの無限リピートは安全のため有限回で打ち切られ、警告が返る場合があります。

## 開発

```bash
# 全テスト
uv run pytest

# lint
uv run ruff check .

# format
uv run ruff format .

# stdioサーバを手動起動
uv run mml-composemusic-mcp --output-dir ./data
```

受理するMML文法を変更する場合は、実装・テストと合わせて`doc/MML_BNF.md`を更新してください。

## 変更履歴

[CHANGELOG.md](https://github.com/takashi000/mml-composemusic-mcp/blob/main/CHANGELOG.md)を参照してください。

## ライセンス

MIT