CtrEditor/Documentation/MCP_LLM_Guide.md

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

take_screenshot()

• Captures entire simulation at 2x resolution
• Saves to /screenshots/ subdirectory
• Returns detailed file information

Targeted Screenshots

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

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