resolume-mcp-server: Instructions file for Claude Code

Resolume MCP Server — Project Context

概要

Resolume Arena/Avenue VJ ソフトウェアを Claude などの LLM から自然言語で操作するための MCP サーバー。

アーキテクチャ

LLM (Claude) <--stdio--> MCP Server (Node.js) ──HTTP/WS─→ Resolume Web Server (8080)
                                              ──UDP/OSC─→ Resolume OSC IN/OUT (7000/7001)

Resolume の Web Server は Preferences > Web Server で有効化可能。デフォルトで http://127.0.0.1:8080 を listen。 OSC は Preferences > OSC で有効化。MCP は OSC IN port (default 7000) に送信、OSC OUT port (default 7001) を listen。

ディレクトリ構成

resolume-mcp-server/
├── src/
│   ├── index.ts                    # stdio エントリポイント
│   ├── config.ts                   # 環境変数からの設定ロード
│   ├── resolume/
│   │   ├── client.ts               # 高レベルファサード (validation, summary)
│   │   ├── rest.ts                 # 型付き REST クライアント (fetch + abort)
│   │   ├── osc-codec.ts            # OSC 1.0 encoder/decoder (deps なし)
│   │   ├── osc-client.ts           # stateless UDP send/query/subscribe/probe
│   │   └── types.ts                # Zod スキーマ + TS 型
│   ├── tools/
│   │   ├── types.ts                # ToolDefinition + ToolResult 型
│   │   ├── index.ts                # 全ツール集約 (型消去)
│   │   ├── composition/get-composition.ts
│   │   ├── clip/{trigger,select,get-thumbnail}.ts
│   │   ├── layer/{set-opacity,clear-layer}.ts
│   │   └── osc/{send,query,subscribe,status}.ts
│   ├── server/
│   │   └── registerTools.ts        # SDK サーバーへのツール登録 + エラー整形
│   └── errors/
│       └── types.ts                # ResolumeError tagged union + マッパー
└── tests are colocated as *.test.ts next to source

設計原則

1. ハンドラ → ファサード → REST の3層分離

• ツールハンドラは ResolumeClient ファサードのメソッドだけ呼ぶ。生 fetch は触らない。
• ResolumeClient が Zod パース + 1-based インデックス検証を担当。
• ResolumeRestClient は HTTP 実装の詳細(タイムアウト, abort, content-type)を吸収。

2. エラーは LLM が自己修復可能な形に

• ResolumeApiError の detail は tagged union で kind を持つ。
• 各 kind は hint フィールドに次にすべきことを書く。
• mapHttpError(path, status, body) と mapNetworkError(path, err) で正規化。
• ツール側では throw → safeHandle が JSON で isError: true 付き結果に変換。