281 lines
21 KiB
Markdown
281 lines
21 KiB
Markdown
[English](TOOL_REFERENCE.md)
|
||
|
||
# uLoopMCP ツールリファレンス
|
||
|
||
このドキュメントでは、全uLoopMCPツールの詳細仕様を提供します。
|
||
|
||
## 共通レスポンス形式
|
||
|
||
すべてのUnity MCPツールは以下の共通要素を持ちます：
|
||
|
||
### 共通レスポンスプロパティ
|
||
すべてのツールには以下のプロパティが自動的に含まれます：
|
||
- `Ver` (string): CLIとの互換性チェック用のuLoopMCPサーバーバージョン
|
||
|
||
---
|
||
|
||
## Unity コアツール
|
||
|
||
### 1. compile
|
||
- **説明**: AssetDatabase.Refresh()を実行後、コンパイルを行います。詳細なタイミング情報付きでコンパイル結果を返します。
|
||
- **パラメータ**:
|
||
- `ForceRecompile` (boolean): 強制再コンパイルを実行するかどうか（デフォルト: false）
|
||
- `WaitForDomainReload` (boolean): Domain Reload完了まで待機するかどうか（デフォルト: false）
|
||
- **レスポンス**:
|
||
- `Success` (boolean | null): コンパイルが成功したかどうか。ForceRecompile=true時はDomain Reload完了まで結果が取得できないためnull
|
||
- `ErrorCount` (number | null): エラーの総数。ForceRecompile=true時はnull
|
||
- `WarningCount` (number | null): 警告の総数。ForceRecompile=true時はnull
|
||
- `Errors` (array | null): コンパイルエラーの配列。ForceRecompile=true時はnull
|
||
- `Message` (string): エラーメッセージ
|
||
- `File` (string): エラーが発生したファイルパス
|
||
- `Line` (number): エラーが発生した行番号
|
||
- `Warnings` (array | null): コンパイル警告の配列。ForceRecompile=true時はnull
|
||
- `Message` (string): 警告メッセージ
|
||
- `File` (string): 警告が発生したファイルパス
|
||
- `Line` (number): 警告が発生した行番号
|
||
- `Message` (string): 追加情報のためのオプションメッセージ
|
||
- `ProjectRoot` (string): Unityプロジェクトのルートパス。WaitForDomainReload=true時のみセットされる
|
||
|
||
### 2. get-logs
|
||
- **説明**: フィルタリングおよび高度な検索機能付きでUnityコンソールからログ情報を取得します
|
||
- **パラメータ**:
|
||
- `LogType` (enum): フィルタするログタイプ - "Error", "Warning", "Log", "All"（デフォルト: "All"）
|
||
- `MaxCount` (number): 取得するログの最大数（デフォルト: 100）
|
||
- `SearchText` (string): ログメッセージ内で検索するテキスト（空の場合はすべて取得）（デフォルト: ""）
|
||
- `UseRegex` (boolean): 検索に正規表現を使用するかどうか（デフォルト: false）
|
||
- `SearchInStackTrace` (boolean): スタックトレース内も検索対象に含めるかどうか（デフォルト: false）
|
||
- `IncludeStackTrace` (boolean): スタックトレースを表示するかどうか（デフォルト: false）
|
||
- **レスポンス**:
|
||
- `TotalCount` (number): 利用可能なログの総数
|
||
- `DisplayedCount` (number): このレスポンスで表示されるログの数
|
||
- `LogType` (string): 使用されたログタイプフィルタ
|
||
- `MaxCount` (number): 使用された最大数制限
|
||
- `SearchText` (string): 使用された検索テキストフィルタ
|
||
- `IncludeStackTrace` (boolean): スタックトレースが含まれているかどうか
|
||
- `Logs` (array): ログエントリの配列
|
||
- `Type` (string): ログタイプ（Error, Warning, Log）
|
||
- `Message` (string): ログメッセージ
|
||
- `StackTrace` (string): スタックトレース（IncludeStackTraceがtrueの場合）
|
||
|
||
### 3. run-tests
|
||
- **説明**: Unity Test Runnerを実行し、包括的なレポート付きでテスト結果を取得します
|
||
- **パラメータ**:
|
||
- `FilterType` (enum): テストフィルタのタイプ - "all"(0), "exact"(1), "regex"(2), "assembly"(3)（デフォルト: "all"）
|
||
- `FilterValue` (string): フィルタ値（FilterTypeがall以外の場合に指定）（デフォルト: ""）
|
||
- `exact`: 個別テストメソッド名（完全一致）（例：io.github.hatayama.uLoopMCP.ConsoleLogRetrieverTests.GetAllLogs_WithMaskAllOff_StillReturnsAllLogs）
|
||
- `regex`: クラス名または名前空間（正規表現パターン）（例：io.github.hatayama.uLoopMCP.ConsoleLogRetrieverTests, io.github.hatayama.uLoopMCP）
|
||
- `assembly`: アセンブリ名（例：uLoopMCP.Tests.Editor）
|
||
- `TestMode` (enum): テストモード - "EditMode"(0), "PlayMode"(1)（デフォルト: "EditMode"）
|
||
- **PlayMode注意**: PlayModeテスト実行時は、一時的にdomain reloadが無効化されます
|
||
- `SaveBeforeRun` (boolean): 未保存のロード済みScene変更と現在のPrefab Stage変更を保存してからテストを実行（デフォルト: false）
|
||
- **レスポンス**:
|
||
- `Success` (boolean): テスト実行が成功したかどうか
|
||
- `Message` (string): テスト実行メッセージ
|
||
- `CompletedAt` (string): テスト実行完了タイムスタンプ（ISO形式）
|
||
- `TestCount` (number): 実行されたテストの総数
|
||
- `PassedCount` (number): 合格したテストの数
|
||
- `FailedCount` (number): 失敗したテストの数
|
||
- `SkippedCount` (number): スキップされたテストの数
|
||
- `XmlPath` (string): NUnit XML結果ファイルのパス（テスト失敗時に自動保存）。XMLファイルは `{project_root}/.uloop/outputs/TestResults/` フォルダに保存されます
|
||
|
||
### 4. clear-console
|
||
- **説明**: クリーンな開発ワークフローのためにUnityコンソールログをクリアします
|
||
- **パラメータ**:
|
||
- `AddConfirmationMessage` (boolean): クリア後に確認ログメッセージを追加するかどうか（デフォルト: false）
|
||
- **レスポンス**:
|
||
- `Success` (boolean): コンソールクリア操作が成功したかどうか
|
||
- `ClearedLogCount` (number): コンソールからクリアされたログの数
|
||
- `ClearedCounts` (object): タイプ別のクリアされたログの内訳
|
||
- `ErrorCount` (number): クリアされたエラーログの数
|
||
- `WarningCount` (number): クリアされた警告ログの数
|
||
- `LogCount` (number): クリアされた情報ログの数
|
||
- `Message` (string): クリア操作結果を説明するメッセージ
|
||
- `ErrorMessage` (string): 操作が失敗した場合のエラーメッセージ
|
||
|
||
### 5. find-game-objects
|
||
- **説明**: 高度な検索条件（コンポーネントタイプ、タグ、レイヤーなど）で複数のGameObjectを検索します
|
||
- **パラメータ**:
|
||
- `NamePattern` (string): 検索するGameObject名のパターン（デフォルト: ""）
|
||
- `SearchMode` (enum): 検索モード - "Exact", "Path", "Regex", "Contains", "Selected"（デフォルト: "Exact"）
|
||
- `RequiredComponents` (array): GameObjectが持つ必要のあるコンポーネントタイプ名の配列（デフォルト: []）
|
||
- `Tag` (string): タグフィルター（デフォルト: ""）
|
||
- `Layer` (number): レイヤーフィルター（デフォルト: null）
|
||
- `IncludeInactive` (boolean): 非アクティブなGameObjectを含めるかどうか（デフォルト: false）
|
||
- `MaxResults` (number): 返す結果の最大数（デフォルト: 20）
|
||
- `IncludeInheritedProperties` (boolean): 継承プロパティを含めるかどうか（デフォルト: false）
|
||
- **レスポンス**:
|
||
- `results` (array): 見つかったGameObjectの配列
|
||
- `name` (string): GameObject名
|
||
- `path` (string): 完全な階層パス
|
||
- `isActive` (boolean): GameObjectがアクティブかどうか
|
||
- `tag` (string): GameObjectタグ
|
||
- `layer` (number): GameObjectレイヤー
|
||
- `components` (array): GameObject上のコンポーネントの配列
|
||
- `type` (string): コンポーネントタイプ名
|
||
- `fullTypeName` (string): 完全なアセンブリ修飾タイプ名
|
||
- `properties` (array): コンポーネントプロパティ（IncludeInheritedPropertiesがtrueの場合）
|
||
- `totalFound` (number): 見つかったGameObjectの総数
|
||
- `errorMessage` (string): 検索が失敗した場合のエラーメッセージ
|
||
- `resultsFilePath` (string): 結果がファイルにエクスポートされた場合のファイルパス
|
||
- `message` (string): 操作メッセージ
|
||
- `processingErrors` (array): シリアライズに失敗したオブジェクトの配列
|
||
- `gameObjectName` (string): 失敗したGameObjectの名前
|
||
- `gameObjectPath` (string): 失敗したGameObjectのパス
|
||
- `error` (string): エラーの説明
|
||
|
||
---
|
||
|
||
## Unity 検索・発見ツール
|
||
|
||
### 6. get-hierarchy
|
||
- **説明**: Unity階層構造をネストされたJSON形式で取得します
|
||
- **パラメータ**:
|
||
- `IncludeInactive` (boolean): 階層結果に非アクティブなGameObjectを含めるかどうか（デフォルト: true）
|
||
- `MaxDepth` (number): 階層を探索する最大深度（無制限深度の場合は-1）（デフォルト: -1）
|
||
- `RootPath` (string): 階層探索を開始するルートGameObjectパス（すべてのルートオブジェクトの場合は空/null）（デフォルト: null）
|
||
- `IncludeComponents` (boolean): 階層内の各GameObjectのコンポーネント情報を含めるかどうか（デフォルト: true）
|
||
- `IncludePaths` (boolean): ノードのパス情報を含めるかどうか（デフォルト: false）
|
||
- `UseComponentsLut` (string): コンポーネント用LUTの使用 - "auto", "true", "false"（デフォルト: "auto"）
|
||
- `UseSelection` (boolean): 現在選択中のGameObjectをルートとして使用するかどうか。trueの場合、RootPathは無視されます（デフォルト: false）
|
||
- **レスポンス**:
|
||
- `message` (string): クライアントがJSONファイルを参照するための案内メッセージ
|
||
- `hierarchyFilePath` (string): 階層データが保存されたファイルパス（例: "{project_root}/.uloop/outputs/HierarchyResults/hierarchy_2025-07-10_21-30-15.json"）。エクスポートされたJSONファイルには `hierarchy`（GameObjectのネスト配列）と `context`（シーン情報、ノード数、最大深度）が含まれる
|
||
|
||
### 7. execute-dynamic-code
|
||
- **説明**: Unity Editor内で動的C#コードを実行します。セキュリティレベルに応じてAPI利用を制限し、using文の自動処理やエラーメッセージの改善機能を提供します
|
||
- **パラメータ**:
|
||
- `Code` (string): 実行するC#コード（デフォルト: ""）
|
||
- `Parameters` (Dictionary<string, object>): 実行時パラメータ（デフォルト: {}）
|
||
- `CompileOnly` (boolean): コンパイルのみ実行（実行はしない）（デフォルト: false）
|
||
- **レスポンス**:
|
||
- `Success` (boolean): 実行が成功したかどうか
|
||
- `Result` (string): 実行結果
|
||
- `Logs` (array): ログメッセージの配列
|
||
- `CompilationErrors` (array): コンパイルエラーの配列（存在する場合）
|
||
- `Message` (string): エラーメッセージ
|
||
- `Line` (number): エラーが発生した行番号
|
||
- `Column` (number): エラーが発生した列番号
|
||
- `ErrorCode` (string): コンパイラーエラーコード（CS0103など）
|
||
- `Hint` (string): エラー解決のためのオプションヒント
|
||
- `Suggestions` (array of string): 修正候補（例: usingの追加や完全修飾名の使用）
|
||
- `Context` (string): エラー周辺のコード行とキャレットポインタ
|
||
- `PointerColumn` (number): キャレット描画用のポインタカラム（1-based）
|
||
- `ErrorMessage` (string): エラーメッセージ（失敗時）
|
||
- `SecurityLevel` (string): 現在のセキュリティレベル（"Disabled", "Restricted", "FullAccess"）
|
||
- `UpdatedCode` (string): 更新されたコード（修正適用後）
|
||
- `DiagnosticsSummary` (string): 診断情報のサマリー（ユニークエラー数、総数、最初のエラー概要）
|
||
- `Diagnostics` (array): リッチクライアント向けの構造化された診断情報（CompilationErrorsと同じ構造）
|
||
|
||
### 8. focus-window
|
||
- **説明**: macOSおよびWindowsでUnity Editorウィンドウを前面に表示します
|
||
- **パラメータ**: なし
|
||
- **レスポンス**:
|
||
- `Success` (boolean): 操作が成功したかどうか
|
||
- `Message` (string): 操作結果メッセージ
|
||
- `ErrorMessage` (string): 操作が失敗した場合のエラーメッセージ
|
||
|
||
### 9. screenshot
|
||
- **説明**: Unity EditorWindowのスクリーンショットを撮影してPNG画像として保存します。名前による柔軟なマッチングモードで任意のEditorWindowをキャプチャ可能です
|
||
- **パラメータ**:
|
||
- `WindowName` (string): キャプチャするウィンドウ名（例: "Game", "Scene", "Console", "Inspector", "Project", "Hierarchy"）（デフォルト: "Game"）
|
||
- `ResolutionScale` (number): キャプチャ画像の解像度スケール、0.1〜1.0（デフォルト: 1）
|
||
- `MatchMode` (enum): ウィンドウ名のマッチングモード（すべて大文字小文字を区別しない） - "exact", "prefix", "contains"（デフォルト: "exact"）
|
||
- `exact`: ウィンドウ名が完全に一致する必要があります
|
||
- `prefix`: ウィンドウ名が入力で始まる必要があります
|
||
- `contains`: ウィンドウ名に入力が含まれている必要があります
|
||
- `OutputDirectory` (string): スクリーンショット保存先のディレクトリパス。空の場合はデフォルトパス（.uloop/outputs/Screenshots/）を使用。絶対パスも指定可能（デフォルト: ""）
|
||
- **レスポンス**:
|
||
- `ScreenshotCount` (number): キャプチャされたウィンドウの数
|
||
- `Screenshots` (array): スクリーンショット情報の配列
|
||
- `ImagePath` (string): 保存されたPNGファイルの絶対パス
|
||
- `FileSizeBytes` (number): 保存されたファイルのサイズ（バイト）
|
||
- `Width` (number): キャプチャ画像の幅（ピクセル）
|
||
- `Height` (number): キャプチャ画像の高さ（ピクセル）
|
||
|
||
### 10. control-play-mode
|
||
- **説明**: Unity Editorのプレイモードを制御します（再生/停止/一時停止）
|
||
- **パラメータ**:
|
||
- `Action` (enum): 実行するアクション - "Play", "Stop", "Pause"（デフォルト: "Play"）
|
||
- `Play`: プレイモードを開始（一時停止からの再開も含む）
|
||
- `Stop`: プレイモードを終了し、エディットモードに戻る
|
||
- `Pause`: プレイモードのまま一時停止する
|
||
- **レスポンス**:
|
||
- `IsPlaying` (boolean): Unityが現在プレイモードかどうか
|
||
- `IsPaused` (boolean): プレイモードが一時停止中かどうか
|
||
- `Message` (string): 実行されたアクションの説明
|
||
|
||
### 11. simulate-mouse-ui
|
||
- **説明**: PlayMode中のUI要素に対してマウスクリック・長押し・ドラッグをシミュレーション。EventSystemとExecuteEventsを使ってポインタイベントを直接ディスパッチするため、旧・新Input Systemの両方に依存せず動作。Input Systemを読むゲームロジック（`Mouse.current.leftButton.wasPressedThisFrame`等）には `simulate-mouse-input` を使用
|
||
- **パラメータ**:
|
||
- `Action` (enum): マウスアクション - "Click", "Drag", "DragStart", "DragMove", "DragEnd", "LongPress"（デフォルト: "Click"）
|
||
- `Click`: (X, Y)でクリック。PointerDown → PointerUp → PointerClick を発火
|
||
- `LongPress`: (X, Y)でDuration秒間押し続けてからリリース。PointerClickは発火しない
|
||
- `Drag`: (FromX, FromY)から(X, Y)へのワンショットドラッグ
|
||
- `DragStart`: (X, Y)でドラッグを開始しホールド
|
||
- `DragMove`: 現在位置から(X, Y)へ指定速度でアニメーション移動
|
||
- `DragEnd`: (X, Y)へ移動後、ドラッグをリリース
|
||
- `X` (number): ターゲットX座標（スクリーンピクセル、原点: 左上）（デフォルト: 0）
|
||
- `Y` (number): ターゲットY座標（スクリーンピクセル、原点: 左上）（デフォルト: 0）
|
||
- `FromX` (number): Dragアクションの開始X座標（デフォルト: 0）
|
||
- `FromY` (number): Dragアクションの開始Y座標（デフォルト: 0）
|
||
- `DragSpeed` (number): ドラッグ速度（ピクセル/秒）、0で即時移動（デフォルト: 2000）
|
||
- `Duration` (number): LongPressアクションのホールド秒数（デフォルト: 0.5）
|
||
- `Button` (enum): マウスボタン - "Left", "Right", "Middle"（デフォルト: "Left"）
|
||
- **レスポンス**:
|
||
- `Success` (boolean): アクションが正常に完了したかどうか
|
||
- `Message` (string): 実行されたアクションの説明
|
||
- `Action` (string): 実行されたアクション
|
||
- `HitGameObjectName` (string): ヒットしたUI要素の名前（ヒットなしの場合null）
|
||
- `PositionX` (number): 使用されたX座標
|
||
- `PositionY` (number): 使用されたY座標
|
||
- `EndPositionX` (number): 終了X座標（Dragアクション用）
|
||
- `EndPositionY` (number): 終了Y座標（Dragアクション用）
|
||
|
||
### 12. simulate-mouse-input
|
||
- **説明**: Input System経由でPlayMode中のマウス入力をシミュレーション。ボタンクリック、マウスデルタ、スクロールホイールを `Mouse.current` に直接注入。`wasPressedThisFrame`や`Mouse.current.delta`等を読むゲームロジック向け。Input Systemパッケージ導入時のみ利用可能で、Player SettingsのActive Input Handlingを `Input System Package (New)` または `Both` に設定する必要がある。IPointerClickHandler等のUI要素には `simulate-mouse-ui` を使用
|
||
- **パラメータ**:
|
||
- `Action` (enum): マウス入力アクション - "Click", "LongPress", "MoveDelta", "SmoothDelta", "Scroll"（デフォルト: "Click"）
|
||
- `Click`: ボタンのpress+releaseを注入し、`wasPressedThisFrame`がtrueを返すようにする
|
||
- `LongPress`: Duration秒間ボタンをホールド
|
||
- `MoveDelta`: マウスデルタを注入（ワンショット、FPSカメラ操作等）
|
||
- `SmoothDelta`: Duration秒かけて滑らかにマウスデルタを注入（人間的なカメラ旋回）
|
||
- `Scroll`: スクロールホイールを注入（ホットバー切替、ズーム等）
|
||
- `X` (number): ターゲットX座標（スクリーンピクセル、原点: 左上）。ClickとLongPressで使用（デフォルト: 0）
|
||
- `Y` (number): ターゲットY座標（スクリーンピクセル、原点: 左上）。ClickとLongPressで使用（デフォルト: 0）
|
||
- `Button` (enum): マウスボタン - "Left", "Right", "Middle"（デフォルト: "Left"）。ClickとLongPressで使用
|
||
- `Duration` (number): LongPressのホールド秒数、またはClickの最小ホールド時間。0=ワンショットタップ（デフォルト: 0）
|
||
- `DeltaX` (number): MoveDeltaアクションのデルタX（ピクセル）。正=右（デフォルト: 0）
|
||
- `DeltaY` (number): MoveDeltaアクションのデルタY（ピクセル）。正=上（デフォルト: 0）
|
||
- `ScrollX` (number): Scrollアクションの水平スクロールデルタ（デフォルト: 0）
|
||
- `ScrollY` (number): Scrollアクションの垂直スクロールデルタ。正=上、通常1ノッチ=120（デフォルト: 0）
|
||
- **レスポンス**:
|
||
- `Success` (boolean): アクションが正常に完了したかどうか
|
||
- `Message` (string): 実行されたアクションの説明
|
||
- `Action` (string): 実行されたアクション
|
||
- `Button` (string): 使用されたボタン（Click/LongPress用）
|
||
- `PositionX` (number, nullable): 使用されたX座標（位置を使わないアクションではnull）
|
||
- `PositionY` (number, nullable): 使用されたY座標（位置を使わないアクションではnull）
|
||
|
||
### 13. simulate-keyboard
|
||
- **説明**: Input System経由でPlayMode中のキーボード入力をシミュレーション。単発のキータップ、長押し、複数キーの同時押しに対応。Input Systemパッケージ導入時のみ利用可能で、Player SettingsのActive Input Handlingを `Input System Package (New)` または `Both` に設定する必要がある。ゲームコードがInput System API（例: `Keyboard.current[Key.W].isPressed`）で入力を読み取っている必要があり、レガシーの `Input.GetKey()` には非対応
|
||
- **パラメータ**:
|
||
- `Action` (enum): キーボードアクション - "Press", "KeyDown", "KeyUp"（デフォルト: "Press"）
|
||
- `Press`: ワンショットキータップ（KeyDown→KeyUp）。`Duration`で長押し時間を指定可能
|
||
- `KeyDown`: KeyUpで明示的に解放するまでキーを押し続ける
|
||
- `KeyUp`: KeyDownで押下中のキーを解放
|
||
- `Key` (string): Input SystemのKey enumに対応するキー名（例: "W", "Space", "LeftShift", "Enter"）。大文字小文字を区別しない
|
||
- `Duration` (number): Pressアクションのホールド秒数、0でワンショットタップ（デフォルト: 0）。KeyDown/KeyUpでは無視される
|
||
- **レスポンス**:
|
||
- `Success` (boolean): アクションが正常に完了したかどうか
|
||
- `Message` (string): 実行されたアクションの説明
|
||
- `Action` (string): 実行されたアクション
|
||
- `KeyName` (string, nullable): 操作対象のキー名
|
||
|
||
---
|
||
|
||
## 関連ドキュメント
|
||
|
||
- [メインREADME](README_ja.md) - プロジェクト概要とセットアップ
|
||
- [アーキテクチャドキュメント](ARCHITECTURE_ja.md) - 技術アーキテクチャの詳細
|
||
- [変更履歴](CHANGELOG.md) - バージョン履歴と更新
|