diff --git a/Documentation/MCP.md b/Documentation/MCP/MCP.md similarity index 100% rename from Documentation/MCP.md rename to Documentation/MCP/MCP.md diff --git a/Documentation/MCP/MCP_LLM_Guide.md b/Documentation/MCP/MCP_LLM_Guide.md new file mode 100644 index 0000000..c7d2acc --- /dev/null +++ b/Documentation/MCP/MCP_LLM_Guide.md @@ -0,0 +1,126 @@ +# CtrEditor MCP Server - LLM Guide + +## โšก Command Efficiency Tiers + +### ๐Ÿš€ **Ultra-Fast** (Use Liberally) +- `get_simulation_status` โ†’ ~25 tokens, instant +- `get_ctreditor_status` โ†’ ~20 tokens, instant +- `start/stop_simulation` โ†’ ~15 tokens, 2-3 sec + +### ๐ŸŸก **Medium** (Use When Needed) +- `search_debug_log` โ†’ 50-200 tokens (max_lines=3-10) +- `build_project` โ†’ 100-500 tokens (errors only) + +### ๐Ÿ”ด **Heavy** (Use Sparingly) +- `list_objects` โ†’ 500-2000+ tokens +- `take_screenshot` โ†’ 100-300 tokens + file + +## ๐Ÿ”ง Core Operations + +### Process Management +```json +{"tool": "start_ctreditor", "parameters": {}} +{"tool": "get_ctreditor_status", "parameters": {}} +{"tool": "stop_ctreditor", "parameters": {}} +``` + +### Build & Debug +```json +{"tool": "build_project", "parameters": {}} +{"tool": "start_debug_listener", "parameters": {}} +{"tool": "search_debug_log", "parameters": {"pattern": "error|exception", "max_lines": 5}} +{"tool": "stop_debug_listener", "parameters": {}} +``` + +### Simulation Control +```json +{"tool": "get_simulation_status", "parameters": {}} +{"tool": "start_simulation", "parameters": {}} +{"tool": "stop_simulation", "parameters": {}} +``` + +### Object Management +```json +{"tool": "list_objects", "parameters": {}} +{"tool": "create_object", "parameters": {"type": "osHydPump", "x": 10, "y": 5}} +{"tool": "update_object", "parameters": {"id": "123", "properties": {"PumpHead": 75.0}}} +{"tool": "delete_objects", "parameters": {"ids": ["123", "456"]}} +``` + +## โšก Optimal Workflows + +### Quick Development Cycle +```json +{"tool": "get_ctreditor_status", "parameters": {}} +{"tool": "build_project", "parameters": {}} +{"tool": "start_simulation", "parameters": {}} +{"tool": "get_simulation_status", "parameters": {}} +``` + +### Bug Investigation +```json +{"tool": "search_debug_log", "parameters": {"pattern": "error|exception", "max_lines": 3}} +{"tool": "get_simulation_status", "parameters": {}} +``` + +### System Recovery +```json +{"tool": "stop_ctreditor", "parameters": {}} +{"tool": "start_ctreditor", "parameters": {}} +``` + +## ๐Ÿ“Š Key Object Properties + +### Hydraulic Components +- **osHydTank**: `TankPressure`, `MaxLevel`, `MinLevel`, `IsFixedPressure` +- **osHydPump**: `PumpHead`, `MaxFlow`, `SpeedRatio`, `IsRunning` +- **osHydPipe**: `Length`, `Diameter`, `CurrentFlow`, `PressureDrop` + +### Common Properties +- **Position**: `Left`, `Top` (meters) +- **Dimensions**: `Ancho`, `Alto` (meters) +- **Connections**: `Id_ComponenteA`, `Id_ComponenteB` + +## ๐Ÿ–ผ๏ธ Screenshots + +### Full Canvas +```json +{"tool": "take_screenshot", "parameters": {}} +``` + +### Targeted Area +```json +{"tool": "take_screenshot", "parameters": { + "x": 39.0, "y": 19.0, "width": 7.0, "height": 3.0 +}} +``` + +## ๐Ÿ” Debug Search Patterns + +High-value, low-token patterns: +- **Critical Errors**: `"error|exception|fail"` (max_lines=3) +- **Performance**: `"fps|slow|memory"` (max_lines=5) +- **Simulation**: `"simulation.*error|physics.*fail"` (max_lines=3) + +## ๐Ÿšจ Troubleshooting + +### Build Issues +```json +{"tool": "get_ctreditor_status", "parameters": {}} +{"tool": "stop_ctreditor", "parameters": {}} +{"tool": "clean_project", "parameters": {}} +{"tool": "build_project", "parameters": {}} +``` + +### Connection Issues +1. Use `get_simulation_status` to test connectivity +2. Check CtrEditor is running with `get_ctreditor_status` +3. Verify MCP server is active on port 5006 + +## ๐Ÿ’ก Best Practices + +- Always use `get_simulation_status` before expensive operations +- Use specific patterns in `search_debug_log` with low max_lines +- Call `list_objects` only when object data is actually needed +- Stop simulation before major structural changes +- Use appropriate units: meters, Pascal, mยณ/s diff --git a/Documentation/MCP/MCP_LLM_Guide_Optimized.md b/Documentation/MCP/MCP_LLM_Guide_Optimized.md new file mode 100644 index 0000000..c7d2acc --- /dev/null +++ b/Documentation/MCP/MCP_LLM_Guide_Optimized.md @@ -0,0 +1,126 @@ +# CtrEditor MCP Server - LLM Guide + +## โšก Command Efficiency Tiers + +### ๐Ÿš€ **Ultra-Fast** (Use Liberally) +- `get_simulation_status` โ†’ ~25 tokens, instant +- `get_ctreditor_status` โ†’ ~20 tokens, instant +- `start/stop_simulation` โ†’ ~15 tokens, 2-3 sec + +### ๐ŸŸก **Medium** (Use When Needed) +- `search_debug_log` โ†’ 50-200 tokens (max_lines=3-10) +- `build_project` โ†’ 100-500 tokens (errors only) + +### ๐Ÿ”ด **Heavy** (Use Sparingly) +- `list_objects` โ†’ 500-2000+ tokens +- `take_screenshot` โ†’ 100-300 tokens + file + +## ๐Ÿ”ง Core Operations + +### Process Management +```json +{"tool": "start_ctreditor", "parameters": {}} +{"tool": "get_ctreditor_status", "parameters": {}} +{"tool": "stop_ctreditor", "parameters": {}} +``` + +### Build & Debug +```json +{"tool": "build_project", "parameters": {}} +{"tool": "start_debug_listener", "parameters": {}} +{"tool": "search_debug_log", "parameters": {"pattern": "error|exception", "max_lines": 5}} +{"tool": "stop_debug_listener", "parameters": {}} +``` + +### Simulation Control +```json +{"tool": "get_simulation_status", "parameters": {}} +{"tool": "start_simulation", "parameters": {}} +{"tool": "stop_simulation", "parameters": {}} +``` + +### Object Management +```json +{"tool": "list_objects", "parameters": {}} +{"tool": "create_object", "parameters": {"type": "osHydPump", "x": 10, "y": 5}} +{"tool": "update_object", "parameters": {"id": "123", "properties": {"PumpHead": 75.0}}} +{"tool": "delete_objects", "parameters": {"ids": ["123", "456"]}} +``` + +## โšก Optimal Workflows + +### Quick Development Cycle +```json +{"tool": "get_ctreditor_status", "parameters": {}} +{"tool": "build_project", "parameters": {}} +{"tool": "start_simulation", "parameters": {}} +{"tool": "get_simulation_status", "parameters": {}} +``` + +### Bug Investigation +```json +{"tool": "search_debug_log", "parameters": {"pattern": "error|exception", "max_lines": 3}} +{"tool": "get_simulation_status", "parameters": {}} +``` + +### System Recovery +```json +{"tool": "stop_ctreditor", "parameters": {}} +{"tool": "start_ctreditor", "parameters": {}} +``` + +## ๐Ÿ“Š Key Object Properties + +### Hydraulic Components +- **osHydTank**: `TankPressure`, `MaxLevel`, `MinLevel`, `IsFixedPressure` +- **osHydPump**: `PumpHead`, `MaxFlow`, `SpeedRatio`, `IsRunning` +- **osHydPipe**: `Length`, `Diameter`, `CurrentFlow`, `PressureDrop` + +### Common Properties +- **Position**: `Left`, `Top` (meters) +- **Dimensions**: `Ancho`, `Alto` (meters) +- **Connections**: `Id_ComponenteA`, `Id_ComponenteB` + +## ๐Ÿ–ผ๏ธ Screenshots + +### Full Canvas +```json +{"tool": "take_screenshot", "parameters": {}} +``` + +### Targeted Area +```json +{"tool": "take_screenshot", "parameters": { + "x": 39.0, "y": 19.0, "width": 7.0, "height": 3.0 +}} +``` + +## ๐Ÿ” Debug Search Patterns + +High-value, low-token patterns: +- **Critical Errors**: `"error|exception|fail"` (max_lines=3) +- **Performance**: `"fps|slow|memory"` (max_lines=5) +- **Simulation**: `"simulation.*error|physics.*fail"` (max_lines=3) + +## ๐Ÿšจ Troubleshooting + +### Build Issues +```json +{"tool": "get_ctreditor_status", "parameters": {}} +{"tool": "stop_ctreditor", "parameters": {}} +{"tool": "clean_project", "parameters": {}} +{"tool": "build_project", "parameters": {}} +``` + +### Connection Issues +1. Use `get_simulation_status` to test connectivity +2. Check CtrEditor is running with `get_ctreditor_status` +3. Verify MCP server is active on port 5006 + +## ๐Ÿ’ก Best Practices + +- Always use `get_simulation_status` before expensive operations +- Use specific patterns in `search_debug_log` with low max_lines +- Call `list_objects` only when object data is actually needed +- Stop simulation before major structural changes +- Use appropriate units: meters, Pascal, mยณ/s diff --git a/Documentation/MCP/MCP_LLM_Guide_Original.md b/Documentation/MCP/MCP_LLM_Guide_Original.md new file mode 100644 index 0000000..22b4a8a --- /dev/null +++ b/Documentation/MCP/MCP_LLM_Guide_Original.md @@ -0,0 +1,789 @@ +# CtrEditor MCP Server - LLM Guide + +## โšก Command Efficiency Tiers + +### ๐Ÿš€ **Ultra-Fast** (Use Liberally) +- `get_simulation_status` โ†’ ~25 tokens, instant +- `get_ctreditor_status` โ†’ ~20 tokens, instant +- `start/stop_simulation` โ†’ ~15 tokens, 2-3 sec + +### ๐ŸŸก **Medium** (Use When Needed) +- `search_debug_log` โ†’ 50-200 tokens (max_lines=3-10) +- `build_project` โ†’ 100-500 tokens (errors only) + +### ๐Ÿ”ด **Heavy** (Use Sparingly) +- `list_objects` โ†’ 500-2000+ tokens +- `take_screenshot` โ†’ 100-300 tokens + file + +## ๏ฟฝ Core Operations + +### Process Management +```json +{"tool": "start_ctreditor", "parameters": {}} +{"tool": "get_ctreditor_status", "parameters": {}} +{"tool": "stop_ctreditor", "parameters": {}} +``` + +### Build & Debug +```json +{"tool": "build_project", "parameters": {}} +{"tool": "start_debug_listener", "parameters": {}} +{"tool": "search_debug_log", "parameters": {"pattern": "error|exception", "max_lines": 5}} +{"tool": "stop_debug_listener", "parameters": {}} +``` + +### Simulation Control +```json +{"tool": "get_simulation_status", "parameters": {}} +{"tool": "start_simulation", "parameters": {}} +{"tool": "stop_simulation", "parameters": {}} +``` + +### Object Management +```json +{"tool": "list_objects", "parameters": {}} +{"tool": "create_object", "parameters": {"type": "osHydPump", "x": 10, "y": 5}} +{"tool": "update_object", "parameters": {"id": "123", "properties": {"PumpHead": 75.0}}} +{"tool": "delete_objects", "parameters": {"ids": ["123", "456"]}} +``` + +## โšก Optimal Workflows + +### Quick Development Cycle +```json +{"tool": "get_ctreditor_status", "parameters": {}} +{"tool": "build_project", "parameters": {}} +{"tool": "start_simulation", "parameters": {}} +{"tool": "get_simulation_status", "parameters": {}} +``` + +### Bug Investigation +```json +{"tool": "search_debug_log", "parameters": {"pattern": "error|exception", "max_lines": 3}} +{"tool": "get_simulation_status", "parameters": {}} +``` + +### System Recovery +```json +{"tool": "stop_ctreditor", "parameters": {}} +{"tool": "start_ctreditor", "parameters": {}} +``` + +### ๐ŸŽฏ Micro-Workflows (Ultra-Efficient) + +#### **Instant Status Check (1-2 seconds, <50 tokens)** +```json +{"tool": "get_simulation_status", "parameters": {}} +``` +Use this before any operation - tells you everything you need to know + +#### **Quick Error Scan (3-5 seconds, <100 tokens)** +```json +{"tool": "search_debug_log", "parameters": { + "pattern": "error|fail|exception", + "max_lines": 3 +}} +``` +Surgical error detection without token waste + +#### **Smart Object Count Verification (1 second, ~25 tokens)** +```json +{"tool": "get_simulation_status", "parameters": {}} +``` +Check object_count property instead of calling list_objects + +#### **Efficient Build Verification (5-10 seconds, filtered output)** +```json +{"tool": "build_project", "parameters": {}} +``` +Only returns errors - ignores verbose build output + +### ๏ฟฝ Optimized Recovery Patterns + +#### **Process Recovery (Fast)** +```json +// 1. Check status (instant) +{"tool": "get_ctreditor_status", "parameters": {}} + +// 2. If needed, restart (5-10 seconds) +{"tool": "stop_ctreditor", "parameters": {}} +{"tool": "start_ctreditor", "parameters": {}} +``` + +#### **Simulation Recovery (Ultra-Fast)** +```json +// 1. Quick reset (3 seconds total) +{"tool": "stop_simulation", "parameters": {}} +{"tool": "start_simulation", "parameters": {}} + +// 2. Verify (instant) +{"tool": "get_simulation_status", "parameters": {}} +``` + +#### **Debug Recovery (Minimal)** +```json +{"tool": "stop_debug_listener", "parameters": {}} +{"tool": "start_debug_listener", "parameters": {}} +``` + +### ๐Ÿงน Cleanup (Minimal Token Usage) +``` +{"tool": "stop_simulation", "parameters": {}} // if running +{"tool": "save_project", "parameters": {}} // if changes made +{"tool": "stop_ctreditor", "parameters": {}} // when done +``` + +## ๐Ÿ“Š Object Property Deep Dive + +### Hydraulic Components + +#### **osHydTank** (Hydraulic Tank) +Key Properties to Monitor: +- `TankType`: Type of tank (1=standard) +- `CrossSectionalArea`: Tank cross-section in mยฒ +- `MaxLevel`, `MinLevel`: Level limits in meters +- `TankPressure`: Pressure in Pascal +- `IsFixedPressure`: Whether pressure is constant + +#### **osHydPump** (Hydraulic Pump) +Key Properties to Monitor: +- `PumpHead`: Pump head in meters +- `MaxFlow`: Maximum flow rate in mยณ/s +- `SpeedRatio`: Speed ratio (0.0-1.0) +- `IsRunning`: Pump operational state +- `PumpDirection`: Flow direction (1=forward, -1=reverse) + +#### **osHydPipe** (Hydraulic Pipe) +Key Properties to Monitor: +- `Length`: Pipe length in meters +- `Diameter`: Internal diameter in meters +- `Roughness`: Surface roughness +- `CurrentFlow`: Current flow rate in mยณ/s +- `PressureDrop`: Pressure loss across pipe +- `Id_ComponenteA`, `Id_ComponenteB`: Connected components + +### Dynamic Properties +During simulation, monitor these changing values: +- Flow rates in pipes (`CurrentFlow`) +- Pressure drops (`PressureDrop`) +- Tank levels (if applicable) +- Pump performance metrics + +## ๐Ÿ–ผ๏ธ Screenshots + +### Full Canvas +```json +{"tool": "take_screenshot", "parameters": {}} +``` + +### Targeted Area +```json +{"tool": "take_screenshot", "parameters": { + "x": 39.0, "y": 19.0, "width": 7.0, "height": 3.0 +}} +``` + +## ๐Ÿ” Debug Search Patterns + +High-value, low-token patterns: +- **Critical Errors**: `"error|exception|fail"` (max_lines=3) +- **Performance**: `"fps|slow|memory"` (max_lines=5) +- **Simulation**: `"simulation.*error|physics.*fail"` (max_lines=3) + +## ๏ฟฝ Troubleshooting + +### Build Issues +```json +{"tool": "get_ctreditor_status", "parameters": {}} +{"tool": "stop_ctreditor", "parameters": {}} +{"tool": "clean_project", "parameters": {}} +{"tool": "build_project", "parameters": {}} +``` + +### Connection Issues +1. Use `get_simulation_status` to test connectivity +2. Check CtrEditor is running with `get_ctreditor_status` +3. Verify MCP server is active on port 5006 + +## ๐Ÿ’ก Best Practices + +- Always use `get_simulation_status` before expensive operations +- Use specific patterns in `search_debug_log` with low max_lines +- Call `list_objects` only when object data is actually needed +- Stop simulation before major structural changes +- Use appropriate units: meters, Pascal, mยณ/s + "pattern": "error|exception", + "max_lines": 20 +}} + +// Check buffer stats +{"tool": "get_debug_stats", "parameters": {}} + +// Stop monitoring +{"tool": "stop_debug_listener", "parameters": {}} +``` + +### Combined Development Workflow +```json +// 1. Ensure clean environment +{"tool": "get_ctreditor_status", "parameters": {}} +{"tool": "stop_ctreditor", "parameters": {}} +{"tool": "clean_project", "parameters": {}} + +// 2. Build and check for errors +{"tool": "build_project", "parameters": {}} + +// 3. Start CtrEditor with monitoring +{"tool": "start_debug_listener", "parameters": {}} +{"tool": "start_ctreditor", "parameters": {}} + +// 4. Monitor for issues +{"tool": "search_debug_log", "parameters": { + "pattern": "error|exception|fail", + "max_lines": 10 +}} + +// 5. Test simulation +{"tool": "get_simulation_status", "parameters": {}} +{"tool": "start_simulation", "parameters": {}} + +// 6. Search for simulation issues +{"tool": "search_debug_log", "parameters": { + "pattern": "simulation|physics", + "max_lines": 15 +}} +``` + +## ๐Ÿ”ง Enhanced Debugging Workflows (NEW) + +### 1. Build Error Investigation +``` +1. build_project - Get compilation errors only (filtered) +2. search_debug_log(pattern="error|warning", max_lines=50) - Find related debug info +3. start_ctreditor - Launch for testing +4. get_debug_stats - Monitor for new issues +``` + +### 2. Runtime Issue Investigation +``` +1. start_debug_listener - Begin monitoring +2. start_simulation - Trigger the issue +3. search_debug_log(pattern="exception|error", last_n_lines=200) - Find problems +4. search_debug_log(pattern="stack trace", max_lines=10) - Get stack traces +5. stop_simulation - Stop for analysis +``` + +### 3. Performance Analysis +``` +1. clear_debug_buffer - Start with clean slate +2. start_simulation - Begin performance test +3. search_debug_log(pattern="fps|performance|slow", max_lines=20) - Find performance issues +4. search_debug_log(pattern="memory|allocation", max_lines=15) - Check memory usage +5. get_debug_stats - Overall statistics +``` + +### 4. Component Behavior Analysis +``` +1. search_debug_log(pattern="pump|flow|pressure", max_lines=30) - Hydraulic behavior +2. search_debug_log(pattern="simulation.*object", max_lines=25) - Object interactions +3. take_screenshot() - Visual verification +4. list_objects - Current property values +``` + +### 5. Pre-Simulation Analysis +``` +1. list_objects - Document initial state +2. take_screenshot() - Visual documentation +3. Analyze object configurations and connections +4. Verify proper component setup +``` + +### 6. Simulation Monitoring +``` +1. start_simulation - Begin simulation +2. get_simulation_status - Confirm running +3. list_objects - Monitor dynamic properties +4. take_screenshot(area) - Capture specific components +5. stop_simulation - End when needed +``` + +### 7. Performance Investigation +``` +1. list_objects - Get baseline measurements +2. start_simulation - Run simulation +3. Wait 5-10 seconds for stabilization +4. list_objects - Compare with baseline +5. take_screenshot() - Document final state +``` + +### 8. Component Analysis +``` +1. take_screenshot(component_area) - High-res component view +2. list_objects - Get detailed properties +3. update_object - Modify parameters if needed +4. start_simulation - Test changes +5. take_screenshot(component_area) - Compare results +``` + +## ๐Ÿ“ˆ Simulation Data Interpretation + +### Flow Analysis +- **Positive Flow**: Normal direction flow +- **Negative Flow**: Reverse flow direction +- **Zero Flow**: No flow (blockage or equilibrium) + +### Pressure Analysis +- **High Pressure Drop**: Potential flow restriction +- **Low Pressure Drop**: Free-flowing condition +- **Pressure Patterns**: Indicate system behavior + +### Pump Performance +- **SpeedRatio**: Pump operation intensity +- **IsRunning**: Operational state +- **PumpDirection**: Flow direction control + +## โšก Rapid Iteration Patterns (NEW) + +### Lightning Fast Debug Cycle +**Single-Command Quick Check (5 seconds):** +```json +{"tool": "get_simulation_status", "parameters": {}} +``` +- Instantly know: running state, object count, visibility +- Use this before any other operation + +### Minimal Token Development Loop +**Ultra-Efficient 3-Step Pattern:** +```json +// 1. Quick status (minimal tokens) +{"tool": "get_ctreditor_status", "parameters": {}} + +// 2. Smart build (errors only, no full log) +{"tool": "build_project", "parameters": {}} + +// 3. Target-specific debug search (specific pattern) +{"tool": "search_debug_log", "parameters": { + "pattern": "error|exception", + "max_lines": 5 +}} +``` + +### Zero-Waste Object Analysis +**Smart Object Inspection (instead of full list_objects):** +```json +// Instead of listing all objects, target specific ones: +{"tool": "list_objects", "parameters": {}} +// Then filter client-side by type/name/properties +``` + +### Micro-Screenshot Strategy +**Targeted Visual Validation (saves bandwidth):** +```json +// Full canvas only when needed +{"tool": "take_screenshot", "parameters": {}} + +// For specific components (higher detail, smaller file): +{"tool": "take_screenshot", "parameters": { + "x": 42.0, "y": 20.0, "width": 2.0, "height": 2.0 +}} +``` + +## ๏ฟฝ Token-Optimized Workflows + +### Development Iteration (Minimal Tokens) +``` +1. get_ctreditor_status (1 call - instant) +2. build_project (errors only - no verbose output) +3. start_simulation (1 call - instant feedback) +4. get_simulation_status (verify running) +``` + +### Bug Investigation (Surgical Precision) +``` +1. search_debug_log(pattern="specific_error", max_lines=3) +2. list_objects (only if object data needed) +3. take_screenshot (targeted area only) +``` + +### Performance Testing (Streamlined) +``` +1. clear_debug_buffer (clean slate) +2. start_simulation +3. search_debug_log(pattern="fps|performance", max_lines=10) +4. stop_simulation +``` + +## ๐ŸŽฏ Smart Command Selection Guide + +### When to Use Each Function: +- **get_ctreditor_status**: Always first command (2 tokens response) +- **build_project**: Only when code changed (filtered output) +- **search_debug_log**: Instead of full console dump (targeted) +- **get_simulation_status**: Quick health check (3 tokens response) +- **list_objects**: Only when need object data (can be large) +- **take_screenshot**: Last resort for visual confirmation + +### Command Efficiency Ranking: +1. ๐ŸŸข **Ultra-Fast** (use liberally): `get_ctreditor_status`, `get_simulation_status` +2. ๐ŸŸก **Fast** (use when needed): `start/stop_simulation`, `search_debug_log` +3. ๐ŸŸ  **Medium** (use selectively): `build_project`, `save_project` +4. ๐Ÿ”ด **Heavy** (use sparingly): `list_objects`, `take_screenshot` + +## ๏ฟฝ๐Ÿšจ Enhanced Troubleshooting Guide (NEW) + +### Process Management Issues +If CtrEditor won't start or crashes: +1. `get_ctreditor_status` - Check current process state (instant) +2. `stop_ctreditor` - Ensure clean termination +3. `build_project` - Check for compilation issues (errors only) +4. `start_ctreditor` - Launch fresh instance +5. `search_debug_log` - Monitor for startup issues (targeted pattern) + +### Build Problems (Smart Filtering) +Critical Build Error Patterns: +- **CS#### errors**: Compilation issues (fix immediately) +- **MSB3027/MSB3021**: File lock errors (CtrEditor running) +- **MSB#### warnings**: Build system (usually safe to ignore) + +Quick Build Fix Flow: +```json +// 1. Check if app is blocking compilation +{"tool": "get_ctreditor_status", "parameters": {}} + +// 2. Stop if running +{"tool": "stop_ctreditor", "parameters": {}} + +// 3. Clean and rebuild +{"tool": "clean_project", "parameters": {}} +{"tool": "build_project", "parameters": {}} +``` + +### Debug Console Issues (Connection Problems) +Fast Debug Recovery: +```json +// 1. Check connection health +{"tool": "get_debug_stats", "parameters": {}} + +// 2. Reset connection +{"tool": "stop_debug_listener", "parameters": {}} +{"tool": "start_debug_listener", "parameters": {}} +``` + +### Connection Issues +If MCP commands fail: +1. Use `get_simulation_status` to test connectivity (fastest) +2. Check CtrEditor is running with `get_ctreditor_status` +3. Verify MCP server is active on port 5006 + +### Simulation Issues (Rapid Response) +If simulation behaves unexpectedly: +```json +// Quick diagnostic sequence +{"tool": "get_simulation_status", "parameters": {}} +{"tool": "search_debug_log", "parameters": { + "pattern": "simulation|physics|error", + "max_lines": 5 +}} +``` + +### Data Inconsistencies +Efficient data validation: +1. Use `get_simulation_status` for quick object count check +2. Only call `list_objects` if counts don't match expectations +3. Use targeted screenshots for visual verification + +## ๐Ÿ’ก Enhanced Best Practices (UPDATED) + +### ๐Ÿš€ Token Efficiency (Critical for Performance) + +#### **Ultra-Lightweight Commands (Use Liberally)** +- `get_ctreditor_status` โ†’ 15-25 tokens response +- `get_simulation_status` โ†’ 20-30 tokens response +- `start/stop_simulation` โ†’ 10-15 tokens response + +#### **Medium Weight Commands (Use When Needed)** +- `search_debug_log` โ†’ 50-200 tokens (with max_lines=5-10) +- `build_project` โ†’ 100-500 tokens (errors only, filtered) +- `create/update/delete_objects` โ†’ 30-100 tokens each + +#### **Heavy Commands (Use Sparingly)** +- `list_objects` โ†’ 500-2000+ tokens (depends on object count) +- `take_screenshot` โ†’ 100-300 tokens metadata + file + +### โšก Speed Optimization Patterns + +#### **Lightning-Fast Status Check (2-3 seconds)** +```json +{"tool": "get_simulation_status", "parameters": {}} +``` +Returns: running state, object count, visibility in minimal tokens + +#### **Smart Error Detection (5-10 seconds)** +```json +{"tool": "search_debug_log", "parameters": { + "pattern": "error|exception|fail", + "max_lines": 3 +}} +``` +Targeted error search instead of full console dump + +#### **Efficient Object Management** +```json +// Instead of list_objects -> update -> list_objects again: +// 1. Single targeted update +{"tool": "update_object", "parameters": {"id": "123", "properties": {...}}} + +// 2. Quick verification with status +{"tool": "get_simulation_status", "parameters": {}} +``` + +### ๐ŸŽฏ Workflow Optimization + +#### **Development Iteration (Under 30 seconds)** +``` +1. get_ctreditor_status (instant) +2. build_project (filtered errors) +3. start_simulation (instant) +4. search_debug_log (targeted, max_lines=5) +``` + +#### **Bug Investigation (Under 15 seconds)** +``` +1. search_debug_log (specific error pattern, max_lines=3) +2. get_simulation_status (confirm state) +3. targeted screenshot (only if visual needed) +``` + +#### **Performance Testing (Under 20 seconds)** +``` +1. clear_debug_buffer +2. start_simulation +3. search_debug_log(pattern="fps|slow", max_lines=5) +4. stop_simulation +``` + +### ๐Ÿ” Smart Debug Search Patterns + +#### **High-Value, Low-Token Patterns** +- **Critical Errors**: `"error|exception|fail|crash"` (max_lines=3) +- **Performance Issues**: `"fps|slow|memory|lag"` (max_lines=5) +- **Simulation Problems**: `"simulation.*error|physics.*fail"` (max_lines=3) +- **Object Issues**: `"object.*error|create.*fail|update.*error"` (max_lines=3) + +#### **Efficient Search Strategy** +```json +// Good: Specific, targeted +{"pattern": "pump.*error", "max_lines": 3} + +// Avoid: Too broad, token-heavy +{"pattern": ".*", "max_lines": 100} +``` + +### ๐Ÿ“Š Data Minimization Techniques + +#### **Before Calling list_objects (Heavy)** +Ask yourself: +1. Do I need ALL objects or just count? โ†’ Use `get_simulation_status` +2. Do I need specific object? โ†’ Search by type/name client-side +3. Do I need visual confirmation? โ†’ Use targeted `take_screenshot` + +#### **Before Taking Screenshots** +Consider: +1. Is object data sufficient? โ†’ Use `list_objects` for position/properties +2. Do I need full canvas? โ†’ Use area parameters for specific region +3. Is this for documentation? โ†’ Full canvas OK +4. Is this for debugging? โ†’ Targeted area preferred + +### ๐Ÿ”ง Advanced Efficiency Tips + +#### **Batch Operations (When Possible)** +```json +// Good: Single call for multiple deletes +{"tool": "delete_objects", "parameters": {"ids": ["1", "2", "3"]}} + +// Avoid: Multiple single calls +// delete_objects(id="1"), delete_objects(id="2"), delete_objects(id="3") +``` + +#### **State Caching Strategy** +- Cache `get_simulation_status` results for 5-10 seconds +- Only call `list_objects` when object count changes +- Re-use screenshot data for multiple analyses + +#### **Conditional Command Execution** +```json +// Check state before expensive operations +if (simulation_status.is_running) { + // Only then do expensive analysis + list_objects(); +} +``` + +### ๐Ÿšจ Anti-Patterns (Avoid These) + +#### **Token Wasters** +- โŒ Calling `list_objects` repeatedly without state change +- โŒ Using `search_debug_log` without specific patterns +- โŒ Taking full screenshots for simple status checks +- โŒ Building project when no code changes made + +#### **Time Wasters** +- โŒ Not checking `get_ctreditor_status` before operations +- โŒ Using `stop_ctreditor` โ†’ `start_ctreditor` for simple resets +- โŒ Clearing debug buffer unnecessarily +- โŒ Taking screenshots without area parameters for small checks + +### ๐ŸŽฏ Context-Aware Command Selection + +#### **Development Context** +Use: `build_project`, `search_debug_log`, `get_ctreditor_status` + +#### **Simulation Testing Context** +Use: `start/stop_simulation`, `get_simulation_status`, targeted `search_debug_log` + +#### **Object Analysis Context** +Use: `list_objects` (when needed), `update_object`, `get_simulation_status` + +#### **Visual Documentation Context** +Use: `take_screenshot`, `list_objects` (for positions), `save_project` + +### ๐Ÿ”„ Recovery Patterns (Fast Error Recovery) + +#### **Process Recovery (5 seconds)** +```json +{"tool": "get_ctreditor_status", "parameters": {}} +// If not running: +{"tool": "start_ctreditor", "parameters": {}} +``` + +#### **Simulation Recovery (3 seconds)** +```json +{"tool": "stop_simulation", "parameters": {}} +{"tool": "start_simulation", "parameters": {}} +``` + +#### **Debug Recovery (2 seconds)** +```json +{"tool": "stop_debug_listener", "parameters": {}} +{"tool": "start_debug_listener", "parameters": {}} +``` + +### Safety +- Always verify critical changes with `get_simulation_status` +- Use appropriate units for all parameters (meters, Pascal, mยณ/s) +- Stop simulation before major structural changes +- Save project after significant modifications + +## ๐Ÿ“‹ Real-World Testing Results (VERIFIED PATTERNS) + +### โœ… **Proven Efficient Patterns (From Live Testing)** + +#### **Complete System Test (19/19 functions verified)** +```json +// 1. Process verification (instant) +{"tool": "get_ctreditor_status", "parameters": {}} + +// 2. System assessment (25 tokens) +{"tool": "get_simulation_status", "parameters": {}} + +// 3. Object discovery (when needed) +{"tool": "list_objects", "parameters": {}} + +// 4. Visual confirmation (targeted) +{"tool": "take_screenshot", "parameters": {}} +``` + +#### **Hydraulic System Analysis (Real Example)** +**Found Objects** (from actual test): +- 2 ร— Hydraulic Tanks (osHydTank): `TankPressure: 101000.0 Pascal` +- 1 ร— Hydraulic Pump (osHydPump): `PumpHead: 75.0m, MaxFlow: 0.015 mยณ/s` +- 2 ร— Hydraulic Pipes (osHydPipe): `Diameter: 0.05m, Length: 1.0m` + +**Key Properties Verified**: +- Flow rates: `CurrentFlow: 0.0` (static state) +- Pressure drops: `PressureDrop: 0.0` (no flow) +- Connections: `Id_ComponenteA/B` linking system components + +#### **Build Error Handling (Real Example)** +**Actual Error Encountered**: MSB3027/MSB3021 - File locked by CtrEditor process +**Smart Response Pattern**: +```json +// 1. Check if process is blocking +{"tool": "get_ctreditor_status", "parameters": {}} + +// 2. If running, stop for clean build +{"tool": "stop_ctreditor", "parameters": {}} + +// 3. Clean and rebuild +{"tool": "clean_project", "parameters": {}} +{"tool": "build_project", "parameters": {}} +``` + +#### **Object Manipulation Workflow (Verified)** +```json +// 1. Create object (tested: osTextPlate, ID: 307325) +{"tool": "create_object", "parameters": { + "type": "osTextPlate", "x": 46, "y": 21 +}} + +// 2. Update properties (verified) +{"tool": "update_object", "parameters": { + "id": "307325", + "properties": {"Text": "Sistema Hidrรกulico", "TextColor": "#FF0000FF"} +}} + +// 3. Verify with status check (efficient) +{"tool": "get_simulation_status", "parameters": {}} + +// 4. Clean up when done +{"tool": "delete_objects", "parameters": {"ids": ["307325"]}} +``` + +### ๐Ÿ“Š **Performance Metrics (Actual Results)** +- **Screenshot**: 3.4MB file, 78ร—54 meter canvas captured +- **Object types**: 33 types across 9 categories available +- **Process startup**: ~5-10 seconds from stop to ready +- **Simulation control**: Instant start/stop responses +- **Debug search**: <2 seconds for targeted patterns + +### ๐ŸŽฏ **Object Type Categories (Complete List)** +1. **Componentes Hidrรกulicos** (3): Pumps, Tanks, Pipes +2. **Decorativos** (3): Images, Frames, Text Plates +3. **Dinamicos** (2): Bottles, Bottle with Neck +4. **Emuladores** (3): Bottle Generator, Filler, Tank +5. **Estaticos** (9): Conveyors, Guides, Motors, Curves +6. **Extraccion Datos** (2): Template Search, Tag Extraction +7. **SensoresComandos** (6): Buttons, Encoders, Photocells, Sensors +8. **TagsSignals** (3): Consensus, Analog Tags, Digital Tags +9. **Traces** (2): Signal Tracers + +### ๐Ÿ” **Debug Patterns That Work (Tested)** +```json +// Critical errors (high value) +{"pattern": "error|exception|fail", "max_lines": 3} + +// Performance issues +{"pattern": "fps|slow|memory", "max_lines": 5} + +// Simulation specific +{"pattern": "simulation|physics", "max_lines": 5} + +// Object operations +{"pattern": "object.*create|update.*error", "max_lines": 3} +``` + +### โšก **Fastest Diagnostic Sequence (Under 10 seconds)** +```json +// 1. Health check (instant) +{"tool": "get_simulation_status", "parameters": {}} + +// 2. Error scan (2-3 seconds) +{"tool": "search_debug_log", "parameters": { + "pattern": "error|fail", "max_lines": 3 +}} + +// 3. Process verification if needed (instant) +{"tool": "get_ctreditor_status", "parameters": {}} +``` + +This sequence gives you complete system health in minimal time and tokens. diff --git a/Documentation/MCP_LLM_Guide.md b/Documentation/MCP_LLM_Guide.md deleted file mode 100644 index f042c90..0000000 --- a/Documentation/MCP_LLM_Guide.md +++ /dev/null @@ -1,435 +0,0 @@ -# CtrEditor Enhanced MCP Server - LLM Usage Guide - -## ๐Ÿค– Quick Start for Language Models - -This guide provides step-by-step instructions for LLMs to interact with CtrEditor simulations programmatically. The enhanced MCP server provides complete control over simulation objects, execution, monitoring, process management, build tools, and intelligent debug console access. - -## ๐Ÿš€ Enhanced Workflow - -### 1. Process Management (NEW) -Control CtrEditor application lifecycle: - -``` -๐Ÿš€ start_ctreditor - Launch CtrEditor instance -๐Ÿ” get_ctreditor_status - Check process status -๐Ÿ›‘ stop_ctreditor - Terminate CtrEditor -``` - -### 2. Build Management (NEW) -Intelligent compilation with error filtering: - -``` -๐Ÿ”จ build_project - Compile with smart error filtering -๐Ÿงน clean_project - Clean build artifacts -``` - -### 3. Debug Console Access (NEW) -Real-time debug monitoring with intelligent filtering: - -``` -๐ŸŽง start_debug_listener - Connect to debug output -๐Ÿ” search_debug_log - Regex/grep search in console -๐Ÿ“Š get_debug_stats - Debug buffer statistics -๐Ÿงน clear_debug_buffer - Clear debug history -๐Ÿ›‘ stop_debug_listener - Disconnect debug monitoring -``` - -### 4. Simulation Assessment -Get the current state of the simulation: - -``` -๐Ÿ” list_objects - See what's currently in the simulation -๐ŸŽฎ get_simulation_status - Check if simulation is running -๐Ÿ”Œ get_plc_status - Check PLC connection state -``` - -### 5. Object Analysis -For each object found, examine its properties to understand: -- **Position**: `Left`, `Top` coordinates in meters -- **Dimensions**: `Ancho` (width), `Alto` (height) in meters -- **Type-Specific Properties**: Flow rates, pressures, speeds, etc. -- **Connection States**: Which components are connected -- **Simulation Parameters**: Physics and hydraulic settings - -### 6. Simulation Control -Control the simulation lifecycle: -- `start_simulation` - Begin physics calculations -- `stop_simulation` - Halt simulation -- Monitor changes with repeated `list_objects` calls - -## ๐Ÿ”ง Enhanced Development Workflow (NEW) - -### Full Development Cycle Automation -The enhanced MCP server enables complete development automation: - -1. **๐Ÿš€ Launch Environment** - ``` - start_ctreditor - Launch fresh CtrEditor instance - get_ctreditor_status - Verify process started - ``` - -2. **๐Ÿ”จ Build and Test** - ``` - build_project - Compile with intelligent error filtering - # Only compilation errors/warnings returned, not full build log - clean_project - Clean artifacts if needed - ``` - -3. **๐Ÿ› Debug Monitoring** - ``` - start_debug_listener - Connect to CtrEditor debug console - # Real-time monitoring of debug output with buffering - ``` - -4. **๐Ÿ” Intelligent Debug Search** - ``` - search_debug_log(pattern="ERROR|EXCEPTION", max_lines=20) - search_debug_log(pattern="simulation.*started", case_sensitive=false) - search_debug_log(pattern="pump.*flow", last_n_lines=500) - ``` - -5. **๐Ÿ“Š System Monitoring** - ``` - get_debug_stats - Buffer status and recent activity - get_simulation_status - Runtime state - list_objects - Current simulation objects - ``` - -6. **๐Ÿงน Cleanup** - ``` - stop_simulation - Stop if running - stop_ctreditor - Terminate process - clear_debug_buffer - Clean debug history - ``` - -## ๐Ÿ“Š Object Property Deep Dive - -### Hydraulic Components - -#### **osHydTank** (Hydraulic Tank) -Key Properties to Monitor: -- `TankType`: Type of tank (1=standard) -- `CrossSectionalArea`: Tank cross-section in mยฒ -- `MaxLevel`, `MinLevel`: Level limits in meters -- `TankPressure`: Pressure in Pascal -- `IsFixedPressure`: Whether pressure is constant - -#### **osHydPump** (Hydraulic Pump) -Key Properties to Monitor: -- `PumpHead`: Pump head in meters -- `MaxFlow`: Maximum flow rate in mยณ/s -- `SpeedRatio`: Speed ratio (0.0-1.0) -- `IsRunning`: Pump operational state -- `PumpDirection`: Flow direction (1=forward, -1=reverse) - -#### **osHydPipe** (Hydraulic Pipe) -Key Properties to Monitor: -- `Length`: Pipe length in meters -- `Diameter`: Internal diameter in meters -- `Roughness`: Surface roughness -- `CurrentFlow`: Current flow rate in mยณ/s -- `PressureDrop`: Pressure loss across pipe -- `Id_ComponenteA`, `Id_ComponenteB`: Connected components - -### Dynamic Properties -During simulation, monitor these changing values: -- Flow rates in pipes (`CurrentFlow`) -- Pressure drops (`PressureDrop`) -- Tank levels (if applicable) -- Pump performance metrics - -## ๐Ÿ–ผ๏ธ Visual Documentation - -### Full Canvas Screenshots -```json -take_screenshot() -``` -- Captures entire simulation at 2x resolution -- Saves to `/screenshots/` subdirectory -- Returns detailed file information - -### Targeted Screenshots -```json -take_screenshot({ - "x": 39.0, // Start X in meters - "y": 19.0, // Start Y in meters - "width": 7.0, // Width in meters - "height": 3.0 // Height in meters -}) -``` -- Captures specific region at 3x resolution (high detail) -- Perfect for component close-ups -- Use object positions to determine coordinates - -### Screenshot Use Cases -1. **Component Documentation**: Capture individual components -2. **System Overview**: Full canvas for complete system view -3. **Before/After Comparison**: Screenshots before and after simulation -4. **Issue Investigation**: High-resolution captures of problem areas - -## ๐Ÿ”ง Property Modification - -### Updating Object Properties -```json -update_object({ - "id": "307211", - "properties": { - "PumpHead": 75.0, - "MaxFlow": 0.015, - "IsRunning": true - } -}) -``` - -### Safe Property Modification -- Always check current properties first with `list_objects` -- Modify only relevant properties for the object type -- Use appropriate units (meters, Pascal, mยณ/s, etc.) -- Verify changes by calling `list_objects` again - -## ๐ŸŽฏ Enhanced Usage Examples (NEW) - -### Process Management Example -```json -// Check if CtrEditor is running -{"tool": "get_ctreditor_status", "parameters": {}} - -// Start CtrEditor if needed -{"tool": "start_ctreditor", "parameters": {}} - -// Stop CtrEditor when done -{"tool": "stop_ctreditor", "parameters": {}} -``` - -### Build Management Example -```json -// Clean before building -{"tool": "clean_project", "parameters": {}} - -// Build and get only errors/warnings -{"tool": "build_project", "parameters": {}} -``` - -### Debug Console Example -```json -// Start monitoring -{"tool": "start_debug_listener", "parameters": {}} - -// Search for errors -{"tool": "search_debug_log", "parameters": { - "pattern": "error|exception", - "max_lines": 20 -}} - -// Check buffer stats -{"tool": "get_debug_stats", "parameters": {}} - -// Stop monitoring -{"tool": "stop_debug_listener", "parameters": {}} -``` - -### Combined Development Workflow -```json -// 1. Ensure clean environment -{"tool": "get_ctreditor_status", "parameters": {}} -{"tool": "stop_ctreditor", "parameters": {}} -{"tool": "clean_project", "parameters": {}} - -// 2. Build and check for errors -{"tool": "build_project", "parameters": {}} - -// 3. Start CtrEditor with monitoring -{"tool": "start_debug_listener", "parameters": {}} -{"tool": "start_ctreditor", "parameters": {}} - -// 4. Monitor for issues -{"tool": "search_debug_log", "parameters": { - "pattern": "error|exception|fail", - "max_lines": 10 -}} - -// 5. Test simulation -{"tool": "get_simulation_status", "parameters": {}} -{"tool": "start_simulation", "parameters": {}} - -// 6. Search for simulation issues -{"tool": "search_debug_log", "parameters": { - "pattern": "simulation|physics", - "max_lines": 15 -}} -``` - -## ๐Ÿ”ง Enhanced Debugging Workflows (NEW) - -### 1. Build Error Investigation -``` -1. build_project - Get compilation errors only (filtered) -2. search_debug_log(pattern="error|warning", max_lines=50) - Find related debug info -3. start_ctreditor - Launch for testing -4. get_debug_stats - Monitor for new issues -``` - -### 2. Runtime Issue Investigation -``` -1. start_debug_listener - Begin monitoring -2. start_simulation - Trigger the issue -3. search_debug_log(pattern="exception|error", last_n_lines=200) - Find problems -4. search_debug_log(pattern="stack trace", max_lines=10) - Get stack traces -5. stop_simulation - Stop for analysis -``` - -### 3. Performance Analysis -``` -1. clear_debug_buffer - Start with clean slate -2. start_simulation - Begin performance test -3. search_debug_log(pattern="fps|performance|slow", max_lines=20) - Find performance issues -4. search_debug_log(pattern="memory|allocation", max_lines=15) - Check memory usage -5. get_debug_stats - Overall statistics -``` - -### 4. Component Behavior Analysis -``` -1. search_debug_log(pattern="pump|flow|pressure", max_lines=30) - Hydraulic behavior -2. search_debug_log(pattern="simulation.*object", max_lines=25) - Object interactions -3. take_screenshot() - Visual verification -4. list_objects - Current property values -``` - -### 5. Pre-Simulation Analysis -``` -1. list_objects - Document initial state -2. take_screenshot() - Visual documentation -3. Analyze object configurations and connections -4. Verify proper component setup -``` - -### 6. Simulation Monitoring -``` -1. start_simulation - Begin simulation -2. get_simulation_status - Confirm running -3. list_objects - Monitor dynamic properties -4. take_screenshot(area) - Capture specific components -5. stop_simulation - End when needed -``` - -### 7. Performance Investigation -``` -1. list_objects - Get baseline measurements -2. start_simulation - Run simulation -3. Wait 5-10 seconds for stabilization -4. list_objects - Compare with baseline -5. take_screenshot() - Document final state -``` - -### 8. Component Analysis -``` -1. take_screenshot(component_area) - High-res component view -2. list_objects - Get detailed properties -3. update_object - Modify parameters if needed -4. start_simulation - Test changes -5. take_screenshot(component_area) - Compare results -``` - -## ๐Ÿ“ˆ Simulation Data Interpretation - -### Flow Analysis -- **Positive Flow**: Normal direction flow -- **Negative Flow**: Reverse flow direction -- **Zero Flow**: No flow (blockage or equilibrium) - -### Pressure Analysis -- **High Pressure Drop**: Potential flow restriction -- **Low Pressure Drop**: Free-flowing condition -- **Pressure Patterns**: Indicate system behavior - -### Pump Performance -- **SpeedRatio**: Pump operation intensity -- **IsRunning**: Operational state -- **PumpDirection**: Flow direction control - -## ๐Ÿšจ Enhanced Troubleshooting Guide (NEW) - -### Process Management Issues -If CtrEditor won't start or crashes: -1. `get_ctreditor_status` - Check current process state -2. `stop_ctreditor` - Ensure clean termination -3. `build_project` - Check for compilation issues -4. `start_ctreditor` - Launch fresh instance -5. `start_debug_listener` - Monitor for startup issues - -### Build Problems -If compilation fails: -1. `clean_project` - Clean build artifacts -2. `build_project` - Get filtered error list (not full log) -3. Focus on CS#### errors (compilation) vs MSB#### (build system) -4. Check for file locks or permission issues - -### Debug Console Issues -If debug monitoring fails: -1. `stop_debug_listener` - Clean disconnect -2. `get_debug_stats` - Check connection status -3. Verify CtrEditor has debug console enabled on port 5007 -4. `start_debug_listener` - Reconnect with fresh connection - -### Connection Issues -If MCP commands fail: -1. Check CtrEditor is running -2. Verify MCP server is active on port 5006 -3. Use `get_simulation_status` to test connectivity - -### Simulation Issues -If simulation behaves unexpectedly: -1. Stop simulation with `stop_simulation` -2. Check object properties with `list_objects` -3. Verify component connections -4. Take screenshots for visual verification -5. Restart simulation with `start_simulation` - -### Data Inconsistencies -If properties seem wrong: -1. Get fresh data with `list_objects` -2. Compare with visual evidence via `take_screenshot` -3. Check if simulation is running vs stopped -4. Verify meter-based coordinates - -## ๐Ÿ’ก Enhanced Best Practices (NEW) - -### Token Efficiency -- Use `build_project` instead of running full `dotnet build` - returns only errors -- Use `search_debug_log` with specific patterns instead of requesting full console -- Set `max_lines` parameter to limit returned results -- Use `last_n_lines` to focus on recent activity - -### Development Workflow -- Always use `get_ctreditor_status` before attempting to start CtrEditor -- Use `clean_project` if builds seem inconsistent -- Monitor debug output with `start_debug_listener` during development -- Use regex patterns for precise debug searches: `error|exception|fail` - -### Debug Search Patterns -Effective patterns for common issues: -- **Errors**: `error|exception|fail|crash` -- **Performance**: `fps|slow|performance|memory` -- **Simulation**: `simulation.*start|simulation.*stop|physics` -- **Hydraulics**: `pump|flow|pressure|tank|pipe` -- **Objects**: `object.*create|object.*delete|object.*update` - -### Efficient Monitoring -- Use `get_simulation_status` for quick status checks -- Call `list_objects` only when detailed data is needed -- Take targeted screenshots instead of full canvas when possible - -### Data Analysis -- Always compare before/after simulation states -- Monitor key performance indicators for each component type -- Use screenshots to validate data interpretations - -### Documentation -- Screenshot key configurations and results -- Document property changes with timestamps -- Maintain clear before/after comparisons - -### Safety -- Always stop simulation before making major changes -- Verify property updates with `list_objects` -- Use appropriate units for all parameters