diff options
| author | tanaka takashi <isazaka@gmail.com> | 2026-09-13 14:12:41 +0900 |
|---|---|---|
| committer | tanaka takashi <isazaka@gmail.com> | 2026-09-13 14:13:04 +0900 |
| commit | 97b34627667fd699f4e0e054533eb89a205a2878 (patch) | |
| tree | 1d4549d56b7c53be9ecb583db9bb1a5593e54126 /doc/mcp.md | |
| parent | 3b5bd2f8fd15bcc13542ff5ffd3c35453af9a9df (diff) | |
feat: return composed WAV as MCP audio content
Replace the server-local wav_path result with a protocol-native multimedia response.
- Split internal composition execution from MCP ToolResult serialization so filesystem paths never enter public payloads.
- Return every successfully composed WAV as AudioContent with the audio/wav MIME type, regardless of file size.
- Keep structured audio metadata, duration, note sequence, and validation details alongside the multimedia content.
- Use CallToolResult.isError as the authoritative MCP execution status while retaining compose success and validate valid as domain fields.
- Treat invalid compose/API requests and runtime failures as tool errors, while invalid MML discovered by validate remains a successful validation operation.
- Sanitize synthesis, file-write, audio-serialization, and unexpected failure responses so internal paths and exception details are not exposed.
- Add protocol-level coverage for base64 round trips, content block types, error semantics, ResourceLink absence, and path non-disclosure.
- Update existing tests for the separated execution layer and path-free result contract.
- Document AudioContent and isError behavior in the README, MCP schema, and design specification.
- Require the tested FastMCP 3.4.4 API line and exclude the incompatible 4.x major version.
Verification: 487 tests passed; ruff check passed; git diff --check passed; uv lock --check passed; and a manual MCP call returned TextContent plus AudioContent with no wav_path.
Diffstat (limited to 'doc/mcp.md')
| -rw-r--r-- | doc/mcp.md | 42 |
1 files changed, 33 insertions, 9 deletions
@@ -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 |
