Sketchup-Booth-Designer/docs/INSTALL.md

# Installation Guide

## Prerequisites

| Requirement | Version | Notes |
|---|---|---|
| **FreeCAD** | 1.0+ | [freecad.org](https://freecad.org) — select Windows (64-bit) installer |
| **Node.js** | 18+ | [nodejs.org](https://nodejs.org) |
| **npm** | 9+ | Ships with Node.js |
| **Git** | — | [git-scm.com](https://git-scm.com) |
| **AI Assistant** | — | Claude Desktop, Claude Code, or any MCP-compatible client |

## Step 1: Install FreeCAD

1. Download FreeCAD 1.0+ from [freecad.org](https://freecad.org/downloads)
2. Run the installer (default options are fine)
3. Verify installation:
   ```
   "C:\Program Files\FreeCAD 1.0\bin\FreeCAD.exe" --version
   ```
4. Note your FreeCAD user data directory (for adding the ExpolincLib module):
   - Windows: `%APPDATA%\FreeCAD\Mod\`
   - Linux: `~/.local/share/FreeCAD/Mod/`
   - macOS: `~/Library/Application Support/FreeCAD/Mod/`

## Step 2: Install the freecad-mcp Base Server

```bash
git clone https://github.com/sergiudanstan/freecad-mcp.git
cd freecad-mcp
npm install
npm run build
```

Test that it can connect to FreeCAD:
1. Start FreeCAD
2. In FreeCAD, go to **Tools → Addon Manager** and install the freecad-mcp workbench
3. Activate the freecad-mcp workbench from the workbench dropdown
4. Click **Start Server** — you should see: `MCP server listening on port 12345`
5. Back in the terminal:
   ```bash
   node dist/server.js
   ```
   Verify it starts without errors.

## Step 3: Install ExpolincLib

```bash
# Clone the Expolinc Booth Designer repository
git clone https://github.com/your-org/expolinc-booth-designer.git
cd expolinc-booth-designer

# Copy the component library to FreeCAD's Mod directory
# Windows:
copy ExpolincLib "%APPDATA%\FreeCAD\Mod\ExpolincLib\"

# Linux:
# cp -r ExpolincLib ~/.local/share/FreeCAD/Mod/ExpolincLib/

# macOS:
# cp -r ExpolincLib ~/"Library/Application Support/FreeCAD/Mod/ExpolincLib/"
```

Restart FreeCAD. You should see "ExpolincLib" listed in the **Macro → Macros...** menu as available modules.

## Step 4: Install the MCP Server Extension

```bash
cd mcp-server
npm install
npm run build
```

## Step 5: Configure Your AI Assistant

### Claude Desktop

Edit `claude_desktop_config.json` (`%APPDATA%\Claude\` on Windows, `~/Library/Application Support/Claude/` on macOS):

```json
{
  "mcpServers": {
    "expolinc": {
      "command": "node",
      "args": [
        "C:\\path\\to\\expolinc-booth-designer\\mcp-server\\dist\\server.js"
      ],
      "env": {
        "FREECAD_MCP_PORT": "12345",
        "EXPOLINC_LIB_PATH": "ExpolincLib"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add expolinc node /path/to/expolinc-booth-designer/mcp-server/dist/server.js
```

### VS Code / GitHub Copilot

Add to `.vscode/settings.json` or `.github/copilot/mcp.json`:

```json
{
  "mcpServers": {
    "expolinc": {
      "command": "node",
      "args": ["/path/to/expolinc-booth-designer/mcp-server/dist/server.js"],
      "env": {
        "FREECAD_MCP_PORT": "12345",
        "EXPOLINC_LIB_PATH": "ExpolincLib"
      }
    }
  }
}
```

## Step 6: Verify Installation

1. Start FreeCAD and activate the freecad-mcp workbench → **Start Server**
2. Restart your AI assistant
3. Ask:
   > *"List available Expolinc systems and components"*

   The assistant should call `expolinc_info` and return details about Classic Frame and Light Frame.

4. Try a simple command:
   > *"Create a single 1950×2500mm Classic Frame wall"*

   The wall should appear in FreeCAD's 3D viewport.

## Windows-Specific Notes

### FreeCAD Installation Paths

Common FreeCAD installation paths on Windows:

| Version | Path |
|---|---|
| FreeCAD 1.0 | `C:\Program Files\FreeCAD 1.0\bin\FreeCAD.exe` |
| FreeCAD 1.1 | `C:\Program Files\FreeCAD 1.1\bin\FreeCAD.exe` |

### FreeCAD Mod Directory

```
%APPDATA%\FreeCAD\Mod\
# Typically resolves to:
C:\Users\<YourUsername>\AppData\Roaming\FreeCAD\Mod\
```

### Environment Variables

The MCP server needs to know where FreeCAD is. If automatic detection fails, set:

```json
"env": {
  "FREECAD_PATH": "C:\\Program Files\\FreeCAD 1.0\\bin",
  "FREECAD_MCP_PORT": "12345",
  "EXPOLINC_LIB_PATH": "ExpolincLib"
}
```

## Headless Mode (Optional)

For batch operations without the FreeCAD GUI, configure the MCP server to use `freecadcmd`:

```json
"env": {
  "USE_HEADLESS": "true",
  "FREECADCMD_PATH": "C:\\Program Files\\FreeCAD 1.0\\bin\\freecadcmd.exe",
  "EXPOLINC_LIB_PATH": "ExpolincLib"
}
```

## Troubleshooting

| Problem | Solution |
|---|---|
| **"Cannot connect to FreeCAD"** | Ensure FreeCAD is running and the freecad-mcp workbench server is started (click **Start Server**) |
| **"ExpolincLib not found"** | Verify ExpolincLib was copied to the correct Mod directory. Check `%APPDATA%\FreeCAD\Mod\ExpolincLib\` |
| **MCP tool not found** | Restart the AI assistant after adding the MCP configuration |
| **Wall positions wrong** | The layout engine uses the 990mm grid (standard exhibition grid). Specify dimensions in multiples of 990mm when possible |
| **Port conflict** | Change `FREECAD_MCP_PORT` in environment variables if port 12345 is already in use |