Sketchup-Booth-Designer/docs/INSTALL.md

Installation Guide

Prerequisites

Requirement	Version	Notes
FreeCAD	1.0+	freecad.org — select Windows (64-bit) installer
Node.js	18+	nodejs.org
npm	9+	Ships with Node.js
Git	—	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
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

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:

   node dist/server.js
   

   Verify it starts without errors.

Step 3: Install ExpolincLib

# 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

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):

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

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:

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

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

"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