# aviutl2-mcp

**AviUtl ExEdit2 (AviUtl2) を LLM（Claude Code など）から操作する MCP サーバー。**

Claude Code に「1920x1080 30fps のプロジェクトを作って、タイトルテキストを入れて、拡散光をかけて、AviUtl2 で開いて」と指示するだけで、`.aup2` プロジェクトを組み立てて実際に AviUtl2 で開くところまで自動化できます。

**さらに、ネイティブブリッジプラグイン（`plugin/`）を導入すると、既に開いている AviUtl2 をリアルタイムに操作できます。** ファイルの書き換え・開き直しは不要で、`live_add_object` 等のツールを呼ぶと即座にプレビュー画面へ反映されます。詳細は [plugin/README.md](plugin/README.md) を参照してください。

動作確認済み環境: AviUtl ExEdit2 version 2.00 beta53a / Windows 11 / Node.js 22。

## ダウンロード

**[Releases から最新版の zip をダウンロード](https://github.com/sima05020/aviutl2-mcp/releases/latest)** して展開し、`setup.bat` をダブルクリックするだけで導入できます。手順の詳細は [GETTING_STARTED.md](GETTING_STARTED.md) を参照してください。

> ⚠️ 同梱の `plugin/build/mcp_bridge.dll`（リアルタイム制御用プラグイン）は現時点では**コード署名されていません**。導入時にセキュリティソフトが反応することがあります。ソースコードは `plugin/src/` に全て公開していますので、気になる方は中身を確認してから使ってください。署名対応の計画は [SIGNING.md](SIGNING.md) を参照してください。

以下はこのプロジェクトの技術的な仕組みの説明です。

---

## 仕組み

AviUtl2 のプロジェクトファイル `.aup2` は **UTF-8・CRLF の INI 風テキスト**です。このサーバーはそのフォーマットを解析・生成することで、GUI 操作なしにプロジェクトを構築します。

- 実機が保存した `.aup2` を `parse → serialize` して**バイト単位で完全一致**することをテストで保証（`test/roundtrip.test.js`）。フォーマットを壊しません。
- オブジェクトは「メディア入力エフェクト → 任意のフィルタ → 描画/再生エフェクト」という AviUtl2 の内部構造どおりに生成します。
- パラメータの書式（`拡散光` の `強さ` など）は実機が出力したプロジェクトから採取した検証済みの値を使用しています。

### 安全設計（本体を壊さない）

`src/paths.js` の `assertWritable()` で書き込み先を検証し、以下を**コードレベルで拒否**します。

| 領域 | 読み取り | 書き込み |
|------|:---:|:---:|
| 本体フォルダ `C:\Program Files\AviUtl2` | ✅ | ❌ 常に拒否 |
| データフォルダ `C:\ProgramData\aviutl2` | ✅ | ❌ 拒否（`Script\MCP` 配下のみ許可） |
| それ以外（ユーザーのプロジェクト置き場など） | ✅ | ✅ |

スクリプトのインストールは `C:\ProgramData\aviutl2\Script\MCP\` という専用サブフォルダにのみ行うため、既存のスクリプトや設定を上書きしません。

---

## セットアップ

このリポジトリを好きな場所に clone/展開してください。

```powershell
cd <展開したフォルダ>\aviutl2-mcp
npm install
npm test        # ラウンドトリップ + MCP 統合テスト
```

`setup.bat`（または`setup.ps1`）を実行すると、依存インストールから下記の `.mcp.json` 作成まで自動化されます。詳しくは [GETTING_STARTED.md](GETTING_STARTED.md) を参照してください。

### Claude Code への登録

このフォルダの直下に `.mcp.json` を作成すると、Claude Code をこのフォルダで起動したときに自動で読み込まれます。

```json
{
  "mcpServers": {
    "aviutl2": {
      "command": "node",
      "args": ["<展開したフォルダの絶対パス>\\aviutl2-mcp\\src\\index.js"]
    }
  }
}
```

`args` にはこのリポジトリの `src/index.js` への絶対パスを指定してください（`setup.ps1` を使えば自動で書き込まれます）。Claude Code をこのフォルダで起動すると `aviutl2` サーバーが読み込まれ、`/mcp` で確認できます。別の場所で使う場合は `claude mcp add` で登録するか、任意の設定ファイルにこの JSON を追記してください。

### 環境変数（任意）

- `AVIUTL2_EXE_DIR` — `aviutl2.exe` のあるフォルダ（自動検出に失敗する場合）
- `AVIUTL2_DATA_DIR` — データフォルダ（既定 `C:\ProgramData\aviutl2`）

---

## 提供ツール

| ツール | 説明 |
|--------|------|
| `get_environment` | インストール状態・バージョン・起動中かを返す（最初に呼ぶ） |
| `list_assets` | 導入済みスクリプト/プラグイン/図形/フォント等の一覧 |
| `read_docs` | 本体付属の `aviutl2.txt` / `lua.txt` / `style.conf` を参照 |
| `create_project` | 空の `.aup2` を作成（解像度・fps 指定） |
| `read_project` | `.aup2` を JSON で読み取り（既存プロジェクトの書式学習にも） |
| `add_objects` | 動画/画像/音声/テキスト/任意構成のオブジェクトを追加 |
| `update_object` | レイヤー/フレーム範囲/エフェクトパラメータを変更、フィルタ追加 |
| `delete_object` | オブジェクト削除 |
| `update_scene` | シーンの解像度・fps・名前などを変更 |
| `launch_aviutl2` | AviUtl2 を起動（プロジェクトを開く） |
| `install_script` | スクリプト(.anm2 等)を `Script\MCP` にインストール |
| `uninstall_script` | 管理フォルダのスクリプトを削除 |
| `package_scripts` | 配布用 zip を作成 |
| `install_live_bridge` | ネイティブブリッジプラグインを `Plugin` フォルダに導入（要 AviUtl2 再起動） |
| `live_status` | ブリッジプラグインへの接続確認 |
| `live_get_state` | 起動中プロジェクトの現在シーンの状態をリアルタイム取得 |
| `live_add_object` | 起動中プロジェクトにオブジェクトをその場で追加（開き直し不要） |
| `live_update_object` | 起動中プロジェクトのオブジェクトをその場で編集 |
| `live_delete_object` | 起動中プロジェクトのオブジェクトをその場で削除 |

### オブジェクトの型（`add_objects`）

- `video` / `image` / `audio` … `file`（絶対パス）を指定
- `text` … `text`（改行可）と `text_params`（`サイズ` `フォント` `文字色` `文字装飾` `文字揃え` など）
- `raw` … `effects` でエフェクト列を完全指定（高度な用途）
- 共通: `layer` `frame_start` `frame_end`、`draw_params`（`X` `Y` `拡大率` `透明度` `合成モード` `音量` など）、`filters`（`拡散光` `ぼかし` `ラスター` などフィルタ効果の配列）

移動アニメは値を `"開始値,終了値,直線移動"` の形式で渡します（例 `draw_params: { X: "-960,960,直線移動" }`）。使えるフィルタ名・パラメータ名は `read_docs(doc:"readme")` や既存プロジェクトの `read_project` で確認できます。

---

## 使い方の例

Claude Code への指示例：

> 1280x720 60fps のプロジェクトを `C:\Users\<ユーザー名>\Videos\intro.aup2` に作って、
> 中央にタイトル「新作動画」を縁取り文字で置いて、左から右へスライドインさせて、
> AviUtl2 で開いて。

コードから直接叩く例は [`examples/build-demo.mjs`](examples/build-demo.mjs) を参照（`node examples/build-demo.mjs` で `demo/demo.aup2` を生成して AviUtl2 で開きます）。

---

## リアルタイム制御（ブリッジプラグイン）

`.aup2` ファイルの生成・編集は「開き直し」が必要になりますが、`plugin/` に同梱したネイティブプラグイン（`.aux2`、AviUtl2 公式 SDK の `EDIT_SECTION` API を使用）を導入すると、**既に開いている AviUtl2 に対して名前付きパイプ経由でその場に反映**できます。

```
install_live_bridge を実行 → AviUtl2 を再起動 → live_status で接続確認 → live_add_object / live_update_object / live_delete_object
```

- 対象は AviUtl2 で現在表示・編集中のシーン（ファイル方式のようなシーン番号指定はない）
- オブジェクトの特定は `layer`（0始まり）と `frame_start` の完全一致で行う
- 本体は改変せず、`ProgramData\aviutl2\Plugin\aviutl2-mcp-bridge.aux2` という専用ファイル名にのみ書き込む（他のプラグインと衝突しない）
- 仕組み・ビルド方法・IPC プロトコルの詳細は [plugin/README.md](plugin/README.md) を参照

---

## スクリプトの配布（MOD）

`install_script` で自作の Lua スクリプト（アニメーション効果 `.anm2` など）を導入し、`package_scripts` で配布用 zip を作れます。zip は「解凍して出てくるフォルダを `ProgramData\aviutl2\Script` に入れる」構成になっており、受け取った人は AviUtl2 のプレビュー画面へ D&D するだけでもインストールできます。Lua の仕様は `read_docs(doc:"lua")` で本体付属の `lua.txt` を読めます。

---

## このツール自体の配布パッケージを作る

他の人に配れる zip（`setup.bat` で導入できる完成品）を作るには:

```powershell
npm run package
```

`release/aviutl2-mcp-vX.X.X.zip` が生成されます。`node_modules` や `.git`、開発中の一時ファイルは含まれず、
受け取った人がそのまま `setup.bat` を実行できる最小構成（ソース一式 + ビルド済みの `plugin/build/mcp_bridge.dll`）になります。
プラグインを最新のソースから作り直したい場合は、先に [plugin/README.md](plugin/README.md) の手順でビルドしてから
`npm run package` を実行してください（ビルド済みDLLが無くても、ファイル方式の機能だけを含んだパッケージが作られます）。

配布を受け取った側の手順は [GETTING_STARTED.md](GETTING_STARTED.md) にまとめてあります。

---

## コード署名について

`plugin/build/mcp_bridge.dll` は未署名のネイティブDLLです。動画編集ソフトのプロセスに読み込まれ
名前付きパイプで通信するという性質上、セキュリティソフトが警戒する可能性があります。

このプロジェクトは [SignPath.io](https://signpath.io/) のオープンソース向け無料署名プログラムへの
申請を前提に、GitHub Actions での自動ビルド（[`.github/workflows/build-plugin.yml`](.github/workflows/build-plugin.yml)）
を用意しています。申請〜設定の具体的な手順は [SIGNING.md](SIGNING.md) を参照してください。

署名してもセキュリティソフトの警戒が完全になくなるわけではありません（未知の発行元という理由での警告は
減りますが、「動画編集ソフトに注入されIPC通信を行う」という挙動自体への挙動検知は署名の有無に関わらず
残る可能性があります）。SignPathでの審査が難しい場合の代替として、Azure Trusted Signing（月額課金・
要Microsoftアカウントでの本人確認）や、Sectigo/Certum等が提供する個人向けOV証明書（年額課金・要身分証明）
もあります。

---

## 注意点

- **ファイル方式**（`create_project`/`add_objects` 等）は、AviUtl2 で**既に開いているプロジェクトを外部から編集しても自動では反映されません**。編集後は AviUtl2 で開き直してください。逆に、AviUtl2 で編集・保存すると外部の変更は上書きされます。同じプロジェクトを両方から同時に触らないようにしてください。**リアルタイムに反映したい場合はブリッジプラグイン経由の `live_*` ツールを使ってください**（上記「リアルタイム制御」参照）。
- `add_objects` は同一レイヤー・同一シーンでフレーム範囲が重なる追加を拒否します。
- 対応フォーマットは AviUtl2 2.00 beta53a で確認したものです。将来のバージョンでキーが増えても、未知のセクションはパーサが明示的にエラーにするため、気付かず壊すことはありません。

## ライセンス

MIT。AviUtl2 本体は同梱しません（各自でインストール）。