CtrEditor/Documentation/MCP/MCP.md

# CtrEditor MCP Server Documentation

## 🎯 Overview

The CtrEditor MCP (Model Context Protocol) Server transforms the CtrEditor WPF application into a programmable automation platform for debugging, testing, and simulation control. This server enables remote control of all major application features through JSON-RPC style communication.

## 🚀 Architecture

### Communication Flow
```
LLM/Client ↔ MCP Proxy (Python) ↔ CtrEditor MCP Server (C#) ↔ WPF Application
```

### Connection Setup
- **Protocol**: TCP Socket on port 5006
- **Format**: JSON-RPC style messages
- **Proxy**: Python proxy for VS Code Copilot integration

### VS Code Configuration
```json
"ctreditor": {
    "command": "C:/Users/migue/miniconda3/envs/mcp_proxy/python.exe",
    "args": [
        "d:/Proyectos/Scripts/MCP_Proxy/mcp_proxy.py",
        "--host", "localhost",
        "--port", "5006",
        "--name", "CtrEditor",
        "--description", "CtrEditor WPF Application MCP Server for debugging and testing"
    ]
}
```

## 📋 Available Tools

### 🔧 Object Management

#### `list_objects`
**Description**: Get complete list of all simulation objects  
**Parameters**: None  
**Returns**: Array of objects with full metadata (ID, name, type, position, properties)

#### `create_object`
**Description**: Create a new simulation object  
**Parameters**:
- `type` (string): Object type (e.g., "osHydTank", "osHydPump")
- `x` (number): X position in meters
- `y` (number): Y position in meters

#### `update_object`
**Description**: Modify properties of existing object  
**Parameters**:
- `id` (string): Object ID
- `properties` (object): JSON object with properties to update

#### `delete_objects`
**Description**: Remove objects from simulation  
**Parameters**:
- `ids` (array): Array of object IDs to delete

#### `list_object_types`
**Description**: Get list of all creatable object types  
**Parameters**: None

### ⚙️ Simulation Control

#### `start_simulation`
**Description**: Start the physics simulation  
**Parameters**: None

#### `stop_simulation`
**Description**: Stop the physics simulation  
**Parameters**: None

#### `get_simulation_status`
**Description**: Get current simulation state  
**Parameters**: None  
**Returns**: Status info (running, object count, etc.)

### 🔌 PLC Integration

#### `get_plc_status`
**Description**: Get PLC connection status  
**Parameters**: None  
**Returns**: Connection state and status information

### 📸 Visual Documentation

#### `take_screenshot`
**Description**: Capture canvas screenshot with high resolution  
**Parameters** (all optional):
- `x` (number): X position in meters for partial capture
- `y` (number): Y position in meters for partial capture  
- `width` (number): Width in meters for partial capture
- `height` (number): Height in meters for partial capture
- `include_background` (boolean): Include canvas background (default: false)

**Features**:
- **High Resolution**: 2x scale for full canvas, 3x for partial captures
- **Auto-Directory**: Saves to `/screenshots/` subdirectory
- **Detailed Response**: File size, dimensions, timestamps, paths

### 💾 Project Management

#### `save_project`
**Description**: Save current project state  
**Parameters**: None

## 🎨 Key Features

### 📊 Rich Object Information
- **Complete Properties**: All object properties in JSON format
- **Simulation Data**: Real-time physics and hydraulic states
- **Coordinate System**: All positions in engineering meters
- **Type Safety**: Full .NET type information preserved

### 🖼️ Advanced Screenshots
- **Meter-Based Coordinates**: Natural engineering units
- **High Resolution**: Anti-aliased, print-quality images
- **Flexible Areas**: Full canvas or custom rectangular regions
- **Background Control**: With/without canvas background

### 🔄 Real-Time Monitoring
- **Live Updates**: Monitor simulation state changes
- **Property Tracking**: Observe dynamic property changes during simulation
- **Performance Data**: Track flow rates, pressures, speeds, etc.

### 🛡️ Error Handling
- **Detailed Errors**: Comprehensive error messages with context
- **Safe Operations**: Thread-safe UI operations via Dispatcher
- **Graceful Degradation**: Handles connection issues and timeouts

## 🎯 Use Cases

### 🔬 Simulation Debugging
1. **Pre-Simulation**: Inspect object configurations and positions
2. **Runtime Monitoring**: Track dynamic properties during simulation
3. **Post-Analysis**: Compare before/after states
4. **Visual Verification**: Screenshot specific areas for documentation

### 🤖 Automated Testing
- **Regression Testing**: Verify simulation behavior consistency
- **Performance Benchmarking**: Monitor simulation performance metrics
- **Configuration Validation**: Ensure proper object setup
- **Visual Regression**: Compare screenshots across versions

### 📚 Documentation Generation
- **Auto-Documentation**: Extract object configurations automatically
- **Visual Documentation**: Generate annotated screenshots
- **State Reports**: Create detailed simulation state reports
- **Training Materials**: Generate step-by-step simulation guides

## 🔧 Technical Implementation

### Core Components
- **MCPServer.cs**: Main TCP server with JSON-RPC handling
- **Tool Handlers**: Specialized handlers for each operation type
- **Thread Safety**: UI operations via WPF Dispatcher
- **Error Management**: Comprehensive exception handling

### Performance Optimizations
- **Lazy Connection**: Connect only when needed
- **Efficient Serialization**: Optimized JSON generation
- **Memory Management**: Proper resource cleanup
- **High-Resolution Rendering**: Optimized screenshot generation

### Security Considerations
- **Local-Only**: Bound to localhost for security
- **No File System Access**: Limited to application operations
- **Controlled Operations**: No dangerous system operations
- **Sandboxed**: Isolated from system configuration