🛠️ MCP-FreeCAD 集成

注意： 本仓库正处于积极开发阶段。预计每天都会有提交，并可能存在破坏性更改。

该项目通过模型上下文协议 (MCP) 提供了 AI 助手与 FreeCAD CAD 软件之间的强大集成。它允许外部应用程序通过标准化接口与 FreeCAD 进行交互，提供了多种连接方式和专用工具。

快速开始（推荐：AppImage + 启动器）

为了获得最可靠的设置，请按照以下步骤操作：

1. 设置环境（一次性）：运行设置脚本。这会将仓库克隆到 ~/.mcp-freecad，创建一个 Python 虚拟环境，下载最新的稳定版 FreeCAD AppImage，解压并配置服务器以使用它。

   curl -sSL https://raw.githubusercontent.com/jango-blockchained/mcp-freecad/main/scripts/bin/setup_freecad_env.sh | bash
   

   或者，你可以手动克隆仓库并运行 ./scripts/bin/setup_freecad_env.sh。

2. 运行 MCP 服务器：使用安装脚本（现在只是确保虚拟环境处于激活状态并运行服务器），或全局命令（如果已通过 install-global.sh 安装）。

   # 选项 A：在默认位置通过安装脚本运行
   ~/.mcp-freecad/scripts/bin/mcp-freecad-installer.sh
   
   # 选项 B：运行全局命令（如果已通过 install-global.sh 安装）
   mcp-freecad
   

这将使用下载并解压的 AppImage 通过推荐的 launcher 方法启动 MCP 服务器。

Docker 支持

你也可以在 Docker 容器中运行 MCP-FreeCAD，以便更轻松地部署和隔离。

使用 Docker Compose 运行

1. 启动容器：

   docker compose up
   

2. 从头构建（如果你做了修改）：

   docker compose build --no-cache
   docker compose up
   

Docker 容器暴露以下端口：

• 8080: MCP 服务器
• 12345: FreeCAD 服务器

Docker 配置

Docker 设置包括：

• Dockerfile：定义包含 Python 3.12 的容器，安装依赖项，并设置环境
• docker-compose.yml：配置服务、端口、卷和重启策略
• .dockerignore：排除不必要的文件

这种方法特别适用于 CI/CD 管道，或者当你需要将 MCP-FreeCAD 环境与系统隔离开时。

🔄 MCP 流程图

graph TD
    subgraph "Client"
        A["AI Assistant / MCP Client"]
    end

    subgraph "Server & Connection"
        B["MCP Server (freecad_mcp_server.py)"]
        C["FreeCAD Connection (freecad_connection_manager.py)"]
        C_Auto{"Auto-Select Method"}
    end

    subgraph "Connection Methods (Backends)"
        D["Server Mode (freecad_socket_server.py)"]
        E["Bridge Mode (freecad_connection_bridge.py)"]
        F["Wrapper Mode (freecad_connection_wrapper.py)"]
        L["Launcher Mode (freecad_connection_launcher.py)"]
        M["Mock Mode"]
    end

    subgraph "FreeCAD Execution"
        FS["Socket Server inside FreeCAD"]
        FCLI["FreeCAD CLI"]
        FSub["FreeCAD via Subprocess"]
        FAppRun["FreeCAD via AppRun"]
        G["FreeCAD Instance/Modules"]
    end

    %% Client to Server
    A --> |MCP Request| B

    %% Server uses Connection Layer
    B --> |Requests Connection| C

    %% Connection Logic
    C --> C_Auto
    C_Auto -- "Pref=Launcher or Auto" --> L
    C_Auto -- "Pref=Wrapper or Auto Fail" --> F
    C_Auto -- "Pref=Server or Auto Fail" --> D
    C_Auto -- "Pref=Bridge or Auto Fail" --> E
    C_Auto -- "Pref=Mock or Auto Fail" --> M

    %% Backends to Execution
    L --> |"Uses AppRun"| FAppRun
    F --> |"Uses freecad_subprocess.py"| FSub
    D --> |"Connects via Socket"| FS
    E --> |"Calls CLI"| FCLI

    %% Execution to FreeCAD
    FAppRun --> G
    FSub --> G
    FS --> G
    FCLI --> G

    %% Style (Optional)
    classDef client fill:#cde4ff,stroke:#333,stroke-width:1px;
    classDef server fill:#ccffcc,stroke:#333,stroke-width:1px;
    classDef backend fill:#fff0cc,stroke:#333,stroke-width:1px;
    classDef execution fill:#ffcccc,stroke:#333,stroke-width:1px;
    class A,B,C,C_Auto client;
    class D,E,F,L,M backend;
    class FS,FCLI,FSub,FAppRun,G execution;

此流程图展示了主要组件以及由 freecad_connection_manager.py 选择的不同连接方法如何导致在 FreeCAD 中以各种方式执行命令。通常与通过 AppRun 提取的 AppImages 一起使用的 launcher 方法是出于可靠性考虑的推荐方法。

有关更详细的流程图，请参见 FLOWCHART.md。

🔄 核心组件

1. FreeCAD MCP 服务器 (freecad_mcp_server.py)

• 描述: 实现模型上下文协议 (MCP) 的主服务器。它作为 AI 助手或其他客户端通过 MCP 与 FreeCAD 通信的中心枢纽。
• 功能:
  • 处理标准的 MCP 请求 (mcp/listTools, mcp/executeTool)。
  • 使用 FreeCADConnection 通过配置的方法与 FreeCAD 交互。
  • 基于配置暴露各种工具集（原语、操作、导出等）。
  • 可通过 config.json 配置。
• 用法:

  # 启动服务器（默认使用 config.json）
  python src/mcp_freecad/server/freecad_mcp_server.py
  
  # 使用特定配置启动
  python src/mcp_freecad/server/freecad_mcp_server.py --config my_config.json
  

2. FreeCAD 连接 (src/mcp_freecad/freecad_connection_manager.py)

• 描述: 封装了连接到 FreeCAD 的逻辑的统一 Python 接口。MCP 服务器内部使用，并可用于直接脚本编写。
• 功能:
  • 根据配置和可用性智能选择最佳连接方法。
• 方法:
  • Launcher: （推荐）使用 freecad_connection_launcher.py 和 AppRun。
  • Wrapper: 使用 freecad_connection_wrapper.py 和 freecad_subprocess.py。
  • Server: 通过套接字连接到正在运行的 freecad_socket_server.py。
  • Bridge: 通过 freecad_connection_bridge.py 使用 FreeCAD CLI。
  • Mock: 用于测试，模拟 FreeCAD。
  • Auto: 按推荐顺序尝试方法 (launcher > wrapper > server > bridge > mock)。
• 用法（直接脚本示例）:

  from freecad_connection_manager import FreeCADConnection
  
  # 使用可能来自 config.json 的设置自动连接
  # （确保存在 config.json 或提供参数）
  fc = FreeCADConnection(auto_connect=True)
  
  if fc.is_connected():
      print(f"已通过: {fc.get_connection_type()} 连接")
      version_info = fc.get_version()
      print(f"FreeCAD 版本: {version_info}")
      fc.create_document("TestDocFromScript")
  else:
      print("无法连接到 FreeCAD。")
  

3. FreeCAD 启动器 (freecad_connection_launcher.py)

• 描述: 处理 FreeCAD 环境的启动，通常使用从解压的 AppImage 中提取的 AppRun。它在启动的环境中执行 freecad_launcher_script.py。
• 功能:
  • 管理 FreeCAD/AppRun 的子进程执行。
  • 将命令和参数传递给内部的 FreeCAD 脚本。
  • 解析脚本输出中的 JSON 结果。
• 用法: 主要由 FreeCADConnection 在选择 launcher 方法时内部使用（配置在 config.json 中）。通常不由用户直接运行。

4. FreeCAD 包装器 (freecad_connection_wrapper.py) & 子进程 (freecad_subprocess.py)

• 描述: freecad_connection_wrapper.py 在一个单独的 Python 进程中启动 freecad_subprocess.py。freecad_subprocess.py 导入 FreeCAD 模块并通过标准输入输出管道与包装器通信。
• 功能:
  • 将 FreeCAD 模块导入隔离到一个专用进程中。
  • 如果直接模块导入可行但 AppRun/launcher 有问题时，提供另一种连接方法。
• 用法: 当选择 wrapper 方法时由 FreeCADConnection 内部使用（配置在 config.json 中）。需要一个能够成功 import FreeCAD 的 Python 环境。

5. FreeCAD 服务器 (freecad_socket_server.py)

• 描述: 设计为在 FreeCAD 实例内部运行的独立套接字服务器。监听来自 FreeCADConnection 的连接。
• 功能:
  • 允许连接到可能持久化的 FreeCAD 实例。
  • 如果以 --connect 模式运行，则可以与 GUI 交互。
• 用法 (在 FreeCAD 内手动启动):

  # 在 FreeCAD Python 控制台中:
  exec(open("/path/to/mcp-freecad/freecad_socket_server.py").read())
  

  需要在 config.json 中设置 connection_method: server 以便 MCP 服务器连接。（参见 docs/FREECAD_SERVER_SETUP.md）

6. FreeCAD 桥接器 (freecad_connection_bridge.py)

• 描述: 通过命令行与 FreeCAD 可执行文件进行交互。绕过了直接模块导入的问题，但可能会更慢。
• 功能:
  • 通过调用 freecad 可执行文件的子进程来执行 FreeCAD 命令。
• 用法: 当选择 bridge 方法时由 FreeCADConnection 内部使用（配置在 config.json 中）。要求 freecad 在系统 PATH 中或在配置中正确设置了 path。

7. FreeCAD 客户端 (freecad_client.py)

• 描述: 一个命令行工具，用于直接与FreeCADConnection接口交互（用于测试/调试连接方法，而不是MCP服务器）。
• 功能:
  • 允许从终端测试特定的FreeCADConnection命令（例如，创建基本体、获取版本）。
  • 使用config.json来确定连接设置。
• 使用示例:

  # 测试连接并获取版本
  python freecad_client.py version
  
  # 使用配置的连接方法创建一个盒子
  python freecad_client.py create-box --length 20 --width 10
  

🔄 项目结构

MCP-FreeCAD项目的目录结构如下：

mcp-freecad/
├── assets/                  # 3D model assets (STL, STEP files)
├── backups/                 # Backup files
├── config.json              # Main configuration file
├── config.template.json     # Template for configuration
├── docs/                    # Documentation files
│   ├── FLOWCHART.md         # Detailed flow diagrams
│   ├── FREECAD_INTEGRATION.md # FreeCAD integration guide
│   ├── FREECAD_SERVER_SETUP.md # Server setup instructions
│   ├── OPTIMIZATION_FEATURES.md # Performance optimization guide
│   └── PYTHON_INTERPRETER_SETUP.md # Python interpreter configuration
├── examples/                # Example scripts showing API usage
├── freecad_connection_bridge.py        # Bridge for CLI interaction with FreeCAD
├── freecad_client.py        # Command-line client
├── freecad_connection_manager.py    # Unified connection interface
├── freecad_mcp.py           # Entry point script
├── freecad_mcp_server.py    # MCP server implementation
├── freecad_socket_server.py        # Socket-based server for FreeCAD
├── scripts/                 # Shell scripts for installation and execution
│   ├── README.md            # Scripts documentation
│   └── bin/                 # Executable scripts
│       ├── install-global.sh    # Global installation script
│       ├── mcp-freecad-installer.sh # Installer/Runner script
│       ├── mcp-freecad          # Link target for global install
│       └── setup_freecad_env.sh # Environment setup script (AppImage download/extract)
├── src/                     # Source code (contains mcp_freecad package)
│   └── mcp_freecad/
│       ├── __init__.py
│       ├── server/
│       │   ├── __init__.py
│       │   └── freecad_mcp_server.py # The main MCP server implementation
│       ├── freecad_connection_manager.py # Unified connection interface
│       └── ...                # Other source files
├── tests/                   # Test files
│   └── e2e/                 # End-to-end tests
├── .gitignore               # Git ignore patterns
├── pyproject.toml           # Project metadata and dependencies (PEP 621)
├── LICENSE                  # Project License
├── README.md                # This file
├── Dockerfile               # Docker build definition
├── docker-compose.yml       # Docker Compose configuration
└── ...                      # Other config files (.dockerignore, .editorconfig, etc.)

有关脚本的更多详细信息，请参见scripts/README.md。

⚙️ 安装与设置详情

本节提供了不同安装和设置选项的更多细节。

推荐设置：AppImage + 启动器（详细步骤）

这涉及两个主要脚本：

1. scripts/bin/setup_freecad_env.sh: 准备环境。

   • 将仓库克隆或更新到~/.mcp-freecad。
   • 创建/更新Python虚拟环境（.venv）并安装依赖项。
   • 运行download_appimage.py以将最新的稳定版FreeCAD Linux AppImage下载到~/.mcp-freecad。
   • 运行extract_appimage.py，该脚本：
     • 将下载的AppImage解压到~/.mcp-freecad/squashfs-root。
     • 更新~/.mcp-freecad/config.json以使用connection_method: launcher和use_apprun: true，并带有正确的绝对路径。
   • 如何运行: curl -sSL <URL>/setup_freecad_env.sh | bash 或 ./scripts/bin/setup_freecad_env.sh

2. scripts/bin/mcp-freecad-installer.sh: 运行服务器。

   • 注意: 尽管名称如此，但此脚本不再执行完整的安装。它主要是确保仓库是最新的，激活虚拟环境，并启动freecad_mcp_server.py。
   • 它假设环境（AppImage的下载/解压）已由setup_freecad_env.sh或手动准备完成。
   • 如何运行: ~/.mcp-freecad/scripts/bin/mcp-freecad-installer.sh 或 mcp-freecad（全局命令）。

其他安装方法

全局安装 (install-global.sh)

• 在/usr/local/bin中创建指向仓库中mcp-freecad-installer.sh的符号链接mcp-freecad。
• 允许从任何地方运行mcp-freecad。
• 需要先使用setup_freecad_env.sh设置环境，如果你想使用推荐的启动器方法。

# Navigate to the repository (e.g., ~/.mcp-freecad)
cd ~/.mcp-freecad 
# Run the setup script first
./scripts/bin/setup_freecad_env.sh
# Then run the global installation script
sudo ./scripts/bin/install-global.sh # Needs sudo for /usr/local/bin
# Now you can run the server from anywhere
mcp-freecad

手动安装

• 克隆仓库。
• 创建虚拟环境，安装依赖项。
• 手动下载并解压AppImage: 自行运行python download_appimage.py和python extract_appimage.py /path/to/downloaded.AppImage。
• 运行服务器: python freecad_mcp_server.py。

🚀 使用MCP服务器

这是使用像Claude这样的AI助手与FreeCAD交互的主要方式。

启动 MCP 服务器

# Start the server using the default config.json
python src/mcp_freecad/server/freecad_mcp_server.py

# Start with a specific configuration file
python src/mcp_freecad/server/freecad_mcp_server.py --config /path/to/your/config.json

# Enable debug logging
python src/mcp_freecad/server/freecad_mcp_server.py --debug

服务器将运行并监听来自MCP客户端的连接。

连接 MCP 客户端

使用任何兼容MCP的客户端。例如，使用参考 mcp client：

# Replace 'mcp client' with the actual client command if different
mcp client connect stdio --command "python src/mcp_freecad/server/freecad_mcp_server.py"

或者，如果你有一个类似于MCP文档中的客户端脚本，可以使用 uv：

uv run path/to/your/mcp_client.py python src/mcp_freecad/server/freecad_mcp_server.py

替代方案：启动带有集成服务器的 FreeCAD

你也可以通过以下方式启动带有集成服务器的FreeCAD：

./scripts/start_freecad_with_server.sh

这将启动FreeCAD并在其中自动启动服务器。

MCP 服务器配置 (config.json)

config.json 文件控制服务器的各个方面。这里是一个示例，反映了运行 extract_appimage.py 后推荐的启动器设置：

{
  "auth": { // Optional authentication settings
    "api_key": "development",
    "enabled": false
  },
  "server": { // MCP server settings
    "host": "0.0.0.0",
    "port": 8000,
    "debug": true,
    "workers": 1,
    "name": "mcp-freecad",
    "version": "0.7.11",
    "mcp": {
      "transport": "stdio", // Use stdio for Cursor/local clients
      "protocol_version": "0.1.0"
      // ... other MCP settings
    }
  },
  "freecad": { // FreeCAD connection settings
    // Paths are set automatically by extract_appimage.py for launcher mode
    "path": "/home/user/mcp-freecad/squashfs-root/usr/bin/freecad", // Example path
    "python_path": "/home/user/mcp-freecad/squashfs-root/usr/bin/python", // Example path
    "module_path": "/home/user/mcp-freecad/squashfs-root/usr/lib/", // Example path
    "host": "localhost", // Not used by launcher
    "port": 12345, // Not used by launcher
    "auto_connect": false, // Connection handled internally
    "reconnect_on_failure": true,
    "use_mock": false,
    "connection_method": "launcher", // *** KEY: Use the launcher method ***
    "script_path": "/home/user/mcp-freecad/freecad_launcher_script.py", // Script run inside FreeCAD
    "launcher_path": "/home/user/mcp-freecad/freecad_connection_launcher.py", // Script that starts AppRun
    "use_apprun": true, // *** KEY: Tells launcher to use AppRun ***
    "apprun_path": "/home/user/mcp-freecad/squashfs-root/AppRun" // Path to AppRun executable
  },
  "logging": { // Logging configuration
    "level": "INFO",
    "file": "mcp_freecad.log",
    "max_size": 10485760,
    "backup_count": 3
  },
  "tools": { // Optional: control which tool groups are enabled
    "enable_smithery": true,
    "enable_primitives": true,
    "enable_model_manipulation": true,
    "enable_export_import": true,
    "enable_measurement": true,
    "enable_code_generator": true
    // ... other tool settings
  }
  // ... other sections like cache, recovery, cors, performance ...
}

注意：请将示例路径替换为你的实际绝对路径。

有关更多集成选项的详细信息，请参阅 FREECAD_INTEGRATION.md。

🛠️ 可用的MCP工具

MCP服务器目前公开了以下核心工具。计划增加额外的工具集。

• freecad.create_document: 创建新文档。
• freecad.list_documents: 列出所有打开的文档。
• freecad.list_objects: 列出特定文档（或活动文档）中的对象。
• freecad.create_box: 创建一个立方体基元。
• freecad.create_cylinder: 创建一个圆柱体基元。
• freecad.create_sphere: 创建一个球体基元。
• freecad.create_cone: 创建一个圆锥体基元。
• freecad.boolean_union: 对两个对象执行布尔联合（融合）。
• freecad.boolean_cut: 对两个对象执行布尔切割（差集）。
• freecad.boolean_intersection: 对两个对象执行布尔交集（共通部分）。
• freecad.move_object: 将对象移动到新的绝对位置。
• freecad.rotate_object: 按指定角度旋转对象。
• freecad.export_stl: 将指定的对象（或全部）导出为STL文件。

（注：在MCP请求中使用的工具名称可能会有所不同，例如，使用下划线代替点，具体取决于客户端和服务器的实现细节。请参考服务器的 mcp/listTools 输出以获取确切名称。）

📝 示例MCP交互

以下是与AI助手一起使用MCP服务器的概念性示例：

创建并导出一个立方体

User: Create a box 50mm long, 30mm wide, and 20mm high.

Assistant: Okay, I can create that box.
[Tool Call: primitives.create_box (arguments: {"length": 50.0, "width": 30.0, "height": 20.0})]
[Tool Result: {"object_name": "Box", "message": "Created box...", "success": true}]

User: Now export it as box.stl

Assistant: Sure, exporting the model to box.stl.
[Tool Call: export_import.export_stl (arguments: {"file_path": "box.stl", "object_names": ["Box"]})]
[Tool Result: {"file_path": "box.stl", "message": "Exported successfully...", "success": true}]

Assistant: I've exported the box model to `box.stl`.

🔍 故障排除

• MCP 服务器连接问题:

  • 确保 python src/mcp_freecad/server/freecad_mcp_server.py 可以无错误地运行。检查终端输出。
  • 如果相关，请检查防火墙设置（对于 stdio 来说不太可能）。
  • 验证 config.json 是否为有效的 JSON。

• FreeCAD 连接问题（特别是使用 launcher 方法时）:

  • 运行 extract_appimage.py: 确保 AppImage 已正确提取，并且 config.json 已更新。
  • 检查 config.json 路径: 确认 freecad 部分中的所有绝对路径在您的系统上是正确的。
  • 检查权限: 确保 squashfs-root/AppRun 具有执行权限 (chmod +x)。
  • 检查日志: 检查 mcp_freecad.log（如果日志记录开始，会在项目根目录下创建）、freecad_server_stdout.log 和 freecad_server_stderr.log，查找来自 freecad_connection_launcher.py、AppRun 或 FreeCAD 进程本身的错误。
  • 环境变量: 如果 AppRun 找不到库，请确保 LD_LIBRARY_PATH 和 PYTHONPATH 设置正确，如果使用 Cursor，则可能需要在 .cursor/mcp.json 中设置，或者在终端中手动导出。extract_appimage.py 脚本旨在减少这种需求，但它仍可能是因素之一。
  • 无头模式问题: 有时 FreeCAD 在完全无头模式 (QT_QPA_PLATFORM=offscreen) 下运行会有问题。检查与 GUI 相关的错误日志。

• server 方法: 确保 freecad_socket_server.py 在一个活动的 FreeCAD 实例中运行，并监听 config.json 中配置的正确主机/端口。

• bridge 方法: 验证 FreeCAD 是否已安装在系统中，并且 freecad 命令可以在您的终端中正常工作。检查 config.json 中的 freecad_path。

• 缺少 MCP SDK: 通过 pip install modelcontextprotocol 安装。

• Python 路径问题: 如果在不使用推荐的 AppImage 设置时找不到 FreeCAD 模块，请参阅 PYTHON_INTERPRETER_SETUP.md。

📄 许可

该项目根据 MIT 许可证授权 - 详情请参见 LICENSE 文件。

🖥️ Cursor 集成

MCP 服务器设计用于与 Cursor IDE 等工具集成。

1. 配置光标：在 Cursor 的设置中添加 MCP 服务器（设置 > 功能 > MCP 服务器 > 添加新的 MCP 服务器）。配置它直接运行 Python 脚本，设置必要的环境变量和工作目录。.cursor/mcp.json 中的示例配置如下所示：

   {
       "mcpServers": {
         "mcp-freecad": {
           "command": "python3", // 运行 python 的命令
           "args": [
             "src/mcp_freecad/server/freecad_mcp_server.py" // 正确的脚本路径
           ],
           "env": { // 头less AppRun 所需的环境变量
              "QT_QPA_PLATFORM": "offscreen",
              "DISPLAY": "",
              "FREECAD_CONSOLE": "1",
              "PYTHONNOUSERSITE": "1",
              // 如果 AppRun 没有自动设置这些，可能需要以下环境变量
              "LD_LIBRARY_PATH": "/path/to/mcp-freecad/squashfs-root/usr/lib:/path/to/mcp-freecad/squashfs-root/usr/Ext:...",
              "PYTHONPATH": "/path/to/mcp-freecad/squashfs-root/usr/lib/python3.11/site-packages:..."
           },
           "cwd": "/path/to/mcp-freecad" // 将工作目录设置为项目根目录
         }
         // ... 其他如内存等服务器...
       }
   }
   

   将 /path/to/mcp-freecad 替换为您的项目的实际绝对路径。
   如果需要，请确保 LD_LIBRARY_PATH 和 PYTHONPATH 与您的 AppImage 结构匹配。

2. 重启 Cursor：完全重启 Cursor 以使配置更改生效。

3. 服务器通信：服务器默认使用 stdio 传输方式（在 config.json 的 server.mcp.transport 下配置），这与 Cursor 的通信协议兼容。错误应通过 MCP 错误响应报告给 Cursor。

针对 Cursor 的特殊考虑

• freecad_mcp_server.py 脚本默认加载 config.json。确保此文件包含正确的设置，特别是由 extract_appimage.py 更新的 freecad 部分。
• 设置在 .cursor/mcp.json 中的环境变量对于允许 launcher 方法在 Cursor 提供的环境中正确工作至关重要。

📋 可用选项和使用案例

🔧 连接方法

1. 启动器连接（推荐）
   • 使用从解压的 AppImage 中提取的 AppRun。最可靠。
   • 由 extract_appimage.py 自动配置。
   • 配置 (config.json)：

   { "freecad": { "connection_method": "launcher", "use_apprun": true, "apprun_path": "/path/to/squashfs-root/AppRun", ... } }
   

2. 包装器连接
   • 在单独的 Python 子进程中运行 FreeCAD 逻辑。如果 AppImage/AppRun 导致问题，这是一个很好的替代方案。
   • 配置 (config.json)：

   { "freecad": { "connection_method": "wrapper", ... } }
   

3. 套接字服务器连接
   • 需要在 FreeCAD 内部运行 freecad_socket_server.py。
   • 当以持久后台服务器方式运行 FreeCAD 时使用。
   • 配置 (config.json)：

   { "freecad": { "connection_method": "server", "host": "localhost", "port": 12345, ... } }
   

4. CLI 桥接连接
   • 使用 freecad 命令行工具。可能较慢且不太可靠。
   • 配置 (config.json)：

   { "freecad": { "connection_method": "bridge", "freecad_path": "/path/to/system/freecad", ... } }
   

5. 模拟连接
   • 用于在没有 FreeCAD 的情况下进行测试。
   • 配置 (config.json)：

   { "freecad": { "connection_method": "mock", "use_mock": true } }
   

6. 自动连接
   • 自动选择最佳可用方法（启动器 > 包装器 > 服务器 > 桥接 > 模拟）。
   • 如果 connection_method 缺失或设置为 "auto"，则为默认选项。

🛠️ 工具类别和用例

1. 基本的 FreeCAD 操作

   • 必要的文档管理
   • 用例：
     • 创建新文档
     • 保存和加载项目
     • 导出到各种格式
     • 管理文档结构

2. 模型操作

   • 变换和修改对象
   • 用例：
     • 精确旋转对象
     • 在三维空间中移动对象
     • 缩放模型
     • 创建镜像和副本
     • 布尔运算（并集、切割、交集）

3. 测量工具

   • 分析和验证
   • 用例：
     • 距离测量
     • 角度计算
     • 表面积分析
     • 体积计算
     • 质量属性

4. 基本形状创建

   • 基本形状生成
   • 用例：
     • 创建盒子和圆柱
     • 生成球体
     • 制作圆锥和环形
     • 创建正多边形
     • 绘制椭圆

5. 导出/导入操作

   • 文件格式转换
   • 用例：
     • STEP 文件导出/导入
     • IGES 格式处理
     • DXF 文件处理
     • STL 导出用于 3D 打印

6. 代码生成

   • 自动生成代码
   • 用例：
     • 生成 Python 脚本
     • 导出 OpenSCAD 代码
     • 为 CNC 生成 G 代码
     • 优化 3D 打印机设置

💻 集成场景

1. 光标IDE集成

   • 开发环境集成
   • 使用场景：
     • 从IDE直接操作模型
     • 实时反馈
     • 调试日志
     • 错误跟踪

2. AI助手集成

   • 基于AI的设计自动化
   • 使用场景：
     • 自然语言模型创建
     • 自动化设计修改
     • 参数优化
     • 设计验证

3. 命令行使用

   • 脚本和自动化
   • 使用场景：
     • 批量处理
     • 自动化测试
     • CI/CD集成
     • 命令行工具

🎯 常见使用案例示例

1. 快速原型制作

# Create a new document
freecad.create_document("Prototype")
# Add basic shapes
primitives.create_box(length=100, width=50, height=20)
# Export for 3D printing
export_import.export_stl("prototype.stl")

1. 自动化处理

# Import and modify multiple files
for file in files:
    import_step(file)
    model_manipulation.scale(1.5)
    export_stl(f"{file}_scaled.stl")

⚙️ 配置选项

1. 服务器配置

{
    "server": {
        "name": "custom-server-name",
        "version": "1.0.0",
        "description": "Custom description"
    }
}

1. 工具启用

{
    "tools": {
        "enable_smithery": true,
        "enable_primitives": true,
        "enable_model_manipulation": true,
        "enable_export_import": true,
        "enable_measurement": true,
        "enable_code_generator": true
    }
}

1. 调试配置

{
    "cursor": {
        "debug": true,
        "log_level": "DEBUG",
        "stdio_transport": true
    }
}

功能

• 通过MCP协议将AI助手连接到FreeCAD
• 以编程方式创建和操作3D模型
• 支持基本形状（立方体、圆柱体、球体、圆锥体）
• 布尔运算（并集、交集、切割）
• 对象变换（移动、旋转）
• 将模型导出为STL格式
• 文档和对象管理

前提条件

• Python 3.8或更高版本
• 推荐：一个FreeCAD AppImage（使用scripts/bin/setup_freecad_env.sh下载并解压），以便可靠地使用launcher连接方法。
• 或者：系统安装的FreeCAD 0.20+（用于bridge或server方法，可能不太稳定）。
• Git（用于克隆仓库）。

依赖项通过pyproject.toml管理，并在设置过程中安装到虚拟环境中。

可用工具

(此部分与上面的列表重复 - 为了清晰而合并)

目前通过MCP实现的可用工具包括：

文档管理

• freecad.create_document
• freecad.list_documents
• freecad.list_objects

3D基本图形

• freecad.create_box
• freecad.create_cylinder
• freecad.create_sphere
• freecad.create_cone

布尔运算

• freecad.boolean_union
• freecad.boolean_cut
• freecad.boolean_intersection

变换

• freecad.move_object
• freecad.rotate_object

导出

• freecad.export_stl

计划在未来版本中增加覆盖测量、其他导入/导出格式和代码生成的附加工具。

测试

该项目包含端到端（E2E）测试以验证系统功能。

端到端测试

这些测试从客户端的角度验证使用MCP协议的交互。

要运行所有E2E测试：

# Run with mock FreeCAD (default, doesn't require actual FreeCAD installation)
./tests/e2e/run_tests.py

# Run with verbose output
./tests/e2e/run_tests.py --verbose

# Run with real FreeCAD connection (requires FreeCAD to be installed and configured)
./tests/e2e/run_tests.py --real

# Run a specific test file (e.g., test_primitives.py)
./tests/e2e/run_tests.py --single test_primitives.py

E2E测试位于tests/e2e/目录中，并按功能组织。

编写新的E2E测试

要添加新的E2E测试：

1. 在tests/e2e/目录中创建一个新的测试文件
2. 继承适当的基测试类（MCPClientTestBase）
3. 添加使用MCP客户端与工具交互的测试方法
4. 使用测试运行器运行您的测试

参见现有测试文件以获取示例。

文档

项目包含了几个针对不同方面的文档文件：

• PYTHON_INTERPRETER_SETUP.md - 如何配置 Python 解释器
• [FREECAD_SERV