initial checkin

2026-09-29 09:44:16 +00:00
commit 01569b00b5
7 changed files with 1701 additions and 0 deletions
@@ -0,0 +1,187 @@
+# 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 |