docs: FreeCAD wiki updates for three macros (#18)

* docs: FreeCAD wiki updates for three macros

* Fix macro and wiki metadata

* fix: minor bugs in CutObjectForMagnets macro

1. Redundant distToShape call (lines 864-868)
Issue: The _get_inset_point method computed dist_info = cut_face.distToShape(Part.Vertex(inset_point)) at line 841, but then called distToShape again at line 867 with the same arguments.
Fix: Removed the redundant call and reused the already-computed dist_info result.

2. Redundant hide transaction in main() (lines 1907-1914)
Issue: main() had a "Transaction 7: Hide original object" that duplicated the hiding logic already in execute() Transaction 8 (lines 1391-1412). Additionally, the main() version had worse error handling (re-raised exceptions instead of gracefully continuing).
Fix: Removed the redundant transaction block from main(). The execute() method's Transaction 8 already handles hiding the original object properly with graceful error handling.

.github/workflows/macro-release.yaml

@@ -35,6 +35,29 @@ jobs:
 
           echo "Packaging macros for version: $VERSION"
 
+      - name: Update macro versions
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          TODAY=$(date +%Y-%m-%d)
+
+          echo "Updating macros to version: $VERSION (date: $TODAY)"
+
+          # Update __Version__ and __Date__ in all .FCMacro files
+          for macro_file in macros/*/*.FCMacro; do
+              if [ -f "$macro_file" ]; then
+                  echo "Updating: $macro_file"
+
+                  # Update __Version__ line (handles both single and double quotes)
+                  sed -i "s/^__Version__ = [\"'].*[\"']/__Version__ = \"${VERSION}\"/" "$macro_file"
+
+                  # Update __Date__ line (handles both single and double quotes)
+                  sed -i "s/^__Date__ = [\"'].*[\"']/__Date__ = \"${TODAY}\"/" "$macro_file"
+
+                  # Verify the changes
+                  grep -E "^__(Version|Date)__" "$macro_file" || true
+              fi
+          done
+
       - name: Create macro archive
         run: |
           VERSION="${{ steps.version.outputs.version }}"

macros/Cut_Object_for_Magnets/CutObjectForMagnets.FCMacro

@@ -6,8 +6,6 @@ Copyright (c) 2025 Sean P. Kane (GitHub: spkane)
 Cuts an object along a plane and adds connector holes for magnets with
 surface collision detection.
 
-Version: 1.0.0
-
 Requirements:
     - FreeCAD 0.19 or later
     - An object selected in the 3D view
@@ -19,6 +17,22 @@ Usage:
     4. Click "Execute Cut"
 """
 
+# FreeCAD Addon Manager metadata
+__Name__ = "Cut Object for Magnets"
+__Comment__ = "Cut an object along a plane and add aligned magnet holes with surface collision detection"
+__Author__ = "Sean P. Kane"
+__Version__ = "0.5.0-beta"
+__Date__ = "2026-01-05"
+__License__ = "MIT"
+__Web__ = "https://github.com/spkane/freecad-robust-mcp-and-more"
+__Wiki__ = "https://github.com/spkane/freecad-robust-mcp-and-more#readme"
+__Icon__ = ""
+__Help__ = "Select an object to cut, run the macro, configure cut plane and magnet hole parameters, then click Execute Cut. Creates two parts with aligned magnet holes."
+__Status__ = "Beta"
+__Requires__ = "FreeCAD 0.19+"
+__Communication__ = "https://github.com/spkane/freecad-robust-mcp-and-more/issues"
+__Files__ = ""
+
 import FreeCAD as App
 import FreeCADGui as Gui
 import Part
@@ -848,9 +862,9 @@ class SmartCutter:
                 closest_on_face = dist_info[1][0][0]
                 return App.Vector(closest_on_face)
             else:
-                # Point is not on the face - for ring shapes, we may need
-                # to adjust. Try projecting directly onto the face.
-                dist_info = cut_face.distToShape(Part.Vertex(inset_point))
+                # Point is not on the face - for ring shapes, the inset point
+                # may land in the hole. Return the closest point on the face
+                # from the already-computed dist_info.
                 return App.Vector(dist_info[1][0][0])
         except Exception as e:
             App.Console.PrintWarning(f"Failed to validate inset point: {e}\n")
@@ -1888,16 +1902,7 @@ def main():
         bottom_body, top_body = cutter.execute(progress_update)
 
         # Bodies are already created in the document by execute()
-        # Just need to finalize and hide original
-
-        # Transaction 7: Hide original object
-        App.ActiveDocument.openTransaction("Hide Original Object")
-        try:
-            obj.ViewObject.Visibility = False
-            App.ActiveDocument.commitTransaction()
-        except Exception:
-            App.ActiveDocument.abortTransaction()
-            raise
+        # Original object is hidden in execute() Transaction 8
 
         App.ActiveDocument.recompute()
 

macros/Cut_Object_for_Magnets/wiki-source.txt

@@ -0,0 +1,209 @@
+<languages/>
+<translate>
+
+<!--T:1-->
+{{Macro
+|Name=Macro Cut Object for Magnets
+|Icon=Macro_Cut_Object_For_Magnets.png
+|Description=Cut an object along a plane and add aligned magnet holes with surface collision detection. Creates two parts with perfectly aligned holes for embedding magnets that allow the parts to snap together.
+|Author=Sean P. Kane
+|Version=0.5.0-beta
+|Date=2026-01-05
+|FCVersion=0.19+
+|Download=[https://wiki.freecad.org/images/thumb/e/e3/Macro_Cut_Object_For_Magnets.png/48px-Macro_Cut_Object_For_Magnets.png ToolBar Icon]
+|SeeAlso=[[Part_Slice|Part Slice]], [[PartDesign_Hole|PartDesign Hole]]
+}}
+
+==Description== <!--T:2-->
+
+<!--T:3-->
+This macro cuts a 3D object along a specified plane and automatically adds aligned magnet holes to both resulting pieces. The holes are positioned with intelligent collision detection to ensure they don't break through the outer walls of the object.
+
+<!--T:4-->
+This is particularly useful for:
+* Creating multi-part prints that snap together with embedded magnets
+* Splitting large objects for smaller 3D printer beds while maintaining alignment
+* Adding magnetic closure mechanisms to enclosures and cases
+
+<!--T:5-->
+'''Key Features:'''
+* Cut along preset planes (XY, XZ, YZ) or model datum planes
+* Automatic hole placement with even distribution along the cut edge
+* Surface collision detection prevents holes from breaking through walls
+* Configurable hole diameter, depth, and count
+* Preferred and minimum edge clearance settings
+* Smart repositioning of holes when initial placement fails safety checks
+* Creates PartDesign::Body objects with parametric Hole features
+* Supports re-cutting already-cut objects (preserves existing holes)
+* Automatically separates the two parts for easy viewing
+
+==Usage== <!--T:6-->
+
+<!--T:7-->
+# Open a document with the object you want to cut
+# Optionally select the object and/or a datum plane before running the macro
+# Run the macro from '''Macro → Macros → CutObjectForMagnets → Execute'''
+# In the dialog:
+#* Select the body to cut from the dropdown
+#* Choose the cut plane type (Preset or Model Plane)
+#* For preset planes, set the offset from origin
+#* Configure magnet hole parameters:
+#** '''Diameter''': Hole diameter (should match your magnet size)
+#** '''Depth''': Hole depth from cut surface
+#** '''Number of Holes''': Total holes to create
+#** '''Edge Clearance (Preferred)''': Ideal distance from hole edge to object surface
+#** '''Edge Clearance (Minimum)''': Minimum acceptable clearance
+# Click "Execute Cut"
+
+[[File:MacroCutObjectForMagnetsDialog.png|400px|center]]
+
+
+==Example== <!--T:8-->
+
+This image shows a vase object in its original form, and after being cut multiple times with the macro. Magnets can then be inserted to object, and the object can be re-assembled. This example was to create a "breakable" vase for a theatrical stage performance, but there are many other potential uses as well.
+
+[[File:CutObjectForMagnetsExample.png|400px|center]]
+
+==How It Works== <!--T:9-->
+
+<!--T:10-->
+'''Cutting Process:'''
+# Creates a large half-space box aligned with the cutting plane
+# Uses boolean operations to split the object into two parts
+# Creates PartDesign::Body containers for each half
+
+<!--T:11-->
+'''Hole Placement Algorithm:'''
+# Calculates hole positions evenly distributed along the cut face perimeter
+# For each position, validates against BOTH parts (not just one)
+# Uses preferred clearance first, falls back to minimum if needed
+# Checks for hole-to-hole spacing (minimum 2x diameter)
+# Repositions holes that fail safety checks using multiple strategies:
+#* Reduced clearance at same position
+#* Increased inset from edge
+#* Alternative positions along the perimeter
+
+<!--T:12-->
+'''Safety Features:'''
+* Creates test cylinders to check if holes would break through walls
+* Validates each hole against both the top and bottom parts
+* Skips holes that cannot be safely placed
+* Reports repositioned and skipped holes in the console
+
+==Parameters== <!--T:13-->
+
+<!--T:14-->
+{| class="wikitable"
+! Parameter !! Description !! Default
+|-
+| Plane Type || "Preset Plane" (XY/XZ/YZ) or "Model Plane" (datum plane) || Preset Plane
+|-
+| Offset || Distance from origin for preset planes || 0 mm
+|-
+| Diameter || Magnet hole diameter || 3 mm
+|-
+| Depth || Hole depth from cut surface || 3 mm
+|-
+| Number of Holes || Total holes to create || 6
+|-
+| Edge Clearance (Preferred) || Ideal distance from hole edge to object surface || 2 mm
+|-
+| Edge Clearance (Minimum) || Minimum acceptable clearance (used during repositioning) || 0.5 mm
+|}
+
+==Requirements== <!--T:15-->
+
+<!--T:16-->
+* FreeCAD 0.19 or later
+* An object with a solid shape (Part or PartDesign body)
+* For model plane mode: a datum plane or object with planar faces
+
+==Installation== <!--T:17-->
+
+<!--T:18-->
+# Download the macro file: [[Media:CutObjectForMagnets.FCMacro|CutObjectForMagnets.FCMacro]]
+# Copy the file to your FreeCAD macro directory:
+#* '''macOS''': {{FileName|~/Library/Application Support/FreeCAD/Macro/}}
+#* '''Linux''': {{FileName|~/.local/share/FreeCAD/Macro/}}
+#* '''Windows''': {{FileName|%APPDATA%/FreeCAD/Macro/}}
+# Optionally, download the toolbar icon and place it in the same directory
+
+==Tips== <!--T:19-->
+
+<!--T:20-->
+* '''Magnet sizing''': Measure your magnets carefully. Common sizes are 3mm, 5mm, and 6mm diameter.
+* '''Add tolerance''': Consider adding 0.1-0.2mm to the diameter for easier magnet insertion.
+* '''Depth planning''': Set hole depth slightly deeper than magnet height to ensure flush or recessed fit.
+* '''Edge clearance''': For thin-walled objects, reduce the preferred clearance but keep minimum clearance high enough to prevent wall breakthrough.
+* '''Re-cutting''': The macro detects existing magnet holes and preserves them when cutting already-cut parts.
+
+==Source Code== <!--T:21-->
+
+<!--T:22-->
+The full source code is hosted on GitHub:
+* [https://github.com/spkane/freecad-robust-mcp-and-more/blob/main/macros/Cut_Object_for_Magnets/CutObjectForMagnets.FCMacro CutObjectForMagnets.FCMacro on GitHub]
+* [https://github.com/spkane/freecad-robust-mcp-and-more GitHub Repository (freecad-robust-mcp-and-more)]
+
+==Script== <!--T:23-->
+
+<!--T:24-->
+ToolBar Icon [[Image:Macro_Cut_Object_For_Magnets.png]]
+
+</translate>
+
+'''Macro_Cut_Object_For_Magnets.FCMacro'''
+
+{{MacroCode|code=
+"""FreeCAD Macro: Cut Object for Magnets.
+
+SPDX-License-Identifier: MIT
+Copyright (c) 2025 Sean P. Kane (GitHub: spkane)
+
+Cuts an object along a plane and adds connector holes for magnets with
+surface collision detection.
+
+Requirements:
+    - FreeCAD 0.19 or later
+    - An object selected in the 3D view
+
+Usage:
+    1. Select the object to cut
+    2. Run the macro
+    3. Configure cut plane and hole parameters
+    4. Click "Execute Cut"
+"""
+
+# FreeCAD Addon Manager metadata
+__Name__ = "Cut Object for Magnets"
+__Comment__ = "Cut an object along a plane and add aligned magnet holes with surface collision detection"
+__Author__ = "Sean P. Kane"
+__Version__ = "0.5.0-beta"
+__Date__ = "2026-01-05"
+__License__ = "MIT"
+__Web__ = "https://github.com/spkane/freecad-robust-mcp-and-more"
+__Wiki__ = "https://github.com/spkane/freecad-robust-mcp-and-more#readme"
+__Icon__ = ""
+__Help__ = "Select an object to cut, run the macro, configure cut plane and magnet hole parameters, then click Execute Cut. Creates two parts with aligned magnet holes."
+__Status__ = "Beta"
+__Requires__ = "FreeCAD 0.19+"
+__Communication__ = "https://github.com/spkane/freecad-robust-mcp-and-more/issues"
+__Files__ = ""
+
+import FreeCAD as App
+import FreeCADGui as Gui
+import Part
+from PySide import QtGui
+
+# ... (full macro code continues - see GitHub repository for complete source)
+# https://github.com/spkane/freecad-robust-mcp-and-more/blob/main/macros/Cut_Object_for_Magnets/CutObjectForMagnets.FCMacro
+}}
+
+==Links== <!--T:25-->
+
+<!--T:26-->
+* [[Part_Slice|Part Slice]] - FreeCAD's built-in slice tool
+* [[PartDesign_Hole|PartDesign Hole]] - Parametric hole feature documentation
+* [[PartDesign_Body|PartDesign Body]] - Body container documentation
+
+[[Category:Macros{{#translation:}}]]
+[[Category:User Documentation{{#translation:}}]]

macros/Multi_Export/MultiExport.FCMacro

@@ -6,10 +6,8 @@ Copyright (c) 2025 Sean P. Kane (GitHub: spkane)
 Export selected bodies to multiple file formats simultaneously with a
 user-friendly dialog for format selection and output configuration.
 
-Version: 1.0.0
-
 Requirements:
-    - FreeCAD 0.19 or later
+    - FreeCAD 0.21 or later
     - One or more objects selected in the 3D view
 
 Usage:
@@ -20,6 +18,22 @@ Usage:
     5. Click "Export"
 """
 
+# FreeCAD Addon Manager metadata
+__Name__ = "Multi Export"
+__Comment__ = "Export selected bodies to multiple file formats (STL, STEP, 3MF, OBJ, IGES, BREP, PLY, AMF) simultaneously"
+__Author__ = "Sean P. Kane"
+__Version__ = "0.5.0-beta"
+__Date__ = "2026-01-05"
+__License__ = "MIT"
+__Web__ = "https://github.com/spkane/freecad-robust-mcp-and-more"
+__Wiki__ = "https://github.com/spkane/freecad-robust-mcp-and-more#readme"
+__Icon__ = ""
+__Help__ = "Select one or more objects, run the macro, choose export formats and output location, then click Export."
+__Status__ = "Beta"
+__Requires__ = "FreeCAD 0.21+"
+__Communication__ = "https://github.com/spkane/freecad-robust-mcp-and-more/issues"
+__Files__ = ""
+
 import os
 
 import FreeCAD as App

macros/Multi_Export/wiki-source.txt

@@ -0,0 +1,175 @@
+<languages/>
+<translate>
+
+<!--T:1-->
+{{Macro
+|Name=Macro Multi Export
+|Icon=Macro_Multi_Export.png
+|Description=Export selected bodies to multiple file formats (STL, STEP, 3MF, OBJ, IGES, BREP, PLY, AMF) simultaneously with a user-friendly dialog for format selection and output configuration.
+|Author=Sean P. Kane
+|Version=0.5.0-beta
+|Date=2026-01-05
+|FCVersion=0.21+
+|Download=[https://wiki.freecad.org/images/thumb/1/19/Macro_Multi_Export.png/48px-Macro_Multi_Export.png ToolBar Icon]
+|SeeAlso=[[Std_Export|Std Export]], [[Import_Export|Import Export]]
+}}
+
+==Description== <!--T:2-->
+
+<!--T:3-->
+This macro provides a convenient way to export selected FreeCAD objects to multiple file formats at once. Instead of exporting to each format individually, you can select all desired formats in a single dialog and export them simultaneously.
+
+<!--T:4-->
+'''Supported Export Formats:'''
+* STL - Stereolithography (common for 3D printing)
+* STEP - Standard for Exchange of Product Data (CAD interchange)
+* 3MF - 3D Manufacturing Format (modern 3D printing format)
+* OBJ - Wavefront OBJ (3D graphics and game engines)
+* IGES - Initial Graphics Exchange Specification (legacy CAD format)
+* BREP - OpenCASCADE native format (preserves exact geometry)
+* PLY - Polygon File Format (3D scanning and printing)
+* AMF - Additive Manufacturing Format (XML-based 3D printing)
+
+<!--T:5-->
+'''Features:'''
+* Export to multiple formats in a single operation
+* User-friendly dialog for format selection
+* Configurable output directory and base filename
+* Mesh tolerance settings for STL/OBJ/PLY/3MF/AMF exports
+* Preview of files to be created
+* Quick select buttons: "Select All", "Select None", "Reset Defaults"
+* Default formats: STL, STEP, and 3MF are pre-selected
+
+==Usage== <!--T:6-->
+
+<!--T:7-->
+# Select one or more objects in the 3D view that you want to export
+# Run the macro from '''Macro → Macros → MultiExport → Execute'''
+# In the dialog:
+#* Review the selected objects in the "Objects to Export" section
+#* Check the formats you want to export to (STL, STEP, 3MF are selected by default)
+#* Choose an output directory using the "Browse..." button
+#* Enter a base filename (the format extension will be appended automatically)
+#* Optionally adjust mesh tolerance settings for mesh-based formats
+# Click "Export" to create the files
+
+[[File:Macro_Multi_Export_dialog.png|400px|center]]
+
+==Requirements== <!--T:8-->
+
+<!--T:9-->
+* FreeCAD 0.21 or later
+* Objects with solid shapes (Part or PartDesign bodies)
+
+==Installation== <!--T:10-->
+
+<!--T:11-->
+# Download the macro file: [[Media:MultiExport.FCMacro|MultiExport.FCMacro]]
+# Copy the file to your FreeCAD macro directory:
+#* '''macOS''': {{FileName|~/Library/Application Support/FreeCAD/Macro/}}
+#* '''Linux''': {{FileName|~/.local/share/FreeCAD/Macro/}}
+#* '''Windows''': {{FileName|%APPDATA%/FreeCAD/Macro/}}
+# Optionally, download the toolbar icon and place it in the same directory
+
+==Source Code== <!--T:12-->
+
+<!--T:13-->
+The full source code is hosted on GitHub:
+* [https://github.com/spkane/freecad-robust-mcp-and-more/blob/main/macros/Multi_Export/MultiExport.FCMacro MultiExport.FCMacro on GitHub]
+* [https://github.com/spkane/freecad-robust-mcp-and-more GitHub Repository (freecad-robust-mcp-and-more)]
+
+==Script== <!--T:14-->
+
+<!--T:15-->
+ToolBar Icon [[Image:Macro_Multi_Export.png]]
+
+</translate>
+
+'''Macro_Multi_Export.FCMacro'''
+
+{{MacroCode|code=
+"""FreeCAD Macro: Multi-Format Export.
+
+SPDX-License-Identifier: MIT
+Copyright (c) 2025 Sean P. Kane (GitHub: spkane)
+
+Export selected bodies to multiple file formats simultaneously with a
+user-friendly dialog for format selection and output configuration.
+
+Requirements:
+    - FreeCAD 0.21 or later
+    - One or more objects selected in the 3D view
+
+Usage:
+    1. Select the object(s) to export
+    2. Run the macro
+    3. Select desired export formats (STL, STEP, 3MF selected by default)
+    4. Choose output directory and base filename
+    5. Click "Export"
+"""
+
+# FreeCAD Addon Manager metadata
+__Name__ = "Multi Export"
+__Comment__ = "Export selected bodies to multiple file formats (STL, STEP, 3MF, OBJ, IGES, BREP, PLY, AMF) simultaneously"
+__Author__ = "Sean P. Kane"
+__Version__ = "0.5.0-beta"
+__Date__ = "2026-01-05"
+__License__ = "MIT"
+__Web__ = "https://github.com/spkane/freecad-robust-mcp-and-more"
+__Wiki__ = "https://github.com/spkane/freecad-robust-mcp-and-more#readme"
+__Icon__ = ""
+__Help__ = "Select one or more objects, run the macro, choose export formats and output location, then click Export."
+__Status__ = "Beta"
+__Requires__ = "FreeCAD 0.21+"
+__Communication__ = "https://github.com/spkane/freecad-robust-mcp-and-more/issues"
+__Files__ = ""
+
+import os
+
+import FreeCAD as App
+import FreeCADGui as Gui
+import Mesh
+import Part
+from PySide import QtGui
+
+
+class ExportFormat:
+    """Represents an export format with its properties."""
+
+    def __init__(
+        self,
+        name: str,
+        extension: str,
+        description: str,
+        default_enabled: bool = False,
+    ):
+        self.name = name
+        self.extension = extension
+        self.description = description
+        self.default_enabled = default_enabled
+
+
+# Define available export formats
+EXPORT_FORMATS = [
+    ExportFormat("STL", "stl", "Stereolithography - common for 3D printing", default_enabled=True),
+    ExportFormat("STEP", "step", "Standard for Exchange of Product Data - CAD interchange", default_enabled=True),
+    ExportFormat("3MF", "3mf", "3D Manufacturing Format - modern 3D printing format", default_enabled=True),
+    ExportFormat("OBJ", "obj", "Wavefront OBJ - 3D graphics and game engines", default_enabled=False),
+    ExportFormat("IGES", "iges", "Initial Graphics Exchange Specification - legacy CAD format", default_enabled=False),
+    ExportFormat("BREP", "brep", "OpenCASCADE native format - preserves exact geometry", default_enabled=False),
+    ExportFormat("PLY", "ply", "Polygon File Format - 3D scanning and printing", default_enabled=False),
+    ExportFormat("AMF", "amf", "Additive Manufacturing Format - XML-based 3D printing", default_enabled=False),
+]
+
+# ... (full macro code continues - see GitHub repository for complete source)
+# https://github.com/spkane/freecad-robust-mcp-and-more/blob/main/macros/Multi_Export/MultiExport.FCMacro
+}}
+
+==Links== <!--T:16-->
+
+<!--T:17-->
+* [[Std_Export|Std Export]] - FreeCAD's built-in export function
+* [[Import_Export|Import Export]] - Overview of FreeCAD import/export formats
+
+[[Category:Macros{{#translation:}}]]
+[[Category:User Documentation{{#translation:}}]]

macros/Start_MCP_Bridge/StartMCPBridge.FCMacro

@@ -5,8 +5,6 @@ Copyright (c) 2025 Sean P. Kane (GitHub: spkane)
 
 Start the MCP bridge server for AI assistant integration with FreeCAD.
 
-Version: 1.0.0
-
 Requirements:
     - FreeCAD 0.21 or later
     - freecad-mcp project installed and accessible
@@ -17,6 +15,22 @@ Usage:
     3. Connect your MCP client (Claude Code, etc.) to the running bridge
 """
 
+# FreeCAD Addon Manager metadata
+__Name__ = "Start MCP Bridge"
+__Comment__ = "Start the MCP bridge server for AI assistant integration with FreeCAD"
+__Author__ = "Sean P. Kane"
+__Version__ = "0.5.0-beta"
+__Date__ = "2026-01-05"
+__License__ = "MIT"
+__Web__ = "https://github.com/spkane/freecad-robust-mcp-and-more"
+__Wiki__ = "https://github.com/spkane/freecad-robust-mcp-and-more#readme"
+__Icon__ = ""
+__Help__ = "Run this macro to start the MCP bridge server on ports 9875 (XML-RPC) and 9876 (Socket). Connect your MCP client (Claude Code, etc.) to the running bridge."
+__Status__ = "Beta"
+__Requires__ = "FreeCAD 0.21+"
+__Communication__ = "https://github.com/spkane/freecad-robust-mcp-and-more/issues"
+__Files__ = ""
+
 import sys
 
 import FreeCAD

macros/Start_MCP_Bridge/wiki-source.txt

@@ -0,0 +1,252 @@
+<languages/>
+<translate>
+
+<!--T:1-->
+{{Macro
+|Name=Macro Start MCP Bridge
+|Icon=Macro_Start_MCP_Bridge.png
+|Description=Start the MCP (Model Context Protocol) bridge server  which is part of the [https://github.com/spkane/freecad-robust-mcp-and-more FreeCAD Robust MCP server] which helps facilitate AI assistant integration with FreeCAD. Enables AI tools like Claude Code to control FreeCAD programmatically.
+|Author=Sean P. Kane
+|Version=0.5.0-beta
+|Date=2026-01-05
+|FCVersion=0.21+
+|Download=[https://wiki.freecad.org/images/thumb/d/d7/Macro_Start_MCP_Bridge.png/48px-Macro_Start_MCP_Bridge.png ToolBar Icon]
+|SeeAlso=[[Python_scripting_tutorial|Python Scripting Tutorial]]
+}}
+
+==Description== <!--T:2-->
+
+<!--T:3-->
+This macro starts the MCP (Model Context Protocol) bridge server which is part of the [https://github.com/spkane/freecad-robust-mcp-and-more FreeCAD Robust MCP server] on GitHub. This enables AI assistants like [https://claude.com/claude-code Claude Code] and other MCP-compatible clients to control FreeCAD programmatically.
+
+<!--T:4-->
+'''What is MCP?'''
+
+The Model Context Protocol (MCP) is an open standard developed by Anthropic that allows AI assistants to interact with external tools and applications. With this bridge running, an AI assistant can:
+* Create and manipulate FreeCAD documents
+* Build 3D models using Part and PartDesign workbenches
+* Execute Python code within FreeCAD's environment
+* Export models to various formats (STEP, STL, 3MF, etc.)
+* Query object properties and document state
+
+<!--T:5-->
+'''Server Ports:'''
+* '''XML-RPC''' (port 9875): Compatible with neka-nat's original freecad-mcp implementation
+* '''JSON-RPC Socket''' (port 9876): Modern protocol for MCP clients
+
+<!--T:6-->
+'''Key Features:'''
+* Dual protocol support (XML-RPC and JSON-RPC)
+* Full access to FreeCAD's Python API
+* Safe code execution with result capture
+* Console output streaming
+* Works with Claude Code, and other MCP-compatible AI tools
+
+==Usage== <!--T:7-->
+
+<!--T:8-->
+'''Prerequisites:'''
+# Install the freecad-robust-mcp package from PyPI or GitHub
+# Configure the macro with the correct project path (done automatically by the installer)
+
+<!--T:9-->
+'''Starting the Bridge:'''
+# Open FreeCAD
+# Run the macro from '''Macro → Macros → StartMCPBridge → Execute'''
+# The console will show:
+#: {{Code|code=
+MCP Bridge started!
+  - XML-RPC: localhost:9875
+  - Socket: localhost:9876
+
+You can now connect your MCP client (Claude Code, etc.) to FreeCAD.
+}}
+
+<!--T:10-->
+'''Connecting an AI Client:'''
+
+For Claude Code, add this to your MCP settings:
+{{Code|code=
+{
+  "mcpServers": {
+    "freecad": {
+      "command": "freecad-mcp",
+      "args": ["--mode", "xmlrpc"]
+    }
+  }
+}
+}}
+
+==Requirements== <!--T:11-->
+
+<!--T:12-->
+* FreeCAD 0.21 or later
+* Python 3.11+ (must match FreeCAD's bundled Python version)
+* The freecad-robust-mcp package installed
+
+==Installation== <!--T:13-->
+
+<!--T:14-->
+'''Method 1: Using the Installer Script'''
+
+If you have the freecad-robust-mcp project cloned locally:
+{{Code|code=
+just install-bridge-macro
+}}
+
+This automatically:
+* Copies the macro to your FreeCAD macro directory
+* Injects the correct project path
+* Sets up the icon
+
+<!--T:15-->
+'''Method 2: Manual Installation'''
+
+# Install the freecad-robust-mcp package:
+#: {{Code|code=
+pip install freecad-robust-mcp
+}}
+# Download the macro file: [[Media:StartMCPBridge.FCMacro|StartMCPBridge.FCMacro]]
+# Edit the macro and replace {{Incode|__PROJECT_PATH__}} with the actual path to the installed package
+# Copy the file to your FreeCAD macro directory:
+#* '''macOS''': {{FileName|~/Library/Application Support/FreeCAD/Macro/}}
+#* '''Linux''': {{FileName|~/.local/share/FreeCAD/Macro/}}
+#* '''Windows''': {{FileName|%APPDATA%/FreeCAD/Macro/}}
+
+==Troubleshooting== <!--T:16-->
+
+<!--T:17-->
+'''Error: "MCP Bridge macro not properly installed"'''
+
+The project path placeholder was not replaced during installation. Run:
+{{Code|code=
+just install-bridge-macro
+}}
+
+<!--T:18-->
+'''Error: "Failed to import MCP Bridge module"'''
+
+The freecad-robust-mcp package is not installed or not accessible. Ensure:
+* The package is installed: {{Incode|pip install freecad-robust-mcp}}
+* The project path in the macro points to the correct location
+
+<!--T:19-->
+'''Connection Issues'''
+
+* Verify the bridge is running (check the FreeCAD console for startup messages)
+* Ensure no firewall is blocking ports 9875 and 9876
+* Try connecting with a simple test: {{Incode|curl http://localhost:9875}}
+
+==Source Code== <!--T:20-->
+
+<!--T:21-->
+The full source code is hosted on GitHub:
+* [https://github.com/spkane/freecad-robust-mcp-and-more/blob/main/macros/Start_MCP_Bridge/StartMCPBridge.FCMacro StartMCPBridge.FCMacro on GitHub]
+* [https://github.com/spkane/freecad-robust-mcp-and-more GitHub Repository (freecad-robust-mcp-and-more)]
+
+==Script== <!--T:22-->
+
+<!--T:23-->
+ToolBar Icon [[Image:Macro_Start_MCP_Bridge.png]]
+
+</translate>
+
+'''Macro_Start_MCP_Bridge.FCMacro'''
+
+{{MacroCode|code=
+"""FreeCAD Macro: Start MCP Bridge Server.
+
+SPDX-License-Identifier: MIT
+Copyright (c) 2025 Sean P. Kane (GitHub: spkane)
+
+Start the MCP bridge server for AI assistant integration with FreeCAD.
+
+Requirements:
+    - FreeCAD 0.21 or later
+    - freecad-mcp project installed and accessible
+
+Usage:
+    1. Install via: just install-bridge-macro
+    2. Run the macro from: Macro -> Macros -> StartMCPBridge -> Execute
+    3. Connect your MCP client (Claude Code, etc.) to the running bridge
+"""
+
+# FreeCAD Addon Manager metadata
+__Name__ = "Start MCP Bridge"
+__Comment__ = "Start the MCP bridge server for AI assistant integration with FreeCAD"
+__Author__ = "Sean P. Kane"
+__Version__ = "0.5.0-beta"
+__Date__ = "2026-01-05"
+__License__ = "MIT"
+__Web__ = "https://github.com/spkane/freecad-robust-mcp-and-more"
+__Wiki__ = "https://github.com/spkane/freecad-robust-mcp-and-more#readme"
+__Icon__ = ""
+__Help__ = "Run this macro to start the MCP bridge server on ports 9875 (XML-RPC) and 9876 (Socket). Connect your MCP client (Claude Code, etc.) to the running bridge."
+__Status__ = "Beta"
+__Requires__ = "FreeCAD 0.21+"
+__Communication__ = "https://github.com/spkane/freecad-robust-mcp-and-more/issues"
+__Files__ = ""
+
+import sys
+
+import FreeCAD
+
+
+def start_mcp_bridge():
+    """Start the MCP bridge server for AI assistant integration."""
+    # The project path is injected during macro installation
+    # This placeholder will be replaced with the actual path
+    project_path = "__PROJECT_PATH__"
+
+    if project_path == "__PROJECT_PATH__":
+        FreeCAD.Console.PrintError(
+            "MCP Bridge macro not properly installed.\n"
+            "Please run: just install-bridge-macro\n"
+        )
+        return
+
+    if project_path not in sys.path:
+        sys.path.insert(0, project_path)
+
+    try:
+        # Import and start the plugin
+        from freecad_mcp.freecad_plugin.server import FreecadMCPPlugin
+
+        # Create and start the plugin
+        plugin = FreecadMCPPlugin(
+            host="localhost",
+            port=9876,  # JSON-RPC socket port
+            xmlrpc_port=9875,  # XML-RPC port (neka-nat compatible)
+            enable_xmlrpc=True,
+        )
+        plugin.start()
+
+        FreeCAD.Console.PrintMessage("MCP Bridge started!\n")
+        FreeCAD.Console.PrintMessage("  - XML-RPC: localhost:9875\n")
+        FreeCAD.Console.PrintMessage("  - Socket: localhost:9876\n")
+        FreeCAD.Console.PrintMessage(
+            "\nYou can now connect your MCP client (Claude Code, etc.) to FreeCAD.\n"
+        )
+
+    except ImportError as e:
+        FreeCAD.Console.PrintError(
+            f"Failed to import MCP Bridge module: {e}\n"
+            f"Ensure the freecad-mcp project is accessible at: {project_path}\n"
+        )
+    except Exception as e:
+        FreeCAD.Console.PrintError(f"Failed to start MCP Bridge: {e}\n")
+
+
+if __name__ == "__main__":
+    start_mcp_bridge()
+}}
+
+==Links== <!--T:24-->
+
+<!--T:25-->
+* [https://modelcontextprotocol.io/ Model Context Protocol Specification]
+* [https://claude.com/claude-code Claude Code] - AI assistant that works with MCP
+* [[Python_scripting_tutorial|Python Scripting Tutorial]] - FreeCAD Python documentation
+
+[[Category:Macros{{#translation:}}]]
+[[Category:User Documentation{{#translation:}}]]