# CATIA_V5_MCP

**Repository Path**: xuscode1/CATIA_V5_MCP

## Basic Information

- **Project Name**: CATIA_V5_MCP
- **Description**: CATIA_V5_MCP
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-08
- **Last Updated**: 2026-06-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CATIA V5 MCP Server

基于 **MCP (Model Context Protocol)** 的 CATIA V5 自动化服务，通过标准 MCP 协议暴露 CATIA V5 的 COM Automation API，让 Claude 等 AI 助手可以直接操控 CATIA V5 进行建模、几何操作等。

---

## 快速开始

### 1. 环境准备

```bash
pip install -r requirements.txt
```

> 注意：需要 CATIA V5 已安装，且支持 COM Automation（所有 CATIA V5 版本默认支持）。

### 2. 启动 MCP Server

```bash
python server.py
```

默认启动在 `http://127.0.0.1:8080`，支持 SSE（Server-Sent Events）传输。

### 3. 在 Claude Desktop 中使用

在 `claude_desktop_config.json` 中添加：

```json
{
  "mcpServers": {
    "catia-v5": {
      "command": "python",
      "args": ["D:/SYNC/CODE/CATIA_V5_MCP/server.py"],
      "env": {}
    }
  }
}
```

---

## 项目结构

```
catia_v5_mcp/
├── server.py                 # MCP 服务器主入口，注册所有工具
├── catia_bridge.py           # CATIA COM 连接管理器
├── catia_tools.py            # 工具定义和实现
├── hybridshape_ops.py        # GSD (Generative Shape Design) 几何操作
├── requirements.txt          # 依赖清单
└── README.md                 # 本文件
```

---

## 架构设计

```
┌─────────────┐    MCP协议     ┌────────────────┐
│  Claude AI   │ ◄───────────► │  MCP Server    │
│  / MCP客户端 │   JSON-RPC    │  (Python)      │
└─────────────┘                └───────┬────────┘
                                       │ COM Automation
                                       ▼
                               ┌────────────────┐
                               │  CATIA V5 App  │
                               │  (COM Server)  │
                               │  Part/Product  │
                               │  HybridShape   │
                               └────────────────┘
```

### 关键模块

| 模块 | 职责 |
|------|------|
| `server.py` | MCP 服务启动、工具注册、SSE 传输 |
| `catia_bridge.py` | 管理 CATIA COM 连接（启动/获取/释放） |
| `catia_tools.py` | 所有暴露给 MCP 的工具函数 |
| `hybridshape_ops.py` | GSD 曲面/线框操作封装 |

---

## MCP 工具清单

### 基础操作

| 工具名称 | 功能 |
|---------|------|
| `catia_connect` | 连接（或启动）CATIA 应用 |
| `catia_status` | 检查 CATIA 连接状态 |
| `new_part` | 新建 Part 文档 |
| `new_product` | 新建 Product 文档 |
| `save_document` | 保存当前文档 |

### 几何建模（GSD 曲面）

| 工具名称 | 功能 |
|---------|------|
| `create_point` | 创建点 (xyz 坐标) |
| `create_line` | 创建直线 (两点) |
| `create_sphere_surface` | 创建球体曲面 (中心+半径) |
| `create_cylinder_surface` | 创建圆柱曲面 |
| `create_plane` | 创建平面 (偏移/通过点) |

---

## 示例

### 画一个球体曲面

通过 MCP 调用 `create_sphere_surface` 工具：

```python
# 在 MCP 客户端中调用
result = await client.call_tool("create_sphere_surface", {
    "center_x": 0,
    "center_y": 0,
    "center_z": 0,
    "radius": 50.0,
    "geometrical_set_name": "Sphere Surface"
})
```

效果：在 CATIA V5 中创建一个半径为 50mm 的完整球体曲面（GSD 模块）。

### 生成完整零件

```python
result = await client.call_tool("create_sphere_with_part", {
    "part_name": "MySphere",
    "center_x": 0,
    "center_y": 0,
    "center_z": 0,
    "radius": 50.0
})
```

---

## 依赖

- `mcp` — Model Context Protocol Python SDK
- `comtypes` — Python COM 库（用于 CATIA 交互）
- `httpx` — HTTP 传输支持

> 可选：`pywin32` 可替代 `comtypes`，但推荐 `comtypes` 更轻量稳定。

---

## 注意事项

1. **CATIA 必须已安装**：服务器依赖 CATIA 的 COM 接口，需要 CATIA V5 R21+。
2. **COM 线程模型**：COM 调用必须在 STA（Single-Threaded Apartment）下，`catia_bridge.py` 已做处理。
3. **错误处理**：所有工具都包含 try-except 包装，连接失败会返回友好的错误信息。
4. **几何单位**：所有尺寸单位均为 **毫米 (mm)**，角度为 **度 (°)**。

---

## 扩展指南

添加新的几何工具只需两步：

1. 在 `hybridshape_ops.py` 中实现功能函数
2. 在 `catia_tools.py` 中用 `@mcp.tool()` 注册

示例：
```python
# hybridshape_ops.py
def create_cylinder(catia, radius, height):
    """创建圆柱曲面"""
    # ... CATIA API 调用 ...

# catia_tools.py
@mcp.tool()
async def create_cylinder_surface(radius: float, height: float) -> str:
    """创建圆柱曲面"""
    return create_cylinder(ensure_catia(), radius, height)
```

---

## 参考

- [CATIA V5 Automation API 文档](./references/)
- [MCP 协议规范](https://spec.modelcontextprotocol.io)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)