# CtrEditor 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 MCP server allows complete control over simulation objects, execution, and monitoring.

## 🚀 Basic Workflow

### 1. Initial Assessment
Start by getting 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
```

### 2. 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

### 3. Simulation Control
Control the simulation lifecycle:
- `start_simulation` - Begin physics calculations
- `stop_simulation` - Halt simulation
- Monitor changes with repeated `list_objects` calls

## 📊 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

## 🎯 Common Debugging Workflows

### 1. 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
```

### 2. 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
```

### 3. 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
```

### 4. 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

## 🚨 Troubleshooting Guide

### 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

## 💡 Best Practices

### 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