🛠️ MCP FreeCAD集成
状态： 主动开发-干净、有组织的代码库，具有多种连接方法和全面的工具提供商。
该项目使用 模型上下文协议（MCP）。它允许外部应用程序通过标准化接口与FreeCAD交互，提供多种连接方法和专用工具。
______________________________________________________________________
🤖 人工智能提供商模型（2025）
MCP FreeCAD集成支持多个具有最新2025型号的AI提供商。为您的特定用例选择合适的型号：
OpenAI模型
生产型号：
- gpt-4o -默认多模式模型（文本、图像、音频）
- 上下文：128K令牌 - 定价：每100万输入代币约5美元 - 最适合：通用CAD任务、多模式交互
- gpt-4.1 -具有1M令牌上下文的下一代
- 功能：文本、图像、音频、视频支持 - 定价：每100万输入代币约2.5美元 - 最适合：复杂的CAD项目、大型文档分析
- gpt-4涡轮增压器 -快速、经济高效
- 上下文：128K令牌 - 最适合：大批量操作、批量处理
推理模型：
- 臭氧 -复杂CAD逻辑的高级推理
- 定价：每100万输入代币约10美元 - 最适合：复杂几何计算、设计优化
- o4迷你 / o4迷你高 -成本效益推理
- 定价：每100万输入代币约0.15美元 - 最适合：简单计算，快速迭代
拟人克劳德模型
克劳德4系列（2025）：
- claude-opus-4 -最先进的型号
- 最大上下文：20万个令牌 - 定价：每百万代币15美元/75美元（输入/输出） - 特点：扩展思维、工具使用、记忆处理 - 最适合：复杂的CAD工作流程、自主设计任务
- claude-sonnet-4 -平衡效率
- 最大上下文：20万个令牌 - 定价：每百万代币3美元/15美元 - 特点：高级编码，混合推理 - 最适合：一般CAD操作、脚本辅助
- claude-haiku-3.5 -快速、轻便
- 最适合：快速查询，简单操作
谷歌人工智能模型
Gemini 2.5系列（最新）：
- 双子座-2.5-pro-review-05-06 -最先进
- 上下文：1M代币 - 特点：增强推理、思维方式 - 最适合：复杂的CAD分析、大型装配
- 双子座-2.5激光预览-04-17 -性能优化
- 特点：适应性思维，性价比高 - 最适合：平衡性能和成本
Gemini 2.0系列（稳定型）：
- 双子座-2.0-flash-001 -生产就绪
- 特点：比Gemini 1.5 Pro快2倍 - 最适合：实时CAD辅助
- 双子座-2.0-flash-lite -成本优化
- 最适合：体积大，操作简单
OpenRouter（统一接入）
OpenRouter通过单个API提供对所有模型的访问：
模型格式： provider/model-name
热门型号：
anthropic/claude-sonnet-4-推荐的一般用途openai/gpt-4o-OpenAI的旗舰google/gemini-2.5-pro-preview-谷歌最新
免费型号（50-1000个请求/天）：
deepseek/deepseek-r1-高级推理deepseek/deepseek-v3-一般用途google/gemini-2.5-flash-preview-谷歌免费版
选型指南
| 用例 | 推荐型号 | 替代 |
|---|---|---|
| 一般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使用示例
# Using specific provider
from freecad_ai import CADAssistant
# Initialize with Claude Sonnet 4
assistant = CADAssistant(provider="anthropic", model="claude-sonnet-4")
# Create complex geometry
result = assistant.generate_cad_script(
"Create a parametric gear with 20 teeth, 5mm module, and 20° pressure angle"
)
# Using OpenRouter for cost optimization
assistant_free = CADAssistant(
provider="openrouter",
model="deepseek/deepseek-r1"
)
# Quick operations with free model
result = assistant_free.create_primitive("box", length=10, width=5, height=3)______________________________________________________________________
🚀 快速开始
选项1:FreeCAD插件（推荐给用户）
为了获得GUI集成的最佳用户体验：
- 🧠 克劳德4与思维方式 -高级AI推理
- 🤖 多提供商支持 -Claude、Gemini、OpenRouter，拥有13款以上型号
- 🎨 现代图形用户界面 -专业标签式界面
- 🔗 通用连接 -所有MCP连接方法
- 📊 性能监控 -实时诊断
选项2:MCP服务器（适用于开发人员/集成）
# Clone the repository
git clone https://github.com/jango-blockchained/mcp-freecad.git
cd mcp-freecad
# Install dependencies
pip install -r requirements.txt
# Start the MCP server
python mcp_server.py
# Or with FastMCP mode (lightweight, ideal for Cursor IDE)
python mcp_server.py --mode fastmcp
# Or with custom config and debug logging
python mcp_server.py --config my_config.json --debugpython-m src.mcp_freecad.main--配置my_config json--调试
### Option 3: FastMCP Server (Cursor IDE & Latest Best Practices)
**✨ NEW: Updated to FastMCP 2.13.0.2** - Modern, declarative MCP server implementation.
Start the FastMCP server for Cursor IDE
python cursor_mcp_server.py
Or run the example to see available tools
python example_fastmcp_usage.py --all
**主要特点：**
- 🎯 **声明性API** -简单 `@mcp.tool()` 和 `@mcp.resource()` 装饰器
- 🔒 **类型安全** -从类型提示自动生成架构
- 🚀 **最佳实践** -遵循FastMCP 2.13推荐的模式
- ✅ **测试良好** -综合测试套件，合格率100%
- 📚 **优秀的文档** -请参阅 [FASTCMP_实施.md](docs/FASTMCP_IMPLEMENTATION.md)
**可用工具：**
- `test_connection` -测试FreeCAD连接
- `create_box` -创建长方体图元
- `create_cylinder` -创建圆柱体
- `create_sphere` -创建球体
- `create_document` -管理FreeCAD文档
**资源：**
- `freecad://status` -获取服务器状态和FreeCAD可用性
有关详细用法，请参阅 [FastMCP实施指南](docs/FASTMCP_IMPLEMENTATION.md).
______________________________________________________________________
## 🏗️ **架构概述**
### 核心组件
src/mcp_freecad/ ├── main.py # Main entry point ├── __init__.py # Package exports and registry ├── client/ # FreeCAD connection management │ └── freecad_connection_manager.py ├── server/ # MCP server implementation │ └── freecad_mcp_server.py ├── tools/ # Tool providers │ ├── base.py # Base tool provider class │ ├── primitives.py # Primitive shapes (box, cylinder, etc.) │ ├── model_manipulation.py # Transform, boolean ops, etc. │ ├── export_import.py # File format handling │ ├── measurement.py # Analysis tools │ └── code_generator.py # Code generation ├── core/ # Core infrastructure │ ├── server.py # FastAPI-based server │ ├── cache.py # Resource caching │ ├── diagnostics.py # Performance monitoring │ └── recovery.py # Connection recovery └── connections/ # Connection backends
### 连接方法
系统支持多种方式连接到FreeCAD：
1. **🚀 启动器** （推荐）-将AppImage与AppRun结合使用
1. **🔌 服务器** -基于套接字的FreeCAD服务器连接
1. **🌉 桥** -使用FreeCAD可执行文件进行基于CLI的连接
1. **📡 远程过程调用** -与FreeCAD的XML-RPC连接
1. **📦 包装器** -子进程包装器连接
1. **🎭 模拟** -用于无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
Create connection (auto-selects best method)
fc = FreeCADConnection(auto_connect=True)
if fc.is_connected(): print(f"Connected via: {fc.get_connection_type()}")
# Create a document doc_name = fc.create_document("MyProject")
# Create objects box = fc.create_box(length=20, width=10, height=5) cylinder = fc.create_cylinder(radius=3, height=10)
# Export fc.export_stl(box, "my_box.stl")
### 工具提供程序使用情况
from src.mcp_freecad.tools.primitives import PrimitiveToolProvider
Initialize tool provider
primitives = PrimitiveToolProvider()
Execute tools
result = await primitives.execute_tool("create_box", { "length": 10.0, "width": 5.0, "height": 3.0 })
print(f"Created: {result.result['object_id']}")
### MCP服务器集成
from src.mcp_freecad.core.server import MCPServer from src.mcp_freecad import TOOL_PROVIDERS
Setup server
server = MCPServer()
Register tool providers
server.register_tool("primitives", TOOL_PROVIDERS["primitives"]()) server.register_tool("model_manipulation", TOOL_PROVIDERS["model_manipulation"]())
Initialize and run
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图形用户界面插件
- **`tests/`** -测试套件
- **`docs/`** -文件
- **`scripts/`** -设置和实用程序脚本
### 添加新工具
1. 在中创建新的工具提供程序 `src/mcp_freecad/tools/`
1. 从……继承…… `ToolProvider` 基类
1. 实施所需方法(`tool_schema`, `execute_tool`)
1. 注册 `TOOL_PROVIDERS` 在 `__init__.py`
from .base import ToolProvider, ToolResult, ToolSchema
class MyToolProvider(ToolProvider): @property def tool_schema(self) -> ToolSchema: return ToolSchema( name="my_tool", description="My custom tool", parameters={...}, returns={...} )
async def execute_tool(self, tool_id: str, params: Dict[str, Any]) -> ToolResult: # Implementation return self.format_result(status="success", result=result)
### 测试
Run tests
python -m pytest tests/
Run with coverage
python -m pytest tests/ --cov=src --cov-report=html
Run specific test
python -m pytest tests/test_primitives.py -v
______________________________________________________________________
## 🐳 **Docker支持**
Build and run with Docker Compose
docker compose up
Build from scratch
docker compose build --no-cache docker compose up
______________________________________________________________________
## 📚 **文档**
- [FreeCAD集成指南](docs/FREECAD_INTEGRATION.md)
- [连接方法](docs/CONNECTION_METHODS.md)
- [工具开发](docs/TOOL_DEVELOPMENT.md)
- [配置参考](docs/CONFIGURATION.md)
______________________________________________________________________
## 🤝 **贡献**
1. 分叉存储库
1. 创建要素分支
1. 进行更改
1. 添加测试
1. 提交拉取请求
______________________________________________________________________
## 📄 **许可证**
此项目根据MIT许可证获得许可-请参阅 [许可证](LICENSE) 文件以获取详细信息。
______________________________________________________________________
## 🙏 **致谢**
- FreeCAD开发团队为优秀的CAD软件
- 模型上下文协议（MCP）框架的拟人化
- 贡献者和社区成员
______________________________________________________________________
🛠️ MCP-FreeCAD Integration - Bridging AI and CAD through advanced connectivity
Crafted with ❤️ by jango-blockchained • 2025