diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 364 |
1 files changed, 335 insertions, 29 deletions
@@ -1,53 +1,359 @@ # mml-composemusic-mcp -ファミコン音源（2A03 APU）風のMMLをLLMに作曲させるためのMCPサーバ。 +ファミコン音源（2A03 APU）風のMMLをLLMに作曲させるためのMCPサーバです。 -## 機能 +`compose_mml` という1つのツールで、MMLの**作曲（WAV生成）**、**構文検証**、**テンプレート生成**を行えます。 -- `compose_mml` ツールを提供 -- ppmck 形式と pyxel 形式のMMLを解析・合成 -- MIDIノート番号に変換後、NES APU風の矩形波/三角波/ノイズでWAV出力 -- バリデーション、テンプレート生成に対応 +--- -## ツール引数 +## 目次 -| 引数 | 説明 | -|------|------| -| `action` | `compose`, `validate`, `template` のいずれか | -| `mml` | MML文字列（compose/validate時必須） | -| `mode` | `ppmck` または `pyxel`（compose/validate時必須） | -| `template` | `basic`, `melody`, `chord`, `drum`, `empty`（action=template時） | -| `sample_rate` | WAV出力サンプリングレート（デフォルト44100） | -| `normalize` | 出力振幅の正規化（デフォルトtrue） | +1. [機能概要](#機能概要) +2. [動作環境](#動作環境) +3. [インストール](#インストール) +4. [MCPクライアントへの登録](#mcpクライアントへの登録) +5. [ツールの使い方](#ツールの使い方) +6. [MML形式](#mml形式) +7. [テスト・開発](#テスト開発) +8. [ディレクトリ構成](#ディレクトリ構成) +9. [ライセンス](#ライセンス) -## 実行 +--- + +## 機能概要 + +| 機能 | 説明 | +|---|---| +| `compose` | MMLを解析し、NES APU風の矩形波/三角波/ノイズでWAVファイルを生成する | +| `validate` | MMLの構文を検証し、エラー・警告・チャンネル概要を返す | +| `template` | `ppmck` / `pyxel` 用のテンプレートMMLを生成する | + +### 対応MML形式 + +| モード | 特徴 | +|---|---| +| `ppmck` | PPMCKインスパイアのFC準拠形式。小文字コマンド、`A`/`B`/`T`/`N` トラック | +| `pyxel` | Pyxel MML準拠形式。大文字コマンド、`0:`〜`3:` トラック、リピート・ゲートタイム対応 | + +--- + +## 動作環境 + +- Python 3.14 以上 +- [uv](https://docs.astral.sh/uv/)（推奨） +- 依存パッケージ: `fastmcp`, `numpy` + +--- + +## インストール + +### 1. リポジトリをクローンまたは配置 ```bash -uv run mml-composemusic-mcp --output-dir ./data +cd C:\\path\\to\\mml-composemusic-mcp ``` -または +### 2. 依存関係をインストール + +`uv` を使う場合: ```bash -uv run python -m mml_composemusic_mcp.server --output-dir ./data +uv sync ``` -## テスト +`pip` を使う場合: + +```bash +pip install -e . +``` + +### 3. 起動確認 + +```bash +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` に以下を追加します。 + + ```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" + ] + } + } + } + ``` + +3. Claude Desktop を再起動します。 + +### 設定ファイル例 + +[`doc/mcp-client-config-example.json`](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で使う場合の例 + +```bash +uv run mml-composemusic-mcp --transport sse --port 8080 --output-dir ./data +``` + +```json +{ + "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を生成 + +```json +{ + "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 +} +``` + +#### 戻り値 + +```json +{ + "success": true, + "wav_path": "./data/output.wav", + "duration_sec": 2.0, + "note_sequence": { ... }, + "validation": { + "errors": [], + "warnings": [] + } +} +``` + +- `success` が `false` の場合、`wav_path` は `null` になります。 +- エラーがある場合は `validation.errors` に詳細なエラー情報が入ります。 + +### action=`validate` — 構文チェック + +```json +{ + "action": "validate", + "mml": "A t120 l8 o4 v15 q2\n c d e f", + "mode": "ppmck" +} +``` + +#### 戻り値 + +```json +{ + "valid": true, + "errors": [], + "warnings": [], + "note_sequence": { ... }, + "channel_summary": [ + { + "channel": "Pulse1", + "note_count": 4, + "octave_range": [4, 5], + "duration_ticks": 768 + } + ] +} +``` + +### action=`template` — テンプレート生成 + +```json +{ + "action": "template", + "mode": "pyxel", + "template": "basic" +} +``` + +#### 戻り値 + +```json +{ + "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`](doc/Design.md) を参照してください。 + +--- + +## テスト・開発 + +### テスト実行 ```bash uv run pytest +``` + +### リント・フォーマット + +```bash uv run ruff check . uv run ruff format . ``` +### 手動でサーバを起動 + +```bash +uv run mml-composemusic-mcp --output-dir ./data +``` + +または: + +```bash +uv run python -m mml_composemusic_mcp.server --output-dir ./data +``` + +--- + ## ディレクトリ構成 -- `src/mml_composemusic_mcp/` - - `server.py` - MCPサーバ - - `lexer.py` - MML字句解析 - - `parser_ppmck.py`, `parser_pyxel.py` - 構文解析 - - `ir.py` - 中間表現・エラー型 - - `synthesizer.py` - APU風合成・WAV出力 - - `templates.py` - テンプレート -- `tests/` - テスト -- `doc/` - 設計書 +``` +. +├── 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 # プロジェクト設定 +``` + +--- + +## ライセンス + +（プロジェクトのライセンスをここに記載してください） |