Vensim MCP

把结构化的系统动力学规格生成成真正可打开的 Vensim .mdl，同时提供布局、SVG 预览、静态审计和本机 Vensim 交接。项目既能作为 MCP server 使用，也能直接从命令行运行。

Vensim PLE 实机运行证据

以下图片不是 SVG 预览或设计稿，而是 2026-07-20 在本机 Vensim PLE 10.5.1 中打开本仓库生成的 examples/market_adoption.mdl 后直接截取的运行界面。

原生检查均通过：

SyntheSim 能实际启动，常量被转换为滑杆，库存、流率和辅助变量显示仿真曲线：

完整验收步骤、环境和边界见 docs/native-validation.md。

为什么需要它

现有开源方案通常只覆盖其中一段：PySD 和 SDEverywhere 擅长跨平台仿真，VenPy/VST 面向 Windows DLL 或 DSS 命令文件，一些 .mdl 美化脚本只重排已有坐标。这个项目把 macOS 上实际可用的路径连起来：

1. 用 JSON 明确库存、流率、变量、单位和因果连接；

2. 生成包含正确库存、阀门、源汇云和信息箭头的 Vensim Sketch；

3. 用确定性分层布局与碰撞评分选择弧线控制点；

4. 从真实 Sketch 记录渲染 SVG，而不是画一张与模型无关的示意图；

5. 静态审计后直接在本机 Vensim 中打开，完成权威的 Check Model 和 Units Check。

能力边界

PLE 可以被可靠地调用来打开模型，但不能被包装成并不存在的 DSS 批处理能力。vensim-mcp doctor 会报告当前机器的真实版本和边界。

快速开始

需要 Python 3.10+；推荐使用 uv。

git clone https://github.com/Cybing521/vensim-mcp.git
cd vensim-mcp
uv sync

uv run python -m vensim_mcp.cli doctor
uv run python -m vensim_mcp.cli generate examples/market_adoption.json \
  --output examples/market_adoption.mdl
uv run python -m vensim_mcp.cli validate examples/market_adoption.mdl
uv run python -m vensim_mcp.cli render examples/market_adoption.mdl \
  --output examples/market_adoption.svg
uv run python -m vensim_mcp.cli open examples/market_adoption.mdl

在 Vensim 中依次执行：

• Model > Check Model

• Model > Units Check

• 运行一次仿真，确认库存曲线和边界行为符合预期

静态审计结果不会冒充这三项原生检查。

MCP 配置

安装后运行 stdio server：

uv run python -m vensim_mcp.server

Codex/兼容客户端可使用以下命令配置本地 server（把目录换成你的绝对路径）：

{
  "mcpServers": {
    "vensim": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/vensim-mcp",
        "run",
        "python",
        "-m",
        "vensim_mcp.server"
      ]
    }
  }
}

暴露的 MCP tools：

• vensim_doctor

• generate_vensim_model

• inspect_vensim_model

• validate_vensim_model

• render_vensim_preview

• open_vensim_model

• create_vensim_dss_script

JSON 规格

最小规格由四部分组成：

{
  "name": "simple_model",
  "title": "Simple Model",
  "levels": [
    {"name": "Population", "equation": "INTEG ( Births - Deaths, 1000 )", "unit": "Person"}
  ],
  "flows": [
    {"name": "Births", "equation": "Population * Birth Fraction", "unit": "Person/Month", "target": "Population"}
  ],
  "variables": [
    {"name": "Birth Fraction", "equation": "0.02", "unit": "1/Month", "kind": "constant"}
  ],
  "links": [
    {"source": "Population", "target": "Births", "polarity": "+"},
    {"source": "Birth Fraction", "target": "Births", "polarity": "+"}
  ]
}

完整例子见 examples/market_adoption.json。生成器不会猜测研究数据、方程或单位；这些必须由建模者明确提供。

布局原则

• 库存和物理流率构成水平主骨架；

• 常量均匀分布在上层，计算型辅助变量靠近其作用目标；

• 无障碍的短连接优先保持直线，只有避让节点、物理管道或相邻路线时才使用单控制点弧线；

• 对多个曲率和两个弯曲方向同时评分，节点碰撞的惩罚高于路线交叉，避免为了少一次交叉而穿过变量；

• 变量名按实际字符宽度调整节点尺寸；

• 物理管道与信息箭头使用不同样式；

• 过长连接、重叠节点、路线穿节点、路线交叉和断裂对象引用都会进入审计报告。

当前主示例的静态审计为：节点重叠 0、路线穿节点 0；13 条信息连接中仍有 7 对相交，另有 4 个交点涉及库存—流率物理管道。密集反馈图不承诺数学意义上的零交叉，但路由器会在保持 Vensim 单控制点兼容性的前提下尽量减少交叉，并如实报告残留值。

测试

uv run python -m unittest discover -s tests -v

测试覆盖 JSON 校验、模型生成、Sketch 引用、物理管道、直线/曲线混合路由、节点与路径碰撞指标、SVG 预览、DSS 脚本边界，以及本机 Vensim PLE 检测。

研究依据

公开方案对比和官方能力边界见 docs/research.md。核心文件格式依据 Vensim 官方 File Formats 与 Sketch Format。

License

MIT。Vensim 是 Ventana Systems, Inc. 的产品；本项目不包含或重新分发 Vensim 软件、DLL 或专有二进制格式。