内容
# FreeCAD 工具服务器
一个使用 HTTP + [MCP](https://modelcontextprotocol.io) 的工具服务器，允许您选择的 AI 代理以编程方式驱动 [FreeCAD](https://www.freecad.org) —— 通过输入的工具调用，构建、分析并导出真正的 3D CAD 几何体。
代理调用 REST 端点（或 MCP 工具）以创建基本形状，运行布尔运算，生成翼型，钻孔，圆角边缘，检查间隙，通过 [Elmer](https://www.elmerfem.org) 运行有限元分析，并导出验证的 STEP 文件 —— 在每一步都接收结构化反馈。
```
您的代理（Claude Code，Claude Desktop，任何 MCP/HTTP 客户端）
│ MCP 工具 或 HTTP 上的 JSON
▼
FreeCAD 工具服务器 （main.py，models.py 中的类型模型）
│ 进程内导入
▼
FreeCAD 1.1 捆绑 Python ──► OpenCASCADE 几何内核
```
服务器在 **FreeCAD 的捆绑 Python 解释器**中运行 —— FreeCAD 作为模块导入，而不是作为子进程运行。这就是为什么您使用 FreeCAD 的 `python.exe` 启动它，而不是您的系统 Python。
---
## 前置条件
- **[FreeCAD 1.1+](https://www.freecad.org/downloads.php)** 已安装（自带 Python 3.11）。
- *(可选，用于有限元分析)* **[Elmer](https://www.elmerfem.org/blog/binaries/)** 和 **[Gmsh](https://gmsh.info)** 在您的 `PATH` 中，用于 `/fem/*` 端点和 `elmer_*.py` 运行程序。
运行服务器不需要系统 Python —— FreeCAD 的解释器提供了一切。
---
## 设置
### 1. 在 FreeCAD 的解释器中安装 Python 依赖项
**Windows**
```bat
"C:\Program Files\FreeCAD 1.1\bin\python.exe" -m pip install -r requirements.txt
```
**Linux / macOS** （根据您的 FreeCAD 安装进行调整）
```bash
/path/to/FreeCAD/bin/python -m pip install -r requirements.txt
```
### 2. 启动服务器
**Windows** —— 如果需要，请编辑 `start.bat` 中的 FreeCAD 路径，然后：
```bat
start.bat
```
**Linux / macOS** —— 将 `FREECAD_PYTHON` 设置为您的 FreeCAD 解释器，然后：
```bash
FREECAD_PYTHON=/path/to/FreeCAD/bin/python ./start.sh
```
服务器监听 **http://localhost:8000**。交互式 API 文档（Swagger UI）位于 **http://localhost:8000/docs**。
### 3. 健康检查
```bash
curl http://localhost:8000/health
# {"status":"ok","freecad_available":true,"freecad_version":"1.1.1",...}
```
---
## 连接您的代理
### 选项 A —— MCP（Claude Code，Claude Desktop，任何 MCP 客户端）
`mcp_server.py` 通过模型上下文协议公开工具服务器。指向您的 MCP 客户端。对于 **Claude Code**，将其添加到您的 MCP 配置中：
```bash
claude mcp add freecad -- "C:\Program Files\FreeCAD 1.1\bin\python.exe" /path/to/mcp_server.py
```
或在客户端的 MCP 设置 JSON 中添加一个条目：
```json
{
"mcpServers": {
"freecad": {
"command": "C:\\Program Files\\FreeCAD 1.1\\bin\\python.exe",
"args": ["/absolute/path/to/mcp_server.py"]
}
}
}
```
然后，代理获得每个 FreeCAD 工具作为原生 MCP 工具。
### 选项 B —— Claude Code 直接读取 `AGENTS.md` / `CLAUDE.md`
克隆此仓库并在 Claude Code（或任何读取 `AGENTS.md` 的代理）中打开它。捆绑的 [`AGENTS.md`](AGENTS.md) 是一个完整的运行手册 —— 建模循环、每个端点、常见陷阱和所需的集成检查。启动服务器，告诉您的代理构建什么，它使用该指南驱动 HTTP API。副本作为 `CLAUDE.md` 提供，以便 Claude Code 自动加载。
### 选项 C —— 任何语言的原始 HTTP
每个工具都是一个普通的 REST 端点。 [`tools/freecad_client.py`](tools/freecad_client.py) 中的最小标准库 Python 客户端（无额外依赖）：
```python
from tools.freecad_client import FreeCADClient
fc = FreeCADClient() # 默认值为 http://127.0.0.1:8000
fc.tool("POST", "/document/create", name="demo")
fc.tool("POST", "/shapes/add_box", name="b", length=50, width=30, height=10)
info = fc.tool("POST", "/model/get_shape_info", shape_name="b")
print(info["volume_mm3"]) # 15000.0
```
---
## 核心建模循环
```
create_document
→ 添加基本形状（add_box / add_cylinder / add_cone / add_wing）
→ 布尔运算（boolean_union / boolean_cut / make_hole）
→ 检查（get_shape_info / bounding_box / check_interference）
→ 完成（fillet_edges / chamfer_edges）
→ 导出（export_step）
→ 验证（validate_step） ← 目标是 is_clean == true, solid_count == 1
```
有关完整的端点参考、边缘选择器规则、就地布尔更新模式和机械集成检查（干扰/间隙）的详细信息，请参见 [`AGENTS.md`](AGENTS.md)。
---
## 有限元分析（可选）
安装 Elmer 和 Gmsh 后，`/fem/*` 端点和 `elmer_*.py` 运行程序涵盖了广泛的教程集 —— 弹性、热、电静学、磁静学、流体流动、本征模式等。这些较为繁重，需要外部 Elmer/Gmsh 工具链；CAD 工具无需它们即可工作。
---
## 仓库布局
| 路径 | 它是什么 |
|---|---|
| `main.py` | FastAPI 工具服务器 —— 所有 HTTP 端点 |
| `session.py` | FreeCAD 会话逻辑（几何、布尔值、导出、有限元分析） |
| `models.py` | 类型化的 Pydantic 请求/响应模型 |
| `mcp_server.py` | MCP 桥 —— 将工具公开给 MCP 客户端 |
| `freecad_bridge.py` | 无头 FreeCAD 发现/导入助手 |
| `AGENTS.md` / `CLAUDE.md` | 代理操作手册（内容相同） |
| `elmer_*.py` | 独立的 Elmer 有限元分析教程运行程序 |
| `tools/` | 客户端助手、测试套件、集成检查钩子、示例脚本 |
| `start.bat` / `start.sh` | 启动器（使用 FreeCAD 的捆绑 Python） |
---
## 许可证
[MIT](LICENSE)。
