Ottosim — Simulation MCP Server

Ottosim — 仿真 MCP 服务

为 AI 助手提供基于真实 CAD 模型的一阶工程物理分析能力。这个本地 stdio MCP 服务会将 STEP 文件依次经过 Gmsh 中的显式网格划分，再交由 Elmer 执行类型化研究——包括稳态和瞬态热分析、线性静力结构分析、模态分析、直流导电分析和层流分析——并返回带版本号的结果，无需云服务或预先准备求解器输入。

所有工程输入均明确指定：材料、边界和网格都由用户声明，绝不推断；每项研究、网格和结果均绑定到特定版本，因此始终可以追溯数值的来源。

已通过解析参考验证。 Gmsh 4.15.2 和 Elmer（devel，最近发布的版本为 26.2.1）已针对所有宣称支持的物理类型完成生产级 SIF 验证——稳态和瞬态热分析、静力结构分析、模态频率分析、直流电势分析，以及稳态和瞬态层流分析——每项均使用网格（或时间步长）细化与解析参考进行对照。

基于 Node 26 / TypeScript 7 运行，使用 MCP SDK 2.4.0，并通过一次请求对应一次响应的 JSON 文件协议运行 Python Gmsh 工作进程（protocol: 1）。

安装和启动

发行目标平台与 Geometry MCP 一致：Windows x64、macOS ARM64（Apple Silicon）和 Linux x64。Intel macOS、Linux ARM64 和 Windows ARM64 不在目标平台范围内。CI 会在这三个目标平台上运行单元、产物和进程检查；在每个平台上构建固定版本的串行 Elmer 求解器并缓存原生安装；运行解析集成和验证套件；最后打包并对已发布的 tarball 进行冒烟测试。这能验证原生执行，但目前尚未发布独立运行时软件包。

本仓库在 contracts/ 中维护自己的产物架构。构建时会打包该架构和 Python 工作进程；Gmsh 和 Elmer 运行时则需单独安装。

在此目录中：

nix develop
just setup
just build
export SIMULATION_INPUT_ROOTS='["/absolute/path/to/models"]'
export SIMULATION_WORKSPACE=/absolute/path/to/run-workspace
just start

.envrc 已包含 use flake；也可以使用 direnv allow 代替 nix develop。.env.example 记录了各项变量；不会自动加载 .env。just setup 会在不运行生命周期脚本的情况下安装 npm 依赖。flake 按提交固定 nixpkgs（因此也固定 Gmsh），并按提交固定上游 Elmer。Elmer 的传递依赖使用其仓库中自带的锁文件。

Nix 仅在 x86_64-linux 上提供求解器工具链。 packages.<system>.toolchain 会提供 Node、Gmsh、Python 封装程序，以及不含 MPI、OpenMP、ElmerIce 或 Lua 的串行无头上游 Elmer。解析热分析基准可通过该串行求解器。开发 shell 还会提供 Python、Ruff 和 Nix 工具； TypeScript 语言服务器、格式化程序、代码检查器和测试依赖则作为项目本地 npm 依赖。Gmsh 的 Python 模块位于其 Nix 软件包的 lib 目录下，并通过 PYTHONPATH 提供。Elmer 是外部软件包，不由 npm 编译。

非 Nix 部署必须提供兼容的 Gmsh Python 绑定和原生库，以及带有 HeatSolve、FluxSolver、SaveData 和 ResultOutputSolve 模块的 ElmerGrid 和 ElmerSolver。可执行文件由操作人员配置：

变量	默认值 / 含义
SIMULATION_INPUT_ROOTS	必填的现有绝对输入根目录 JSON 数组
SIMULATION_WORKSPACE	.simulation-runs；本地运行和产物存储位置
SIMULATION_PYTHON	python3（Windows：python）；Nix 会设置其封装程序
SIMULATION_ELMERGRID	ElmerGrid
SIMULATION_ELMERSOLVER	ElmerSolver
SIMULATION_TIMEOUT_MS	每个工作进程/转换/求解的超时时间为 120000；最长 3600000

通用主机配置示例（也可以从 Nix shell 继承环境变量）：

{
  "command": "node",
  "args": ["/absolute/path/to/simulation/dist/src/index.js"],
  "env": {
    "SIMULATION_INPUT_ROOTS": "[\"/absolute/path/to/models\"]",
    "SIMULATION_WORKSPACE": "/absolute/path/to/run-workspace",
    "SIMULATION_PYTHON": "/absolute/path/to/provisioned/simulation-python",
    "SIMULATION_ELMERGRID": "/absolute/path/to/ElmerGrid",
    "SIMULATION_ELMERSOLVER": "/absolute/path/to/ElmerSolver"
  }
}

研究工具

公开工作流为 get_capabilities → inspect_model → query_model → validate_study → prepare_study → run_study → inspect_job → query_results。list_jobs 可在上下文丢失后恢复最近的任务，cancel_job 可停止正在进行的准备或求解器进程。

inspect_job 接受 waitMs（最长 60 s），随后会在进程内等待任务进入终止状态，而不是立即返回，因此 prepare_study → inspect_job(waitMs) → run_study → inspect_job(waitMs) → query_results 通常只需调用 5 次，而不是轮询数十次。无论等待窗口是否结束，都会返回状态。客户端请求被取消或超时后，网格划分或求解都会停止：ctx.signal 会传递到任务的中止路径，记录最终状态为 cancelled。准备和求解器执行会立即返回任务 ID。客户端断开连接后，任务仍会保留；服务器关闭后则不会。中断的任务会被记录，但不会恢复。

get_capabilities 会报告可用的物理场和研究配置结构（必填字段、可选字段、说明及完整示例）；机器可读的 simulation://help 资源则包含完整的研究配置架构——每种物理场的材料和边界字段及其单位、适用范围、带时间/模式选择器的观测量、枚举值，以及可解析的示例。两者由同一目录生成，因此发现信息不会与已接受的研究配置架构不一致。

已实现并经过基准测试的物理场包括 steady-thermal、transient-thermal、static-structural、modal、dc-conduction 和 laminar-flow。get_capabilities 报告的其他物理场仍不可用；不能仅凭 Elmer 上游有这些物理场的求解器，就认为它们可用。

瞬态研究要求为每种固体明确指定密度和热容，设置一个统一的初始温度、正时间步长，以及不超过 10,000 的步数。支持恒定温度、绝热和向内热通量边界；不支持随时间变化的条件和各区域独立的初始温度。瞬态标量结果和 VTU 结果会在每个时间步进行验证。观测可以选择与时间步对齐的正值时间（秒）；未指定 time 时，观测最终时间步。验收阈值使用对应物理量的单位（例如 K），而非秒。

静态结构研究要求为每种固体明确指定各向同性杨氏模量和泊松比，并为每个表面明确指定固定位移、规定位移、均匀牵引或自由条件。支持的模型为静态、小变形线弹性模型；位移和应力汇总值为未加权的节点采样值，而非体积平均值。

模态研究除弹性属性外，还要求明确指定密度、固定位移/自由表面条件，并请求 1–20 阶模态。首个模态实现仅报告固有频率；不提供模态形状、阻尼、预应力或谐响应。模态观测需选择模态编号，单位为 Hz。

直流导电研究要求为每种固体明确指定正值各向同性电导率，为每个表面明确指定规定电势或绝缘条件，并且每个不连通的导电区域至少要有两个不同的规定电势。结果报告节点电势场；不对电流、焦耳热、磁效应及瞬态/电容行为进行建模。 层流研究用于模拟不可压缩牛顿流体，并明确指定恒定密度和动力黏度。每个流体表面都必须明确指定规定压力或无滑移壁面；每个不连通的流体区域都需要至少两个不同的规定压力。支持稳态和瞬态计算；瞬态计算采用一阶 BDF、恒定时间步长，并明确指定静止初始速度。求解器为 Elmer 的整体式 FlowSolve 模块；其资格验证涵盖受压力驱动的方形管道流动、与解析矩形管道解对比的瞬态启动、入口/出口通量守恒，以及网格/时间步长细化。未提供通量和截面平均值；报告的速度和压力值为节点极值。Elmer 的分离式 IncompressibleNS 模块已安装，但未经资格验证。不会模拟湍流、可压缩性、运动壁面、非零初始速度以及热/电耦合。

选择使用带维度限定的检视实体 ID（例如，体积为 3:1，表面为 2:7），名称必须唯一，且不能混合实体和表面。每个检视实体必须且只能分配一次。每个实体选择都需要一种材料；在热研究中，每个表面选择默认设为绝热，除非明确覆盖。结构、模态和直流研究要求为每个表面明确指定条件。热研究中的默认设置是声明的工程假设，而不是推断出的边界条件。求解器使用 SI 单位，但研究量可以采用兼容的工程单位提供（例如 mm、in、psi、ksi、lbf、degC），并在 API 边界处转换。网格尺寸默认以米为单位，并可通过 mesh.units 接受 mm、cm、in 或 ft。结果默认采用 SI 单位；可选的 displayUnits 块（例如 { "length": "in", "pressure": "ksi" }）会以工程师使用的单位返回观测值。线性四面体仍是唯一支持的单元类型。

材料条目可以包含可选的 reference，其中包括由 Standards 等参考工具返回的牌号、来源名称/修订版本和依据。研究会在明确的数值属性旁保留调用方提供的上下文；Simulation 不会获取或验证来源。typical 值仍不同于经过资格验证的设计许用值。

检查 STEP 文件后进行稳态热研究的示例：

{
  "schemaVersion": "1",
  "name": "Bar conduction",
  "objective": "Estimate the steady temperature and heat flux",
  "model": {
    "source": {
      "revision": "sha256:<64 lowercase hex digits>",
      "uri": "file:///.../source.step",
      "format": "step",
      "units": "mm"
    },
    "inspection": {
      "revision": "sha256:<64 lowercase hex digits>",
      "uri": "file:///.../inspection.json",
      "format": "json"
    }
  },
  "selections": [
    { "name": "bar", "entities": ["3:1"] },
    { "name": "hot_end", "entities": ["2:2"] },
    { "name": "cold_end", "entities": ["2:3"] },
    { "name": "other_faces", "entities": ["2:4", "2:5", "2:6", "2:7"] }
  ],
  "mesh": { "minSize": 0.003, "maxSize": 0.006, "elementOrder": 1 },
  "physics": {
    "kind": "steady-thermal",
    "defaultBoundary": "insulated",
    "materials": [
      {
        "selection": "bar",
        "conductivity": { "value": 10, "units": "W/(m.K)" }
      }
    ],
    "sources": [],
    "boundaries": [
      {
        "selection": "hot_end",
        "kind": "temperature",
        "temperature": { "value": 400, "units": "K" }
      },
      {
        "selection": "cold_end",
        "kind": "temperature",
        "temperature": { "value": 300, "units": "K" }
      }
    ]
  },
  "observations": [{ "id": "max_temperature", "quantity": "temperature_max" }],
  "acceptanceCriteria": [
    {
      "observationId": "max_temperature",
      "operator": "<",
      "threshold": { "value": 410, "units": "K" }
    }
  ],
  "assumptions": []
}

示例实体标签仅供说明；请使用 query_model 返回的标签，并根据实际零件确认每项选择。prepare_study 会返回一个 jobId；轮询 inspect_job 直至成功，然后将其 prepared 工件传给 run_study，后者会返回另一个 jobId。query_results 会分别报告求解器证据、观测值和判据结果；判据未通过是工程结果，不是求解器错误。其响应默认有界——返回不含重复支撑摘要的观测值、去重后的场描述符，以及一页工件引用（limit/cursor、artifactCount）。请求 include:["summaries"] 时会返回摘要；若未声明观测值，则会将摘要作为后备内容返回。传入 time 可选择一个帧，传入 observations 可进行筛选。标量均值是节点均值，不是体积平均值或积分热量。任意 SIF、过程、表达式、脚本和求解器命令均不得作为研究输入。 工具失败会使用 MCP isError。服务导致的领域失败会返回 JSON { code, message } 对象（如有，则包含带修订版本的诊断日志引用）；无效工具参数会在处理程序运行前由 MCP 层拒绝，并以纯文本返回。领域错误代码是一个封闭且有文档记录的集合 （列于 simulation://help 的 enums.error_codes 下）：invalid_input、 invalid_study、invalid_physics、invalid_selection、invalid_job_kind、 unsupported_condition、unsupported_physics、unsupported_format、 stale_artifact、path_policy、file_not_found、too_large、bad_mesh、 bad_groups、malformed_results、solver_failed、worker_failed、 conversion_failed、process_failed、spawn_error、output_limit、 persistence_failed、cancelled、timeout、interrupted、worker_protocol、 以及 internal_error。求解失败时会返回可供检查的运行元数据，而不会把部分输出伪装成成功结果。

服务器诊断信息会以换行分隔的 JSON 格式写入 stderr（stdout 是 MCP 通道）。设置 MCP_LOG_LEVEL（debug|info|warn|error，默认值为 info）、设置 MCP_LOG_FORMAT=human 可使用简洁格式，并可设置 MCP_TRACE_ID 以关联事件；类似密钥的字段会被脱敏。

边界、安全与保留期限

• 这是一个受信任的本地工具，并非文件系统沙箱。输入根目录会被规范化，以捕获意外的路径错误；服务器假定本地用户和文件可信。请勿将其暴露给不受信任的客户端。
• 工件修订版本是所读取或生成的确切字节的 SHA-256 摘要。文件更改后重用引用会明确失败，但无法防范操作期间发生的并发编辑。
• 进程使用已配置的可执行文件和参数数组，不使用 shell。为确保运行时兼容性，会继承本地进程环境，并应用确定性的区域设置和线程设置；因此，子工具也会继承本地环境变量。
• 系统会强制执行每个进程的墙钟超时、串行执行，以及 8 MiB 的合并捕获输出上限。没有可移植的内存、网格大小、输入大小或工作区磁盘配额；如果部署需要这些限制，请配置 OS 配额或 cgroups。
• V1 支持单独的实体区域和外部 BC 组。内部或孤立的原生边界会导致失败；不支持接触热阻、自动碎片划分、修复、非共形耦合、辐射、塑性或几何非线性。瞬态热分析仅支持上述显式的常属性/时间步模型；结构分析仅支持各向同性、小应变线弹性；模态分析不考虑阻尼和载荷。
• 选择器绑定到确切的源修订版本、Gmsh 版本和 gmsh-occ-import-v1。不保证 Geometry SubjectRef 与 Gmsh 拓扑等价。导入的名称仅作提示，不代表工程意图。
• 不会自动删除内容。关闭服务器后，在不再需要引用时，显式归档或移除 UUID 操作目录。just clean 仅移除编译后的代码。中断的记录不会恢复。非正常终止后，重启并使用该工作区之前，请检查并回收任何孤立的求解器进程。正常关闭时会取消服务器拥有的运行任务。
• 托管部署需要外部隔离边界（例如，使用带有显式输入挂载和资源限制的容器或 VM）；应用程序的路径检查不能替代隔离。这些输出是数值证据，并非工程认证。

实现选择

• Gmsh Python API 负责 STEP 导入、拓扑清单和网格生成。 它通过有界 JSON 文件工作进程协议与 TypeScript 通信； 无需生成 .geo 脚本。
• 类型化输入会生成确定性的 SIF。对于受支持的工作流，PyElmer 和模型编写的 SIF 都不是必需的。
• ASCII MSH 2.2 会将显式物理组传递给 ElmerGrid；会验证转换后的组成员关系和连通性，而不是只相信标签。
• 上游 Elmer 和 Gmsh 是由 Nix 配置的外部工具，不会在服务器启动时通过 npm 下载。非 Nix 部署可以配置可执行文件路径。
• 标量摘要和 VTU 清单仅限于受支持的求解器输出。几何 ID 不是跨内核网格选择器。

工件引用

每个引用都通过 revision: "sha256:<64 lowercase hex digits>" 和 format 标识一个精确的字节流。URI 是可选的定位符；需要字节的操作必须使用可访问的本地 file: URI。支持的格式标识符为 step、gmsh-msh、elmer-mesh、vtu、elmer-sif、text 和 json。派生工件会获得各自的摘要。Elmer 网格目录不是单个工件：其元数据引用各个原生文件。

限制

• 仅支持线性四面体；研究采用小应变，并使用上文列出的物理类型。所有工程输入都必须显式指定——不会推断材料、边界和理想化条件。
• 结果是数值证据，不构成工程认证；未通过验收准则属于工程结果，而非求解器错误。
• 客户端断开连接后，作业仍会继续；但服务器关闭后不会继续，且中断的作业会被记录，而不会恢复。

开发

需要 Node.js 26+ 和 just。Nix flake 和 .envrc 会提供工具链；修改任一文件后，请运行 direnv allow。

配方	用途
just setup	安装依赖（禁用 npm 脚本）。
just dev	通过 stdio 运行服务。
just start	运行编译后的服务。
just build	编译到 dist/。
just test	运行不依赖求解器的单元测试。
just test-integration	运行选择启用的 Gmsh/Elmer 集成基准测试。
just lint	运行 oxlint。
just fmt	使用 Prettier 重写格式。
just fmt-check	检查格式。
just typecheck	运行 tsc --noEmit。
just check	fmt-check + lint + typecheck + test。
just fixture	重新生成解析棒基准样例。
just clean	移除构建输出。

服务日志以按行分隔的 pino JSON 格式输出到 stderr。可通过 MCP_LOG_LEVEL （debug|info|warn|error）、MCP_LOG_FORMAT=human 和 MCP_TRACE_ID 调整 日志；类似密钥的字段会被隐藏。

轻量级的 checks shell 包含 Node 和 Ruff，无需构建 Gmsh/Elmer 求解器工具链：

# Run from this repository.
nix develop .#checks --accept-flake-config --command just setup
nix develop .#checks --accept-flake-config --command just check
nix develop --accept-flake-config --command just test-integration
nix develop --accept-flake-config --command just check
nix develop --accept-flake-config --command just build

just test-integration 运行选择启用的直接服务 Gmsh/Elmer 基准测试。这是服务自身负责的集成测试；面向公众的 stdio 验收测试会针对构建后的服务制品单独运行。

在源码检出目录中，tests/fixtures/README.md 记录了解析棒尺寸、 生成方式以及温度/热通量容差。单元检查不需要求解器运行时。原生集成检查还会覆盖 格式错误的输入、求解器故障、超时/取消、重启后的持久性以及过期输出。 测试使用操作系统的临时目录； SIMULATION_TEST_TMP 可指定其他临时根目录。

许可信息和上游源代码引用记录在 第三方声明中。

打包

npm pack 会先进行构建，并包含编译后的运行时代码、本地制品 schema、Python worker、README 和第三方声明。测试、源映射和 Python 缓存不会包含在内。安装打包文件后，可使用兼容的 MCP 客户端检查 simulation-mcp-server。服务支持两个协议版本：标准 MCP 主机协商使用的 2025-11-25 握手，以及通过 server/discover 支持的 2026-07-28。 原生工具仍需单独安装。

just check 包含不依赖求解器的 stdio 协议测试，涵盖现代发现、 工作流资源、工具错误以及两个协议版本。

许可证

MIT。第三方工具链条款见 THIRD_PARTY_NOTICES.md。