CtrEditor/Documentation/MCP/MCP_LLM_Guide.md

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

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

📊 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

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

🚨 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