13 KiB

Raw Blame History

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:

🚀 Launch Environment

start_ctreditor - Launch fresh CtrEditor instance
get_ctreditor_status - Verify process started

🔨 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

🐛 Debug Monitoring

start_debug_listener - Connect to CtrEditor debug console
# Real-time monitoring of debug output with buffering

🔍 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)

📊 System Monitoring

get_debug_stats - Buffer status and recent activity
get_simulation_status - Runtime state
list_objects - Current simulation objects

🧹 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

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

Component Documentation: Capture individual components
System Overview: Full canvas for complete system view
Before/After Comparison: Screenshots before and after simulation
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

🎯 Enhanced Usage Examples (NEW)

Process Management Example

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

// Clean before building
{"tool": "clean_project", "parameters": {}}

// Build and get only errors/warnings
{"tool": "build_project", "parameters": {}}

Debug Console Example

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

// 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:

get_ctreditor_status - Check current process state
stop_ctreditor - Ensure clean termination
build_project - Check for compilation issues
start_ctreditor - Launch fresh instance
start_debug_listener - Monitor for startup issues

Build Problems

If compilation fails:

clean_project - Clean build artifacts
build_project - Get filtered error list (not full log)
Focus on CS#### errors (compilation) vs MSB#### (build system)
Check for file locks or permission issues

Debug Console Issues

If debug monitoring fails:

stop_debug_listener - Clean disconnect
get_debug_stats - Check connection status
Verify CtrEditor has debug console enabled on port 5007
start_debug_listener - Reconnect with fresh connection

Connection Issues

If MCP commands fail:

Check CtrEditor is running
Verify MCP server is active on port 5006
Use get_simulation_status to test connectivity

Simulation Issues

If simulation behaves unexpectedly:

Stop simulation with stop_simulation
Check object properties with list_objects
Verify component connections
Take screenshots for visual verification
Restart simulation with start_simulation

Data Inconsistencies

If properties seem wrong:

Get fresh data with list_objects
Compare with visual evidence via take_screenshot
Check if simulation is running vs stopped
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

13 KiB Raw Blame History

CtrEditor Enhanced MCP Server - LLM Usage Guide

🤖 Quick Start for Language Models

🚀 Enhanced Workflow

1. Process Management (NEW)

2. Build Management (NEW)

3. Debug Console Access (NEW)

4. Simulation Assessment

5. Object Analysis

6. Simulation Control

🔧 Enhanced Development Workflow (NEW)

Full Development Cycle Automation

📊 Object Property Deep Dive

Hydraulic Components

osHydTank (Hydraulic Tank)

osHydPump (Hydraulic Pump)

osHydPipe (Hydraulic Pipe)

Dynamic Properties

🖼️ Visual Documentation

Full Canvas Screenshots

Targeted Screenshots

Screenshot Use Cases

🔧 Property Modification

Updating Object Properties

Safe Property Modification

🎯 Enhanced Usage Examples (NEW)

Process Management Example

Build Management Example

Debug Console Example

Combined Development Workflow

🔧 Enhanced Debugging Workflows (NEW)

1. Build Error Investigation

2. Runtime Issue Investigation

3. Performance Analysis

4. Component Behavior Analysis

5. Pre-Simulation Analysis

6. Simulation Monitoring

7. Performance Investigation

8. Component Analysis

📈 Simulation Data Interpretation

Flow Analysis

Pressure Analysis

Pump Performance

🚨 Enhanced Troubleshooting Guide (NEW)

Process Management Issues

Build Problems

Debug Console Issues

Connection Issues

Simulation Issues

Data Inconsistencies

💡 Enhanced Best Practices (NEW)

Token Efficiency

Development Workflow

Debug Search Patterns

Efficient Monitoring

Data Analysis

Documentation

Safety

13 KiB

Raw Blame History