Operation and help
Updating, going back to an earlier version, recovering after a problem in CATIA, reporting problems and removing CadPilot again – all without administrator rights.
1. Which version is running?
In a command prompt in the CadPilot folder:
.venv\Scripts\python.exe -c "import catia_mcp; print(catia_mcp.__version__)"The set-up (scripts\setup_user.cmd) also ends with ALL TESTS PASSED — 103 tools ready; the number of tools changes with new versions. What changed in which version is listed in the news.
2. Updating to a new version
- Get the ZIP file:
CadPilot-<version>.zip(from Martin or from the release in the repository). - Unpack it into a new folder next to the old one, e.g.
C:\Users\<name>\CadPilot-0.4.0. Do not overwrite the old folder – it is your way back. - Set up: double-click
scripts\setup_user.cmdin the new folder. The working folder stays the same; your working copies are kept. - Switch: in VS Code “File → Open Folder” with the new folder, then “MCP: List Servers” →
catia-v5→ Start.
With Git instead of ZIP: git pull in the folder, then run scripts\setup_user.cmd again.
From 0.5.0: the structured result format (v2) is the default. If you use the setup script, nothing changes – it already set v2. Only your own program that parses the old text answers needs "CATIA_MCP_RESULT_FORMAT": "v1" in mcp.json.
3. Going back to an earlier version
Every version has its own folder with its own Python environment and server settings. Going back therefore only means opening the old folder in VS Code and starting the server there. With Git: git checkout v0.3.0 (the version you want) and scripts\setup_user.cmd.
4. When something goes wrong in CATIA
| Situation | What helps |
|---|---|
| The last step was wrong | Ask Copilot: “Show the journal” and “Undo the last change” (catia_journal_list, catia_undo_last). Works for parameter changes and new features, only for the last step and only as long as nothing builds on it. |
| Material, properties, new parameters or formulas should be undone | Not via the journal. The old values are in the tool’s result – reset them by hand in CATIA. |
| Worried about the original file | In safe mode (the default) originals are never overwritten; saving only goes to the working folder %USERPROFILE%\CATIA_MCP_Work. If in doubt, delete the working copy and create it again from the original. |
Message COM_TIMEOUT or SESSION_BLOCKED | CATIA is probably showing a dialog – look in CATIA and close it. Until then CadPilot deliberately accepts no new commands. |
| CATIA does not respond at all | End CATIA in the Task Manager (unsaved work is lost), start it again, then in VS Code “MCP: List Servers” → catia-v5 → Restart. |
| Copilot uses wrong parameters | CadPilot rejects unknown parameters and names the allowed ones; Copilot usually corrects this itself. |
5. Common set-up problems
| Message | Cause / solution |
|---|---|
| “Kein passendes Python … gefunden” (no suitable Python found) | Install Python in the user profile (handbook, chapter 4), open a new command prompt. |
| “Invalid class string” | CATIA is not registered for Automation – a one-time task for IT. |
| “This program is blocked by group policy” | Python in the user profile is blocked (AppLocker) – only IT can solve this. |
| Copilot shows no CATIA tools | Agent mode selected? Server started? With company Copilot: policy “MCP servers in Copilot”. |
| “Failed to connect to CATIA V5” | Start CATIA first; neither CATIA nor VS Code “Run as administrator”. |
The complete table with proxy, offline installation and company policies is in the project guide (docs\ANLEITUNG_COPILOT.md, German) and in the live-test guide.
6. Reporting a problem
Please send:
- the version (section 1) and the exact message, ideally as a screenshot of the chat,
- the environment report:
.venv\Scripts\python.exe scripts\live_env_report.py --catia --out umgebung.json– it contains the Windows, Python and CATIA versions and the authorised licences, but no document name, - the log file
catia_mcp.logfrom the CadPilot folder – in safe mode without paths and values.
Please do not send CAD files, customer or project data.
7. Removing CadPilot
- Stop the server in VS Code (“MCP: List Servers” →
catia-v5→ Stop). - Delete the CadPilot folder – it also contains the Python environment and the server settings.
- Check the working folder
%USERPROFILE%\CATIA_MCP_Work, back up working copies, then delete it. - Optional: uninstall Python via “Apps and features” and delete the cache
%LOCALAPPDATA%\pip\Cache.
CadPilot creates no services, autostart or registry entries and installs nothing outside these folders.