diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Design.md | 39 | ||||
| -rw-r--r-- | doc/mcp.md | 42 |
2 files changed, 61 insertions, 20 deletions
diff --git a/doc/Design.md b/doc/Design.md index 7c3d076..49543bf 100644 --- a/doc/Design.md +++ b/doc/Design.md @@ -139,21 +139,32 @@ MML文字列 ```json { - "success": true, - "wav_path": "./data/20260711_120000_123/output.wav", - "duration_sec": 2.0, - "note_sequence": { ... }, - "validation": { - "errors": [], - "warnings": [] - } + "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出力が成功したか | -| `wav_path` | string \| null | 生成されたWAVファイルパス（失敗時はnull） | +| `audio` | object \| null | MIMEタイプ、WAVのバイト数、サンプルレート。失敗時はnull | | `duration_sec` | number | 生成された音声の長さ（秒） | | `note_sequence` | object \| null | 中間表現（IR）のNoteSequence | | `validation.errors` | array | エラーのリスト | @@ -161,7 +172,11 @@ MML文字列 > `compose` は必ず検証を内包する。エラーがあればWAVは生成せず、検証結果のみ返す。 > -> **出力構成**: 生成時刻を表す `YYYYMMDD_HHMMSS_mmm` ディレクトリを作成し、WAVを `output.wav`、合成元のMML原文をUTF-8の `output.mml` として出力する。MCPの戻り値には従来どおりWAVのパスだけを含める。 +> **MCP出力**: 成功時はWAVをサイズにかかわらず`AudioContent`（`audio/wav`、base64）として返す。`ResourceLink`は使用せず、サーバ内部のファイルパスも公開しない。 +> +> **内部出力構成**: 生成時刻を表す `YYYYMMDD_HHMMSS_mmm` ディレクトリを作成し、WAVを `output.wav`、合成元のMML原文をUTF-8の `output.mml` として保存する。 +> +> **成否**: MCPツールの正式な成否は`CallToolResult.isError`で表す。composeおよびAPI入力の失敗は`true`、正常に完了したvalidateは対象MMLが不正でも`false`とし、妥当性は`valid`で表す。composeの`success`は構造化結果として残し、`success == !isError`を不変条件とする。 **`action: "validate"`** — MMLの構文チェックのみ（音声生成なし） @@ -687,6 +702,8 @@ NoteSequence IRを入力としてPulse1、Pulse2、Triangle、Noiseを合成し | 6 | Noise note_number → period マッピング | ppmck: `period=8, mode=0` 固定。pyxel: マッピング式適用 | | 7 | 出力構成 | `YYYYMMDD_HHMMSS_mmm/output.wav`, `YYYYMMDD_HHMMSS_mmm/output.mml` | | 8 | リピート安全上限 | 各トラックの展開後イベント数は100,000件以下。超過時は展開前に意味error | +| 9 | MCP音声応答 | WAVを常に`AudioContent`（`audio/wav`）で返し、`ResourceLink`とファイルパスは公開しない | +| 10 | MCPエラー判定 | 正式な成否は`CallToolResult.isError`。composeの`success`は構造化結果として同期させる | --- @@ -694,7 +711,7 @@ NoteSequence IRを入力としてPulse1、Pulse2、Triangle、Noiseを合成し | カテゴリ | 実装内容 | |---|---| -| MCPツール | `compose_mml`（compose/validate/template） | +| MCPツール | `compose_mml`（compose/validate/template）。`ToolResult`で構造化結果と`AudioContent`を返却 | | Lexer | ppmck/pyxel 両モード対応、共通トークン定義、INVALIDトークン。ppmck向けに `@v`/`@@`/`@MP`/`@EP`/`@EN`/`^`/`D`/`s`/`v+`/`v-` トークンを追加 | | Parser | ppmck/pyxel 別Parser。必須token、トップレベル順序、case、リピート対応を検証し、ppmckの`RepeatBreakStmt`と専用L文法を構築 | | SemanticAnalyzer | ppmck/pyxel別Analyzer、AST→IR変換。共通反復展開、事前イベント上限、値域→チャンネル→状態→IR順の検証、Lのloop_start算出を実装 | @@ -31,25 +31,47 @@ MML文字列を解析し、以下のいずれかの処理を実行します。 ### 戻り値 +ツール結果は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 { - "success": true, - "wav_path": "./data/20260711_120000_123/output.wav", - "duration_sec": 2.0, - "note_sequence": { ... }, - "validation": { - "errors": [], - "warnings": [] - } + "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出力が成功したか | -| `wav_path` | string \| null | 生成されたWAVファイルのパス（失敗時はnull） | +| `audio` | object \| null | MIMEタイプ、WAVのバイト数、サンプルレート。失敗時はnull | | `duration_sec` | number | 生成された音声の長さ（秒） | | `note_sequence` | object \| null | 中間表現（IR）のNoteSequence | @@ -59,6 +81,8 @@ MML文字列を解析し、以下のいずれかの処理を実行します。 | `validation.errors` | array | エラーのリスト | | `validation.warnings` | array | 警告のリスト | +WAVファイルのパスは公開しません。WAVはサイズにかかわらず`AudioContent`としてbase64エンコードして返し、`ResourceLink`への切り替えは行いません。サーバ内部では`--output-dir`以下へ`output.wav`と`output.mml`を保存します。 + #### action=`validate` の場合 ```json |