ft/Client/Packages/io.github.hatayama.uloopmcp/TOOL_REFERENCE.md

[日本語](TOOL_REFERENCE_ja.md)

# uLoopMCP Tool Reference

This document provides detailed specifications for all uLoopMCP tools.

## Common Response Format

All Unity MCP tools share the following common elements:

### Common Response Properties
All tools automatically include the following property:
- `Ver` (string): uLoopMCP server version for CLI compatibility check

---

## Unity Core Tools

### 1. compile
- **Description**: Executes compilation after AssetDatabase.Refresh(). Returns compilation results with detailed timing information.
- **Parameters**:
  - `ForceRecompile` (boolean): Whether to perform forced recompilation (default: false)
  - `WaitForDomainReload` (boolean): Whether to wait for domain reload completion before returning (default: false)
- **Response**:
  - `Success` (boolean | null): Whether compilation was successful. Null when ForceRecompile=true because results are unavailable until domain reload completes
  - `ErrorCount` (number | null): Total number of errors. Null when ForceRecompile=true
  - `WarningCount` (number | null): Total number of warnings. Null when ForceRecompile=true
  - `Errors` (array | null): Array of compilation errors. Null when ForceRecompile=true
    - `Message` (string): Error message
    - `File` (string): File path where error occurred
    - `Line` (number): Line number where error occurred
  - `Warnings` (array | null): Array of compilation warnings. Null when ForceRecompile=true
    - `Message` (string): Warning message
    - `File` (string): File path where warning occurred
    - `Line` (number): Line number where warning occurred
  - `Message` (string): Optional message for additional information
  - `ProjectRoot` (string): Unity project root path. Set only when WaitForDomainReload=true

### 2. get-logs
- **Description**: Retrieves log information from Unity console with filtering and advanced search capabilities
- **Parameters**:
  - `LogType` (enum): Log type to filter - "Error", "Warning", "Log", "All" (default: "All")
  - `MaxCount` (number): Maximum number of logs to retrieve (default: 100)
  - `SearchText` (string): Text to search within log messages (retrieve all if empty) (default: "")
  - `UseRegex` (boolean): Whether to use regular expression for search (default: false)
  - `SearchInStackTrace` (boolean): Whether to search within stack trace as well (default: false)
  - `IncludeStackTrace` (boolean): Whether to display stack traces (default: false)
- **Response**:
  - `TotalCount` (number): Total number of logs available
  - `DisplayedCount` (number): Number of logs displayed in this response
  - `LogType` (string): Log type filter used
  - `MaxCount` (number): Maximum count limit used
  - `SearchText` (string): Search text filter used
  - `IncludeStackTrace` (boolean): Whether stack trace was included
  - `Logs` (array): Array of log entries
    - `Type` (string): Log type (Error, Warning, Log)
    - `Message` (string): Log message
    - `StackTrace` (string): Stack trace (if IncludeStackTrace is true)

### 3. run-tests
- **Description**: Executes Unity Test Runner and retrieves test results with comprehensive reporting
- **Parameters**:
  - `FilterType` (enum): Type of test filter - "all"(0), "exact"(1), "regex"(2), "assembly"(3) (default: "all")
  - `FilterValue` (string): Filter value (specify when FilterType is other than all) (default: "")
    - `exact`: Individual test method name (exact match) (e.g.: io.github.hatayama.uLoopMCP.ConsoleLogRetrieverTests.GetAllLogs_WithMaskAllOff_StillReturnsAllLogs)
    - `regex`: Class name or namespace (regex pattern) (e.g.: io.github.hatayama.uLoopMCP.ConsoleLogRetrieverTests, io.github.hatayama.uLoopMCP)
    - `assembly`: Assembly name (e.g.: uLoopMCP.Tests.Editor)
  - `TestMode` (enum): Test mode - "EditMode"(0), "PlayMode"(1) (default: "EditMode")
    - **PlayMode Warning**: During PlayMode test execution, domain reload is temporarily disabled
  - `SaveBeforeRun` (boolean): Save unsaved loaded Scene changes and current Prefab Stage changes before running tests (default: false)
- **Response**:
  - `Success` (boolean): Whether test execution was successful
  - `Message` (string): Test execution message
  - `CompletedAt` (string): Test execution completion timestamp (ISO format)
  - `TestCount` (number): Total number of tests executed
  - `PassedCount` (number): Number of passed tests
  - `FailedCount` (number): Number of failed tests
  - `SkippedCount` (number): Number of skipped tests
  - `XmlPath` (string): NUnit XML result file path (auto-saved when tests fail). XML files are saved to `{project root}/.uloop/outputs/TestResults/` folder

### 4. clear-console
- **Description**: Clears Unity console logs for clean development workflow
- **Parameters**:
  - `AddConfirmationMessage` (boolean): Whether to add a confirmation log message after clearing (default: false)
- **Response**:
  - `Success` (boolean): Whether the console clear operation was successful
  - `ClearedLogCount` (number): Number of logs that were cleared from the console
  - `ClearedCounts` (object): Breakdown of cleared logs by type
    - `ErrorCount` (number): Number of error logs that were cleared
    - `WarningCount` (number): Number of warning logs that were cleared
    - `LogCount` (number): Number of info logs that were cleared
  - `Message` (string): Message describing the clear operation result
  - `ErrorMessage` (string): Error message if the operation failed

### 5. find-game-objects
- **Description**: Find multiple GameObjects with advanced search criteria (component type, tag, layer, etc.)
- **Parameters**:
  - `NamePattern` (string): GameObject name pattern to search for (default: "")
  - `SearchMode` (enum): Search mode - "Exact", "Path", "Regex", "Contains", "Selected" (default: "Exact")
  - `RequiredComponents` (array): Array of component type names that GameObjects must have (default: [])
  - `Tag` (string): Tag filter (default: "")
  - `Layer` (number): Layer filter (default: null)
  - `IncludeInactive` (boolean): Whether to include inactive GameObjects (default: false)
  - `MaxResults` (number): Maximum number of results to return (default: 20)
  - `IncludeInheritedProperties` (boolean): Whether to include inherited properties (default: false)
- **Response**:
  - `results` (array): Array of found GameObjects
    - `name` (string): GameObject name
    - `path` (string): Full hierarchy path
    - `isActive` (boolean): Whether the GameObject is active
    - `tag` (string): GameObject tag
    - `layer` (number): GameObject layer
    - `components` (array): Array of components on the GameObject
      - `type` (string): Component type name
      - `fullTypeName` (string): Full assembly qualified type name
      - `properties` (array): Component properties (if IncludeInheritedProperties is true)
  - `totalFound` (number): Total number of GameObjects found
  - `errorMessage` (string): Error message if search failed
  - `resultsFilePath` (string): File path where results were saved (when results are exported to file)
  - `message` (string): Operation message
  - `processingErrors` (array): Array of objects that failed to serialize
    - `gameObjectName` (string): Name of the GameObject that failed
    - `gameObjectPath` (string): Path of the GameObject that failed
    - `error` (string): Error description

---

## Unity Search & Discovery Tools

### 6. get-hierarchy
- **Description**: Get Unity Hierarchy structure in nested JSON format for AI-friendly processing
- **Parameters**:
  - `IncludeInactive` (boolean): Whether to include inactive GameObjects in the hierarchy result (default: true)
  - `MaxDepth` (number): Maximum depth to traverse the hierarchy (-1 for unlimited depth) (default: -1)
  - `RootPath` (string): Root GameObject path to start hierarchy traversal from (empty/null for all root objects) (default: null)
  - `IncludeComponents` (boolean): Whether to include component information for each GameObject in the hierarchy (default: true)
  - `IncludePaths` (boolean): Whether to include path information for nodes (default: false)
  - `UseComponentsLut` (string): Use LUT for components - "auto", "true", "false" (default: "auto")
  - `UseSelection` (boolean): Whether to use currently selected GameObject(s) as root(s). When true, RootPath is ignored (default: false)
- **Response**:
  - `message` (string): Human-readable guidance for clients to locate and read the JSON file
  - `hierarchyFilePath` (string): File path where hierarchy data was saved (e.g., "{project_root}/.uloop/outputs/HierarchyResults/hierarchy_2025-07-10_21-30-15.json"). The exported JSON file contains `hierarchy` (nested array of GameObjects) and `context` (scene info, node count, max depth)

### 7. execute-dynamic-code
- **Description**: Execute C# code dynamically within Unity Editor. Implements security levels and automatic using statement processing with enhanced error messaging
- **Parameters**:
  - `Code` (string): The C# code to execute (default: "")
  - `Parameters` (Dictionary<string, object>): Runtime parameters for execution (default: {})
  - `CompileOnly` (boolean): Only compile, do not execute (default: false)
- **Response**:
  - `Success` (boolean): Whether execution was successful
  - `Result` (string): Execution result
  - `Logs` (array): Array of log messages
  - `CompilationErrors` (array): Array of compilation errors (if any)
    - `Message` (string): Error message
    - `Line` (number): Line number where error occurred
    - `Column` (number): Column number where error occurred
    - `ErrorCode` (string): Compiler error code (e.g., CS0103)
    - `Hint` (string): Optional hint for resolving the error
    - `Suggestions` (array of string): Suggested fixes (e.g., add using or qualify)
    - `Context` (string): Context lines around the error with a caret pointer
    - `PointerColumn` (number): Pointer column for caret rendering (1-based)
  - `ErrorMessage` (string): Error message (if failed)
  - `SecurityLevel` (string): Current security level ("Disabled", "Restricted", "FullAccess")
  - `UpdatedCode` (string): Updated code (after applying fixes)
  - `DiagnosticsSummary` (string): Summary of diagnostics (unique count, total count, first error brief)
  - `Diagnostics` (array): Structured diagnostics for rich clients (same structure as CompilationErrors)

### 8. focus-window
- **Description**: Brings Unity Editor window to front on macOS and Windows
- **Parameters**: None
- **Response**:
  - `Success` (boolean): Whether the operation was successful
  - `Message` (string): Operation result message
  - `ErrorMessage` (string): Error message if operation failed

### 9. screenshot
- **Description**: Take a screenshot of Unity EditorWindow and save as PNG. Supports capturing any open EditorWindow by name with flexible matching modes
- **Parameters**:
  - `WindowName` (string): Window name to capture (e.g., "Game", "Scene", "Console", "Inspector", "Project", "Hierarchy") (default: "Game")
  - `ResolutionScale` (number): Resolution scale for the captured image, 0.1 to 1.0 (default: 1)
  - `MatchMode` (enum): Window name matching mode (all case-insensitive) - "exact", "prefix", "contains" (default: "exact")
    - `exact`: Window name must match exactly
    - `prefix`: Window name must start with the input
    - `contains`: Window name must contain the input anywhere
  - `OutputDirectory` (string): Output directory path for saving screenshots. When empty, uses default path (.uloop/outputs/Screenshots/). Accepts absolute paths (default: "")
- **Response**:
  - `ScreenshotCount` (number): Number of windows captured
  - `Screenshots` (array): Array of screenshot info
    - `ImagePath` (string): Absolute path to the saved PNG file
    - `FileSizeBytes` (number): Size of the saved file in bytes
    - `Width` (number): Captured image width in pixels
    - `Height` (number): Captured image height in pixels

### 10. control-play-mode
- **Description**: Control Unity Editor play mode (play/stop/pause)
- **Parameters**:
  - `Action` (enum): Action to perform - "Play", "Stop", "Pause" (default: "Play")
    - `Play`: Start play mode (also resumes from pause)
    - `Stop`: Exit play mode and return to edit mode
    - `Pause`: Pause the game while remaining in play mode
- **Response**:
  - `IsPlaying` (boolean): Whether Unity is currently in play mode
  - `IsPaused` (boolean): Whether play mode is paused
  - `Message` (string): Description of the action performed

---

### 11. simulate-mouse-ui
- **Description**: Simulate mouse click, long-press, and drag on PlayMode UI elements via EventSystem screen coordinates. Uses EventSystem and ExecuteEvents to dispatch pointer events directly — works independently of both old and new Input System. For game logic that reads Input System (e.g. `Mouse.current.leftButton.wasPressedThisFrame`), use `simulate-mouse-input` instead
- **Parameters**:
  - `Action` (enum): Mouse action - "Click", "Drag", "DragStart", "DragMove", "DragEnd", "LongPress" (default: "Click")
    - `Click`: Click at (X, Y). Fires PointerDown → PointerUp → PointerClick
    - `LongPress`: Press and hold at (X, Y) for Duration seconds, then release. No PointerClick fired
    - `Drag`: One-shot drag from (FromX, FromY) to (X, Y). Fires BeginDrag → Drag×N → EndDrag
    - `DragStart`: Begin drag at (X, Y) and hold
    - `DragMove`: Animate from current position to (X, Y) at the specified speed
    - `DragEnd`: Animate to (X, Y), then release drag
  - `X` (number): Target X position in screen pixels, origin: top-left (default: 0)
  - `Y` (number): Target Y position in screen pixels, origin: top-left (default: 0)
  - `FromX` (number): Start X position for Drag action (default: 0)
  - `FromY` (number): Start Y position for Drag action (default: 0)
  - `DragSpeed` (number): Drag speed in pixels per second, 0 for instant (default: 2000)
  - `Duration` (number): Hold duration in seconds for LongPress action (default: 0.5)
  - `Button` (enum): Mouse button - "Left", "Right", "Middle" (default: "Left")
- **Response**:
  - `Success` (boolean): Whether the action completed successfully
  - `Message` (string): Description of the action performed
  - `Action` (string): The action that was executed
  - `HitGameObjectName` (string): Name of the UI element hit (null if none)
  - `PositionX` (number): X position used
  - `PositionY` (number): Y position used
  - `EndPositionX` (number): End X position (for Drag actions)
  - `EndPositionY` (number): End Y position (for Drag actions)

### 12. simulate-mouse-input
- **Description**: Simulate mouse input in PlayMode via Input System. Injects button clicks, mouse delta, and scroll wheel directly into `Mouse.current` for game logic that reads Input System (e.g. `wasPressedThisFrame`, `Mouse.current.delta`). Requires the Input System package and Active Input Handling set to `Input System Package (New)` or `Both` in Player Settings. For UI elements with IPointerClickHandler, use `simulate-mouse-ui` instead
- **Parameters**:
  - `Action` (enum): Mouse input action - "Click", "LongPress", "MoveDelta", "SmoothDelta", "Scroll" (default: "Click")
    - `Click`: Inject button press and release so `wasPressedThisFrame` returns true
    - `LongPress`: Inject button hold for Duration seconds
    - `MoveDelta`: Inject mouse delta one-shot (for FPS camera/look control)
    - `SmoothDelta`: Inject mouse delta smoothly over Duration seconds (human-like camera pan)
    - `Scroll`: Inject scroll wheel (for hotbar switching, zoom, etc.)
  - `X` (number): Target X position in screen pixels, origin: top-left. Used by Click and LongPress (default: 0)
  - `Y` (number): Target Y position in screen pixels, origin: top-left. Used by Click and LongPress (default: 0)
  - `Button` (enum): Mouse button - "Left", "Right", "Middle" (default: "Left"). Used by Click and LongPress
  - `Duration` (number): Hold duration for LongPress, or minimum hold time for Click. 0 = one-shot tap (default: 0)
  - `DeltaX` (number): Delta X in pixels for MoveDelta. Positive = right (default: 0)
  - `DeltaY` (number): Delta Y in pixels for MoveDelta. Positive = up (default: 0)
  - `ScrollX` (number): Horizontal scroll delta for Scroll action (default: 0)
  - `ScrollY` (number): Vertical scroll delta for Scroll action. Positive = up, typically 120 per notch (default: 0)
- **Response**:
  - `Success` (boolean): Whether the action completed successfully
  - `Message` (string): Description of the action performed
  - `Action` (string): The action that was executed
  - `Button` (string): The button used (for Click/LongPress)
  - `PositionX` (number, nullable): X position used (null for non-positional actions)
  - `PositionY` (number, nullable): Y position used (null for non-positional actions)

### 13. simulate-keyboard
- **Description**: Simulate keyboard key input in PlayMode via Input System. Supports single key taps, sustained holds, and multi-key combinations. Requires the Input System package, and Active Input Handling must be set to `Input System Package (New)` or `Both` in Player Settings. Game code must read input via Input System API (e.g. `Keyboard.current[Key.W].isPressed`), not legacy `Input.GetKey()`
- **Parameters**:
  - `Action` (enum): Keyboard action - "Press", "KeyDown", "KeyUp" (default: "Press")
    - `Press`: One-shot key tap (KeyDown then KeyUp). Use `Duration` for timed holds
    - `KeyDown`: Hold key down until explicitly released with KeyUp
    - `KeyUp`: Release a key currently held by KeyDown
  - `Key` (string): Key name matching the Input System Key enum (e.g. "W", "Space", "LeftShift", "Enter"). Case-insensitive
  - `Duration` (number): Hold duration in seconds for Press action, 0 for one-shot tap (default: 0). Ignored by KeyDown/KeyUp
- **Response**:
  - `Success` (boolean): Whether the action completed successfully
  - `Message` (string): Description of the action performed
  - `Action` (string): The action that was executed
  - `KeyName` (string, nullable): Name of the key that was acted upon

---

## Related Documentation

- [Main README](README.md) - Project overview and setup
- [Architecture Documentation](ARCHITECTURE.md) - Technical architecture details
- [Changelog](CHANGELOG.md) - Version history and updates