Sketchup-Booth-Designer/docs/MCP_TOOLS.md

# MCP Tools Reference

## Overview

The Expolinc Booth Designer extends the sergiudanstan/freecad-mcp server with **12 custom MCP tools** for designing trade fair booths using Expolinc modular systems. These tools work alongside the server's 165 built-in CAD tools.

## Quick Reference

| Tool | Purpose |
|---|---|
| `expolinc_info` | List available systems, sizes, and components |
| `expolinc_create_wall` | Create a single Classic Frame or Light Frame wall |
| `expolinc_create_corner` | Create a corner connector |
| `expolinc_create_storage` | Create a storage room enclosure |
| `expolinc_create_door` | Add a door to an existing wall |
| `expolinc_build_booth` | Build a complete booth from a layout spec |
| `expolinc_arrange_layout` | Adjust positions of existing wall components |
| `expolinc_add_light_frame` | Convert a wall section to backlit |
| `expolinc_export_bom` | Export bill of materials (CSV/JSON/Spreadsheet) |
| `expolinc_export_step` | Export complete booth as STEP file |
| `expolinc_export_drawing` | Generate dimensioned technical drawing |
| `expolinc_get_component_info` | Get detailed specs for a placed component |

---

## Tool Reference

### `expolinc_info`

Returns available Expolinc systems, component types, and valid size options.

**Parameters:** None

**Example:**
```
User: "What Expolinc components are available?"
Assistant: → calls expolinc_info
```

**Response:**
```json
{
  "systems": {
    "classic_frame": {
      "description": "Modular aluminum frame with SEG fabric graphics",
      "available_widths_mm": [500, 950, 1950, 2950, 3950, 4950],
      "available_heights_mm": [2500, 3000],
      "features": ["tool_free_assembly", "magnetic_connectors", "double_sided"],
      "weight_kg": {"1950x2500": 14.5, "4950x2500": 25.0, ...}
    },
    "light_frame": {
      "description": "Backlit LED frame system, integrates with Classic Frame",
      "available_widths_mm": [500, 950, 1950, 2950, 3950, 4950],
      "available_heights_mm": [2500, 3000],
      "led_options": {"temperature_K": [2700, 3000, 4000, 5000, 6500], "brightness_lm": "500-3000"}
    }
  },
  "accessories": ["storage_room", "door", "shelf", "bridge_connector"],
  "connectors": ["90_degree", "180_inline", "T_connector"],
  "transport_cases": ["basic_box", "travel_set", "standard_case_xl"]
}
```

---

### `expolinc_create_wall`

Creates a single Expolinc wall (Classic Frame or Light Frame) at a specified position.

**Parameters:**

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `width` | number | yes | — | Wall width in mm (500/950/1950/2950/3950/4950) |
| `height` | number | yes | — | Wall height in mm (2500/3000) |
| `system` | string | no | `"classic_frame"` | `"classic_frame"` or `"light_frame"` |
| `position` | object | no | `{"x":0,"y":0,"z":0}` | Wall position (mm) |
| `rotation` | number | no | `0` | Rotation about Z axis in degrees |
| `double_sided` | boolean | no | `false` | Graphic on both sides |
| `finish` | string | no | `"silver"` | Profile finish: `"silver"`, `"white"`, `"black"` |
| `led_temperature` | number | no | `4000` | LED temp in Kelvin (Light Frame only) |
| `led_brightness` | number | no | `1000` | LED brightness in lumens (Light Frame only) |

**Example:**
```
User: "Create a 3950×2500mm Classic Frame wall at position x=0, y=0"
```

**Response:**
```json
{
  "success": true,
  "component_id": "wall_01",
  "type": "classic_frame",
  "system": "classic_frame",
  "width_mm": 3950,
  "height_mm": 2500,
  "weight_kg": 20.4,
  "position": {"x": 0, "y": 0, "z": 0},
  "document": "Booth_001"
}
```

---

### `expolinc_create_corner`

Creates a corner connector.

**Parameters:**

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `angle` | number | no | `90` | Connector angle in degrees (45/90/180) |
| `connector_type` | string | no | `"90_degree"` | `"90_degree"`, `"180_inline"`, `"T_connector"` |
| `position` | object | no | `{"x":0,"y":0,"z":0}` | Position (mm) |

---

### `expolinc_create_storage`

Creates a storage room enclosure.

**Parameters:**

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `width` | number | yes | — | Room width in mm |
| `depth` | number | yes | — | Room depth in mm |
| `height` | number | no | `2500` | Room height in mm |
| `has_door` | boolean | no | `true` | Include door |
| `door_type` | string | no | `"hinged"` | `"hinged"`, `"sliding"` |
| `has_shelving` | boolean | no | `false` | Include shelves |
| `wall_position` | string | no | `"back"` | Which wall to attach to |

---

### `expolinc_create_door`

Adds a door to an existing wall.

**Parameters:**

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `wall_id` | string | yes | — | Component ID of the target wall |
| `width` | number | no | `900` | Door width in mm |
| `height` | number | no | `2200` | Door height in mm |
| `type` | string | no | `"hinged"` | `"hinged"`, `"sliding"`, `"pocket"` |
| `position` | number | no | `"center"` | Horizontal position along wall |

---

### `expolinc_build_booth` (Main Tool)

Builds a complete trade fair booth from a layout specification. This is the primary tool for booth design.

**Parameters:**

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `layout` | string | yes | — | Layout type: `"inline"`, `"corner"`, `"peninsula"`, `"island"`, `"custom"` |
| `width` | number | yes | — | Booth width in mm (inline/peninsula/island) |
| `depth` | number | yes | — | Booth depth in mm (inline/peninsula/island) |
| `height` | number | no | `2500` | Wall height in mm |
| `system` | string | no | `"classic_frame"` | Default wall system |
| `backlit_walls` | number[] | no | `[]` | Wall indices to make backlit (0-indexed) |
| `storage_rooms` | object[] | no | `[]` | Storage room configuration |
| `double_sided` | number[] | no | `[]` | Wall indices to make double-sided |
| `finish` | string | no | `"silver"` | Profile finish |
| `custom_walls` | object[] | no | — | Custom wall definitions (for `custom` layout) |
| `add_connectors` | boolean | no | `true` | Auto-add connectors |
| `name` | string | no | `"Booth"` | Document name |

**Layout-specific wall generation:**

| Layout | Walls Generated | Open Sides |
|---|---|---|
| `inline` | 1 back wall + 2 partial side walls | 1 (front) |
| `corner` | 2 walls at 90° | 2 |
| `peninsula` | 3 walls (U-shape) | 1 (front) |
| `island` | 4 walls (rectangle) | 0 (all sides open) |

**storage_rooms format:**
```json
[
  {
    "wall_index": 0,
    "width": 1950,
    "depth": 1000,
    "has_door": true,
    "door_type": "hinged",
    "has_shelving": true
  }
]
```

**custom_walls format (for layout="custom"):**
```json
[
  {
    "width": 3950,
    "height": 2500,
    "system": "classic_frame",
    "position": {"x": 0, "y": 0, "z": 0},
    "rotation": 0,
    "backlit": false,
    "double_sided": false
  }
]
```

**Example:**
```
User: "Build a 6x4 meter island booth with 2.5m walls, backlit sections on the front and back, and a storage room on the right wall"
Assistant: → calls expolinc_build_booth with:
  layout="island", width=6000, depth=4000, height=2500,
  backlit_walls=[0, 2],
  storage_rooms=[{"wall_index":1, "width":1950, "depth":1000, "has_door":true}]
```

**Response:**
```json
{
  "success": true,
  "document": "Booth_Island_6x4",
  "layout": "island",
  "dimensions": {"width_mm": 6000, "depth_mm": 4000, "height_mm": 2500},
  "walls": [
    {"id": "wall_00", "width": 6000, "height": 2500, "system": "classic_frame", "backlit": true},
    {"id": "wall_01", "width": 4000, "height": 2500, "system": "classic_frame", "has_storage": true},
    {"id": "wall_02", "width": 6000, "height": 2500, "system": "classic_frame", "backlit": true},
    {"id": "wall_03", "width": 4000, "height": 2500, "system": "classic_frame"}
  ],
  "connectors": 4,
  "components": [
    {"id": "conn_00", "type": "90_degree", "between": ["wall_00", "wall_01"]},
    {"id": "conn_01", "type": "90_degree", "between": ["wall_01", "wall_02"]},
    {"id": "conn_02", "type": "90_degree", "between": ["wall_02", "wall_03"]},
    {"id": "conn_03", "type": "90_degree", "between": ["wall_03", "wall_00"]},
    {"id": "storage_00", "type": "storage_room", "attached_to": "wall_01"}
  ],
  "bom_preview": {
    "component_count": 12,
    "total_weight_kg": 110.2,
    "seg_area_m2": 48.5
  }
}
```

---

### `expolinc_arrange_layout`

Adjust the positions and orientations of existing components in the booth.

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `positions` | object[] | yes | Array of `{component_id, position: {x,y,z}, rotation}` |

---

### `expolinc_add_light_frame`

Converts an existing Classic Frame wall to a Light Frame (backlit) wall, replacing the graphic panel with an LED panel assembly.

**Parameters:**

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `wall_id` | string | yes | — | ID of the wall to convert |
| `led_temperature` | number | no | `4000` | LED temperature in Kelvin |
| `led_brightness` | number | no | `1000` | Brightness in lumens |

---

### `expolinc_export_bom`

Exports the bill of materials for the current booth design.

**Parameters:**

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `format` | string | no | `"json"` | Output format: `"json"`, `"csv"`, `"spreadsheet"` |
| `filepath` | string | no | — | Optional file path for CSV/JSON output |

**Response (JSON format):**
```json
{
  "project": "Booth_Island_6x4",
  "layout": "island",
  "dimensions": {"width_mm": 6000, "depth_mm": 4000, "height_mm": 2500},
  "components": [
    {"component": "Classic Frame Wall 6000×2500mm", "system": "classic_frame", "qty": 2, "weight_kg": 30.0, "total_kg": 60.0},
    {"component": "Classic Frame Wall 4000×2500mm", "system": "classic_frame", "qty": 2, "weight_kg": 22.0, "total_kg": 44.0},
    {"component": "Light Frame Conversion 6000×2500mm", "system": "light_frame", "qty": 2, "weight_kg": 5.0, "total_kg": 10.0},
    {"component": "90° Corner Connector", "system": "connector", "qty": 4, "weight_kg": 1.5, "total_kg": 6.0},
    {"component": "Support Feet (pair)", "system": "accessory", "qty": 8, "weight_kg": 0.8, "total_kg": 6.4},
    {"component": "Storage Room 1950×1000×2500mm", "system": "accessory", "qty": 1, "weight_kg": 35.0, "total_kg": 35.0}
  ],
  "totals": {
    "component_count": 19,
    "total_weight_kg": 161.4,
    "seg_area_m2": 48.0,
    "walls_light_frame": 2,
    "transport_cases": [
      {"type": "Standard Case XL", "quantity": 3}
    ],
    "estimated_setup_time_minutes": 45
  }
}
```

---

### `expolinc_export_step`

Exports the complete booth assembly as a STEP file.

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `filepath` | string | yes | Output file path (absolute or relative) |

---

### `expolinc_export_drawing`

Generates a dimensioned technical drawing using FreeCAD's TechDraw workbench.

**Parameters:**

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `format` | string | no | `"pdf"` | Output format: `"pdf"`, `"svg"` |
| `filepath` | string | yes | — | Output file path |
| `views` | string[] | no | `["front","top","right","isometric"]` | Views to include |
| `include_dimensions` | boolean | no | `true` | Include dimension annotations |

---

### `expolinc_get_component_info`

Returns detailed specifications and metadata for a placed component.

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `component_id` | string | yes | ID of the component to inspect |

---

## Built-in Tools (from freecad-mcp)

The following built-in tools are especially useful when working with Expolinc booths:

| Module | Key Tools |
|---|---|
| **Document** | New, open, save, close, list objects |
| **Import/Export** | STEP, STL, OBJ, DXF, IFC import/export |
| **BIM** | Walls, slabs (for flooring), spaces (for volume calculation) |
| **TechDraw** | Drawing pages, views, dimensions, SVG/PDF export |
| **Spreadsheet** | Create, set cells, formulas (for BOM data) |
| **Part** | Move, rotate, copy, mirror (for manual adjustment) |

## Error Handling

All Expolinc tools return structured error responses:

```json
{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Invalid wall width: 5000mm. Valid widths: 500, 950, 1950, 2950, 3950, 4950mm",
  "details": {
    "field": "width",
    "value": 5000,
    "allowed_values": [500, 950, 1950, 2950, 3950, 4950]
  }
}
```