# ResoniteLink MCP

ResoniteLink WebSocket プロトコルを使用して Resonite VR ワールドを操作するための MCP サーバ & CLI ツール。

## インストール

```bash
npm install
npm run build
```

## MCP サーバとして使用

### Claude Code 設定

プロジェクトルートの `.mcp.json` に設定済み。Claude Code を再起動すると自動的にMCPサーバーが利用可能になります。

### Claude Desktop 設定

`claude_desktop_config.json` に以下を追加:

```json
{
  "mcpServers": {
    "resonitelink": {
      "command": "node",
      "args": ["C:/Users/neo/GitHub/resolink_mcp/dist/mcp-server.js"],
      "env": {
        "RESONITE_WS_URL": "ws://localhost:29551"
      }
    }
  }
}
```

### 利用可能なツール

| ツール | 説明 |
|--------|------|
| `connect` | Resonite に接続 |
| `disconnect` | 接続を切断 |
| `get_slot` | スロット情報を取得 |
| `find_slot` | 名前でスロットを検索 |
| `add_slot` | スロットを追加 |
| `remove_slot` | スロットを削除 |
| `update_slot` | スロットを更新 |
| `add_component` | コンポーネントを追加 |
| `get_component` | コンポーネント情報を取得 |
| `update_component` | コンポーネントを更新 |
| `remove_component` | コンポーネントを削除 |
| `import_texture_file` | テクスチャをファイルからインポート |
| `search_components` | コンポーネントを検索 |
| `get_component_info` | コンポーネント詳細を取得 |
| `list_categories` | カテゴリ一覧 |
| `search_by_category` | カテゴリで検索 |
| `search_by_member` | メンバー名で検索 |
| `get_component_source` | ソースコードを取得 |
| `grep_source` | ソースを全文検索 |

## CLI として使用

### WebSocket URL の指定方法

CLI は WebSocket URL を以下の優先順位で決定します:

1. コマンドライン引数 `--url` (最優先)
2. 環境変数 `RESONITELINK_URL`
3. デフォルト値: `ws://localhost:29551`

**環境変数で設定する例:**

```bash
# Windows (PowerShell)
$env:RESONITELINK_URL = "ws://localhost:29469"

# Windows (コマンドプロンプト)
set RESONITELINK_URL=ws://localhost:29469

# Linux/Mac
export RESONITELINK_URL=ws://localhost:29469
```

環境変数を設定すれば、毎回 `--url` オプションを指定する必要がなくなります。

### 基本的なコマンド

```bash
# Rootスロット情報を取得
node dist/cli.js root --depth 1

# 特定のスロット情報を取得
node dist/cli.js get-slot --id <slotId> --depth 1

# コンポーネント情報も含めて取得
node dist/cli.js get-slot --id <slotId> --components

# 名前でスロットを検索
node dist/cli.js find --name MyObject

# スロットを追加
node dist/cli.js add-slot --name NewSlot --position 0,1,0

# 親スロットを指定してスロットを追加
node dist/cli.js add-slot --parent <parentId> --name MySlot --position 0,1,0 --scale 1,1,1

# コンポーネントを追加
node dist/cli.js add-component --slot <slotId> --type "[FrooxEngine]FrooxEngine.BoxMesh"

# スロットを更新
node dist/cli.js update-slot --id <slotId> --name NewName --position 0,2,0

# スロットを削除
node dist/cli.js remove-slot --id <slotId>

# コンポーネントを取得
node dist/cli.js get-component --id <componentId>

# コンポーネントを削除
node dist/cli.js remove-component --id <componentId>

# スロット階層をツリー表示
node dist/cli.js tree --depth 3

# WebSocket URLを指定（異なるポートの場合）
node dist/cli.js root --url ws://localhost:9422 --depth 2
```

## ライブラリとして使用

```typescript
import { ResoniteLinkClient } from './src/index.js';

const client = new ResoniteLinkClient({ url: 'ws://localhost:29551' });
await client.connect();

// スロットを追加
await client.addSlot({ name: 'MyObject', position: { x: 0, y: 1, z: 0 } });

// コンポーネントを追加
await client.addComponent({
  containerSlotId: slotId,
  componentType: '[FrooxEngine]FrooxEngine.BoxMesh'
});

client.disconnect();
```

### クライアントオプション

```typescript
const client = new ResoniteLinkClient({
  url: 'ws://localhost:29551',  // WebSocket URL（必須）
  debug: true,                   // コンソールにログ出力
  logFile: 'debug.log',          // ファイルにログ出力
  requestTimeout: 30000,         // リクエストタイムアウト（ミリ秒、デフォルト: 30000）
  autoReconnect: false,          // 自動再接続
  reconnectInterval: 5000,       // 再接続間隔（ミリ秒）
});
```

### デバッグログ

問題が発生した場合、デバッグログを有効にすると SEND/RECV メッセージを確認できます：

```typescript
const client = new ResoniteLinkClient({
  url: 'ws://localhost:29551',
  debug: true,           // コンソール出力
  logFile: 'debug.log',  // ファイル出力
});
```

ログ例:
```
[2026-01-08T06:10:24.504Z] SEND: { "$type": "addSlot", "messageId": "..." }
[2026-01-08T06:10:24.506Z] RECV: { "success": true, "messageId": "...", "error": null }
```

### リクエストタイムアウト

レスポンスが返らない場合（不正な形式のデータ送信時など）、タイムアウトでエラーが発生します：

```typescript
const client = new ResoniteLinkClient({
  url: 'ws://localhost:29551',
  requestTimeout: 10000,  // 10秒でタイムアウト
});
```

タイムアウト発生時は `Error: Request timeout after 10000ms: updateComponent (...)` のようなエラーがスローされます。

### テクスチャインポート

ResoniteLink のアセットインポートAPIを使用して、テクスチャをインポートできます。

#### ファイルからインポート

```typescript
// Resoniteホストのローカルファイルからテクスチャをインポート
const result = await client.importTexture2DFile({
  filePath: 'C:/path/to/texture.png'
});

if (result.success) {
  console.log('Asset URL:', result.assetURL);
  // assetURL を StaticTexture2D などに設定可能
}
```

#### 生データからインポート

```typescript
// RGBAピクセルデータからテクスチャをインポート
const width = 256;
const height = 256;
const rawData = Buffer.alloc(width * height * 4); // RGBA, 4 bytes per pixel

// ピクセルデータを生成（例: グラデーション）
for (let y = 0; y < height; y++) {
  for (let x = 0; x < width; x++) {
    const offset = (y * width + x) * 4;
    rawData[offset] = x;         // R
    rawData[offset + 1] = y;     // G
    rawData[offset + 2] = 128;   // B
    rawData[offset + 3] = 255;   // A
  }
}

const result = await client.importTexture2DRawData({
  width,
  height,
  colorProfile: 'sRGB',  // 'sRGB' または 'Linear'
  rawData
});

if (result.success) {
  console.log('Asset URL:', result.assetURL);
}
```

#### 注意事項

- `filePath` は Resonite が動作しているホストのローカルパス
- `assetURL` はセッション内でのみ有効（一時的なURL）
- サポートされる形式: PNG, JPG など一般的な画像形式
- 生データは RGBA フォーマット（1ピクセル4バイト）

## 重要: ワールドシステムオブジェクト

Resonite ワールドの Root 以下には、削除してはいけないシステムオブジェクトがあります。

### 削除禁止オブジェクト

| オブジェクト名 | 説明 |
|--------------|------|
| `Controllers` | コントローラー入力システム |
| `Roles` | ユーザーロール管理 |
| `SpawnArea` | ユーザーのスポーン位置 |
| `Light` | ワールドの照明 |
| `Skybox` | 空・背景 |
| `User <...>` | 接続中のユーザー（削除するとキックされる） |
| `__TEMP` | 一時オブジェクト管理 |
| `Undo Manager` | アンドゥ履歴 |
| `Assets` | 共有アセット |
| `Clipboard Importer` | クリップボードインポート機能 |

### 安全な削除方法

```typescript
const SYSTEM_OBJECTS = [
  'Controllers', 'Roles', 'SpawnArea', 'Light', 'Skybox',
  '__TEMP', 'Undo Manager', 'Assets', 'Clipboard Importer'
];

// システムオブジェクトとUserはスキップ
if (SYSTEM_OBJECTS.includes(name) || name.startsWith('User ')) {
  continue;
}
```

## コンポーネントタイプの書式

```
[FrooxEngine]FrooxEngine.ComponentName
```

### よく使うコンポーネント

| コンポーネント | 用途 |
|--------------|------|
| `BoxMesh` | 直方体メッシュ |
| `SphereMesh` | 球体メッシュ |
| `CylinderMesh` | 円柱メッシュ |
| `ConeMesh` | 円錐メッシュ |
| `BevelBoxMesh` | 角丸直方体 |
| `RampMesh` | スロープ |
| `FrameMesh` | フレーム |
| `TorusMesh` | トーラス |
| `CapsuleMesh` | カプセル |
| `MeshRenderer` | メッシュ描画 |
| `PBS_Metallic` | PBRマテリアル |
| `Light` | ライト |

### マテリアルの設定例

```typescript
await client.updateComponent({
  id: materialId,
  members: {
    AlbedoColor: { $type: 'colorX', value: { r: 1, g: 0, b: 0, a: 1, profile: 'sRGB' } },
    Smoothness: { $type: 'float', value: 0.5 },
    Metallic: { $type: 'float', value: 0.2 },
  }
});
```

### Enum型の設定（BlendMode, LightType など）

Enum 型のメンバーを更新する場合、以下の形式を使用する必要があります：

```typescript
{
  $type: 'enum',      // 小文字の 'enum'
  value: 'Alpha',     // 文字列で値を指定（数値ではない）
  enumType: 'BlendMode'  // Enum の型名
}
```

#### BlendMode の値

| 値 | 説明 |
|----|------|
| `Opaque` | 不透明（デフォルト） |
| `Cutout` | カットアウト（アルファテスト） |
| `Alpha` | 半透明（アルファブレンド） |

#### 半透明マテリアルの例

```typescript
await client.updateComponent({
  id: materialId,
  members: {
    BlendMode: { $type: 'enum', value: 'Alpha', enumType: 'BlendMode' },
    AlbedoColor: { $type: 'colorX', value: { r: 0.6, g: 0.75, b: 0.9, a: 0.3, profile: 'sRGB' } },
  }
});
```

#### LightType の値

| 値 | 説明 |
|----|------|
| `Directional` | ディレクショナルライト |
| `Point` | ポイントライト |
| `Spot` | スポットライト |

```typescript
await client.updateComponent({
  id: lightId,
  members: {
    LightType: { $type: 'enum', value: 'Point', enumType: 'LightType' },
    Intensity: { $type: 'float', value: 2.0 },
    Range: { $type: 'float', value: 10.0 },
  }
});
```

#### 注意事項

- `$type` は必ず小文字の `'enum'`（`'Enum'` ではない）
- `value` は数値ではなく文字列で指定
- `enumType` を省略すると動作しない場合がある
- 正しくない形式を送信するとレスポンスが返らずタイムアウトする

### メンバーの型一覧

| $type | 説明 | 例 |
|-------|------|-----|
| `float` | 浮動小数点 | `{ $type: 'float', value: 0.5 }` |
| `int` | 整数 | `{ $type: 'int', value: 10 }` |
| `bool` | 真偽値 | `{ $type: 'bool', value: true }` |
| `float2` | 2Dベクトル | `{ $type: 'float2', value: { x: 1, y: 1 } }` |
| `float3` | 3Dベクトル | `{ $type: 'float3', value: { x: 1, y: 2, z: 3 } }` |
| `floatQ` | クォータニオン | `{ $type: 'floatQ', value: { x: 0, y: 0, z: 0, w: 1 } }` |
| `colorX` | 色 | `{ $type: 'colorX', value: { r: 1, g: 0, b: 0, a: 1, profile: 'sRGB' } }` |
| `enum` | 列挙型 | `{ $type: 'enum', value: 'Alpha', enumType: 'BlendMode' }` |
| `reference` | 参照 | `{ $type: 'reference', targetId: 'Reso_XXXXX' }` |
| `list` | リスト | `{ $type: 'list', elements: [...] }` |
| `empty` | 出力メンバー | `{ $type: 'empty', id: 'Reso_XXXXX' }` |

### empty 型（ProtoFlux 出力メンバー）

ResoniteLink の更新により、ProtoFlux ノードの**出力メンバー**が `$type: "empty"` として返されるようになりました。

#### 背景

ProtoFlux ノードには入力（SyncRef）と出力（NodeValueOutput）があります：

- **入力**: 値を受け取る（reference型で返される）
- **出力**: 値を出力する（以前は返されなかった → **今は empty 型で返される**）

#### 例: GlobalTransform ノード

```json
{
  "componentType": "...GlobalTransform",
  "members": {
    "Instance": { "$type": "reference", "targetId": null, ... },
    "GlobalPosition": { "$type": "empty", "id": "Reso_82E" },
    "GlobalRotation": { "$type": "empty", "id": "Reso_82F" },
    "GlobalScale": { "$type": "empty", "id": "Reso_830" }
  }
}
```

#### 出力メンバーの参照方法

出力メンバーの `id` を使って、他のノードの入力に接続できます：

```typescript
// GlobalTransform の GlobalPosition 出力を取得
const globalTransformComp = slotData.data?.components?.find(c =>
  c.componentType?.includes('GlobalTransform')
);
const globalPositionId = globalTransformComp.members.GlobalPosition.id; // "Reso_82E"

// ValueSub の A 入力に GlobalPosition を接続
await client.updateComponent({
  id: subComp.id,
  members: {
    A: { $type: 'reference', targetId: globalPositionId },  // 出力IDを直接参照！
  }
});
```

#### 以前との違い

| 項目 | 以前 | 現在 |
|------|------|------|
| 出力メンバー | JSONに含まれない | `$type: "empty"` で返される |
| 複数出力ノードの参照 | コンポーネントID全体を参照 → エラー | 出力IDを個別に参照 → 成功 |

これにより、GlobalTransform のような複数出力を持つノードも正しく接続できるようになりました。

### Materials リストの更新（2段階）

MeshRenderer の Materials リストを更新するには2段階の操作が必要です。

#### なぜ2段階必要か

ResoniteLink の制限により、リスト要素への参照設定は以下の動作をします：

1. **1回目の更新**: リストに新しい要素が追加されるが、`targetId` は **null になる**
2. **2回目の更新**: 要素の `id` を指定することで、既存要素の `targetId` を設定できる

つまり、要素の追加と参照の設定は別々の操作として行う必要があります。

#### コード例

```typescript
// 1. まずリストに要素を追加（この時点では targetId は null になる）
await client.updateComponent({
  id: rendererId,
  members: {
    Materials: {
      $type: 'list',
      elements: [{ $type: 'reference', targetId: materialId }]
    }
  }
});

// 2. 追加された要素のIDを取得
const rendererData = await client.getComponent(rendererId);
const elementId = rendererData.data.members.Materials.elements[0].id;

// 3. 要素のIDを指定して、参照を設定
await client.updateComponent({
  id: rendererId,
  members: {
    Materials: {
      $type: 'list',
      elements: [{ $type: 'reference', id: elementId, targetId: materialId }]
    }
  }
});
```

#### 重要なポイント

- `id` フィールドを省略すると、新しい要素が追加される（既存要素は更新されない）
- `id` フィールドを指定すると、その ID を持つ既存要素が更新される
- 1回目で `targetId` を指定しても無視され、null になる

## ProtoFlux コンポーネントの追加

ProtoFlux ノード（ジェネリック型コンポーネント）を追加するには、特定の形式が必要です。

### 正しい形式

```
[ProtoFluxBindings]FrooxEngine.FrooxEngine.ProtoFlux.CoreNodes.<コンポーネント名><型>
```

#### ポイント

| 項目 | 正しい形式 | 間違った形式 |
|------|-----------|-------------|
| アセンブリ名 | `[ProtoFluxBindings]` | `[FrooxEngine]` |
| 名前空間 | `FrooxEngine.FrooxEngine.ProtoFlux.CoreNodes` | `FrooxEngine.ProtoFlux.CoreNodes` |
| ジェネリック型 | `<bool>`, `<int>`, `<float>` | `<System.Boolean>`, `` `1[System.Boolean] `` |

- **名前空間**: `FrooxEngine` が2回繰り返される
- **型指定**: C# エイリアス（`bool`, `int`, `float`）を使用する（`System.Boolean` ではない）
- **記法**: `<>` 形式を使用する（.NET のバッククォート記法 `` `1[...] `` ではない）

#### 複合型パラメータ（Slot, User など）

スロットやユーザーなどの複合型を型パラメータに使う場合は、**アセンブリ名付きの完全修飾名**を使用する：

```
[ProtoFluxBindings]...RefObjectInput<[FrooxEngine]FrooxEngine.Slot>
```

| 型 | 正しい形式 | 間違った形式 |
|----|-----------|-------------|
| Slot | `<[FrooxEngine]FrooxEngine.Slot>` | `<Slot>`, `<FrooxEngine.Slot>` |
| User | `<[FrooxEngine]FrooxEngine.User>` | `<User>` |
| IButton | `<[FrooxEngine]FrooxEngine.IButton>` | `<IButton>` |

**重要**: プリミティブ型（`int`, `float`, `bool` など）はエイリアスをそのまま使い、複合型（`Slot`, `User` など）は `[FrooxEngine]FrooxEngine.TypeName` 形式を使う。

### 動作確認済みコンポーネント

| ノード | componentType |
|--------|---------------|
| ValueInput\<int\> | `[ProtoFluxBindings]FrooxEngine.ProtoFlux.Runtimes.Execution.Nodes.ValueInput<int>` |
| ValueAdd\<int\> | `[ProtoFluxBindings]FrooxEngine.ProtoFlux.Runtimes.Execution.Nodes.Operators.ValueAdd<int>` |
| ValueDisplay\<int\> | `[ProtoFluxBindings]FrooxEngine.ProtoFlux.Runtimes.Execution.Nodes.ValueDisplay<int>` |
| WorldTimeFloat | `[ProtoFluxBindings]FrooxEngine.ProtoFlux.Runtimes.Execution.Nodes.FrooxEngine.Time.WorldTimeFloat` |
| AxisAngle_floatQ | `[ProtoFluxBindings]FrooxEngine.ProtoFlux.Runtimes.Execution.Nodes.Math.Quaternions.AxisAngle_floatQ` |
| HSV_ToColorX | `[ProtoFluxBindings]FrooxEngine.ProtoFlux.Runtimes.Execution.Nodes.Color.HSV_ToColorX` |
| ValueFieldDrive\<floatQ\> | `[ProtoFluxBindings]FrooxEngine.FrooxEngine.ProtoFlux.CoreNodes.ValueFieldDrive<floatQ>` |
| ValueFieldDrive\<colorX\> | `[ProtoFluxBindings]FrooxEngine.FrooxEngine.ProtoFlux.CoreNodes.ValueFieldDrive<colorX>` |
| ValueFieldDrive\<bool\> | `[ProtoFluxBindings]FrooxEngine.FrooxEngine.ProtoFlux.CoreNodes.ValueFieldDrive<bool>` |

### コード例

```typescript
// ValueFieldDrive<floatQ> を追加（回転ドライブ用）
await client.addComponent({
  containerSlotId: slotId,
  componentType: '[ProtoFluxBindings]FrooxEngine.FrooxEngine.ProtoFlux.CoreNodes.ValueFieldDrive<floatQ>'
});

// WorldTimeFloat を追加（時間取得用）
await client.addComponent({
  containerSlotId: slotId,
  componentType: '[ProtoFluxBindings]FrooxEngine.ProtoFlux.Runtimes.Execution.Nodes.FrooxEngine.Time.WorldTimeFloat'
});

// HSV_ToColorX を追加（色変換用）
await client.addComponent({
  containerSlotId: slotId,
  componentType: '[ProtoFluxBindings]FrooxEngine.ProtoFlux.Runtimes.Execution.Nodes.Color.HSV_ToColorX'
});
```

### ProtoFlux ノード間の接続

```typescript
// ValueAdd の A, B 入力に ValueInput ノードを接続
await client.updateComponent({
  id: addCompId,
  members: {
    A: { $type: 'reference', targetId: input1CompId },
    B: { $type: 'reference', targetId: input2CompId },
  }
});

// ValueDisplay の Input に ValueAdd の出力を接続
await client.updateComponent({
  id: displayCompId,
  members: {
    Input: { $type: 'reference', targetId: addCompId },
  }
});
```

### よく使う ProtoFlux ノード

| コンポーネント | 用途 |
|--------------|------|
| `ValueFieldDrive<T>` | フィールドをドライブ |
| `ReferenceFieldDrive<T>` | 参照フィールドをドライブ |
| `GlobalValue<T>` | グローバル値 |
| `GlobalReference<T>` | グローバル参照 |

### ProtoFlux ノードの配置

ProtoFlux ノードを追加する際は、各ノードを別々のスロットに配置し、適切な位置に並べることで視認性が向上します。

#### 座標系

Resonite の座標系:
- **X軸**: 左右（右が正）
- **Y軸**: 上下（上が正）
- **Z軸**: 前後（手前が正）

ProtoFlux ノードは**左から右（X軸方向）**に配置するのが一般的です。

#### 配置の基本パターン

```
左 ────────────────────────────────────────────→ 右 (X軸)

[入力ノード群]  →  [処理ノード]  →  [出力ノード]  →  [ドライブノード]
   x=-1.5            x=-1.0           x=-0.5            x=0
```

#### 複数入力がある場合

Y軸で上下にずらして配置:

```typescript
// 入力1（上側）
await client.addSlot({ name: 'Input1', position: { x: -1.5, y: 0.15, z: 0 } });

// 入力2（下側）
await client.addSlot({ name: 'Input2', position: { x: -1.5, y: -0.15, z: 0 } });

// 処理ノード（中央）
await client.addSlot({ name: 'Process', position: { x: -1.0, y: 0, z: 0 } });
```

#### 実践例: 回転するボックス

```typescript
// 親スロット
const fluxSlot = await client.addSlot({ name: 'Flux', position: { x: 0, y: 2, z: 0 } });

// 各ノードを左から右に配置
const nodes = [
  { name: 'AxisInput',      x: -0.6, y: 0.15 },  // 回転軸入力
  { name: 'TimeNode',       x: -0.6, y: -0.15 }, // 時間取得
  { name: 'AxisAngleNode',  x: -0.3, y: 0 },     // 軸角度→クォータニオン変換
  { name: 'DriveNode',      x: 0,    y: 0 },     // 回転ドライブ
];

for (const node of nodes) {
  await client.addSlot({
    name: node.name,
    parentId: fluxSlot.data.id,
    position: { x: node.x, y: node.y, z: 0 }
  });
}
```

#### 配置のコツ

| 項目 | 推奨値 |
|------|--------|
| ノード間の水平間隔 | 0.3〜0.5 |
| 分岐時の垂直間隔 | 0.15〜0.3 |
| 親スロットからの相対座標 | 使用する |

- 親スロット（例: `Flux`）を作成し、その下に各ノードを配置
- 位置は親スロットからの相対座標になる
- データフローが左から右に流れるように配置
- 分岐がある場合は Y軸で上下にずらす

### 制限事項

一部の ProtoFlux ノードは追加できない場合があります：
- 複雑なジェネリック制約を持つノード
- 特殊な初期化が必要なノード

回避策：
- Resonite 内で手動で ProtoFlux を作成
- 既存の ProtoFlux をテンプレートとして複製
- PackedObject として保存したものをインポート

## デコンパイル検索 (CLI)

```bash
# コンポーネント名で検索
node dist/cli.js search --query Mesh

# コンポーネント詳細を表示
node dist/cli.js info --name PBS_Metallic

# カテゴリ一覧
node dist/cli.js categories

# カテゴリで検索
node dist/cli.js category --query "Materials"

# メンバー名で検索
node dist/cli.js member --query Smoothness

# ソースコード全文検索
node dist/cli.js grep --query "SyncPlayback"

# ソースコード表示
node dist/cli.js source --name BoxMesh
```

## サンプルスクリプト

```bash
# ProtoFlux 1+1 を作成（ValueInput → ValueAdd → ValueDisplay）
node dist/scripts/create-flux-add.js ws://localhost:58971

# 東京タワー（詳細版）を作成
node dist/scripts/create-tokyo-tower-detailed.js ws://localhost:58971

# 東京スカイツリーを作成
node dist/scripts/create-skytree.js ws://localhost:58971

# 東京タワーを削除
node dist/scripts/delete-tokyo-tower.js ws://localhost:58971

# モダンハウス（内装付き）を作成
node dist/scripts/create-house3.js

# 街を作成
node dist/scripts/create-town.js

# 雲を作成
node dist/scripts/create-clouds.js

# すべて削除して床だけにする
node dist/scripts/reset-to-floor.js
```

## License

MIT