FEA (finite element analysis)

mcp-fea

在对话中进行真实的有限元分析。 AI 助手发送 STEP 文件和一个通俗易懂的问题（“这根臂能承受装有 400 g 电机时的 6 g 机动吗？”）；这个 MCP 服务将文字映射到几何体，在消耗任何计算资源之前，确定性地拒绝不合格的设置，然后使用 Modal 上的 CalculiX 进行网格划分和求解，将其作为异步 MCP 任务，并返回有数据支撑的判断结果——von Mises 峰值应力、安全系数、挠度、固有频率——以及渲染后的应力图和交互式 3D 查看器。每项研究结束时都必须进行反力平衡检查，不可跳过；验证页面上的每项基准测试都会在每次提交时由 CI 重新生成。

在实际运行的部署中测得（2026-07-31）：冷启动 3.8 s · 悬臂研究从提交到完成：预热 9.3 s / 求解器容器冷启动时 12.9 s · 按 Modal 公布的费率计算，每项研究约 $0.002。

基准测试	参考值	计算值	误差
悬臂端部挠度（PL³/3EI）	0.58055 mm	0.58046 mm	0.02%
NAFEMS LE10 σ_yy @ D	−5.38 MPa	−5.456 MPa	1.41%
带孔板峰值（Heywood Kt）	62.8 MPa	61.92 MPa	1.40%
悬臂 f₁（Euler–Bernoulli）	816.0 Hz	815.4 Hz	0.08%

完整表格、网格统计数据和明确的局限性说明： docs/validation.md — 由 CI 重新生成，从不手动编辑。

协议：MCP 2026-07-28（无状态核心），并实现了 io.modelcontextprotocol/tasks 扩展，遵循 SEP-2663（官方 Python SDK v2 发布时尚未包含该扩展——本仓库还包含客户端扩展，可让官方 SDK 使用支持任务的服务），以及 MCP Apps（SEP-1865）3D 查看器。所有工程决策及其原因请参见 docs/decisions.md。

部署（3 条命令）

uv sync
uv run modal secret create mcp-fea-token MCP_FEA_TOKEN=$(openssl rand -hex 24)
uv run modal deploy -m src.server.modal_app

Modal 会打印端点 URL（https://<workspace>--mcp-fea-mcp-endpoint.modal.run）。 使用 Authorization: Bearer <your token> 连接任意 2026-07-28 MCP 客户端。 首次使用 Modal 的用户：运行一次 uv run modal token new。然后端到端验证正在运行的部署：

MCP_FEA_LIVE_URL=https://... MCP_FEA_TOKEN=... make verify-live

工具

工具	同步/异步	功能
inspect_geometry	同步	STEP → 面表（face_id、类型、质心、法线/轴、面积、bbox）+ 零件 bbox/体积。请先调用：它用于将英文描述映射到面 ID。
list_materials	同步	内置材料库：Al 6061-T6、Al 7075-T6、Steel 4140、Stainless 304、Ti-6Al-4V、ABS、PLA、Nylon 12、PC（E、ν、屈服强度、密度）。
submit_fea_study	任务	线性静力分析：验证 → 网格划分（C3D10、自适应曲率、局部薄壁细化）→ CalculiX → 判断结果/应力/安全系数 + 3 张应力 PNG。
submit_modal_study	任务	固有频率 + 振型（*FREQUENCY），前 N 阶模态（默认 6 阶），每种模态生成一张放大变形 PNG。需要约束和密度。
get_report	同步	已完成任务的完整数据；include_mesh_data: true 会添加 3D 查看器应用获取的表面网格数据。

任务生命周期：working（statusMessage 依次显示 validating → meshing → solving → postprocessing）→ completed | failed | cancelled； tasks/cancel 会终止正在运行的容器。任务保留 24 h。

单位策略

在导入时进行一次单位转换。 内部统一使用 mm–N–MPa（–吨）：长度为 mm，力为 N，应力/模量为 MPa，密度为吨/mm³（kg/m³ × 1e-12 — 仅在 Material.density_tonne_mm3 中转换一次），因此模态频率可直接以 Hz 得出。STEP 坐标按声明的单位（mm|m|in）解释；禁用 gmsh 自身的单位转换，以声明单位为准，并进行合理性检查（一个声明为 "m" 的 100 mm 零件会被标记）。

验证代码

每次拒绝都会返回 {code, message, suggested_fix}。

Code	含义	阶段
GEOMETRY_REF_INVALID	STEP 文件缺失/无法读取/超过 25 MB，单位字段无效	解析
GEOMETRY_KERNEL_CRASH / GEOMETRY_TIMEOUT	CAD 内核在处理文件时崩溃/挂起（使用隔离的子进程；不影响端点）	检查
MATERIAL_UNKNOWN / MATERIAL_UNPHYSICAL	不在材料库中 / E ∉ [0.01, 1500] GPa、ν ∉ (0, 0.5)、屈服强度 ≤ 0、密度 ∉ [10, 25000] kg/m³，模态分析缺少密度	解析
CONSTRAINT_INVALID / CONSTRAINT_CONFLICT	类型无效；节点在两个局部坐标系中均被固定	解析/模型输入文件
LOAD_INVALID / LOAD_MISSING / MODAL_INVALID	类型/单位/方向无效；载荷为零；n_modes 无效	解析
GEOM_NO_SOLID / GEOM_MULTIPLE_SOLIDS	不是单个实体（装配体 = v2）	网格划分前
FACE_ID_INVALID	面 ID 不属于该零件	网格划分前
RIGID_BODY_MOTION	约束仍留有自由运动（会命名说明，例如“绕孔轴旋转”）— SVD 秩检查	网格划分前
LOAD_ON_FIXED_FACE	载荷施加在完全固定的面上	网格划分前
UNITS_SUSPECT (警告)	零件 > 5 m 或 < 0.5 mm — 声明的单位可能有误	网格划分前
LOAD_MAGNITUDE_EXTREME / _NEGLIGIBLE (警告)	σ ≈ F/A > 10× 屈服强度或 < 1e-6× 屈服强度	网格划分前
MESH_ELEMENT_CAP	即使经过粗化/局部细化，单元数仍 > 400k	网格划分
MESH_QUALITY_JACOBIAN / MESH_QUALITY_ASPECT / MESH_THIN_WALLS	质量检查未通过；薄壁会先进行一次局部自动细化	网格划分
MESH_TIMEOUT	网格划分超过时间预算（近切线狭长面、螺旋螺纹）— 从外部终止工作进程	网格划分
SOLVER_SINGULAR / SOLVER_MESH_DEGENERATE / SOLVER_TIMEOUT / SOLVER_FAILED	映射后的 ccx 失败（超过 150k 个单元时自动切换到迭代求解器）	求解
EQUILIBRIUM_FAIL (警告，结果不可信)	ΣRF 与自由节点所受载荷相差 > 0.5%	后处理
LOAD_INTO_SUPPORT (警告)	> 5% 的载荷施加到受约束节点上（受载面与固定面相接），由支撑直接承受	后处理
BEYOND_YIELD / LARGE_DEFLECTION (警告)	FoS < 1（屈服后的数值会标记为不符合物理意义）/ u > 最小尺寸的 5%	后处理

滥用限制（均可通过环境变量调整）

STEP 上限为 25 MB · 请求上限为 40 MB（413）· 每个令牌的速率限制 （MCP_FEA_RATE_LIMIT/_WINDOW_S，429）· 并发求解上限 （MCP_FEA_MAX_CONCURRENT）· 每日预算（MCP_FEA_MAX_SPAWNS_PER_DAY）· 终止开关（MCP_FEA_DISABLE_SPAWN=1）。CAD 解析绝不会在端点进程中运行 （参见 SECURITY.md）。

本地开发

uv sync
curl -Ls https://micro.mamba.pm/api/micromamba/osx-arm64/latest | tar -xj bin/micromamba
./bin/micromamba create -y -p .tools/ccx-env -c conda-forge calculix=2.23
make test        # fast suite (protocol, benchmarks, validation, hardening)
make torture     # 21 real-world STEP files through the endpoint
make validation-page
uv run uvicorn --factory src.server.app:create_local_app --port 8000  # local server

仓库结构

src/pipeline/ 几何、网格划分、模型输入文件、求解器、验证、后处理、渲染 · src/materials/ 材料库 · src/server/ 协议、工具、任务、限制、 工作进程宿主、Modal 应用、Apps UI · src/client/ SDK 任务扩展 · tests/（含 torture/）· demo/ · docs/ 决策、验证、上游说明。许可证：Apache-2.0。