# 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-17 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # CATIA V5 MCP Server 基于 **MCP (Model Context Protocol)** 的 CATIA V5 自动化服务，通过 **Streamable HTTP 远程模式**暴露 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 # 默认启动（Streamable HTTP，127.0.0.1:8080） python server.py # 远程部署 python server.py --host 0.0.0.0 --port 9090 # 纯 JSON 响应模式（不依赖 SSE） python server.py --json-response # 无状态模式（每请求创建新 transport） python server.py --stateless # stdio 模式（本地进程，用于 Claude Desktop 集成） python server.py --transport stdio ``` 也可以通过 `.env` 文件配置（复制 `.env.example` 为 `.env` 修改）： ```bash FASTMCP_HOST=0.0.0.0 FASTMCP_PORT=9090 FASTMCP_LOG_LEVEL=INFO ``` ### 3. 在 Claude Code 中使用 ```bash claude mcp add --transport http catia-v5 http://localhost:8080/mcp ``` ### 4. 在 Claude Desktop 中使用 在 `claude_desktop_config.json` 中添加： ```json { "mcpServers": { "catia-v5": { "url": "http://localhost:8080/mcp" } } } ``` --- ## 项目结构 ``` catia_v5_mcp/ ├── server.py # 入口点 — 解析参数，创建服务器，启动 ├── .env.example # 环境变量配置模板 ├── catia_mcp/ # 主包 │ ├── __init__.py # 包初始化，导出 create_server │ ├── app.py # create_server() 工厂函数 │ ├── tools_basic.py # 基础工具注册（连接/状态/文档管理） │ ├── tools_geometry.py # 几何工具注册（点/球/圆柱/平面） │ ├── part_module.py # CATIA Part 文档管理 │ └── hybridshape_ops.py # GSD 几何操作封装 ├── tests/ │ ├── __init__.py │ └── test_client.py # MCP 测试客户端 ├── examples/ │ └── create_sphere_demo.py # 独立示例（不依赖 MCP） ├── claude_desktop_config.example.json ├── requirements.txt └── README.md ``` --- ## 架构设计 ``` ┌─────────────────┐ Streamable HTTP ┌────────────────────┐ │ Claude Desktop │ ◄──────────────────► │ MCP Server │ │ / Claude Code │ JSON-RPC over HTTP │ (Python/FastMCP) │ │ / MCP 客户端 │ 端点: /mcp │ │ └─────────────────┘ └─────────┬──────────┘ │ COM Automation ▼ ┌────────────────────┐ │ CATIA V5 App │ │ (COM Server) │ │ Part / Product │ │ HybridShape (GSD) │ └────────────────────┘ ``` ### 模块职责 | 模块 | 职责 | |------|------| | `server.py` | CLI 入口，参数解析，创建服务器、注册工具、启动 | | `catia_mcp/app.py` | `create_server()` 工厂，封装 FastMCP 配置 | | `catia_mcp/tools_basic.py` | `register_basic_tools()` — 基础 MCP 工具注册 | | `catia_mcp/tools_geometry.py` | `register_geometry_tools()` — 几何 MCP 工具注册 | | `catia_mcp/part_module.py` | COM 连接管理（连接/启动/释放 CATIA） | | `catia_mcp/hybridshape_ops.py` | GSD 曲面/线框操作（纯业务逻辑，不依赖 MCP） | ### Streamable HTTP 传输模式 本项目默认使用 **Streamable HTTP** 传输模式，相比传统 stdio/SSE 有以下优势： | 特性 | stdio | SSE | Streamable HTTP | |------|-------|-----|-----------------| | 远程连接 | N | Y | Y | | 会话管理 | N/A | 隐式 | 显式（Session ID） | | 断线重连 | N | N | Y（EventStore） | | 纯 JSON 响应 | N/A | N | Y（json_response） | | 无状态模式 | N/A | N | Y（stateless_http） | | 认证支持 | N | N | Y（Bearer Token） | | CORS / 安全 | N/A | 有限 | Y（Transport Security） | ### 配置优先级 ``` CLI 参数 > .env 环境变量 (FASTMCP_*) > SDK 默认值 ``` --- ## MCP 工具清单 ### 基础操作 | 工具名称 | 功能 | |---------|------| | `catia_connect` | 连接（或启动）CATIA 应用 | | `catia_status` | 检查 CATIA 连接状态 | | `new_part` | 新建 Part 文档 | | `save_current_document` | 保存当前文档 | ### 几何建模（GSD 曲面） | 工具名称 | 功能 | |---------|------| | `create_point` | 创建点 (xyz 坐标) | | `create_sphere_surface` | 创建球体曲面 (中心+半径) | | `create_cylinder_surface` | 创建圆柱曲面 | | `create_offset_plane` | 创建平面 (偏移/通过点) | | `new_part_with_sphere` | 一键新建带球体的 Part | --- ## 示例 ### 画一个球体曲面 通过 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 模块）。 ### 远程部署示例 ```bash # 服务器端（远程机器） python server.py --host 0.0.0.0 --port 9090 # 客户端连接 claude mcp add --transport http catia-v5 http://:9090/mcp ``` --- ## 依赖 - `mcp>=1.0.0` — Model Context Protocol Python SDK（含 Streamable HTTP 支持） - `comtypes>=1.4.0` — Python COM 库（用于 CATIA 交互） - `httpx>=0.27.0` — HTTP 传输支持 - `uvicorn` — ASGI 服务器（MCP SDK 依赖，自动安装） --- ## 扩展指南 添加新的几何工具只需两步： 1. 在 `catia_mcp/hybridshape_ops.py` 中实现功能函数 2. 在 `catia_mcp/tools_geometry.py` 的 `register_geometry_tools()` 中用 `@mcp.tool()` 注册 示例： ```python # catia_mcp/hybridshape_ops.py def create_cylinder(catia, radius, height): """创建圆柱曲面""" # ... CATIA API 调用 ... # catia_mcp/tools_geometry.py def register_geometry_tools(mcp): @mcp.tool() async def create_cylinder_surface(radius: float, height: float) -> str: """创建圆柱曲面""" catia = ensure_catia() doc = catia.ActiveDocument part = get_part_from_doc(doc) # 统一使用 get_part_from_doc 绕过 comtypes 缓存 bug return create_cylinder(part=part, radius=radius, height=height) ``` ### 添加新的工具类别 如需添加新类别的工具（如 `tools_assembly.py`），遵循同样的函数式注册模式： ```python # catia_mcp/tools_assembly.py def register_assembly_tools(mcp: FastMCP) -> None: @mcp.tool() def add_component(...) -> str: ... # server.py from catia_mcp.tools_assembly import register_assembly_tools register_assembly_tools(mcp) ``` --- ## 注意事项 1. **CATIA 必须已安装**：服务器依赖 CATIA 的 COM 接口，需要 CATIA V5 R21+。 2. **COM 线程模型**：COM 调用必须在 STA（Single-Threaded Apartment）下，`part_module.py` 已做处理。 3. **错误处理**：所有工具都包含 try-except 包装，连接失败会返回友好的错误信息。 4. **几何单位**：所有尺寸单位均为 **毫米 (mm)**，角度为 **度 (°)**。 5. **远程部署安全**：远程部署时（`--host 0.0.0.0`），请确保网络层面有防火墙/VPN 保护。服务器会自动关闭 DNS rebinding 保护以允许远程访问。 --- ## 参考 - [CATIA V5 Automation API 文档](./references/) - [MCP 协议规范](https://spec.modelcontextprotocol.io) - [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)