summaryrefslogtreecommitdiff
path: root/doc/mcp.md
diff options
context:
space:
mode:
authortanaka takashi <isazaka@gmail.com>2026-09-13 14:12:41 +0900
committertanaka takashi <isazaka@gmail.com>2026-09-13 14:13:04 +0900
commit97b34627667fd699f4e0e054533eb89a205a2878 (patch)
tree1d4549d56b7c53be9ecb583db9bb1a5593e54126 /doc/mcp.md
parent3b5bd2f8fd15bcc13542ff5ffd3c35453af9a9df (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.md42
1 files changed, 33 insertions, 9 deletions
diff --git a/doc/mcp.md b/doc/mcp.md
index a59c340..17661de 100644
--- a/doc/mcp.md
+++ b/doc/mcp.md
@@ -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