Miguel
/
CtrEditor
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
CtrEditor/Documentation/MCP/MCP_LLM_Guide_Original.md

24 KiB
Raw Blame History

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

<EFBFBD> Core Operations

Process Management

{"tool": "start_ctreditor", "parameters": {}}
{"tool": "get_ctreditor_status", "parameters": {}}
{"tool": "stop_ctreditor", "parameters": {}}

Build & Debug

{"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

{"tool": "get_simulation_status", "parameters": {}}
{"tool": "start_simulation", "parameters": {}}
{"tool": "stop_simulation", "parameters": {}}

Object Management

{"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

{"tool": "get_ctreditor_status", "parameters": {}}
{"tool": "build_project", "parameters": {}}
{"tool": "start_simulation", "parameters": {}}
{"tool": "get_simulation_status", "parameters": {}}

Bug Investigation

{"tool": "search_debug_log", "parameters": {"pattern": "error|exception", "max_lines": 3}}
{"tool": "get_simulation_status", "parameters": {}}

System Recovery

{"tool": "stop_ctreditor", "parameters": {}}
{"tool": "start_ctreditor", "parameters": {}}

🎯 Micro-Workflows (Ultra-Efficient)

Instant Status Check (1-2 seconds, <50 tokens)

{"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)

{"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)

{"tool": "get_simulation_status", "parameters": {}}

Check object_count property instead of calling list_objects

Efficient Build Verification (5-10 seconds, filtered output)

{"tool": "build_project", "parameters": {}}

Only returns errors - ignores verbose build output

<EFBFBD> Optimized Recovery Patterns

Process Recovery (Fast)

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

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

{"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

{"tool": "take_screenshot", "parameters": {}}

Targeted Area

{"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)

<EFBFBD> Troubleshooting

Build Issues

{"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):

{"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:

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

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

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

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

<EFBFBD>🚨 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:

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

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

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

{"tool": "get_simulation_status", "parameters": {}}

Returns: running state, object count, visibility in minimal tokens

Smart Error Detection (5-10 seconds)

{"tool": "search_debug_log", "parameters": {
  "pattern": "error|exception|fail",
  "max_lines": 3
}}

Targeted error search instead of full console dump

Efficient Object Management

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

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

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

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

{"tool": "get_ctreditor_status", "parameters": {}}
// If not running:
{"tool": "start_ctreditor", "parameters": {}}

Simulation Recovery (3 seconds)

{"tool": "stop_simulation", "parameters": {}}
{"tool": "start_simulation", "parameters": {}}

Debug Recovery (2 seconds)

{"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)

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

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

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

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

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