MCP 服务器

mcp-freecad

这个项目旨在使用模型上下文协议（MCP）在人工智能助手和FreeCAD CAD软件之间提供强大的集成。它允许外部应用程序通过标准化的接口与FreeCAD交互，提供多种连接方式和专用工具。

README

🛠️ MCP-FreeCAD 集成

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

🔄 MCP 流程图

graph TD
    A[AI 助手] -->|MCP 协议| B[MCP 服务器]
    B -->|连接| C[FreeCAD 连接]
    C -->|方法 1| D[Socket 服务器]
    C -->|方法 2| E[CLI 桥接]
    C -->|方法 3| F[模拟连接]
    D -->|Python API| G[FreeCAD]
    E -->|命令行| G
    F -->|测试| G

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

🏗️ 核心组件

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

描述: 实现模型上下文协议的主服务器。它充当 AI 助手与 FreeCAD 通信的中心枢纽。
特性:
- 支持标准 MCP 请求 (ListTools, ExecuteTool, ListResources, GetResource)。
- 使用各种方法连接到 FreeCAD（见下文）。
- 公开专用工具，包括铁匠操作。
- 可通过 config.json 进行配置。

2. FreeCAD 连接 (`freecad_connection.py`)

描述: 一个统一的 Python 接口，用于连接到 FreeCAD，供 MCP 服务器内部使用，也可直接使用。
方法:
- Socket 服务器连接: 与正在运行的 freecad_server.py 实例通信。
- CLI 桥接连接: 使用通过 freecad_bridge.py 的命令行调用。
- 模拟连接: 提供一个回退方案，用于在没有运行 FreeCAD 实例的情况下进行测试。
- 自动连接: 自动选择最佳可用方法。

3. FreeCAD 服务器 (`freecad_server.py`)

描述: 一个独立的基于 Socket 的服务器脚本，设计为在 FreeCAD 内部 运行。它监听来自 FreeCADConnection 的命令（当使用 server 方法时）。

用法:

# 在 FreeCAD 的 Python 控制台中运行
exec(open("/path/to/freecad_server.py").read())

# 或者从命令行运行（以控制台模式启动 FreeCAD）
freecad -c /path/to/freecad_server.py --host localhost --port 12345 --debug

有关详细的设置说明，请参阅 FREECAD_SERVER_SETUP.md。

4. FreeCAD 桥接 (`freecad_bridge.py`)

描述: 一个 Python 模块，支持与 FreeCAD 的命令行交互，绕过直接模块导入问题。当使用 bridge 方法时，由 FreeCADConnection 使用。

5. FreeCAD 客户端 (`freecad_client.py`)

描述: 一个命令行客户端实用程序，用于直接与 FreeCADConnection 接口（而不是 MCP 服务器）交互。对于在 MCP 上下文之外进行基本测试和脚本编写非常有用。
示例: python freecad_client.py create-box --length 20

📁 项目结构

MCP-FreeCAD 项目采用以下目录结构组织：

mcp-freecad/
├── assets/                  # 3D 模型资源（STL、STEP 文件）
├── backups/                 # 备份文件
├── config.json              # 主要配置文件
├── docs/                    # 文档文件
│   ├── FLOWCHART.md         # 详细的流程图
│   ├── FREECAD_INTEGRATION.md # FreeCAD 集成指南
│   ├── FREECAD_SERVER_SETUP.md # 服务器设置说明
│   ├── OPTIMIZATION_FEATURES.md # 性能优化指南
│   └── PYTHON_INTERPRETER_SETUP.md # Python 解释器配置
├── examples/                # 显示 API 用法的示例脚本
├── freecad_bridge.py        # 用于与 FreeCAD 进行 CLI 交互的桥接
├── freecad_client.py        # 命令行客户端
├── freecad_connection.py    # 统一的连接接口
├── freecad_mcp.py           # 入口点脚本
├── freecad_mcp_server.py    # MCP 服务器实现
├── freecad_server.py        # 用于 FreeCAD 的基于 Socket 的服务器
├── scripts/                 # 用于安装和执行的 Shell 脚本
│   ├── README.md            # 脚本文档
│   ├── bin/                 # 可执行脚本
│   │   ├── install-global.sh    # 全局安装脚本
│   │   ├── mcp-freecad-installer.sh # 安装脚本
│   │   ├── mcp-freecad.sh       # 简单的包装脚本
│   │   └── run-freecad-server.sh # 服务器运行脚本
│   ├── start_freecad_with_server.sh # 带有服务器的 FreeCAD 启动器
│   └── start_server.py       # 用于服务器启动的 Python 脚本
├── src/                     # 源代码
├── tests/                   # 测试文件
└── tmp/                     # 临时文件

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

⚙️ 安装

有几种方法可以安装和使用 MCP-FreeCAD 服务器：

1. AI 工具快速启动

要使用单个命令安装和运行 MCP-FreeCAD 服务器，请运行：

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

此命令将：

克隆 MCP-FreeCAD 存储库（如果已克隆，则更新它）
设置 Python 虚拟环境
安装所有依赖项
启动 MCP 服务器

安装完成后，您可以直接运行服务器：

~/.mcp-freecad/scripts/bin/mcp-freecad.sh

2. 全局安装

如果您已克隆存储库，则可以在系统上全局安装 MCP-FreeCAD 服务器：

# 导航到存储库
cd /path/to/mcp-freecad

# 运行全局安装脚本
./scripts/bin/install-global.sh

安装完成后，您可以从任何位置运行服务器：

mcp-freecad

3. 手动安装

您也可以手动安装服务器：

# 克隆存储库
git clone https://github.com/jango-blockchained/mcp-freecad.git
cd mcp-freecad

# 创建一个虚拟环境
python -m venv .venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

# 安装依赖项
pip install -r requirements.txt

# 以开发模式安装软件包
pip install -e .

# 运行服务器
python freecad_mcp_server.py

4. 推荐设置：使用 FreeCAD AppImage（最可靠）

为了获得最可靠的 FreeCAD 连接，特别是如果您遇到模块导入问题，我们建议使用 FreeCAD AppImage：

下载 FreeCAD AppImage: 从 FreeCAD 发布页面获取最新的稳定版或每周构建版 AppImage。
使其可执行: chmod +x /path/to/FreeCAD_*.AppImage
提取 AppImage: 使用提供的实用程序脚本提取 AppImage。这将创建一个独立的 FreeCAD 环境。
```
# 导航到 mcp-freecad 目录
cd /path/to/mcp-freecad

# 运行提取脚本
./extract_appimage.py /path/to/FreeCAD_*.AppImage

# 可选：指定输出目录
# ./extract_appimage.py /path/to/FreeCAD_*.AppImage --output /custom/extract/path
```
此脚本将：
- 将 AppImage 提取到 squashfs-root 目录（默认情况下，在 AppImage 旁边）。
- 自动更新您的 config.json 以使用提取的 AppImage (use_apprun: true, apprun_path 设置正确, connection_method: launcher)。
- 测试提取的 AppImage 以确保其正常工作。
启动 MCP 服务器: 服务器现在将使用 launcher 连接方法和提取的 AppImage 环境。
```
python freecad_mcp_server.py
```

此方法避免了与系统 Python 版本的潜在冲突，并确保正确加载所有必要的 FreeCAD 依赖项和模块。

5. FreeCAD Python 解释器设置

为了与 FreeCAD 的 Python 模块正确集成，请参阅 PYTHON_INTERPRETER_SETUP.md，其中解释了如何：

提取和使用 FreeCAD 的 AppImage Python 解释器
使用 FreeCAD 的 Python 设置虚拟环境
配置 PYTHONPATH 以访问 FreeCAD 模块

🚀 使用 MCP 服务器

这是使用 AI 助手（如 Claude）与 FreeCAD 交互的主要方式。

启动 MCP 服务器

# 使用默认的 config.json 启动服务器
python freecad_mcp_server.py

# 使用特定的配置文件启动
python freecad_mcp_server.py --config /path/to/your/config.json

# 启用调试日志记录
python freecad_mcp_server.py --debug

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

连接 MCP 客户端

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

# 如果不同，请将“mcp client”替换为实际的客户端命令
mcp client connect stdio --command "python freecad_mcp_server.py"

或者，如果您有像 MCP 文档中的客户端脚本，则可以使用 uv：

uv run path/to/your/mcp_client.py python freecad_mcp_server.py

替代方法：使用集成服务器启动 FreeCAD

您还可以使用以下命令启动带有集成服务器的 FreeCAD：

./scripts/start_freecad_with_server.sh

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

MCP 服务器配置 (`config.json`)

{
    "server": {
        "name": "mcp-freecad",
        "version": "0.1.0"
    },
    "freecad": {
        "path": "/usr/bin/freecad",
        "python_path": "./squashfs-root/usr/bin/python",
        "host": "localhost",
        "port": 12345,
        "auto_connect": true,
        "reconnect_on_failure": true,
        "use_mock": false,
        "connection_method": "server"
    },
    "tools": { // 可选：控制启用哪些工具组
        "enable_smithery": true,
        "enable_primitives": true,
        "enable_model_manipulation": true,
        "enable_export_import": true,
        "enable_measurement": true,
        "enable_code_generator": true
    }
}

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

🛠️ 可用的 MCP 工具

MCP 服务器公开了各种工具组。以下是所有可用的工具：

🔨 铁匠工具 (`smithery.*`)

用于锻造和金属加工设计的专用工具：
- smithery.create_anvil: 生成具有可自定义尺寸的铁砧模型
- smithery.create_hammer: 生成具有可调节手柄和头部尺寸的铁匠锤
- smithery.create_tongs: 生成具有可配置手柄和钳口参数的铁匠钳
- smithery.forge_blade: 创建具有可自定义尺寸的刀/剑刀片模型
- smithery.create_horseshoe: 创建具有可调节尺寸的马蹄铁模型

📐 基本 FreeCAD 工具 (`freecad.*`)

freecad.create_document: 创建一个新文档
freecad.export_stl: 将模型或特定对象导出到 STL
freecad.import_stl: 将 STL 文件导入到当前文档
freecad.save_document: 保存当前文档
freecad.load_document: 加载现有文档

🔧 模型操作工具 (`model_manipulation.*`)

model_manipulation.rotate: 绕指定轴旋转对象
model_manipulation.translate: 在 3D 空间中移动对象
model_manipulation.scale: 均匀或非均匀地缩放对象
model_manipulation.mirror: 跨指定平面镜像对象
model_manipulation.union: 使用布尔并集组合多个对象
model_manipulation.cut: 使用布尔差集切割对象
model_manipulation.intersect: 创建多个对象的交集

📏 测量工具 (`measurement.*`)

measurement.distance: 测量两点之间的距离
measurement.angle: 测量三点之间的角度
measurement.area: 计算对象的表面积
measurement.volume: 计算实体对象的体积
measurement.mass: 计算对象的质量（需要材料属性）

📦 原始工具 (`primitives.*`)

primitives.create_box: 创建一个长方体
primitives.create_cylinder: 创建一个圆柱体
primitives.create_sphere: 创建一个球体
primitives.create_cone: 创建一个圆锥体
primitives.create_torus: 创建一个圆环
primitives.create_polygon: 创建一个正多边形
primitives.create_ellipse: 创建一个椭圆

🔄 导出/导入工具 (`export_import.*`)

export_import.export_step: 导出为 STEP 格式
export_import.import_step: 从 STEP 格式导入
export_import.export_iges: 导出为 IGES 格式
export_import.import_iges: 从 IGES 格式导入
export_import.export_dxf: 导出为 DXF 格式
export_import.import_dxf: 从 DXF 格式导入

💻 代码生成工具 (`code_generator.*`)

code_generator.generate_python: 为当前模型生成 Python 代码
code_generator.generate_openscad: 为当前模型生成 OpenSCAD 代码
code_generator.generate_gcode: 为 CNC 加工生成 G 代码
code_generator.generate_3d_print: 生成优化的 3D 打印设置

📝 MCP 交互示例

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

创建一个铁砧

用户：您能在 FreeCAD 中创建一个铁匠铁砧模型吗？

助手：好的，我可以做到。我将使用 `smithery.create_anvil` 工具。
[工具调用：smithery.create_anvil]
[工具结果：{"anvil_id": "Anvil", "message": "创建了铁砧...", "success": true}]

助手：我已经在 FreeCAD 中创建了铁砧模型。它具有默认尺寸。您想自定义它还是导出它？

创建一个锤子

用户：给我做一个手柄长 400 毫米的铁匠锤。

助手：当然，我可以创建一个带有更长手柄的锤子。
[工具调用：smithery.create_hammer (参数：{"handle_length": 400.0})]
[工具结果：{"hammer_id": "Hammer", "message": "创建了锤子...", "success": true}]

助手：我已经创建了一个手柄长 400 毫米且头部尺寸为默认值的锤子。

🔍 故障排除

MCP 服务器连接问题: 确保 freecad_mcp_server.py 脚本正在运行且可执行。如果远程连接，请检查防火墙设置（尽管 stdio 通常用于本地使用）。
FreeCAD 连接问题:
- auto 或 bridge 方法: 验证是否已安装 FreeCAD 并且 freecad 命令在您的终端中有效。检查 config.json 中的 freecad_path。
- server 方法: 确保 freecad_server.py 正在活动的 FreeCAD 实例中运行，并监听在 config.json 中配置的正确主机/端口上。
- 常规: 检查 FreeCAD 日志中是否有错误。
缺少 MCP SDK: 通过 pip install modelcontextprotocol 安装。
Python 路径问题: 如果找不到 FreeCAD 模块，请参阅 PYTHON_INTERPRETER_SETUP.md 以获取详细指导。

📄 许可证

本项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

🖥️ Cursor 集成

MCP 服务器与 Cursor IDE 集成完全兼容。要将其与 Cursor 一起使用：

使用提供的 cursor_config.json：

./freecad_mcp_server.py --config cursor_config.json

服务器默认使用 stdio 传输，该传输与 Cursor 的通信协议兼容。
错误处理已得到增强，可以使用正确的 MCP 错误响应，从而确保与 Cursor 的错误显示更好地集成。
默认情况下，在 Cursor 配置中启用调试日志记录，以帮助进行故障排除。

Cursor 特定功能

正确的 stdio 传输处理，实现无缝集成
使用 MCP 的 ErrorResponse 格式增强的错误响应
用于更好地了解服务器操作的调试模式
自动功能检测
改进了 Cursor 控制台的日志记录

Cursor 配置

cursor_config.json 文件包含 Cursor 集成的特定设置：

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

这些设置确保在使用服务器与 Cursor 时获得最佳性能。

📋 可用选项和用例

🔧 连接方法

Socket 服务器连接

在将 FreeCAD 作为持久服务器运行时使用
最适合高性能、连续操作
配置：

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

CLI 桥接连接

当您需要为每个操作启动/停止 FreeCAD 时使用
适用于偶尔使用或脚本编写
配置：

{
    "freecad": {
        "connection_method": "bridge",
        "freecad_path": "freecad"
    }
}

模拟连接

用于在没有 FreeCAD 的情况下进行测试
开发和调试
配置：

{
    "freecad": {
        "connection_method": "mock"
    }
}

自动连接

自动选择最佳可用方法
默认选项
配置：

{
    "freecad": {
        "connection_method": "auto"
    }
}

🛠️ 工具类别和用例

铁匠工具
- 创建锻造设备模型
- 用例：
  - 设计具有自定义尺寸的铁砧
  - 建模具有特定手柄长度的锤子
  - 创建具有可调节钳口开口的钳子
  - 锻造刀片设计
  - 生成马蹄铁模型
基本 FreeCAD 操作
- 基本文档管理
- 用例：
  - 创建新文档
  - 保存和加载项目
  - 导出为各种格式
  - 管理文档结构
模型操作
- 转换和修改对象
- 用例：
  - 精确旋转对象
  - 在 3D 空间中移动对象
  - 缩放模型
  - 创建镜像和副本
  - 布尔运算（并集、剪切、相交）
测量工具
- 分析和验证
- 用例：
  - 距离测量
  - 角度计算
  - 表面积分析
  - 体积计算
  - 质量属性
原始创建
- 基本形状生成
- 用例：
  - 创建盒子和圆柱体
  - 生成球体
  - 制作锥体和圆环
  - 创建正多边形
  - 绘制椭圆
导出/导入操作
- 文件格式转换
- 用例：
  - STEP 文件导出/导入
  - IGES 格式处理
  - DXF 文件处理
  - STL 导出用于 3D 打印
代码生成
- 自动代码创建
- 用例：
  - Python 脚本生成
  - OpenSCAD 代码导出
  - G 代码生成用于 CNC
  - 3D 打印机设置优化

💻 集成场景

Cursor IDE 集成
- 开发环境集成
- 用例：
  - 从 IDE 直接进行模型操作
  - 实时反馈
  - 调试日志记录
  - 错误跟踪
AI 助手集成
- AI 驱动的设计自动化
- 用例：
  - 自然语言模型创建
  - 自动设计修改
  - 参数优化
  - 设计验证
命令行用法
- 脚本编写和自动化
- 用例：
  - 批量处理
  - 自动测试
  - CI/CD 集成
  - 命令行工具

🎯 常见用例示例

快速原型制作

# 创建一个新文档
freecad.create_document("Prototype")
# 添加基本形状
primitives.create_box(length=100, width=50, height=20)
# 导出用于 3D 打印
export_import.export_stl("prototype.stl")

工具设计

# 创建自定义铁匠工具
smithery.create_hammer(handle_length=400, head_width=45)
smithery.create_tongs(jaw_length=85, opening_angle=20)

模型分析

# 测量对象属性
volume = measurement.volume("Part1")
mass = measurement.mass("Part1", material="Steel")

自动处理

# 导入和修改多个文件
for file in files:
    import_step(file)
    model_manipulation.scale(1.5)
    export_stl(f"{file}_scaled.stl")

⚙️ 配置选项

服务器配置

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

工具启用

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

调试配置

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

特性

通过 MCP 协议将 AI 助手连接到 FreeCAD
以编程方式创建和操作 3D 模型
支持原始形状（盒子、圆柱体、球体、锥体）
布尔运算（并集、交集、剪切）
对象转换（移动、旋转）
将模型导出为 STL 格式
文档和对象管理
用于锻造模型的专业铁匠工具

先决条件

系统上安装了 FreeCAD 0.20 或更高版本
Python 3.8 或更高版本
MCP SDK (pip install modelcontextprotocol)

可用工具

文档管理

freecad.create_document - 创建一个新的 FreeCAD 文档
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 - 将模型导出到 STL 文件

铁匠工具（专业工具）

smithery.create_anvil - 创建一个铁砧模型
smithery.create_hammer - 创建一个铁匠锤模型
smithery.create_tongs - 创建铁匠钳模型
smithery.forge_blade - 创建一个锻造刀片模型
smithery.create_horseshoe - 创建一个马蹄铁模型

测试

该项目包括单元测试和端到端 (E2E) 测试，以确保质量和可靠性。

单元测试

要运行基本单元测试：

python test_mcp_tools.py
python test_mcp_client.py

端到端测试

端到端测试验证整个系统从客户端的角度来看是否正常工作。它们测试真实世界的场景以及不同组件之间的交互。

要运行所有 E2E 测试：

# 使用模拟 FreeCAD 运行（默认，不需要实际安装 FreeCAD）
./tests/e2e/run_tests.py

# 使用详细输出运行
./tests/e2e/run_tests.py --verbose

# 使用真实的 FreeCAD 连接运行（需要安装 FreeCAD）
./tests/e2e/run_tests.py --real

# 运行特定的测试文件
./tests/e2e/run_tests.py --single test_primitives.py

E2E 测试按功能组织：

test_primitives.py - 用于基本形状创建和操作的测试
test_smithery.py - 用于铁匠工具操作的测试

编写新的 E2E 测试

要添加新的 E2E 测试：

在 tests/e2e/ 目录中创建一个新的测试文件
扩展适当的基本测试类 (MCPClientTestBase)
添加使用 MCP 客户端与工具交互的测试方法
使用测试运行器运行您的测试

有关示例，请参阅现有测试文件。

文档

该项目包括几个用于不同方面的文档文件：

PYTHON_INTERPRETER_SETUP.md - 如何配置 Python 解释器
FREECAD_SERVER_SETUP.md - 服务器设置指南
FREECAD_INTEGRATION.md - FreeCAD 集成方法
FLOWCHART.md - 详细的流程图
OPTIMIZATION_FEATURES.md - 性能优化指南
scripts/README.md - 脚本文档

对于 AI 助手，请参阅 AI_ASSISTANT_GUIDE.md 以获取详细的使用说明和示例。

贡献

欢迎贡献！请随时提交拉取请求。

致谢

FreeCAD 开发团队提供的出色 CAD 软件
Anthropic 和 Claude 提供的模型上下文协议 (MCP) SDK