1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
# MCP Server Tool Schema
本ドキュメントは `mml-composemusic-mcp` が提供するMCPツールのスキーマ定義です。
## ツール一覧
| ツール名 | 説明 |
|---------|------|
| `compose_mml` | レトロチップ音源風MMLの解析・合成・テンプレート生成を行う |
## `compose_mml`
### 概要
MML文字列を解析し、以下のいずれかの処理を実行します。
- `compose`: MMLをレトロAPU風音源で合成し、WAVファイルを出力する
- `validate`: MMLの構文を検証し、エラー・警告・チャンネル概要を返す
- `template`: 指定したモード用のテンプレート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`, `expressive_lead`, `vibrato_lead`, `pitch_motion` |
| `sample_rate` | integer | no | `44100` | 出力WAVのサンプリングレート（Hz） |
| `normalize` | boolean | no | `true` | 出力振幅を正規化するか |
### 戻り値
ツール結果はMCPの`CallToolResult`として返されます。`content`には構造化結果をJSON化した`TextContent`が入り、`structuredContent`には同じ結果がJSONオブジェクトとして入ります。compose成功時だけ、`content`にWAV本体の`AudioContent`が追加されます。
MCPツール呼び出しの正式な成否は`isError`で表します。composeやAPI入力の失敗は`isError: true`、正常に完了した処理は`isError: false`です。validateは対象MMLにエラーがあっても検証処理自体は成功しているため`isError: false`となり、妥当性は`valid`で確認します。
#### action=`compose` の場合
```json
{
"content": [
{
"type": "text",
"text": "{\"success\":true,...}"
},
{
"type": "audio",
"data": "UklGR...",
"mimeType": "audio/wav"
}
],
"structuredContent": {
"success": true,
"audio": {
"mime_type": "audio/wav",
"size_bytes": 176444,
"sample_rate": 44100
},
"duration_sec": 2.0,
"note_sequence": { ... },
"validation": {
"errors": [],
"warnings": []
}
},
"isError": false
}
```
| フィールド | 型 | 説明 |
|-----------|-----|------|
| `success` | boolean | 合成・WAV出力が成功したか |
| `audio` | object \| null | MIMEタイプ、WAVのバイト数、サンプルレート。失敗時はnull |
| `duration_sec` | number | 生成された音声の長さ（秒） |
| `note_sequence` | object \| null | 中間表現（IR）のNoteSequence |
`note_sequence`はIR v2で返される。曲全体で共有するエンベロープ/LFO定義は
`definitions`、選択・解除と演奏イベントは各`channels.*.events`に格納される。
`ppmck`は構文モード名であり、拡張コマンドのPPMCK/mckc互換を保証しない。
| `validation.errors` | array | エラーのリスト |
| `validation.warnings` | array | 警告のリスト |
WAVファイルのパスは公開しません。WAVはサイズにかかわらず`AudioContent`としてbase64エンコードして返し、`ResourceLink`への切り替えは行いません。サーバ内部では`--output-dir`以下へ`output.wav`と`output.mml`を保存します。
#### action=`validate` の場合
```json
{
"valid": true,
"errors": [],
"note_sequence": { ... },
"channel_summary": [
{
"channel": "Pulse1",
"note_count": 4,
"octave_range": [4, 5],
"duration_ticks": 768
}
]
}
```
| フィールド | 型 | 説明 |
|-----------|-----|------|
| `valid` | boolean | MMLにerrorがないか |
| `errors` | array | エラーのリスト |
| `note_sequence` | object \| null | 中間表現（IR）のNoteSequence |
| `channel_summary` | array | チャンネルごとの統計情報 |
#### action=`template` の場合
```json
{
"mml": "0: T120 L8 O4 V100 @1\n C D E F | ...",
"description": "基本的な4ch構成（メロディ+和音+ベース+リズム）"
}
```
| フィールド | 型 | 説明 |
|-----------|-----|------|
| `mml` | string | 生成されたMMLテンプレート |
| `description` | string | テンプレートの説明 |
## エラー詳細
`errors` / `warnings` 配列の要素は以下の形式です。
```json
{
"code": "SYNTAX_INVALID_TOKEN",
"line": 1,
"column": 5,
"message": "未知のモード 'xyz' です。",
"severity": "error",
"hint": "mode は 'ppmck' または 'pyxel' を指定してください。",
"context": ""
}
```
| フィールド | 型 | 説明 |
|-----------|-----|------|
| `code` | string | エラーコード |
| `line` | integer | 発生行（0始まり） |
| `column` | integer | 発生列（0始まり） |
| `message` | string | 人間が読めるメッセージ |
| `severity` | string | `error` または `warning` |
| `hint` | string | 修正のヒント |
| `context` | string | 該当行のコンテキスト |
## サポートするMML形式
### ppmck
- トラック: `A`（Pulse1）、`B`（Pulse2）、`T`（Triangle）、`N`（Noise）
- コマンド例: `t120`（テンポ）、`l8`（音長）、`o4`（オクターブ）、`v15`（音量）、`q2`（デューティ）
### pyxel
- トラック: `0:`（Pulse1）、`1:`（Pulse2）、`2:`（Triangle）、`3:`（Noise）
- コマンド例: `T120`、`L8`、`O4`、`V100`、`@1`
## トランスポート
サーバ起動時に `--transport` で切り替え可能です。
| トランスポート | 用途 |
|---------------|------|
| `stdio` | 標準的なMCPクライアント接続（デフォルト） |
| `http` | HTTPエンドポイント |
| `sse` | Server-Sent Events |
| `streamable-http` | Streamable HTTP |
```bash
uv run mml-composemusic-mcp --transport sse --port 8080
```
|
