risa3d-mcp-server

# RISA-3D MCP 服务器 + CLI 工具包 > 使用模型上下文协议（MCP）将 Claude AI 连接到您的 RISA-3D 结构模型。 由结构工程师构建，旨在为 RISA-3D 带来 AI 辅助工作流。该 MCP 服务器允许您用简单的英语与 `.r3d` 文件对话，无需编码。      --- ## 演示 > *"为报告总结此模型"* > *"此模型使用什么钢材等级？"* > *"柱基的边界条件是什么？"* > *"比较这两个模型并告诉我有什么变化"* 连接后，只需将 Claude 指向任何 `.r3d` 文件并开始提问。 --- ## 为什么存在该项目 RISA-3D 没有公开的 API。 该项目通过将 `.r3d` 文件作为接口，允许 AI 助手检查、比较、修改和报告结构模型，而无需自动运行 RISA 应用程序本身。 目标是增强结构工程师，而不是取代工程判断。 --- ## 什么是该项目 MCP（模型上下文协议）是一个开放标准，允许像 Claude 这样的 AI 助手连接到外部工具和文件。该服务器充当 Claude Desktop 和您的 RISA-3D 模型之间的桥梁。Claude 直接读取您的 `.r3d` 文件并用简单的英语回答问题。 不需要 RISA-3D API。该项目通过直接读取 RISA-3D 的纯文本 `.r3d` 文件格式来工作。包括一个模块化回归测试套件，以确保解析器和写入工具的可靠性随着项目的进展而得到保障。 --- ## 快速入门 ```bash git clone https://github.com/vibhanshu-mishra/risa3d-mcp-server.git cd risa3d-mcp-server npm install node risa-cli.js help ``` 有关 Claude Desktop 集成，请继续阅读下面的安装部分。 --- ## 目录 - [为什么存在该项目](#为什么存在该项目) - [什么是该项目](#什么是该项目) - [快速入门](#快速入门) - [架构](#架构) - [项目结构](#项目结构) - [MCP 工具](#mcp-工具) - [示例提示](#示例提示) - [CLI 用法](#cli-用法) - [技术说明](#技术说明) - [回归测试](#回归测试) - [路线图](#路线图) - [已知限制](#已知限制) - [许可证](#许可证) --- ## 架构 Claude Desktop │ MCP（index.js） │ risa-core.js / \ risa-cli.js .r3d 文件 --- ## 项目结构 ```text risa3d-mcp-server/ │ ├── index.js ├── risa-core.js ├── risa-cli.js │ ├── tests/ │ │ ├── parser.test.js │ ├── loads.test.js │ ├── qc.test.js │ ├── write-tools.test.js │ ├── geometry.test.js │ ├── run-tests.js │ ├── run-all.js │ └── test-utils.js │ ├── package.json ├── README.md └── CHANGELOG.md ``` --- ## 服务器功能 该 MCP 服务器读取和修改 `.r3d` RISA-3D 模型文件。 它可以： - 读取节点、成员、截面、支撑、荷载工况和荷载组合 - 生成模型摘要 - 生成按 RISA 基本荷载工况分组的荷载摘要 - 将成员进度表导出到 Excel - 克隆模型并进行受控更改 - 对 RISA 模型运行 QA/QC 检查 - 在不使用 Claude/MCP 的情况下运行 CLI 诊断 目前包括 40 多种 MCP 工具，涵盖： - 模型查询 - QA/QC - 荷载解析和验证 - 材料估算 - SAF 和 Excel 导出 - 模型比较 - 模型克隆和编辑 - CLI 调试工具包 - 几何编辑 - 批处理工作流 - 回归测试的解析实用程序 --- ## 不使用 Claude 该项目包括一个独立的命令行界面（`risa-cli.js`）。 这允许工程师在不安装 Claude Desktop 或使用 MCP 的情况下测试解析逻辑并生成报告。 示例： ```cmd node risa-cli.js generate-load-summary "C:\Models\TEST.r3d" ``` 有用： - 测试解析器更改 - 验证荷载提取 - 调试 RISA 文件 - 在本地运行报告 --- ## 您可以使用 连接后，您可以问 Claude： - *"为报告总结此模型 -- 包括成员、节点、荷载、边界条件和材料"* - *"此模型使用什么钢材等级和 Fy 值？"* - *"列出所有边界条件，哪些节点是固定的，哪些是铰接的？"* - *"哪些截面尺寸被分配给每个截面集？"* - *"列出所有成员及其截面尺寸"* - *"对该模型运行 QC 检查"* - *"比较这两个模型并告诉我有什么变化"* - *"为所有 HSS 成员导出成员进度表"* --- ## 要求 - 安装 RISA-3D 的 Windows PC - [Claude Desktop](https://claude.ai/download) （免费） - [Node.js](https://nodejs.org) （LTS 版本 -- 免费） - Claude 账户 --- ## 安装 ### 步骤 1 -- 安装 Node.js 从 [nodejs.org](https://nodejs.org) 下载并安装 **LTS 版本**。点击所有默认值。 验证是否成功，打开命令提示符并运行： ``` node --version npm --version ``` 两者都应返回版本号。 --- ### 步骤 2 -- 下载项目 ```bash git clone https://github.com/vibhanshu-mishra/risa3d-mcp-server.git cd risa3d-mcp-server npm install ``` --- ### 步骤 3 -- 测试服务器 在命令提示符中运行： ``` cd risa3d-mcp-server node index.js ``` 如果您看到闪烁的光标且没有错误，它正在工作。按 **Ctrl+C** 停止它。 --- ### 步骤 4 -- 连接到 Claude Desktop 1. 如果您尚未安装，请安装 [Claude Desktop](https://claude.ai/download) 2. 按 **Windows + R**，输入 `%APPDATA%\Claude` 并按 Enter 3. 打开或创建 `claude_desktop_config.json` 4. 粘贴以下内容： ```json { "mcpServers": { "risa3d": { "command": "node", "args": [ "C:\\path\\to\\risa3d-mcp-server\\index.js" ] } } } ``` 5. 保存文件 6. 完全退出 Claude Desktop（右键单击系统托盘图标 -> 退出） 7. 重新打开 Claude Desktop --- ### 步骤 5 -- 验证它正在运行 在 Claude Desktop 中： 1. 点击聊天输入框中的 **+** 按钮 2. 点击 **连接器** 3. 您应该看到 **risa3d** 列为已连接 或前往 **设置 -> 开发者** 并确认risa3d 显示为 **running**。 --- ## 示例提示 ### 模型读取 ``` 总结此模型以备报告： "C:\path\to\model.r3d" ``` ``` 列出此模型中的所有成员。 ``` ``` 仅列出 Wide Flange 成员。 ``` ``` 此模型中使用了哪些材料？ ``` ``` 定义了哪些截面集？ ``` ``` 列出边界条件。 ``` ``` 定义了哪些荷载组合？ ``` --- ### QA / QC ``` 对该模型运行 QC 检查。 ``` ``` 检查此模型是否存在重复节点。 ``` ``` 查找所有使用 HSS8X8X10 的成员。 ``` ``` 标记长度超过 20 英尺的成员。 ``` ``` 比较这两个模型并总结差异。 ``` ``` 显示连接到 M41 的所有成员。 ``` ``` 显示连接到节点 N25 的所有成员。 ``` --- ### 编辑 ``` 将 Stringer 截面集从 C15X33.9 更改为 C12X20.7 并保存为新模型。 ``` ``` 克隆此模型并更改成员 M41 为 HSS6X6X10。 ``` ``` 移动节点 N44 到新坐标。 ``` ``` 删除成员 M20 至 M25。 ``` ``` 复制成员 M41 介于 N200 和 N205 之间。 ``` ``` 将成员 M41 分割为 50% 的长度。 ``` ``` 合并成员 M41 和 M42。 ``` --- ### 几何 ``` 关于 Y 轴镜像这些成员。 ``` ``` 复制这些成员，在 X 方向偏移 20 英尺。 ``` ``` 在 N44 和新点 (6,0,-12) 之间添加支撑。 ``` --- ### 批处理 ``` 总结此文件夹中的每个模型。 ``` ``` 将此文件夹中的每个模型汇总到 Excel。 ``` ``` 在该文件夹中的所有模型中将 C15X33.9 替换为 C12X20.7。 ``` ``` 对该文件夹中的每个模型运行 QC 检查并导出 Excel 摘要。 ``` --- ### 导出 ``` 将成员进度表导出到 Excel。 ``` ``` 将荷载汇总导出到 Excel。 ``` ``` 将此模型导出到 SAF 格式。 ``` ``` 生成材料估算。 ``` ``` 导出所有 HSS 成员的进度表。 ``` --- --- ## MCP 工具 ### 模型读取和报告 | 工具 | 描述 | |---|---| | `read_risa_model` | 读取 `.r3d` 文件并返回项目摘要（标题、节点数、成员数、板数、文件大小）。 | | `summarize_model_for_report` | 包括项目信息、成员、节点、材料、支撑、荷载和荷载组合的单一调用报告。 | | `list_members` | 按类型或详细列出成员，可选过滤。 | | `list_nodes` | 列出所有节点及其坐标。 | | `get_file_section` | 返回命名 `.r3d` 部分的原始内容。 | | `get_model_materials` | 列出所有定义的钢材材料和属性。 | | `get_boundary_conditions` | 返回所有支撑条件，并附有纯英文描述。 | | `get_section_sets` | 列出截面集和分配的成员尺寸。 | | `get_load_cases` | 列出所有基本荷载工况。 | | `list_load_combinations` | 列出所有荷载组合。 | | `get_deflection_limits` | 返回全局和成员挠度规则。 | --- ### QA / QC | 工具 | 描述 | |---|---| | `qc_check_risa_model` | 运行常见的 QA/QC 检查。 | | `find_duplicate_nodes` | 在坐标公差范围内查找重复节点。 | | `find_members_by_section` | 查找所有使用指定截面尺寸的成员。 | | `find_unbraced_length_issues` | 标记超过用户定义阈值的成员长度。 | | `find_connected_members` | 列出连接到指定成员的所有成员。 | | `get_member_connectivity_at_node` | 列出连接到指定节点的所有成员。 | | `compare_risa_models` | 比较两个 `.r3d` 模型并总结差异。 | --- ### 编辑工具 | 工具 | 描述 | |---|---| | `modify_section_set` | 更改截面尺寸并保存新模型。 | | `clone_model_with_changes` | 创建修改后的模型副本，并应用截面、支撑或荷载更改。 | | `add_member` | 使用现有或新创建的节点添加新成员。 | | `move_node` | 移动现有节点。 | | `delete_member` | 删除一个或多个成员。 | | `copy_member` | 在两个节点之间复制现有成员。 | | `split_member` | 将一个成员分成两个。 | | `merge_members` | 合并两个兼容的成员为一个。 | | `mirror_geometry` | 镜像选定的几何形状。 | | `copy_translate_geometry` | 使用 XYZ 偏移复制几何形状。 | --- ### 批处理工具 | 工具 | 描述 | |---|---| | `batch_summarize_folder` | 总结文件夹中的每个模型。 | | `batch_summarize_folder_to_excel` | 直接将文件夹摘要写入 Excel。 | | `replace_section_size_in_folder` | 在文件夹中的所有模型中替换截面尺寸。 | | `batch_replace_section_size` | 在一个模型中执行多个截面替换。 | | `batch_qc_folder` | 对整个文件夹运行 QC 检查并导出 Excel 摘要。 | --- ### 导出工具 | 工具 | 描述 | |---|---| | `export_member_schedule` | 将成员进度表导出为 CSV。 | | `export_member_schedule_to_excel` | 直接将成员进度表写入 Excel。 | | `export_load_summary_to_excel` | 直接将荷载摘要写入 Excel。 | | `export_to_saf` | 将模型导出到 SAF（`.xlsx`）格式。 | --- ## RISA-3D 荷载解析 RISA-3D `.r3d` 文件并不总是直接存储可见的荷载工况名称。例如，荷载行可能包含内部原始 ID： ```text 88 89 90``` 这些是内部 RISA 荷载标识符，不应假设与 RISA 接口中显示的基本荷载工况编号匹配。 该项目使用确认的 RISA 模式解析荷载： ```text [BASIC_LOAD_CASES] -> 分布荷载计数 -> 面积荷载计数 -> 节点荷载计数 -> 荷载表中的行顺序 ``` 共享的帮助程序 `parseLoadsByBasicLoadCase(content)` 根据可见的 RISA 基本荷载工况名称对荷载进行分组，例如： ```text DL LL WLx WLz BLC 1 Transient Area Loads ``` 而不是暴露内部原始 ID。 --- ## 当前荷载编辑支持 `clone_model_with_changes` 目前支持： - 截面尺寸更改 - 边界条件更改 - 成员分布荷载幅度更改 - 节点荷载幅度更改 不 目前编辑面积荷载。 面积荷载故意排除，因为 RISA 可能从面积荷载生成瞬时/成员化分布荷载。编辑面积荷载而不重新生成这些派生荷载可能会创建不一致的模型。 --- ## CLI 用法 CLI 位于 `risa-cli.js`。从项目文件夹运行命令： ```cmd node risa-cli.js help ### 生成荷载摘要 ```cmd node risa-cli.js generate-load-summary "C:\path\to\model.r3d" ``` 包括生成的瞬时荷载工况： ```cmd node risa-cli.js generate-load-summary "C:\path\to/model.r3d" --include-transient### 调试荷载工况计数 ```cmd node risa-cli.js debug-load-case-counts "C:\path/to/model.r3d" ### 调试原始荷载结构 ```cmd node risa-cli.js debug-load-structure "C:\path/to/model.r3d" 10 ### 调试成员荷载行 ```cmd node risa-cli.js debug-member-load-rows "C:\path/to/model.r3d" M41 ### 调试荷载成员资格 ```cmd node risa-cli.js debug-load-membership "C:\path/to/model.r3d" ``` --- ## MCP 用法 使用以下命令启动 MCP 服务器： ```cmd node index.js ``` 在您的 MCP 客户端配置中，指向： ```cmd node C:\path\to\risa3d-mcp-server\index.js ``` ## 安全注意事项 - 服务器永远不会覆盖原始文件进行克隆。 - 使用 `clone_model_with_changes` 时使用不同的 `outputPath`。 - 始终在 RISA-3D 中打开克隆的 `.r3d` 文件，并在使用它们进行设计之前进行验证。 - 将编写/编辑工具视为工程辅助工具，而不是最终设计权威。 --- ## 开发工作流 典型的开发工作流： 1. 在 `risa-core.js` 中添加或修改解析器。 2. 使用 `risa-cli.js` 进行本地测试。 3. 与真实的 `.r3d` 文件进行验证。 4. 将逻辑移动到 `index.js` 中的 MCP 工具。 5. 通过 Claude Desktop 进行再次测试。 CLI 存在专门用于解析器开发，因此在迭代过程中不需要 Claude 或 MCP。 --- ## 开发者检查 提交更改前，请运行： ```cmd node --check index.js node --check risa-core.js node --check risa-cli.js ``` --- ## 回归测试 该项目包含一个模块化回归测试套件，用于保护解析器和写入帮助程序在未来开发过程中不被破坏。 运行完整套件： ```cmd node tests\run-all.js ``` 当前覆盖率： - 解析器 - 荷载所有权 - 几何帮助程序 - QC 引擎 - 写入帮助程序 --- ## `.r3d` 格式的技术说明 RISA 的文件格式中的几个非显式特征，本服务器处理这些特征，供任何扩展它的开发人员记录： **1. 固定宽度引用字段。** 标签、类型和截面尺寸存储为引号填充的字符串，例如 `"M14 "`。幼稚的空格分割会将这些分割为多个幻象令牌。此服务器使用引用感知令牌器， 将 `"..."` 内的任何内容（包括内部空格）视为单个字段。 **2. 成员通过位置引用节点，而不是通过标签。** 在 `.MEMBERS_MAIN_DATA` 中，i 节点和 j 节点字段是基于 `[NODES]` 列表的基于 1 的索引 - 而不是节点标签字符串。例如，成员行中包含 `1 7`，意味着第 1 个列出的节点到第 7 个列出的节点，可能会解析为 `N5` 和 `N18`。此服务器将这些索引与有序节点数组进行解析。 **3. 荷载部分名称。** 点/节点荷载存储在 `[NODE_LOADS]` 下，而不是 `[JOINT_LOADS]`。成员分布荷载存储在 `[DIRECT_DISTRIBUTED_LOADS]` 下，而不是 `[MEMBER_DISTRIBUTED_LOADS]`。 **4. 荷载部分中的荷载工况 ID。** 存储在 `[NODE_LOADS]`、`[DIRECT_DISTRIBUTED_LOADS]` 和 `[AREA_LOADS]` 条目中的荷载工况索引是内部 RISA 数据库 ID，而不是 `[BASIC_LOAD_CASES]` 的顺序 1 基于索引。当找不到名称匹配时，工具将荷载工况标记为 `LC{n}`。 成员行格式（标记后）为： ``` Label, Type (e.g. "Wide Flange", "Tube", "Channel", "None"), Size (e.g. "W14X22", "HSS8X8X10"), iNodeIndex, jNodeIndex, ... ``` --- ## 路线图 - [x] 读取并总结任何 `.r3d` 模型 - [x] 列出带有类型、尺寸和解析的节点连接性的成员 - [x] 列出带有坐标的节点 - [x] 列出荷载组合 - [x] 获取原始文件部分按名称 - [x] 比较两个模型并总结差异 - [x] 以 CSV 格式导出成员进度表 - [x] QC 检查器，用于常见建模问题 - [x] 获取钢材材料属性（等级，E，Fy，Fu） - [x] 获取带有纯英文描述的边界条件 - [x] 获取截面集和分配的尺寸 - [x] 为报告汇总模型（包括荷载） - [x] 批量汇总项目文件夹中的所有模型 - [x] 获取带有荷载类型分类的基本荷载工况 - [x] 查找所有使用特定截面尺寸的成员 - [x] 获取挠度极限规则（全局和每个成员） - [x] 修改成员截面尺寸并保存更新的模型 - [x] 克隆模型并应用截面、边界条件和荷载更改 - [x] AISC 形状权重下的材料估算 - [x] 基于长度的筛选，用于非受力长度审查 - [x] 直接 `.xlsx` 导出（成员进度表和批量汇总） - [x] 添加连接现有或新节点的成员（支撑、柱等） - [x] 导出到 SAF 格式（`.xlsx`）以导入 SCIA、SOFiSTiK、AxisVM 和其他 SAF 兼容软件 - [x] 检测重复节点（坐标公差扫描） - [x] 在一个文件夹中的模型之间替换截面尺寸 - [x] 两个模型版本的差异（节点、成员、截面集、荷载组合） - [x] 静态 CLI 模式用于解析器测试 - [x] 使用基本荷载工况计数解析荷载所有权 - [x] 克隆模型中的节点荷载编辑 - [x] 批量替换一个模型中的多个截面尺寸 - [x] 批量 QC 文件夹导出到 Excel - [x] 将荷载汇总导出到 Excel - [x] 移动现有节点 - [x] 删除成员 - [x] 查找连接的成员 - [x] 获取节点处的成员连接性 - [x] 在现有节点之间复制成员 - [x] 分割成员 - [x] 合并兼容的成员 - [x] 镜像选定的几何形状 - [x] 复制/平移选定的几何形状 - [x] `risa-core.js` 中的共享几何编辑帮助程序 - [x] 模块化回归测试套件 --- ## 已知限制 当前限制： - 不支持区域荷载编辑。 - 不会重新生成生成的瞬时/成员化荷载。 - 服务器不运行 RISA 分析。 - 服务器不运行 RISA 设计检查。 - 服务器仅读取和修改 `.r3d` 文件。 - 应始终在工程使用之前在 RISA-3D 中验证写入操作。 - 目前仅读取但不修改荷载组合。 --- ## 贡献 欢迎拉取请求。如果您使用 RISA-3D 并有新工具的想法，请开一个问题并让我们讨论。 --- ## 关于 由 **Vibhanshu Mishra, PE** 构建 - 奥斯汀 TX AG&E 结构工程师。 专门从事钢结构和关键任务结构。构建 AI 工具，用于一个原本没有 AI 工具的领域。