麦克佩自CAD

Name: 麦克佩自CAD
Author: jango-blockchained

作者：jango-blockchained14 星标更新：2025-11-06

安装使用来源：spider==github.com

项目介绍

技术文档摘要

🛠️ MCP-FreeCAD 集成

状态: 活跃开发 - 清晰、组织良好的代码库，支持多种连接方式和全面的工具提供者。

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

🤖 AI 提供者模型（2025）

MCP-FreeCAD 集成支持多个AI提供者及其最新的2025年模型。选择适合您特定用例的模型：

OpenAI 模型

生产模型：

gpt-4o - 默认多模态模型（文本、图像、音频）
- 上下文：128K 个标记
- 定价：~$5 每百万输入标记
- 最佳用途：通用CAD任务，多模态交互
gpt-4.1 - 下一代，具有1M标记上下文
- 功能：支持文本、图像、音频、视频
- 定价：~$2.5 每百万输入标记
- 最佳用途：复杂的CAD项目，大型文档分析
gpt-4-turbo - 快速、成本效益高
- 上下文：128K 个标记
- 最佳用途：高容量操作，批量处理

推理模型：

o3 - 复杂CAD逻辑的高级推理
- 定价：~$10 每百万输入标记
- 最佳用途：复杂几何计算，设计优化
o4-mini / o4-mini-high - 成本效益高的推理
- 定价：~$0.15 每百万输入标记
- 最佳用途：简单计算，快速迭代

Anthropic Claude 模型

Claude 4 系列（2025）：

claude-opus-4 - 最先进的模型
- 最大上下文：200K 个标记
- 定价：$15/$75 每百万标记（输入/输出）
- 功能：扩展思考、工具使用、内存处理
- 最佳用途：复杂的CAD工作流程，自主设计任务
claude-sonnet-4 - 平衡效率
- 最大上下文：200K 个标记
- 定价：$3/$15 每百万标记
- 功能：卓越编码、混合推理
- 最佳用途：通用CAD操作，脚本辅助
claude-haiku-3.5 - 快速、轻量级
- 最佳用途：快速查询，简单操作

Google AI 模型

Gemini 2.5 系列（最新）：

gemini-2.5-pro-preview-05-06 - 最先进的
- 上下文：1M 个标记
- 功能：增强推理、思考模式
- 最佳用途：复杂的CAD分析，大型装配
gemini-2.5-flash-preview-04-17 - 性能优化
- 功能：自适应思考、成本效益高
- 最佳用途：平衡性能和成本

Gemini 2.0 系列（稳定版）：

gemini-2.0-flash-001 - 生产就绪
- 功能：比Gemini 1.5 Pro快2倍
- 最佳用途：实时CAD协助
gemini-2.0-flash-lite - 成本优化
- 最佳用途：高容量、简单操作

OpenRouter（统一访问）

OpenRouter 通过单一API提供对所有模型的访问：

模型格式: `provider/model-name`

流行模型：

anthropic/claude-sonnet-4 - 推荐通用用途
openai/gpt-4o - OpenAI旗舰产品
google/gemini-2.5-pro-preview - Google最新产品

免费模型（每天50-1000次请求）：

deepseek/deepseek-r1 - 高级推理
deepseek/deepseek-v3 - 通用用途
google/gemini-2.5-flash-preview - Google免费层

模型选择指南

用例	推荐模型	替代方案
通用CAD工作	`claude-sonnet-4`	`gpt-4o`, `gemini-2.0-flash-001`
复杂推理	`claude-opus-4`	`o3`, `gemini-2.5-pro-preview-05-06`
多模态任务	`gpt-4o`	`gpt-4.1`, `claude-opus-4`
成本效益	`o4-mini`	`claude-haiku-3.5`, `gemini-2.0-flash-lite`
高容量	`gpt-4-turbo`	`claude-sonnet-4`, `gemini-2.0-flash-001`
免费使用	`deepseek/deepseek-r1`	`google/gemini-2.5-flash-preview`

配置示例

{
  "providers": {
    "anthropic": {
      "enabled": true,
      "model": "claude-sonnet-4",
      "thinking_mode": true,
      "max_tokens": 64000
    },
    "openai": {
      "enabled": true,
      "model": "gpt-4o",
      "max_tokens": 32000
    },
    "google": {
      "enabled": true,
      "model": "gemini-2.0-flash-001",
      "thinking_mode": true
    },
    "openrouter": {
      "enabled": true,
      "model": "anthropic/claude-sonnet-4",
      "free_models": ["deepseek/deepseek-r1"]
    }
  }
}

API 使用示例

# 使用特定提供商
from freecad_ai import CADAssistant

# 初始化为Claude Sonnet 4
assistant = CADAssistant(provider="anthropic", model="claude-sonnet-4")

# 创建复杂几何图形
result = assistant.generate_cad_script(
    "创建一个参数化齿轮，20齿，5毫米模数，20度压力角"
)

# 使用OpenRouter进行成本优化
assistant_free = CADAssistant(
    provider="openrouter", 
    model="deepseek/deepseek-r1"
)

# 使用免费模型进行快速操作
result = assistant_free.create_primitive("box", length=10, width=5, height=3)

🚀 快速开始

选项 1: FreeCAD 插件（推荐给用户）

为了获得最佳的GUI集成用户体验：

📦 FreeCAD MCP 集成插件

🧠 Claude 4 带有思考模式 - 高级AI推理
🤖 多提供商支持 - Claude、Gemini、OpenRouter，超过13种模型
🎨 现代GUI - 专业的标签式界面
🔗 通用连接 - 所有MCP连接方法
📊 性能监控 - 实时诊断

选项 2: MCP 服务器（适用于开发者/集成）

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

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

# 启动MCP服务器
python mcp_server.py

# 或使用FastMCP模式（轻量级，适用于Cursor IDE）
python mcp_server.py --mode fastmcp

# 或使用自定义配置和调试日志
python mcp_server.py --config my_config.json --debug

python -m src.mcp_freecad.main --config my_config.json --debug


### 选项 3: FastMCP 服务器（Cursor IDE 和最新最佳实践）

**✨ 新功能: 更新至FastMCP 2.13.0.2** - 现代、声明式的MCP服务器实现。

```bash
# 为Cursor IDE启动FastMCP服务器
python cursor_mcp_server.py

# 或运行示例以查看可用工具
python example_fastmcp_usage.py --all

关键特性：

🎯 声明式API - 简单的@mcp.tool()和@mcp.resource()装饰器
🔒 类型安全 - 自动从类型提示生成模式
🚀 最佳实践 - 遵循FastMCP 2.13推荐模式
✅ 经过充分测试 - 综合测试套件，通过率100%
📚 优秀文档 - 查看FASTMCP_IMPLEMENTATION.md

可用工具：

test_connection - 测试FreeCAD连接性
create_box - 创建盒状原始形状
create_cylinder - 创建圆柱
create_sphere - 创建球体
create_document - 管理FreeCAD文档

资源：

freecad://status - 获取服务器状态和FreeCAD可用性

详细使用，请参阅FastMCP 实现指南。

🏗️ 架构概述

核心组件

src/mcp_freecad/
├── main.py                 # 主入口点
├── __init__.py            # 包导出和注册
├── client/                # FreeCAD 连接管理
│   └── freecad_connection_manager.py
├── server/                # MCP 服务器实现
│   └── freecad_mcp_server.py
├── tools/                 # 工具提供者
│   ├── base.py           # 基础工具提供者类
│   ├── primitives.py     # 原始形状（盒子、圆柱等）
│   ├── model_manipulation.py # 转换、布尔运算等
│   ├── export_import.py  # 文件格式处理
│   ├── measurement.py    # 分析工具
│   └── code_generator.py # 代码生成
├── core/                  # 核心基础设施
│   ├── server.py         # 基于FastAPI的服务器
│   ├── cache.py          # 资源缓存
│   ├── diagnostics.py    # 性能监控
│   └── recovery.py       # 连接恢复
└── connections/           # 连接后端

连接方法

系统支持多种连接到FreeCAD的方法：

🚀 启动器（推荐） - 使用AppImage和AppRun
🔌 服务器 - 基于Socket的连接到FreeCAD服务器
🌉 桥接 - 使用FreeCAD可执行文件的CLI连接
📡 RPC - 到FreeCAD的XML-RPC连接
📦 包装器 - 子进程包装器连接
🎭 模拟 - 用于无FreeCAD的测试

🛠️ 可用工具

原始形状创建

create_box - 创建盒状原始形状
create_cylinder - 创建圆柱
create_sphere - 创建球体
create_cone - 创建圆锥

模型操作

transform - 移动、旋转对象
boolean_operation - 并集、差集、交集
fillet_edge - 圆角边缘
chamfer_edge - 倒角边缘
mirror - 在平面上镜像对象
scale - 均匀或非均匀缩放对象

文档管理

create_document - 创建新文档
list_documents - 列出打开的文档
list_objects - 列出文档中的对象

导入/导出

export_stl - 导出为STL格式
将来提供更多格式

📋 使用示例

Python API

from src.mcp_freecad import FreeCADConnection, PrimitiveToolProvider

# 创建连接（自动选择最佳方法）
fc = FreeCADConnection(auto_connect=True)

if fc.is_connected():
    print(f"通过以下方式连接: {fc.get_connection_type()}")
    
    # 创建文档
    doc_name = fc.create_document("MyProject")
    
    # 创建对象
    box = fc.create_box(length=20, width=10, height=5)
    cylinder = fc.create_cylinder(radius=3, height=10)
    
    # 导出
    fc.export_stl(box, "my_box.stl")

工具提供者使用

from src.mcp_freecad.tools.primitives import PrimitiveToolProvider

# 初始化工具提供者
primitives = PrimitiveToolProvider()

# 执行工具
result = await primitives.execute_tool("create_box", {
    "length": 10.0,
    "width": 5.0, 
    "height": 3.0
})

print(f"已创建: {result.result['object_id']}")

MCP 服务器集成

from src.mcp_freecad.core.server import MCPServer
from src.mcp_freecad import TOOL_PROVIDERS

# 设置服务器
server = MCPServer()

# 注册工具提供者
server.register_tool("primitives", TOOL_PROVIDERS["primitives"]())
server.register_tool("model_manipulation", TOOL_PROVIDERS["model_manipulation"]())

# 初始化并运行
await server.initialize()

⚙️ 配置

基本配置（`config.json`）

{
  "server": {
    "name": "mcp-freecad-server",
    "version": "0.7.11"
  },
  "freecad": {
    "connection_method": "auto",
    "host": "localhost",
    "port": 12345,
    "freecad_path": "freecad"
  },
  "tools": {
    "enable_primitives": true,
    "enable_model_manipulation": true,
    "enable_export_import": true
  }
}

连接方法配置

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

🔧 开发

项目结构

src/mcp_freecad/ - 主包
freecad-ai/ - FreeCAD GUI 插件
tests/ - 测试套件
docs/ - 文档
scripts/ - 设置和实用脚本

添加新工具

在src/mcp_freecad/tools/中创建新的工具提供者
继承自ToolProvider基础类
实现所需方法（tool_schema, execute_tool）
在__init__.py中的TOOL_PROVIDERS中注册

from .base import ToolProvider, ToolResult, ToolSchema

class MyToolProvider(ToolProvider):
    @property
    def tool_schema(self) -> ToolSchema:
        return ToolSchema(
            name="my_tool",
            description="我的自定义工具",
            parameters={...},
            returns={...}
        )
    
    async def execute_tool(self, tool_id: str, params: Dict[str, Any]) -> ToolResult:
        # 实现
        return self.format_result(status="success", result=result)

测试

# 运行测试
python -m pytest tests/

# 运行覆盖率测试
python -m pytest tests/ --cov=src --cov-report=html

# 运行特定测试
python -m pytest tests/test_primitives.py -v

🐳 Docker 支持

# 使用Docker Compose构建并运行
docker compose up

# 从零开始构建
docker compose build --no-cache
docker compose up

📚 文档

🤝 贡献

叉出仓库
创建功能分支
进行更改
添加测试
提交拉取请求

📄 许可

本项目采用MIT许可 - 详情见LICENSE文件。

<div align="center"> <sub> 🛠️ <strong>MCP-FreeCAD 集成</strong> - 通过先进