CtrEditor/Documentation/MCP/MCP_LLM_Guide.md

# CtrEditor MCP Server - LLM Guide

*MCP 2025-06-18 compliant | Compatible: Claude Desktop + Cursor*

## ⚡ 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)
- `execute_python` → 50-500 tokens (depends on script)
- `python_help` → 100-300 tokens

### 🔴 **Heavy** (Use Sparingly)
- `list_objects` → 500-2000+ tokens
- `take_screenshot` → 100-300 tokens + file

## 🔧 Core Operations

### Process Management
```json
{"tool": "start_ctreditor", "parameters": {}}
{"tool": "get_ctreditor_status", "parameters": {}}
{"tool": "stop_ctreditor", "parameters": {}}
```

### Build & Debug
Para los Debug se usa DebugTraceListener que es soportado por WPF
```json
{"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
```json
{"tool": "get_simulation_status", "parameters": {}}
{"tool": "start_simulation", "parameters": {}}
{"tool": "stop_simulation", "parameters": {}}
```

### Object Management
```json
{"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"]}}
```

### Python Debug Scripts ⚡ NEW
```json
{"tool": "execute_python", "parameters": {"code": "print(f'Total objects: {len(objects)}')"}}
{"tool": "execute_python", "parameters": {
  "code": "result = [obj for obj in objects if 'Pump' in str(type(obj))]",
  "return_variables": ["result"]
}}
{"tool": "python_help", "parameters": {"object_name": "app"}}
```

## ⚡ Optimal Workflows

### Quick Development Cycle
```json
{"tool": "get_ctreditor_status", "parameters": {}}
{"tool": "build_project", "parameters": {}}
{"tool": "start_simulation", "parameters": {}}
{"tool": "execute_python", "parameters": {"code": "print(f'Objects: {len(objects)}, Running: {app.IsSimulationRunning}')"}}
{"tool": "get_simulation_status", "parameters": {}}
```

### Bug Investigation
```json
{"tool": "search_debug_log", "parameters": {"pattern": "error|exception", "max_lines": 3}}
{"tool": "execute_python", "parameters": {"code": "print([type(obj).__name__ for obj in objects[:5]])"}}
{"tool": "get_simulation_status", "parameters": {}}
```

### System Recovery
```json
{"tool": "stop_ctreditor", "parameters": {}}
{"tool": "start_ctreditor", "parameters": {}}
```

## 📊 Key Object Properties

### Python Debug Variables
- **app**: MainViewModel (simulation state, canvas, objects)
- **canvas**: MainCanvas (Width, Height, visual elements)
- **objects**: ObservableCollection of all simulable objects
- **get_objects()**: Returns List<object> for easier manipulation

### 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
```json
{"tool": "take_screenshot", "parameters": {}}
```

### Targeted Area
```json
{"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)

## 🐍 Python Debug Examples

### Quick Inspections
```python
# Object count by type
types = {}
for obj in objects:
    t = type(obj).__name__
    types[t] = types.get(t, 0) + 1
print(types)

# Canvas info
print(f"Canvas: {canvas.Width}x{canvas.Height}")
print(f"Simulation: {app.IsSimulationRunning}")

# Find specific objects
pumps = [obj for obj in objects if 'Pump' in str(type(obj))]
print(f"Found {len(pumps)} pumps")
```

## 🚨 Troubleshooting

### Build Issues
```json
{"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

### MCP Client Issues
- **Red LED in Cursor**: Proxy now handles all standard MCP methods correctly
- **Connection timeout**: CtrEditor must be running for tool calls to work
- **Build errors**: Use `build_project` to see only error output

## 💡 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
- **NEW**: Use `execute_python` for quick object inspections instead of `list_objects`
- Stop simulation before major structural changes
- Use appropriate units: meters, Pascal, m³/s
- **Python scripts**: Keep under 30 seconds, use `return_variables` for results
- Proxy works with both Claude Desktop and Cursor (MCP 2025-06-18)