# utauMCP

OpenUtau (歌声合成ソフト) を Claude Desktop から操作するための MCP サーバー、
および OpenUtau内蔵のリアルタイム連携プラグイン。

`ymm4MCP` と同じ立ち位置: Claude Desktop の `claude_desktop_config.json` に
登録して使うMCPサーバー本体(Python)と、OpenUtau自体に読み込ませる
プラグイン(C#, `plugin/UtauMcpBridge`)の2部構成。**実機で動作確認済み。**

## 構成

```
utauMCP/
  server.py                MCPサーバー本体 (FastMCP, 全ツール定義)
  utau_mcp/
    config.py              OpenUtauのデータフォルダ(Singers等)をOSごとに検出
    ustx.py                .ustx (YAML) の読み書き・ノート/トラック/パート操作 (ファイルベース)
    lyrics.py               歌詞のモーラ分割・自動ノート割り当て
    voicebank.py             Singersフォルダのスキャン・oto.ini解析
    ust_legacy.py            クラシック.ustの読み書き (Shift_JIS対応)
    automation.py            OpenUtauプロセスの起動/終了/検出
    bridge_client.py         plugin/UtauMcpBridge と通信するHTTPクライアント (ライブ連携)
  plugin/UtauMcpBridge/      OpenUtau本体に読み込ませるC#プラグイン (下記)
  skills/utau-mcp/SKILL.md   Claude向けの使い方ガイド
```

## 2つの操作方式

| | ファイルベース (ustx.py) | ライブブリッジ (bridge_client.py) |
|---|---|---|
| 前提 | 常に使える | OpenUtauで音源のフォニマイザーに「[MCP] Claude連携ブリッジ」を選択済み |
| 反映タイミング | 保存時。OpenUtau起動中なら開き直しが必要 | 即座に画面へ反映 (保存・開き直し不要) |
| できること | プロジェクト全体の作成・編集 | 現在開いているプロジェクトの編集・保存 |

Claudeは基本的に `is_bridge_available()` で確認し、使えれば `*_live` ツールを、
使えなければファイルベースのツールを使う。

## plugin/UtauMcpBridge (OpenUtau内蔵プラグイン)

OpenUtauの「Plugins」フォルダに .dll を1つ置くと、OpenUtau起動時に自動で
読み込まれる。**重要**: OpenUtau 0.1.565 (実際にリリースされているバージョン)
には汎用プラグイン拡張点(BatchEdit等)が無く、唯一サードパーティdllが
実際にロードされる仕組みは**フォニマイザー**(`OpenUtau.Api.Phonemizer`
継承クラス)だけ。そのため、あえてフォニマイザーとして登録し:

- 音源のフォニマイザー選択ドロップダウン(「さらに表示」の中)に
  **「[MCP] Claude連携ブリッジ (発音処理はしません)」** という項目が追加される。
- これを選択すると(コンストラクタが走り)`http://127.0.0.1:51127/`
  (localhost限定、認証なし)でHTTPサーバーが起動する。起動処理は冪等で、
  内部で複数回コンストラクタが呼ばれても問題ない。
- `DocManager.Inst` (今開いているプロジェクトの実体)に直接アクセスし、
  ノート追加/編集/削除・保存を、ファイルを介さず即座にOpenUtauの画面へ反映する。
- `Process()` は空の音素配列を返すダミー実装 (実際の発音・レンダリングはしない)。

### ビルド方法

OpenUtau本体と型を一致させるため、**実際にインストールされているバージョンの
タグ付きソース**でビルドする(masterブランチは先行開発中のAPIを含み、
型が一致してもリフレクションで検出されない/動作しないことがあるため使わない)。

```powershell
git clone --branch <実際のバージョンタグ, 例: 0.1.565> https://github.com/stakira/OpenUtau.git
# UtauMcpBridge.csproj の <ProjectReference> パスをそこに合わせて書き換える
cd plugin/UtauMcpBridge
dotnet build
# 出力された UtauMcpBridge.dll を OpenUtauのPluginsフォルダにコピー
# (例: %USERPROFILE%\Documents\OpenUtau\Plugins\ または OneDriveのドキュメント配下)
```

バージョン確認方法: OpenUtauの `ヘルプ` メニューやログファイル
(`Logs/logYYYYMMDD.txt` 冒頭の `OpenUtau vX.X.X.X`)で確認できる。

### 使い方 (OpenUtau側)

1. OpenUtauでプロジェクトを開く。
2. Track1などの「シンガーを選択」の下にあるフォニマイザー名をクリックし、
   出てきたリストの「さらに表示 ...」を開く。
3. 「[MCP] Claude連携ブリッジ (発音処理はしません) (Contributed by utauMCP)」を選択。
4. これでClaude側から `is_bridge_available()` がTrueを返すようになる。
5. 一度選択すると、そのプロジェクトを開き直したときも自動的に再起動する
   (フォニマイザー選択がプロジェクトに保存されるため)。

**注意**: このフォニマイザーは実際の歌声合成をしないダミーなので、
本当に歌わせたいトラックには使わないこと(レンダリングしても無音になる)。
歌わせる用途では、ブリッジ操作が終わったら通常のフォニマイザー
(JapaneseCVVCPhonemizer等)に選び直すこと。

## Pythonサーバーのセットアップ

```powershell
cd utauMCP
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
```

`claude_desktop_config.json` に `claude_desktop_config_example.json` の内容を
マージして追加し、Claude Desktop を再起動する。

## tick と拍の関係

OpenUtau は 1拍(四分音符) = 480 tick 固定。`convert_beats_ticks` ツールで相互変換できる。

## ノート生成時の注意 (プラグイン開発者向け)

C#側でノートを新規作成する際は `UNote.Create()` を単体で使わず、
`project.CreateNote(tone, position, duration)` を使うこと。
`UNote.Create()` だけだとピッチカーブの初期点が無く、`snapFirst=true` の
デフォルトと組み合わさって検証時に `ArgumentOutOfRangeException` で
クラッシュする(実際に踏んだ罠)。`CreateNote()` は自動でポルタメントの
初期ピッチポイントを追加してくれる。

## ファイル形式について

`.ustx` は YAML (UTF-8, snake_case キー)。本リポジトリの実装は
[stakira/OpenUtau](https://github.com/stakira/OpenUtau) 本家ソース
(`OpenUtau.Core/Ustx/*.cs`, `OpenUtau.Core/Format/USTx.cs`) と、
実際に生成されたプロジェクトファイルを突き合わせて検証している。

## 今後の拡張候補

- レンダリング実行・再生プレビューをブリッジ経由で直接トリガーする
  (現状はノート編集・保存のみ対応)。
- YMM4MCPとの連携 (UTAUで作った歌声を動画の音声トラックに自動配置)。
- 複数キャラクター(音源)の歌唱切り替えの高レベルAPI化。