内容
# 梁分析MCP
一个用于桥梁和建筑框架的线性静态结构分析的**轻量级MCP（模型上下文协议）服务器**，使用Node.js编写，没有沉重的依赖。
它为AI客户端（Claude Desktop，Claude Code，Cursor，...）提供工具：
- **建立3D梁/桁架模型**（节点，成员，截面，材料，支撑，载荷）或从**参数化类型预设**（梁桥，普拉特/豪/沃伦桁架桥，拱桥，斜拉桥，门式框架，矩形框架，3D拉撑建筑，屋顶桁架）生成完整的结构。
- **分析**它们，使用两个引擎：
- **`beam`** — 内置的3D直接刚度框架求解器（纯JavaScript，立即）。欧拉-伯努利元素具有一致的固定端力和精确的跨度内挠度/弯矩恢复 — 每个成员一个元素就足够了。
- **`calculix`** — 编写一个CalculiX输入卡（B32R梁元素），运行`ccx`，并解析位移/反作用力。使用`engine: "both"`来交叉检查两个求解器。
- **导出到FreeCAD** — 构建结构的实体3D模型并保存一个`.FCStd`文档，您可以在FreeCAD中打开和检查它。
- 获取**成员力包络线**（N，V，M，T），**应力**，和**利用率**（σ/fy），**反作用力**，和**位移**。
> **如果您有FreeCAD，则不需要安装CalculiX**：FreeCAD将其FEM工作台与`ccx`捆绑在一起，并且该服务器自动检测它（例如`C:\Program Files\FreeCAD 1.1\bin\ccx.exe`）。
## 需求
- Node.js ≥ 18
- 可选：[FreeCAD](https://www.freecad.org/)（提供`freecadcmd`用于导出**和**捆绑的CalculiX求解器）
- 可选：独立的[CalculiX](http://www.calculix.de/)（`ccx`），如果您不使用FreeCAD
## 安装和运行
```bash
git clone https://github.com/StructuralWizard/beam-analysis-mcp.git
cd beam-analysis-mcp
npm install
npm test # 封闭式验证 + MCP e2e + CalculiX交叉检查
npm run typologies # 使用两个引擎分析10种桥梁/建筑类型
```
### Claude Desktop / Claude Code 配置
添加到 `claude_desktop_config.json` （或Claude Code的 `.mcp.json`）：
```json
{
"mcpServers": {
"beam-analysis": {
"command": "node",
"args": ["C:/path/to/beam-analysis-mcp/src/server.js"]
}
}
}
```
可选环境变量：
| 变量 | 目的 |
|---|---|
| `CCX_PATH` | CalculiX `ccx` 可执行文件的显式路径 |
| `FREECAD_CMD` | `freecadcmd` 的显式路径 |
| `BEAM_MCP_OUTPUT` | 导出的 `.FCStd` / `.inp` 文件的默认目录（默认为 `~/beam-mcp-output`） |
## 工具
| 工具 | 目的 |
|---|---|
| `check_environment` | 报告 Node/ccx/freecadcmd 的可用性和单位约定 |
| `create_model` | 创建一个空模型 |
| `list_structure_presets` | 列出参数化类型生成器及其默认值 |
| `generate_structure` | 从预设 + 参数覆盖构建一个完整的桥梁/建筑 |
| `add_nodes` / `add_material` / `add_section` / `add_members` / `add_supports` / `add_loads` | 手动模型构建 |
| `analyze` | 运行线性静态分析（`beam`，`calculix`，或 `both` 进行比较） |
| `get_results` | 详细的位移，反作用力或成员力包络线 |
| `render_model` | 渲染一个SVG图形：几何，网格，变形形状，弯矩/剪力/轴力图，应力/应变图 |
| `export_freecad` | 保存一个实体3D `.FCStd` 模型（在FreeCAD中打开） |
| `export_calculix_inp` | 编写CalculiX `.inp` 卡而不求解 |
| `model_info` / `list_models` / `delete_model` | 会话管理 |
## 结构预设
| 预设 | 类型 |
|---|---|
| `beam_bridge` | 简单支撑或连续梁桥（1..n 跨度） |
| `truss_bridge` | 3D 通过桁架桥 — `pratt`，`howe`，或 `warren` |
| `arch_bridge` | 桥面拱桥：抛物线肋 + 桥面柱 + 桥面梁 |
| `cable_stayed_bridge` | 单塔扇形斜拉桥 |
| `portal_frame` | 拱形门式框架（仓库/工业棚） |
| `moment_frame_building` | 多层多跨矩形抗弯框架 |
| `braced_frame_building` | 完整的3D建筑，带有柱子，双向梁，周围X型拉撑 |
| `roof_truss` | 三角形（豪氏风格）屋顶桁架 |
与MCP客户端的示例对话：
> “生成一个3跨连续梁桥（30 m + 40 m + 30 m），用两个引擎分析它，并导出到FreeCAD。”
这对应于 `generate_structure {preset: "beam_bridge", params: {spans: [30,40,30]}}` → `analyze {engine: "both"}` → `export_freecad`.
## 约定
- **单位**：SI — 米，牛顿，帕斯卡，千克/立方米。下向荷载为 **负** `fz`/`wz`.
- **轴**：全局 +Z 向上。成员局部 x 沿成员方向；对于非垂直成员，局部 z 位于垂直平面内，因此截面高度 `h` 抗弯矩（强轴 = `Iy`）。
- **支撑**：`fixed`，`pinned`，`roller`（uz），`roller-yz`（桥梁滑动轴承），`planar-xz`（平面外约束，用于2D模型），或自定义6旗字符串，如 `"111100"`（ux，uy，uz，rx，ry，rz）。
- **成员类型**：`beam`（6-DOF 框架元素）或 `truss`（仅轴向 — 支撑，电缆，桁架网）。
## 验证
完整的测试文档 — 每个测试用例，它所检查的理论，公差和交叉引擎差异背后的调查笔记 — 在 [docs/VALIDATION.md](docs/VALIDATION.md) 中。
所有10种类型的**图解验证报告** — 几何/支撑/荷载图，CalculiX网格，荷载工况叠加检查，变形形状（内置 vs CalculiX叠加），弯矩/剪力/轴力图，应力&应变图，CalculiX冯·米塞斯场从 `.frd` 解析，以及35个解析手算检查 — 在 [docs/validation/](docs/validation/README.md) 中。
`npm test` 检查求解器与封闭解的对比：
- 均匀分布荷载下的简单支撑梁：`5wL⁴/384EI` 挠度和 `wL²/8` 弯矩（精确到 1e-6）
- 悬臂梁尖端荷载 / 均匀分布荷载：`PL³/3EI`，`wL⁴/8EI`，固定端弯矩
- 两杆桁架轴向力 `P/(2 sin θ)`
- 每个生成器预设的平衡（ΣR = ΣF）
- 与 CalculiX 的交叉验证（如果未安装 `ccx`，则自动跳过）
`npm run typologies` 构建并分析10种类型，并打印内置 vs CalculiX 比较表。参考机器上的结果（FreeCAD 1.1 捆绑 CalculiX 2.22，Windows 11）：
| # | 类型 | 节点/成员 | 最大挠度梁 [mm] | 最大挠度ccx [mm] | 差异 | 平衡 |
|---|---|---|---|---|---|---|
| 1 | 简单支撑梁桥（35 m） | 7/6 | 137.40 | 138.11 | 0.5% | ok |
| 2 | 连续梁桥（30+40+30 m） | 19/18 | 56.65 | 57.83 | 2.0% | ok |
| 3 | 普拉特桁架桥（60 m） | 32/74 | 48.46 | 48.23 | 0.5% | ok |
| 4 | 沃伦桁架桥（64 m） | 34/79 | 69.51 | 69.27 | 0.3% | ok |
| 5 | 桥面拱桥（90 m） | 34/47 | 10.72 | 10.74 | 0.2% | ok |
| 6 | 斜拉桥（140 m） | 15/26 | 118.90 | 118.72 | 0.2% | ok |
| 7 | 门式框架仓库（30 m） | 5/4 | 136.30 | 131.22 | 3.7% | ok |
| 8 | 5层矩形框架 | 24/35 | 5.60 | 5.59 | 0.3% | ok |
| 9 | 6层3D拉撑塔 | 63/174 | 11.51 | 19.64 | 41%* | ok |
| 10 | 豪氏屋顶桁架（28 m） | 16/29 | 13.86 | 13.22 | 4.6% | ok |
\* 预期：塔混合了多种截面，CalculiX 将不同截面成员之间的节点建模为柔性“结”（见限制）。用统一截面重新运行，两个引擎在 6% 内达成一致。
## 限制
- 仅线性静态：无屈曲，无动力学，无P-Δ，无非线性电缆下垂（索作为线性桁架成员，可以承受压缩）。
- 两个引擎回答的问题略有不同：内置求解器假设理想刚性关节（经典梁理论），而CalculiX 将梁扩展为实体元素，并将不同截面成员之间的关节建模为“结”，更具灵活性。在确定结构上的一致性小于1%，在具有统一截面的框架内的一致性在几个百分点内，但对于混合截面的高层3D框架，预期会有更大的差异（ccx 会报告为注释）。
- CalculiX 后端报告位移和反作用力；成员力包络线来自内置引擎。
- 工字梁和通用截面在CalculiX 卡中映射到等效矩形（ccx 梁截面支持 RECT/CIRC/PIPE/BOX 仅）。
- 结果用于**初步/教育分析** — 不是合格工程师的设计验证的替代品。
## 许可证
MIT
