🏗️ ETABS FastMCP 服务器

用于ETABS结构分析与Claude桌面集成的专业级MCP服务器

🌟 概述

ETABS FastMCP 服务器提供了Claude桌面与ETABS（扩展三维建筑系统分析）结构分析软件之间的无缝集成。这个专业级解决方案采用优化了可扩展性、可靠性和易用性的混合Python+C#架构。

🏛️ 架构

┌─────────────────┐    JSON/stdio    ┌───────────────────┐    COM API    ┌─────────────┐
│   Claude AI     │ ◄────────────► │ Python FastMCP    │ ◄──────────► │ C# Connector │ ◄──────► │   ETABS    │
│   Desktop       │                 │ Server            │               │              │          │ 软件        │
└─────────────────┘                 └───────────────────┘               └─────────────┘          └─────────────┘

关键组件：

• Python FastMCP 服务器：带有@mcp.tool()装饰器的高级MCP接口
• C# ETABS 连接器：强大的COM接口管理器，用于ETABS API
• JSON通信：基于stdio的高效消息传递机制

🚀 快速开始

先决条件

1. ETABS 软件：安装并授权ETABS v18+
2. Python 3.8+：带pip包管理器
3. Visual Studio 2019+：或MSBuild工具用于C#编译
4. Claude 桌面：最新版本

安装

1. 克隆仓库：

   git clone <repository-url>
   cd ETABSFastMCP
   

2. 安装Python依赖项：

   cd python-server
   pip install -r requirements.txt
   

3. 构建C#连接器：

   cd ../csharp-connector
   msbuild ETABSConnector.csproj /p:Configuration=Release
   

4. 配置Claude桌面：

   • 将config/claude_desktop_config.json的内容复制到你的Claude桌面配置中
   • 更新路径以匹配你的安装目录

第一次运行

1. 启动ETABS（可选 - 服务器可以自动启动）

2. 测试连接：

   # 在Claude桌面中尝试：
   "连接到ETABS并创建一个新的空白模型"
   

3. 创建你的第一个结构元素：

   # 给Claude的示例命令：
   "在坐标(0, 0, 0)处创建一个点，并设置UZ约束"
   "从(0, 0, 0)到(10, 0, 0)创建一个框架，使用W14X90截面"
   

🔧 可用工具

连接管理

• connect_to_etabs() - 连接到ETABS应用程序
• create_blank_model() - 创建新的空白模型
• get_connection_status() - 检查连接状态
• disconnect_from_etabs() - 从ETABS断开连接

点操作（CRUD）

• create_point(x, y, z, name?, restraints?) - 创建结构点
• get_point(name) - 获取点信息
• list_points() - 列出模型中的所有点
• modify_point(name, x?, y?, z?, restraints?) - 修改点属性
• delete_point(name) - 从模型中删除点

框架操作（CRUD）

• create_frame(start_x, start_y, start_z, end_x, end_y, end_z, name?, section?, material?) - 创建框架元素
• get_frame(name) - 获取框架信息
• list_frames() - 列出模型中的所有框架
• modify_frame(name, section?, material?) - 修改框架属性
• delete_frame(name) - 从模型中删除框架

模型管理

• save_model(file_path?) - 保存当前模型
• health_check() - 检查系统健康状况

💡 使用示例

基本结构模型创建

# 通过Claude桌面对话：

"连接到ETABS并创建一个新的空白模型"

"创建以下点：
- 点A在(0, 0, 0)，具有UX, UY, UZ约束
- 点B在(10, 0, 0)，具有UZ约束
- 点C在(10, 10, 0)，具有UZ约束
- 点D在(0, 10, 0)，具有UZ约束"

"创建框架连接这些点形成矩形框架：
- 框架AB从点A到B，使用W14X90截面
- 框架BC从点B到C，使用W14X90截面
- 框架CD从点C到D，使用W14X90截面
- 框架DA从点D到A，使用W14X90截面"

"列出模型中的所有框架并显示它们的属性"

高级操作

"创建一个3D建筑物框架：
1. 在标高0处创建一个4x4点网格，间距8米
2. 在标高4米处创建另一个相同的网格
3. 使用W14X74截面连接对应的点形成垂直柱子
4. 使用W21X50截面连接每一层的点形成梁
5. 对所有基点应用铰接约束"

🔧 扩展系统

添加新的ETABS API功能

该系统设计易于扩展。要添加新的ETABS功能：

1. 添加到C#连接器：

   // 在CommandProcessor.cs中添加新情况：
   "your_new_command" => ProcessYourNewCommand(command.Parameters),
   
   // 实现方法：
   private CommandResponse ProcessYourNewCommand(Dictionary<string, object> parameters)
   {
       // 在这里调用ETABS API
       return new CommandResponse { Success = true, Data = result };
   }
   

2. 添加到Python服务器：

   @mcp.tool()
   async def your_new_function(param1: str, param2: float) -> Dict[str, Any]:
       """
       新功能的描述
       """
       try:
           response = await connector.send_command("your_new_command", {
               "param1": param1,
               "param2": param2
           })
           return response
       except Exception as e:
           return {"success": False, "error": str(e)}
   

常见扩展

分析操作：

• 运行分析
• 获取分析结果
• 提取力和弯矩

加载操作：

• 创建加载模式
• 向元素施加负载
• 加载组合

设计操作：

• 运行钢结构设计
• 获取设计结果
• 优化截面

🏗️ 专业特性

错误处理与恢复

• 整个过程中的全面异常处理
• 崩溃时自动进程恢复
• 详细的错误日志记录和报告

性能优化

• 高效的JSON序列化
• 最小的内存占用
• 优化的COM对象管理

可扩展性

• 模块化架构易于扩展
• 清晰的责任分离
• 专业的代码组织

生产就绪

• 全面的日志记录
• 健康监控
• 平稳关闭处理
• 资源清理

🔍 故障排除

常见问题

连接错误：

错误："无法启动ETABS连接器"
- 确保已安装并授权ETABS
- 检查ETABSv1.dll是否可访问
- 验证已安装.NET Framework 4.8

权限问题：

错误："访问ETABS API被拒绝"
- 如需，请以管理员身份运行
- 检查ETABS许可状态
- 验证COM对象注册

通信错误：

错误："未收到ETABS连接器响应"
- 检查C#连接器构建成功
- 验证Python能否执行连接器
- 检查进程权限

调试模式

通过设置环境变量启用详细日志记录：

set ETABS_MCP_DEBUG=1

📚 API参考

数据类型

Point3D：

{
  "x": 0.0,
  "y": 0.0,
  "z": 0.0
}

Restraints：

{
  "UX": true,   // X方向平移
  "UY": false,  // Y方向平移
  "UZ": true,   // Z方向平移
  "RX": false,  // X方向旋转
  "RY": false,  // Y方向旋转
  "RZ": false   // Z方向旋转
}

Frame Properties：

{
  "name": "F1",
  "startPoint": {"x": 10, "y": 0, "z": 0},
  "endPoint": {"x": 10, "y": 0, "z": 0},
  "section": "W14X90",
  "material": "A992",
  "length": 10.0
}

🤝 贡献

1. 分叉仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m '添加神奇功能')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开拉取请求

📄 许可证

此项目采用MIT许可证 - 详情参见LICENSE文件。

🙏 致谢

• CSI（计算机与结构公司）提供ETABS软件
• Anthropic提供Claude和MCP协议
• FastMCP库贡献者

---

为结构工程社区打造，充满爱心的专业级生产就绪解决方案