# 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-27 ## 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 # 设置 PYTHONPATH（必须包含 src/ 目录） $env:PYTHONPATH = "D:\SYNC\AIWORK\CATIA_V5_MCP\src" # 默认启动（Streamable HTTP，127.0.0.1:8080） python -m catia_v5_mcp.server # 远程部署 python -m catia_v5_mcp.server --host 0.0.0.0 --port 9090 # 纯 JSON 响应模式（不依赖 SSE） python -m catia_v5_mcp.server --json-response # 无状态模式（每请求创建新 transport） python -m catia_v5_mcp.server --stateless # stdio 模式（本地进程，用于 Claude Desktop 集成） python -m catia_v5_mcp.server --transport stdio ``` 也可以通过一键启动脚本： ```bash .\start.bat # 简化启动（自动设置 PYTHONPATH） .\start_server.ps1 # PowerShell 启动（支持更多参数） .\start_server.ps1 -Remote # 远程模式 .\start_server.ps1 -Stdio # 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/ ├── config/ # 项目配置 │ └── settings.json # 服务器配置（端口、日志级别等） ├── python3dx/ # CATIA COM 自动化工具库 │ ├── __init__.py │ ├── catia_utils.py │ └── lib/ │ ├── __init__.py │ └── com3dx.py # COM 连接封装 ├── src/ # 源代码 │ └── catia_v5_mcp/ │ ├── __init__.py │ ├── server.py # CLI 入口，参数解析，启动服务器 │ ├── app.py # FastMCP 工厂（create_server） │ ├── config.py # settings.json 加载器 │ ├── part_module.py # CATIA COM 连接管理 │ ├── hybridshape_ops.py # GSD 曲面/线框操作 │ ├── sketch_ops.py # 草图操作 │ ├── partdesign_ops.py # Part Design 操作（pad/pocket/fillet...） │ └── tools/ # MCP 工具注册层 │ ├── __init__.py # 统一 re-export │ ├── basic.py # 基础工具（连接/状态/新建/保存） │ ├── geometry.py # 几何工具（点/球/圆柱/平面） │ ├── sketch.py # 草图工具 │ ├── partdesign.py # Part Design 工具 │ └── document.py # 文档管理工具 ├── examples/ # 独立示例 │ └── create_sphere_demo.py ├── tests/ # 测试文件 ├── start.bat # 一键启动（简化版） ├── start_server.py # Python 启动入口（V6 风格） ├── start_server.bat # 批处理启动脚本 ├── start_server.ps1 # PowerShell 启动脚本 ├── pyproject.toml # 项目元数据和构建配置 ├── requirements.txt # Python 依赖 ├── CLAUDE.md # Claude Code 项目指南 ├── AGENTS.md # Agent 协议 └── 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) │ └────────────────────┘ ``` ### 模块职责 | 模块 | 职责 | |------|------| | `src/catia_v5_mcp/server.py` | CLI 入口，参数解析，创建服务器、注册工具、启动 | | `src/catia_v5_mcp/app.py` | `create_server()` 工厂，封装 FastMCP 配置 | | `src/catia_v5_mcp/config.py` | settings.json 配置加载 | | `src/catia_v5_mcp/tools/basic.py` | `register_basic_tools()` — 基础 MCP 工具注册 | | `src/catia_v5_mcp/tools/geometry.py` | `register_geometry_tools()` — 几何 MCP 工具注册 | | `src/catia_v5_mcp/part_module.py` | COM 连接管理（连接/启动/释放 CATIA） | | `src/catia_v5_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_*) > config/settings.json > 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 | --- ## 扩展指南 添加新的几何工具只需两步： 1. 在 `src/catia_v5_mcp/hybridshape_ops.py` 中实现功能函数 2. 在 `src/catia_v5_mcp/tools/geometry.py` 的 `register_geometry_tools()` 中用 `@mcp.tool()` 注册 ### 添加新的工具类别 如需添加新类别的工具（如 `tools/assembly.py`），遵循同样的函数式注册模式： ```python # src/catia_v5_mcp/tools/assembly.py def register_assembly_tools(mcp: FastMCP) -> None: @mcp.tool() def add_component(...) -> str: ... # src/catia_v5_mcp/tools/__init__.py from .assembly import register_assembly_tools # src/catia_v5_mcp/server.py from .tools 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)